1. Getting Started
  2. Configuration
  3. Integration Details
  4. Creating a Sale
    1. Simple Sale
    2. Advanced Sale
  5. Creating an Authorization and Capture
    1. Simple Authorization
    2. Simple Capture
    3. Simple Offline Capture
    4. Voice Capture
    5. Incremental Authorization
    6. Advanced Authorization
    7. Advanced Capture
  6. Issuing a Refund
    1. Simple Refund
    2. Advanced Refund
  7. Issuing a Void
    1. Simple Void
    2. Advanced Void
  8. Creating a Credit
  9. Get Transaction Details
    1. Inquiry Operation
  10. Airline Passenger Sale
    1. Passenger Sale
  11. Military Star Card
    1. Simple Star Card
    2. Advanced Star Card
  12. Automated Clearing House (ACH)/ eCheck
    1. Simple ACH
    2. Advanced ACH
    3. Simple eCheck
    4. Advanced eCheck
  13. eWallet
    1. eWallet Simple Credit
  14. Fiserv
    1. Fiserv Simple Sale
    2. Advanced Fiserv Sale
  15. Chargeback Entry
    1. Mark as Chargeback
  16. Balance Inquiry
    1. Retrieve Card Balance
  17. Decrypt Custom Fields
    1. Decrypt Data
  18. Credit Card Verification
    1. Account Verification
  19. Data Vault
    1. Adding a Customer
    2. Add Customer by Payment Type
    3. Update Customer
    4. Adding Payment Types to a Customer
    5. Update Payment Type
    6. Delete Payment Type
    7. Delete Data Vault Customer
    8. Retrieve Customer
    9. Retrieve Payment Type
    10. Decrypt Payment Type
    11. Tokenized Payments
  20. Creating Payment Plans
    1. Creating a Payment Plan
    2. Updating a Payment Plan
    3. Building a Sequence
    4. Notification Settings
    5. Add or Update a Sequence
    6. Delete a Sequence
    7. Delete a Plan
    8. Assign Payment Plan
    9. Update Payment Plan Assignment
    10. Cancel Payment Plan Assignment
  21. Invoicing
    1. Creating an Invoice
    2. Update Invoice
    3. Retrieve Invoice
    4. Cancel Invoice
    5. Cancel Invoice by Customer
    6. Pay Invoice with a Credit Card
    7. Pay Invoice with a Bank Account
  22. Forget Customer
    1. Forget Customer Operation
    2. Inquiry GDPR Request
  23. Dynamic Descriptors
    1. Chase Processor
    2. MeS Processors
    3. First Data Processor
    4. MIMS Processor
    5. GlobalOne Processor
    6. TSYS Processor
  24. Response Variables
    1. Transaction Response Variables
    2. Gateway Status
    3. Status
  25. Processor Response Codes
    1. AVS Response Codes
    2. CVV Response Codes
    3. Military Star Responses
  26. Payment Redirect
    1. Architecture
    2. Process Workflow
    3. Integration
    4. Checkout Process
    5. Appendix A
    6. Appendix B
  27. 3DS Checkout API
    1. Architecture
    2. Integration
    3. Checkout Process
    4. Appendix A
    5. Appendix B
    6. Appendix C
    7. Appendix D
  28. Code Samples

Getting Started

The site describes the direct method for payments and value added features in the Sparrow gateway and is referred to as the Services API.

The Services API URL is:

https://secure.sparrowone.com/Payments/Services_api.aspx

Services_api.aspx is an API implementation of secure payments. In this fashion, merchants can seamlessly integrate gateway payment functions into their checkout process using a direct post via HTTP.

Configure the Merchant Account

Merchant Key (mKey)

When sending a payment transaction request to Sparrow a Merchant Key is required. A sample Merchant Key follows:

MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO

Each Merchant Key represents the payment type (credit card, ACH, etc…) and merchant account targeted for processing the transaction. This methodology allows merchants to have multiple merchant accounts and payment types for processing transactions. The transactions can be sent to a particular account based on the merchant’s business rules.

For example, to process transaction send the Merchant key associated with a Visa and MasterCard merchant account. (Discover and American Express cards are also tied to the Visa/MasterCard Merchant Key.)

The mKey can be found inside the gateway under Admin > System Configuration > Transaction Routing.

Integration Details

Services API

To process payment through Services API send an HTTP POST request containing payment fields to the Services API page.

Request should be formatted as HTML form post, i.e. content type should be application/x- www-form-urlencoded and request body should be formatted accordingly:

  1. The form field names and values are escaped: space characters are replaced by +, and then reserved characters are escaped as per URL; that is, non-alphanumeric characters are replaced by %HH, a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks, as in multi-line text field values, are represented as CR LF pairs, i.e. %0D%0A.

  2. The fields are listed in the order they appear in the document with the name separated from the value by = and the pairs separated from each other by &. Fields with null values may be omitted.

Creating a Sale

By sending the appropriate Merchant Key, along with the appropriate API fields the merchant can direct a transaction to the appropriate merchant account for transaction processing.

Test and Validate a Sale

Credit Card test transactions can be submitted with the following information:

Cardnum: 4111111111111111
Cardexp: 10/19
Amount: > 1.00
CVV Match: 999

Forcing errors in test mode:

  • To cause a decline pass an amount less than 1.00

  • To trigger an error message, pass an invalid card number

  • To simulate an AVS mismatch, pass 888 in the address1 field, and 77777 for the zip

Simple Sale

VariableName Format Description
transtype sale sale = Transaction Sale
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0711 = 7/2011)
amount d.dd Total amount to be charged (i.e. 10.00)
cvv Card security code

transtype=sale&mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&amount=9.95&cardnum=4111111111111111&cardexp=1010&cvv=999

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
cvv=999" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10751328&
xref=3829811833&
authcode=123456&
orderid=&
type=sale&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11284989
$resultSimpleSale.xRef;    // 3923166057
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

CODE:


api.sale({
  amount: '9.95',
  cardnum: '4111111111111111',
  cardexp: '1010',
  cvv: '999',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '11037941'
result.xref # => '3877926163'
result.authcode # => '123456'
result.type # => 'sale'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:

var result = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032426
result.XRef;    // 3876731523
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.sale(10.0, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11188324",
    "type": "sale",
    "xref": "3907208029"
}

Advanced Sale

Variable Name Format Description
transtype sale Transaction Sale
mkey secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019
amount d.dd Total amount to be charged (ie. 10.00)
cvv card security code
currency CCC (ISO 4217 alphabetic code) Code of the payment currency. If currency is not specified, the default currency (USD) is assumed.
firstname Billing first name
lastname Billing last name
skunumber_# SKU number of the product being purchased (skunumber_1, skunumber_2, etc)
description_# Description of the product being purchased
amount_# Price of the single unit of a product being purchased
quantity_# Number of units of a product being purchased
orderdesc Order Description
orderid Order ID
cardipaddress ddd.ddd.ddd.ddd IP address of the customer, can be used for fraud prevention in FBI Tools
tax d.dd Total tax amount
shipamount d.dd Total shipping amount
ponumber Original Purchase Order
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
phone Billing phone number
fax Billing fax number
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email
opt_amount_type_1 tip Type of additional amount
opt_amount_value_1 d.dd Value of additional amount (e.g. 1.00)
opt_amount_percentage_1 Percentage of additional amount (e.g. 10)
sendtransreceipttobillemail true/false If true receipt will be sent to email from Billing Information if email is specified
sendtransreceipttoshippemail true/false If true receipt will be sent to email from Shipping Information if email is specified
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.
token [A-Z, 0-9] Customer or customer payment info unique identifier.
saveclient true / false If parameter 'saveclient' = true and the customer is identified as new, then a new Data Vault client will be created with payment/contact info from the transaction data and DV token will be generated. The payment transaction will be assigned to this new DV client.
updateclient true / false If the parameter 'updateclient' = true and the DataVault finds the client according to customer identification rules, then the payment transaction will be assigned to the DataVault client and the DataVault client payment/contact info will be updated according to the transaction's data.
groupid alphanumeric Group ID of the Split Funding group. If groupid is defined for the transaction system splits it in accordance with group settings.
pinlessdebitindicator true / false For Chase Processor only. Indicator to process PIN-less debit transactions.
sendpaymentdesc true / false Overrides ‘Send Payment Descriptor’ account setting for the transaction.
electrcommind Required for any 3DS-aware payment
securecavv Required for any 3DS-aware payment
securexid Required for any 3DS-aware payment
threedsecparesstatus Optional for 3DS-aware payment. Used by OCBC processor only.
signatureverification Optional for 3DS-aware payment
threedsecuretransactionid Optional for 3DS-aware payment
transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=57.85&cardnum=4111111111111111&cardexp=1010&cvv=999&skunumber_1=5558779&description_1=menssweaterblue&amount_1=50.00&quantity_1=1&tax=2.85&shipamount=5.00&firstname=John&lastname=Smith&address1=888+test+address&city=Los+Angeles&country=US&state=CA&phone=222-444-2938&shipfirstname=John&shiplastname=Smith&shipaddress1=888+test+address&shipcity=Los+Angeles&shipstate=CA&shipphone=2224442938

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
cvv=999&\
currency=USD&\
firstname=John&\
lastname=Doe&\
skunumber_1=123&\
skunumber_2=456&\
description_1=Blue widget&\
description_2=Brown widget&\
amount_1=1.99&\
amount_2=2.99&\
quantity_1=1&\
quantity_2=2&\
orderdesc=Order Description&\
orderid=11111&\
cardipaddress=8.8.8.8&\
tax=0.25&\
shipamount=1.25&\
ponumber=22222&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750810&
xref=3829708603&
authcode=123456&
orderid=11111&
type=sale&
avsresponse=N&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.AdvancedSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032425
result.XRef;    // 3876731470
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.sale({
  amount: '57.85',
  cardnum: '4111111111111111',
  cardexp: '1010',
  cvv: '999',
  skunumber_1: '5558779',
  description_1: 'menssweaterblue',
  amount_1: '50.00',
  quantity_1: '1',
  tax: '2.85',
  shipamount: '5.00',
  firstname: 'John',
  lastname: 'Smith',
  address1: '888 test address',
  city: 'Los Angeles',
  country: 'US',
  state: 'CA',
  phone: '222-444-2938',
  shipfirstname: 'John',
  shiplastname: 'Smith',
  shipaddress1: '888 test address',
  shipcity: 'Los Angeles',
  shipstate: 'CA',
  shipphone: '2224442938',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '11037942'
result.xref # => '3877926187'
result.authcode # => '123456'
result.type # => 'sale'
result.avsresponse # => 'A'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


sale = sparrowone.SaleInfo(
    amount=7.96,
    currency="USD",
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
    ),
    ship_to=sparrowone.Contact(
        first_name="Julianne",
        last_name="Stingray",
        address1="16100 N 72nd Street",
        address2="Suite 171",
        city="Glitch City",
        zip="220000",
        country="XX",
        email="noreply@sparrowone.com",
    ),
    products=[
        sparrowone.Product(skunumber=1999,
                        description="Blue whale",
                        amount=1.99,
                        quantity=4)
    ],
    ip_addr="192.168.12.34",
)

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999",
)

resp = sprw.sale(sale, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11188287",
    "type": "sale",
    "xref": "3907204894"
}

CODE:

$paramsAdvancedSale = new AdvancedSaleParams();
$paramsAdvancedSale->creditCard->cardNum = "4111111111111111";
$paramsAdvancedSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsAdvancedSale->amount = 9.99;

$resultAdvancedSale = self::$sparrow->AdvancedSale($paramsAdvancedSale)->wait();

RESULT AdvancedSale:

$resultAdvancedSale.isSuccess;    // 1
$resultAdvancedSale.status;    // 200
$resultAdvancedSale.response;    // 1
$resultAdvancedSale.textResponse;    // SUCCESS
$resultAdvancedSale.transId;    // 11284988
$resultAdvancedSale.xRef;    // 3923166016
$resultAdvancedSale.authCode;    // 123456
$resultAdvancedSale.type;    // sale
$resultAdvancedSale.codeResponse;    // 100
$resultAdvancedSale.codeDescription;    // Transaction was Approved

Creating an Authorization and Capture

A typical Sale has two parts, an Authorization and a Capture. Through the API, merchants have the option to either run a complete sale or break the transaction into two separate parts. Merchants who do not ship/deliver products on the same day, offer future delivery of services or accept tips may want to use the auth and capture method. Examples of these merchant types would be:

  • Car Rentals

  • Hotels

  • Restaurants

Simple Authorization

Authorization transactions are processed immediately but are not flagged for settlement. This process will verify funds availability and hold them until capture (3-7 days). In order to settle an open auth, a subsequent capture must be made.

An authorization may have all of the same fields as a Sale transaction, but with transtype=auth

VariableName Format Description
transtype auth Authorization = Transaction Auth
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0711 = 7/2011)
amount d.dd Total amount to be charged (i.e. 10.00)
cvv Card security code

transtype=auth&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&cardnum=4111111111111111&cardexp=1010&cvv=999

Command Line:

curl -d "transtype=auth&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
cvv=999" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750806&
xref=3829708674&
authcode=123456&
orderid=&
type=auth&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.SimpleAuthorization(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032439
result.XRef;    // 3876731939
result.AuthCode;    // 123456
result.Type;    // auth
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.auth({
  amount: '9.95',
  cardnum: '4111111111111111',
  cardexp: '1010',
  cvv: '999',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '11037943'
result.xref # => '3877926217'
result.authcode # => '123456'
result.type # => 'auth'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.auth(10.0, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150723",
    "type": "auth",
    "xref": "3901033581"
}

CODE:

$paramsSimpleAuthorization = new SimpleAuthorizationParams();
$paramsSimpleAuthorization->creditCard->cardNum = "4111111111111111";
$paramsSimpleAuthorization->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleAuthorization->amount = 9.99;

$resultSimpleAuthorization = self::$sparrow->SimpleAuthorization($paramsSimpleAuthorization)->wait();

RESULT SimpleAuthorization:

$resultSimpleAuthorization.isSuccess;    // 1
$resultSimpleAuthorization.status;    // 200
$resultSimpleAuthorization.response;    // 1
$resultSimpleAuthorization.textResponse;    // SUCCESS
$resultSimpleAuthorization.transId;    // 11285012
$resultSimpleAuthorization.xRef;    // 3923167317
$resultSimpleAuthorization.authCode;    // 123456
$resultSimpleAuthorization.type;    // auth
$resultSimpleAuthorization.codeResponse;    // 100
$resultSimpleAuthorization.codeDescription;    // Transaction was Approved

Simple Capture

Capture transactions flag existing authorizations for settlement. Only authorizations can be captured. Captures can be submitted for an amount equal to or less than the original authorization amount.

*In order to capture an amount that is higher than the original auth, please contact support to make sure that the correct settings have been enabled for your account.

VariableName Format Description
transtype capture Capture = Transaction Capture
mkey Secured merchant account key
transid Original Payment Gateway Transaction ID
amount d.dd Total amount to be charged (i.e. 10.00)
sendtransreceipttobillemail true/false If true receipt will be sent to email from Billing Information if email is specified
sendtransreceipttoshipemail true/false If true receipt will be sent to email from Shipping Information if email is specified
sendtransreceipttoemails email@email.com Additional list of emails to receive receipts

transtype=capture&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&transid=123456&sendtransreceipttobillemail=true

Command Line:

curl -d "transtype=capture&\
mkey=$M_KEY&\
transid=10750806&\
cardexp=1019&\
amount=9.95&\
sendtransreceipttobillemail=true&\
sendtransreceipttoshipemail=true&\
sendtransreceipttoemails=email@email.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750806&
xref=3829708674&
authcode=123456&
orderid=&
type=capture&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var resultSimpleAuthorization = await _sparrow.SimpleAuthorization(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);
var result = await _sparrow.SimpleCapture(
    transId: resultSimpleAuthorization.TransId,
    amount: 9.99m);

RESULT SimpleAuthorization:

resultSimpleAuthorization.Status;    // 200
resultSimpleAuthorization.Response;    // 1
resultSimpleAuthorization.TextResponse;    // SUCCESS
resultSimpleAuthorization.TransId;    // 11032440
resultSimpleAuthorization.XRef;    // 3876731948
resultSimpleAuthorization.AuthCode;    // 123456
resultSimpleAuthorization.Type;    // auth
resultSimpleAuthorization.CodeResponse;    // 100
resultSimpleAuthorization.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032440
result.XRef;    // 3876731948
result.AuthCode;    // 123456
result.Type;    // capture
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.capture({
  transid: '10934003',
  amount: '9.25',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '10934003'
result.xref # => '3865034963'
result.authcode # => '123456'
result.type # => 'capture'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)

resp = sprw.auth(10.0, card)
transid = resp["transid"]

resp = sprw.capture(transid, 10.0, "1019")

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150733",
    "type": "capture",
    "xref": "3901034728"
}

CODE:

$paramsSimpleAuthorization = new SimpleAuthorizationParams();
$paramsSimpleAuthorization->creditCard->cardNum = "4111111111111111";
$paramsSimpleAuthorization->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleAuthorization->amount = 9.99;

$resultSimpleAuthorization = self::$sparrow->SimpleAuthorization($paramsSimpleAuthorization)->wait();

$paramsSimpleCapture = new SimpleCaptureParams();
$paramsSimpleCapture->transId = $resultSimpleAuthorization->transId;
$paramsSimpleCapture->amount = 9.99;

$resultSimpleCapture = self::$sparrow->SimpleCapture($paramsSimpleCapture)->wait();

RESULT SimpleAuthorization:

$resultSimpleAuthorization.isSuccess;    // 1
$resultSimpleAuthorization.status;    // 200
$resultSimpleAuthorization.response;    // 1
$resultSimpleAuthorization.textResponse;    // SUCCESS
$resultSimpleAuthorization.transId;    // 11285013
$resultSimpleAuthorization.xRef;    // 3923167338
$resultSimpleAuthorization.authCode;    // 123456
$resultSimpleAuthorization.type;    // auth
$resultSimpleAuthorization.codeResponse;    // 100
$resultSimpleAuthorization.codeDescription;    // Transaction was Approved

RESULT SimpleCapture:

$resultSimpleCapture.isSuccess;    // 1
$resultSimpleCapture.status;    // 200
$resultSimpleCapture.response;    // 1
$resultSimpleCapture.textResponse;    // SUCCESS
$resultSimpleCapture.transId;    // 11285013
$resultSimpleCapture.xRef;    // 3923167338
$resultSimpleCapture.authCode;    // 123456
$resultSimpleCapture.type;    // capture
$resultSimpleCapture.codeResponse;    // 100
$resultSimpleCapture.codeDescription;    // Transaction was Approved

Simple Offline Capture

VariableName Format Description
transtype offline Offline Capture closes an open authorization which was manually obtained from the card issuer
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0711 = 7/2011)
amount d.dd Total amount to be charged (i.e. 10.00)
authcode string Auth code received from the issuer
authdate MM/DD/YYYY Date that auth code was obtained, required for Chase only
cvv Card security code

transtype=offline&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&cardnum=4111111111111111&cardexp=1010&cvv=999&authcode=987654&authdate=03/25/2016

Command Line:

curl -d "transtype=offline&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
authcode=123456&\
authdate=01/31/2017&\
cvv=999" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750801&
xref=3829708552&
authcode=123456&
orderid=&
type=offline&
avsresponse=&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.SimpleOfflineCapture(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m,
    authCode: "123456",
    authDate: new DateTime(2019,10,21));

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032437
result.XRef;    // 3876731902
result.AuthCode;    // 123456
result.Type;    // offline
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.auth(10.0, card)
transid = resp["transid"]
card_exp = "1019"
amount = 10.0

resp = sprw.offline(amount, card,
                    auth_code="123456",
                    auth_date="01/31/2017")

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150737",
    "type": "offline",
    "xref": "3901034874"
}

CODE:

$paramsSimpleOfflineCapture = new SimpleOfflineCaptureParams();
$paramsSimpleOfflineCapture->creditCard->cardNum = "4111111111111111";
$paramsSimpleOfflineCapture->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleOfflineCapture->amount = 9.99;
$paramsSimpleOfflineCapture->authCode = "123456";
$paramsSimpleOfflineCapture->authDate = new DateTime("2019-10-21");

$resultSimpleOfflineCapture = self::$sparrow->SimpleOfflineCapture($paramsSimpleOfflineCapture)->wait();

RESULT SimpleOfflineCapture:

$resultSimpleOfflineCapture.isSuccess;    // 1
$resultSimpleOfflineCapture.status;    // 200
$resultSimpleOfflineCapture.response;    // 1
$resultSimpleOfflineCapture.textResponse;    // SUCCESS
$resultSimpleOfflineCapture.transId;    // 11285010
$resultSimpleOfflineCapture.xRef;    // 3923167199
$resultSimpleOfflineCapture.authCode;    // 123456
$resultSimpleOfflineCapture.type;    // offline
$resultSimpleOfflineCapture.codeResponse;    // 100
$resultSimpleOfflineCapture.codeDescription;    // Transaction was Approved

Voice Capture (for Visa Only)

When you request an authorization through the system, the issuer might ask that you call the acquirer to answer questions about the transaction. These transaction types are sometimes known as Referrals. To capture verbally authorized transactions, send the verbal authorization code in the capture request.

You can use verbal authorization to capture an authorization that was declined for any of these reasons:

•      Verbal authorization required

•      Card expired

•      Card refused

•      Invalid card

A verbal authorization works as follows:

1.    The authorization reply includes reason code 201, which indicates that the issuing bank is requiring a verbal authorization.

2.    The merchant calls the acquirer to answer questions about the transaction.

3.    If the acquirer verbally authorizes the transaction, the merchant is given a verbal authorization code.

4.    The merchant would include the verbal authorization code in the capture request.

Incremental Authorization (Lodging Industry only)

The additional operation type, Incremental Authorization, is implemented for the Lodging Industry only.

It is used to add an amount to an original open Authorization and can occur multiple times. It cannot be applied to an already captured Authorization.

Please see details in the document “SPARROW API” in the First Data PTS and TSYS sections.

Advanced Authorization

Variable Name Format Description
transtype auth Authorization = Transaction Auth
mkey secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019
amount d.dd Total amount to be charged (ie. 10.00)
cvv card security code
currency CCC (ISO 4217 alphabetic code) Code of the payment currency. If currency is not specified, the default currency (USD) is assumed.
firstname Billing first name
lastname Billing last name
skunumber_# SKU number of the product being purchased (skunumber_1, skunumber_2, etc)
description_# Description of the product being purchased
amount_# Price of the single unit of a product being purchased
quantity_# Number of units of a product being purchased
orderdesc Order Description
orderid Order ID
cardipaddress ddd.ddd.ddd.ddd IP address of the customer, can be used for fraud prevention in FBI Tools
tax d.dd Total tax amount
shipamount d.dd Total shipping amount
ponumber Original Purchase Order
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
phone Billing phone number
fax Billing fax number
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email
opt_amount_type_1 tip Type of additional amount
opt_amount_value_1 d.dd Value of additional amount (e.g. 1.00)
opt_amount_percentage_1 Percentage of additional amount (e.g. 10)
sendtransreceipttobillemail true/false If true receipt will be sent to email from Billing Information if email is specified
sendtransreceipttoshippemail true/false If true receipt will be sent to email from Shipping Information if email is specified
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.
token [A-Z, 0-9] Customer or customer payment info unique identifier.
saveclient true / false If parameter 'saveclient' = true and the customer is identified as new, then a new Data Vault client will be created with payment/contact info from the transaction data and DV token will be generated. The payment transaction will be assigned to this new DV client.
updateclient true / false If the parameter 'updateclient' = true and the DataVault finds the client according to customer identification rules, then the payment transaction will be assigned to the DataVault client and the DataVault client payment/contact info will be updated according to the transaction's data.
groupid alphanumeric Group ID of the Split Funding group. If groupid is defined for the transaction system splits it in accordance with group settings.
pinlessdebitindicator true / false For Chase Processor only. Indicator to process PIN-less debit transactions.
sendpaymentdesc true / false Overrides ‘Send Payment Descriptor’ account setting for the transaction.
electrcommind Required for any 3DS-aware payment
securecavv Required for any 3DS-aware payment
securexid Required for any 3DS-aware payment
threedsecparesstatus Optional for 3DS-aware payment. Used by OCBC processor only.
signatureverification Optional for 3DS-aware payment
threedsecuretransactionid Optional for 3DS-aware payment
authindicator Pre / Final / Undefined This field defines the type of authorization request for Mastercard transactions.

Advanced Capture

VariableName Format Description
transtype capture Capture = Transaction Capture
mkey Secured merchant account key
transid Original Payment Gateway Transaction ID
amount d.dd Total amount to be charged (i.e. 10.00)
sendtransreceipttobillemail true/false If true receipt will be sent to email from Billing Information if email is specified
sendtransreceipttoshipemail true/false If true receipt will be sent to email from Shipping Information if email is specified
sendtransreceipttoemails email@email.com Additional list of emails to receive receipts
shiptracknum Shipping Tracking Number
shipcarrier ups/fedex/dhl/usps Shipping Carrier
orderid Order ID
opt_amount_type_# tip/surcharge Type of additional amount
opt_amount_value_# Value of additional amount (1.00)
opt_amount_percentage_# Percentage of additional amount (10)

transtype=capture&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&transid=123456&sendtransreceipttobillemail=true&orderid=54321

CODE:

var resultSimpleAuthorization = await _sparrow.SimpleAuthorization(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) }, 
    amount: 9.99m);
var result = await _sparrow.AdvancedCapture(
    transId: resultSimpleAuthorization.TransId, 
    amount: 9.99m);

RESULT SimpleAuthorization:

resultSimpleAuthorization.Status;    // 200
resultSimpleAuthorization.Response;    // 1
resultSimpleAuthorization.TextResponse;    // SUCCESS
resultSimpleAuthorization.TransId;    // 11032438
resultSimpleAuthorization.XRef;    // 3876731911
resultSimpleAuthorization.AuthCode;    // 123456
resultSimpleAuthorization.Type;    // auth
resultSimpleAuthorization.CodeResponse;    // 100
resultSimpleAuthorization.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032438
result.XRef;    // 3876731911
result.AuthCode;    // 123456
result.Type;    // capture
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:

api.capture({
  amount: '9.95',
  transid: '123456',
  sendtransreceipttobillemail: 'true',
  orderid: '54321',
})

RESULT:

result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '123456'
result.xref # => '3865035008'
result.authcode # => '654321'
result.type # => 'capture'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)

resp = sprw.auth(10.0, card)
transid = resp["transid"]

resp = sprw.capture(transid, 10.0, "1019",
                    send_receipt_to_billing_email=True)

RESULT:

{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150733",
    "type": "capture",
    "xref": "3901034728"
}

CODE:

$paramsSimpleAuthorization = new SimpleAuthorizationParams();
$paramsSimpleAuthorization->creditCard->cardNum = "4111111111111111";
$paramsSimpleAuthorization->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleAuthorization->amount = 9.99;

$resultSimpleAuthorization = self::$sparrow->SimpleAuthorization($paramsSimpleAuthorization)->wait();

$paramsAdvancedCapture = new AdvancedCaptureParams();
$paramsAdvancedCapture->transId = $resultSimpleAuthorization->transId;
$paramsAdvancedCapture->amount = 9.99;

$resultAdvancedCapture = self::$sparrow->AdvancedCapture($paramsAdvancedCapture)->wait();

RESULT SimpleAuthorization:

$resultSimpleAuthorization.isSuccess;    // 1
$resultSimpleAuthorization.status;    // 200
$resultSimpleAuthorization.response;    // 1
$resultSimpleAuthorization.textResponse;    // SUCCESS
$resultSimpleAuthorization.transId;    // 11285011
$resultSimpleAuthorization.xRef;    // 3923167234
$resultSimpleAuthorization.authCode;    // 123456
$resultSimpleAuthorization.type;    // auth
$resultSimpleAuthorization.codeResponse;    // 100
$resultSimpleAuthorization.codeDescription;    // Transaction was Approved

RESULT AdvancedCapture:

$resultAdvancedCapture.isSuccess;    // 1
$resultAdvancedCapture.status;    // 200
$resultAdvancedCapture.response;    // 1
$resultAdvancedCapture.textResponse;    // SUCCESS
$resultAdvancedCapture.transId;    // 11285011
$resultAdvancedCapture.xRef;    // 3923167234
$resultAdvancedCapture.authCode;    // 123456
$resultAdvancedCapture.type;    // capture
$resultAdvancedCapture.codeResponse;    // 100
$resultAdvancedCapture.codeDescription;    // Transaction was Approved

Issuing a Refund

Transaction refunds will perform either a full or partial refund of an already settled transaction. If the transaction has not need settled, it must be voided instead.

Simple Refund

Variable Name Format Description
transtype refund Refund
mkey Secured merchant account key
transid Original payment gateway transaction ID
amount d.dd Total amount to be refunded

transtype=refund&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transid=12345678&amount=3.95

Command Line:

curl -d "transtype=refund&\
mkey=$M_KEY&\
transid=10750794&\
amount=9.95" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Flagged+for+Review+by+Velocity+and+Duplicates+Policy+(Duplicate+Transactions+Rule).+Original+Transaction+ID%3a+10750789&
transid=10750794&
xref=3829708623&
authcode=123456&
orderid=&
type=refund&
avsresponse=&
cvvresponse=M&
coderesponse=&
codedescription=&
status=300&
origtransid=10750789&
origresponse=1&
origtextresponse=SUCCESS

CODE:

var resultSimpleSale = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);
var result = await _sparrow.SimpleRefund(
    transId: resultSimpleSale.TransId,
    amount: 9.99m);

RESULT SimpleSale:

resultSimpleSale.Status;    // 200
resultSimpleSale.Response;    // 1
resultSimpleSale.TextResponse;    // SUCCESS
resultSimpleSale.TransId;    // 11032432
resultSimpleSale.XRef;    // 3876731707
resultSimpleSale.AuthCode;    // 123456
resultSimpleSale.Type;    // sale
resultSimpleSale.CodeResponse;    // 100
resultSimpleSale.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032432
result.XRef;    // 3876731707
result.AuthCode;    // 123456
result.Type;    // refund
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.sale(10.0, card)
transid = resp["transid"]
amount = 10.0
resp = sprw.refund(transid, amount)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150419",
    "type": "refund",
    "xref": "3900992367"
}

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

$paramsSimpleRefund = new SimpleRefundParams();
$paramsSimpleRefund->transId = $resultSimpleSale->transId;
$paramsSimpleRefund->amount = 9.99;

$resultSimpleRefund = self::$sparrow->SimpleRefund($paramsSimpleRefund)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11285000
$resultSimpleSale.xRef;    // 3923166758
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

RESULT SimpleRefund:

$resultSimpleRefund.isSuccess;    // 1
$resultSimpleRefund.status;    // 200
$resultSimpleRefund.response;    // 1
$resultSimpleRefund.textResponse;    // SUCCESS
$resultSimpleRefund.transId;    // 11285000
$resultSimpleRefund.xRef;    // 3923166758
$resultSimpleRefund.authCode;    // 123456
$resultSimpleRefund.type;    // refund
$resultSimpleRefund.codeResponse;    // 100
$resultSimpleRefund.codeDescription;    // Transaction was Approved

Advanced Refund

Variable Name Format Description
transtype refund Refund
mkey Secured merchant account key
transid Original payment gateway transaction ID
amount d.dd Total amount to be refunded
opt_amount_type_# tip/surcharge Type of additional amount
opt_amount_value_# Value of additional amount (1.00)
sendtransreceipttobillemail true/false If true a receipt will be sent to the email provided in the billing information if email is specified
sendtransreceipttoshipemail true/false If true a receipt will be sent to the email provided in the shipping information if email is specified
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.
transtype=refund&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transid=12345678&amount=12.00&sendtransreceipttoemails=John.Smith@email.com

Command Line:

curl -d "transtype=refund&\
mkey=$M_KEY&\
transid=10750789&\
amount=9.95&\
sendtransreceipttobillemail=true&\
sendtransreceipttoshipemail=true&\
sendtransreceipttoemails=email@email.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750789&
xref=3829708545&
authcode=123456&
orderid=&
type=refund&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var resultSimpleSale = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);
var result = await _sparrow.AdvancedRefund(
    transId: resultSimpleSale.TransId,
    amount: 9.99m);

RESULT SimpleSale:

resultSimpleSale.Status;    // 200
resultSimpleSale.Response;    // 1
resultSimpleSale.TextResponse;    // SUCCESS
resultSimpleSale.TransId;    // 11032433
resultSimpleSale.XRef;    // 3876731759
resultSimpleSale.AuthCode;    // 123456
resultSimpleSale.Type;    // sale
resultSimpleSale.CodeResponse;    // 100
resultSimpleSale.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032433
result.XRef;    // 3876731759
result.AuthCode;    // 123456
result.Type;    // refund
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.refund({
  transid: '10750789',
  amount: '9.95',
  sendtransreceipttobillemail: 'true',
  sendtransreceipttoshipemail: 'true',
  sendtransreceipttoemails: 'email@email.com',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '10750789'
result.xref # => '3829708545'
result.authcode # => '123456'
result.orderid # => ''
result.type # => 'refund'
result.avsresponse # => ''
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.sale(10.0, card)
transid = resp["transid"]
amount = 10.0
resp = sprw.refund(
    transid, amount,
    send_receipt_to_billing_email=True,
    send_receipt_to_shipping_email=True,
    send_receipt_to=["noreply@sparrowone.com"]
)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150439",
    "type": "refund",
    "xref": "3900996167"
}

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

$paramsAdvancedRefund = new AdvancedRefundParams();
$paramsAdvancedRefund->transId = $resultSimpleSale->transId;
$paramsAdvancedRefund->amount = 9.99;

$resultAdvancedRefund = self::$sparrow->AdvancedRefund($paramsAdvancedRefund)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11285003
$resultSimpleSale.xRef;    // 3923166850
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

RESULT AdvancedRefund:

$resultAdvancedRefund.status;    // 300
$resultAdvancedRefund.response;    // 3
$resultAdvancedRefund.textResponse;    // Flagged for Review by Velocity and Duplicates Policy (Duplicate Transactions Rule). Original Transaction ID: 11285000
$resultAdvancedRefund.transId;    // 11285003
$resultAdvancedRefund.xRef;    // 3923166850
$resultAdvancedRefund.authCode;    // 123456
$resultAdvancedRefund.type;    // refund
$resultAdvancedRefund.origTransId;    // 11285000
$resultAdvancedRefund.origResponse;    // 1
$resultAdvancedRefund.origTextResponse;    // SUCCESS

Issuing a Void

Transaction voids will cancel an existing sale, authorization or capture on the same day that the original transaction was processed. Voids can only occur if the transaction has not been settled.

If the transaction has been settled, a refund must be issued.

Simple Void

Variable Name Format Description
transtype void Void
mkey Secured merchant account key
transid Original payment gateway transaction ID
transtype=void&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transid=12345678

Command Line:

curl -d "transtype=void&\
mkey=$M_KEY&\
transid=10750790&\
amount=9.95" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Transaction+Void+Successful&
transid=10750790&
xref=3829708544&
authcode=123456&
orderid=&
type=void&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var resultSimpleSale = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);
var result = await _sparrow.SimpleVoid(
    transId: resultSimpleSale.TransId);

RESULT SimpleSale:

resultSimpleSale.Status;    // 200
resultSimpleSale.Response;    // 1
resultSimpleSale.TextResponse;    // SUCCESS
resultSimpleSale.TransId;    // 11032436
resultSimpleSale.XRef;    // 3876731838
resultSimpleSale.AuthCode;    // 123456
resultSimpleSale.Type;    // sale
resultSimpleSale.CodeResponse;    // 100
resultSimpleSale.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // Transaction Void Successful
result.TransId;    // 11032436
result.XRef;    // 3876731838
result.AuthCode;    // 123456
result.Type;    // void
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.void({
  transid: '12345678',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Transaction Void Successful'
result.transid # => '10750790'
result.xref # => '3829708544'
result.authcode # => '123456'
result.orderid # => ''
result.type # => 'void'
result.avsresponse # => ''
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.sale(10.0, card)
transid = resp["transid"]
amount = 10.0
resp = sprw.void(transid, amount)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "Transaction Void Successful",
    "transid": "11150449",
    "type": "void",
    "xref": "3900997132"
}

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

$paramsSimpleVoid = new SimpleVoidParams();
$paramsSimpleVoid->transId = $resultSimpleSale->transId;

$resultSimpleVoid = self::$sparrow->SimpleVoid($paramsSimpleVoid)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11285005
$resultSimpleSale.xRef;    // 3923166943
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

RESULT SimpleVoid:

$resultSimpleVoid.isSuccess;    // 1
$resultSimpleVoid.status;    // 200
$resultSimpleVoid.response;    // 1
$resultSimpleVoid.textResponse;    // Transaction Void Successful
$resultSimpleVoid.transId;    // 11285005
$resultSimpleVoid.xRef;    // 3923166943
$resultSimpleVoid.authCode;    // 123456
$resultSimpleVoid.type;    // void
$resultSimpleVoid.codeResponse;    // 100
$resultSimpleVoid.codeDescription;    // Transaction was Approved

Advanced Void

Variable Name Format Description
transtype void Void
mkey Secured merchant account key
transid Original payment gateway transaction ID
sendtransreceipttobillemail true/false If true a receipt will be sent to the email provided in the billing information if email is specified
sendtransreceipttoshipemail true/false If true a receipt will be sent to the email provided in the shipping information if email is specified
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.
transtype=void&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transid=12345678&sendtransreceipttoemails=John.Smith@email.com

Command Line:

curl -d "transtype=void&\
mkey=$M_KEY&\
transid=10750800&\
sendtransreceipttobillemail=true&\
sendtransreceipttoshipemail=true&\
sendtransreceipttoemails=email@email.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Transaction+Void+Successful&
transid=10750800&
xref=3829708562&
authcode=123456&
orderid=&
type=void&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var resultSimpleSale = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);
var result = await _sparrow.AdvancedVoid(
    transId: resultSimpleSale.TransId);

RESULT SimpleSale:

resultSimpleSale.Status;    // 200
resultSimpleSale.Response;    // 1
resultSimpleSale.TextResponse;    // SUCCESS
resultSimpleSale.TransId;    // 11032435
resultSimpleSale.XRef;    // 3876731796
resultSimpleSale.AuthCode;    // 123456
resultSimpleSale.Type;    // sale
resultSimpleSale.CodeResponse;    // 100
resultSimpleSale.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // Transaction Void Successful
result.TransId;    // 11032435
result.XRef;    // 3876731796
result.AuthCode;    // 123456
result.Type;    // void
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.sale(10.0, card)
transid = resp["transid"]
amount = 10.0
resp = sprw.void(
    transid, amount,
    send_receipt_to_billing_email=True,
    send_receipt_to_shipping_email=True,
    send_receipt_to=["noreply@sparrowone.com"]
)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "Transaction Void Successful",
    "transid": "11150452",
    "type": "void",
    "xref": "3900997234"
}

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

$paramsAdvancedVoid = new AdvancedVoidParams();
$paramsAdvancedVoid->transId = $resultSimpleSale->transId;

$resultAdvancedVoid = self::$sparrow->AdvancedVoid($paramsAdvancedVoid)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11285004
$resultSimpleSale.xRef;    // 3923166885
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

RESULT AdvancedVoid:

$resultAdvancedVoid.isSuccess;    // 1
$resultAdvancedVoid.status;    // 200
$resultAdvancedVoid.response;    // 1
$resultAdvancedVoid.textResponse;    // Transaction Void Successful
$resultAdvancedVoid.transId;    // 11285004
$resultAdvancedVoid.xRef;    // 3923166885
$resultAdvancedVoid.authCode;    // 123456
$resultAdvancedVoid.type;    // void
$resultAdvancedVoid.codeResponse;    // 100
$resultAdvancedVoid.codeDescription;    // Transaction was Approved

Creating a Credit

Transaction credits apply a positive amount to a cardholder’s card. Unlike a refund, a credit is not associated with an original sale transaction.

Get Transaction Details

The Inquiry operation returns transaction details

Inquiry Operation

VariableName Format Description
transtype inquiry Indicate operation type
mkey alphanumeric Secured merchant account key
transid numeric Transaction ID

Response from the gateway will be as follows:

VariableName Format Description
transid numeric Transaction ID
transtatus Not Processed / Declined / Pending Capture / Approved / Refunded / Canceled / Internal Error / Transaction Failed / Failed / Flagged For Review / Dispute Transaction status
textresponse alphanumeric Original textresponse of the last operation
transtatuschangeddate MM/DD/YYYY HH:MM:SS AM/PM Date and time of the transaction status change
amount d.dd Total amount to be charged
currency CCC (ISO 4217 alphabetic code) Code of the payment currency
xref string External transaction ID from the payment processor
authcode string Auth code received from the issuer
avsresponse C AVS Response Code
cvvresponse C CVV Response Code

transtype=inquiry&mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transid=1234567

Expected Response

textresponse=Transaction+Void+Successful&transid=1234567&xref=1979829668&authcode=123456&avsresponse=Y&cvvresponse=M&transtatus=Canceled&transtatuschangeddate=2%2f3%2f2018+2%3a18%3a31+PM&currency=USD&amount=0.00
No content for this section.

Airline Passenger Sale

Through our integration with the Airline Reporting Corporation (ARC) we have the ability to offer Airline Passenger Sales.

Passenger sales run similarly to traditional sale, auth and capture but all passenger transactions are batched and executed each night via a separate settlement operation.

Passenger Sale

Variable Name Format Description
transtype passengersale Transaction Sale
mkey secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019
amount d.dd Total amount to be charged (ie. 10.00)
cvv Card security code
passengername [a-z, A-Z, 0-9, ‘ ’] First and last name of the passenger, 1-20 characters
stopovercode1 stopovercode2 stopovercode3 stopovercode4 stopovercode5 ‘ ’, ‘O’, ‘X’
airportcode1 [a-z, A-Z, 0-9] Origination Airport Code, 3 characters
airportcode2 airportcode3 airportcode4 airportcode5 [a-z, A-Z, 0-9] Codes for different trip legs, 3 characters
carriercoupon1 carriercoupon2 carriercoupon3 carriercoupon4 [a-z, A-Z, 0-9] 2 characters
airlinecodenumber [a-z, A-Z, 0-9] 3 characters
ticketnumber [0-9] 10 characters
classofservicecoupon1 classofservicecoupon2 classofservicecoupon3 classofservicecoupon4 [a-z, A-Z, 0-9] 1 or 2 characters
flightdatecoupon1 MM/DD/YYYY Departure date
flightdeparturetimecoupon1 HH:mm (military) Departure time
addressverificationcode [a-z, A-Z, 0-9] 1 character
approvalcode [a-z, A-Z, 0-9] 6 characters
transactionid [a-z, A-Z, 0-9] The field must be forwarded when sent from TSYS, or manually filled with zeros. 15 characters
authcharindicator supported values: ‘ ’, ‘A’, ‘E’, ‘F’, ‘I’, ‘C’, ‘K’, ‘M’, ‘N’, ‘P’, ‘R’, ‘S’, ‘T’, ‘U’, ‘V’, ‘W’ Used as Returned Authorization Characteristics Indicator. Must contain the value returned in authorization response (ic case of online auth)
referencenumber [a-z, A-Z, 0-9] 12 characters
validationcode [a-z, A-Z, 0-9] 4 characters
authresponsecode [a-zA-Z0-9 ] or two spaces 2 characters

Example

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
cvv=999&\
passengername=John Doe&\
stopovercode1=O&\
airportcode1=LAS&\
airportcode2=CDG&\
airportcode3=IAD&\
airportcode4=CPH&\
carriercoupon1 carriercoupon2 carriercoupon3 carriercoupon4=AA;BB&\
airlinecodenumber=AA0&\
ticketnumber=1234567890&\
classofservicecoupon1 classofservicecoupon2 classofservicecoupon3 classofservicecoupon4=00;AA&\
flightdatecoupon1=01/31/2017&\
flightdeparturetimecoupon1=23:59&\
addressverificationcode=A&\
approvalcode=123456&\
transactionid=1234567890&\
authcharindicator=A&\
referencenumber=123456789012&\
validationcode=1234&\
authresponsecode=AB" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750803&
xref=3829708653&
authcode=123456&
orderid=&
type=sale&
avsresponse=&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.PassengerSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m,
    passengerName: "John Doe",
    airportCodes: new []{ "" },
    airlineCodeNumber: "AA0",
    ticketNumber: "1234567890",
    flightDateCoupons: new []{ new DateTime(2019,10,21) },
    flightDepartureTimeCoupons: new []{ "" },
    approvalCode: "123456",
    authCharIndicator: Sparrow.AuthCharIndicator.A,
    validationCode: "1234",
    authResponseCode: "AB");

RESULT:

result.Status;    // 500
result.Response;    // 3
result.TextResponse;    // Operation type is not supported by payment processor
result.Type;    // passengersale

CODE:


api.passenger_sale({
  cardnum: '4111111111111111',
  cardexp: '1019',
  amount: '9.95',
  cvv: '999',
  passengername: 'John Doe',
  stopovercode1: 'O',
  airportcode1: 'LAS',
  airportcode2: 'CDG',
  airportcode3: 'IAD',
  airportcode4: 'CPH',
  carriercoupon4: 'AA;BB',
  airlinecodenumber: 'AA0',
  ticketnumber: '1234567890',
  classofservicecoupon4: '00;AA',
  flightdatecoupon1: '01/31/2017',
  flightdeparturetimecoupon1: '23:59',
  addressverificationcode: 'A',
  approvalcode: '123456',
  transactionid: '1234567890',
  authcharindicator: 'A',
  referencenumber: '123456789012',
  validationcode: '1234',
  authresponsecode: 'AB',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '10750803'
result.xref # => '3829708653'
result.authcode # => '123456'
result.orderid # => ''
result.type # => 'sale'
result.avsresponse # => ''
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


sale = sparrowone.SaleInfo(
    amount=9.95,
    airportcode1="LAS",
    airportcode2="CDG",
    airportcode3="IAD",
    airportcode4="CPH",
    ticketnumber=1234567890,
    flightdatecoupon1="01/31/2017",
    flightdeparturetimecoupon1="23:59",
    addressverificationcode="A",
    approvalcode=123456,
    transactionid=1234567890,
    authcharindicator="A",
    referencenumber=123456789012,
    validationcode=1234,
    authresponsecode="AB",
)

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999",
)

resp = sprw.sale(sale, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11188178",
    "type": "sale",
    "xref": "3907193949"
}

CODE:

$paramsPassengerSale = new PassengerSaleParams();
$paramsPassengerSale->creditCard->cardNum = "4111111111111111";
$paramsPassengerSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsPassengerSale->amount = 9.99;
$paramsPassengerSale->passengerName = "John Doe";
$paramsPassengerSale->airportCodes[0] = "";
$paramsPassengerSale->airlineCodeNumber = "AA0";
$paramsPassengerSale->ticketNumber = "1234567890";
$paramsPassengerSale->flightDateCoupons[0] = new DateTime("2019-10-21");
$paramsPassengerSale->flightDepartureTimeCoupons[0] = "";
$paramsPassengerSale->approvalCode = "123456";
$paramsPassengerSale->authCharIndicator = AuthCharIndicator::A;
$paramsPassengerSale->validationCode = "1234";
$paramsPassengerSale->authResponseCode = "AB";

$resultPassengerSale = self::$sparrow->PassengerSale($paramsPassengerSale)->wait();

RESULT PassengerSale:

$resultPassengerSale.status;    // 500
$resultPassengerSale.response;    // 3
$resultPassengerSale.textResponse;    // Operation type is not supported by payment processor
$resultPassengerSale.type;    // passengersale

Military Star Card

The Military Star Card is a private-label line of credit offered by the Military Exchange Credit Service and managed by the Army and Air Force Exchange Service.

Simple Star Card

Variable Name Format Description
transtype sale Transaction sale
mkey Secured merchant account key
cardnum​ Card number
amount d.dd Total amount to be refunded
CID Custom Field 11 digit numerical code
transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&cardnum=6019440000011111&amount=20.00&CID=52347800001

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
amount=9.95&\
cardexp=1019&\
CID=12345678901" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750791&
xref=3829708548&
authcode=123456&
orderid=&
type=sale&
avsresponse=&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.SimpleStarCard(
    cardNum: "4111111111111111",
    amount: 9.99m,
    CID: "12345678901");

RESULT:

result.Status;    // 400
result.TextResponse;    // System Error: Reason Code: 002 CID value is invalid or non existant
result.TransId;    // 11032442
result.Type;    // sale
result.CodeDescription;    // Denied

CODE:


card = sparrowone.MilitaryStarCard(
    number="4111111111111111",
    expiration="1019",
    cid="12345678901"
)
resp = sprw.sale(10.0, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150551",
    "type": "sale",
    "xref": "3901013600"
}

CODE:

$paramsSimpleStarCard = new SimpleStarCardParams();
$paramsSimpleStarCard->cardNum = "4111111111111111";
$paramsSimpleStarCard->amount = 9.99;
$paramsSimpleStarCard->CID = "12345678901";

$resultSimpleStarCard = self::$sparrow->SimpleStarCard($paramsSimpleStarCard)->wait();

RESULT SimpleStarCard:

$resultSimpleStarCard.status;    // 401
$resultSimpleStarCard.textResponse;    // System Error: Reason Code: 000 Empty CID field/No CID provided, unable to verify transaction
$resultSimpleStarCard.transId;    // 11285016
$resultSimpleStarCard.type;    // sale
$resultSimpleStarCard.codeDescription;    // Error

Advanced Star Card

Variable Name Format Description
transtype sale Transaction Sale
mkey secured merchant account key
cardnum Credit card number
amount d.dd Total amount to be charged (ie. 10.00)
CID custom field 11 digit numerical code
currency CCC (ISO 4217 alphabetic code) Code of the payment currency. If currency is not specified, the default currency (USD) is assumed.
firstname Billing first name
lastname Billing last name
skunumber_# SKU number of the product being purchased (skunumber_1, skunumber_2, etc)
description_# Description of the product being purchased
amount_# Price of the single unit of a product being purchased
quantity_# Number of units of a product being purchased
orderdesc Order Description
orderid Order ID
cardipaddress ddd.ddd.ddd.ddd IP address of the customer, can be used for fraud prevention in FBI Tools
tax d.dd Total tax amount
shipamount d.dd Total shipping amount
ponumber Original Purchase Order
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
phone Billing phone number
fax Billing fax number
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=57.85&cardnum=6019440000011111&CID=12345678911&cvv=999&skunumber_1=5558779&description_1=menssweaterblue&amount_1=50.00&quantity_1=1&tax=2.85&shipamount=5.00&firstname=John&lastname=Smith&address1=888+test+address&city=Los+Angeles&country=US&state=CA&phone=222-444-2938&shipfirstname=John&shiplastname=Smith&shipaddress1=888+test+address&shipcity=Los+Angeles&shipstate=CA&shipphone=2224442938

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
CID=12345678901&\
currency=USD&\
firstname=John&\
lastname=Doe&\
skunumber_1=123&\
skunumber_2=456&\
description_1=Blue widget&\
description_2=Brown widget&\
amount_1=1.99&\
amount_2=2.99&\
quantity_1=1&\
quantity_2=2&\
orderdesc=Order Description&\
orderid=11111&\
cardipaddress=8.8.8.8&\
tax=0.25&\
shipamount=1.25&\
ponumber=22222&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750808&
xref=3829708587&
authcode=123456&
orderid=11111&
type=sale&
avsresponse=N&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.AdvancedStarCard(
    cardNum: "4111111111111111",
    cardExp: new DateTime(2019,10,21),
    amount: 9.99m,
    CID: "12345678901");

RESULT:

result.Status;    // 400
result.TextResponse;    // System Error: Reason Code: 002 CID value is invalid or non existant
result.TransId;    // 11032441
result.Type;    // sale
result.CodeDescription;    // Denied

CODE:


sale = sparrowone.SaleInfo(
    amount=7.96,
    currency="USD",
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
    ),
    ship_to=sparrowone.Contact(
        first_name="Julianne",
        last_name="Stingray",
        address1="16100 N 72nd Street",
        address2="Suite 171",
        city="Glitch City",
        zip="220000",
        country="XX",
        email="noreply@sparrowone.com",
    ),
    products=[
        sparrowone.Product(
            skunumber=1999,
            description="Blue whale",
            amount=1.99,
            quantity=4
        )
    ],
    ip_addr="192.168.12.34",
)
card = sparrowone.MilitaryStarCard(
    number="4111111111111111",
    expiration="1019",
    cid="12345678901"
)
resp = sprw.sale(sale, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150550",
    "type": "sale",
    "xref": "3901013550"
}

CODE:

$paramsAdvancedStarCard = new AdvancedStarCardParams();
$paramsAdvancedStarCard->cardNum = "4111111111111111";
$paramsAdvancedStarCard->cardExp = new DateTime("2019-10-21");
$paramsAdvancedStarCard->amount = 9.99;
$paramsAdvancedStarCard->CID = "12345678901";

$resultAdvancedStarCard = self::$sparrow->AdvancedStarCard($paramsAdvancedStarCard)->wait();

RESULT AdvancedStarCard:

$resultAdvancedStarCard.status;    // 401
$resultAdvancedStarCard.textResponse;    // System Error: Reason Code: 000 Empty CID field/No CID provided, unable to verify transaction
$resultAdvancedStarCard.transId;    // 11285015
$resultAdvancedStarCard.type;    // sale
$resultAdvancedStarCard.codeDescription;    // Error

ACH and eCheck

Automated Clearing House (ACH) is an electronic network for financial transactions in the United States. ACH allows merchants to debit and credit funds directly to and from client’s banks accounts.

ACH/ eCheck Test Transaction Information

Bank name: First Test Bank

Routing number: 110000000

Account number: 1234567890123 / 3210987654321

Account type: P / B

Simple ACH

VariableName Format Description
transtype sale/ refund/ credit sale- transaction sale, refund- transaction refund, credit- transaction credit
mkey Secured merchant account key
bankname​ Customers bank name
routing Customers bank routing number
account Customers bank account number
achaccounttype checking/savings Customers type of bank account
achaccountsubtype business/personal Customers type of bank account
amount d.dd Total amount to be charged
company Billing Company

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=123456789&account=11111999&achaccounttype=checking&achaccountsubtype=personal

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=123456789&account=11111999&achaccounttype=checking&achaccountsubtype=business&company=CompanyName

Command Line:

curl -d "transtype=sale&\
mkey=$ACH_M_KEY&\
bankname=First Test Bank&\
routing=110000000&\
account=1234567890123&\
achaccounttype=checking&\
achaccountsubtype=personal&\
amount=9.95&\
firstname=John&\
lastname=Doe" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=00&
textresponse=SUCCESS&
transid=10750797&
xref=3829708697&
authcode=123456&
orderid=&
type=sale&
avsresponse=&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.SimpleACH(
    bankAccount: new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal },
    amount: 9.99m,
    contactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" });

RESULT:

result.Status;    // 200
result.TextResponse;    // SUCCESS
result.TransId;    // 11032420
result.XRef;    // 3876731380
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.sale({
  bankname: 'First Test Bank',
  routing: '110000000',
  account: '1234567890123',
  achaccounttype: 'checking',
  achaccountsubtype: 'personal',
  amount: '9.95',
  firstname: 'John',
  lastname: 'Doe"',
})

RESULT:



result.response # => '00'
result.textresponse # => 'SUCCESS'
result.transid # => '11037938'
result.xref # => '3877926141'
result.authcode # => '123456'
result.type # => 'sale'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


sale = sparrowone.SaleInfo(
    amount=7.95,
    billing_contact=sparrowone.Contact(
        first_name="Gillian",
        last_name="Fenimore",
    ),
)

ach_account = sparrowone.ACHInfo(
    bank_name="First Test Bank",
    routing="110000000",
    account="1234567890123",
    type="checking",
    subtype="personal",
)
resp = sprw.sale(sale, ach_account)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "00",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150237",
    "type": "sale",
    "xref": "3900968815"
}

CODE:

$paramsSimpleACH = new SimpleACHParams();
$paramsSimpleACH->bankAccount->bankName = "First Test Bank";
$paramsSimpleACH->bankAccount->routing = "110000000";
$paramsSimpleACH->bankAccount->account = "1234567890123";
$paramsSimpleACH->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsSimpleACH->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsSimpleACH->amount = 9.99;
$paramsSimpleACH->contactInfo->firstName = "John";
$paramsSimpleACH->contactInfo->lastName = "Doe";

$resultSimpleACH = self::$sparrow->SimpleACH($paramsSimpleACH)->wait();

RESULT SimpleACH:

$resultSimpleACH.isSuccess;    // 1
$resultSimpleACH.status;    // 200
$resultSimpleACH.textResponse;    // SUCCESS
$resultSimpleACH.transId;    // 11284983
$resultSimpleACH.xRef;    // 3923165784
$resultSimpleACH.authCode;    // 123456
$resultSimpleACH.type;    // sale
$resultSimpleACH.codeResponse;    // 100
$resultSimpleACH.codeDescription;    // Transaction was Approved

Advanced ACH

VariableName Format Description
transtype sale/ refund/ credit sale- transaction sale, refund- transaction refund, credit- transaction credit
mkey Secured merchant account key
bankname​ Customers bank name
routing Customers bank routing number
account Customers bank account number
achaccounttype checking/savings Customers type of bank account
achaccountsubtype business/personal Customers type of bank account
amount d.dd Total amount to be charged
orderdesc Order Description
orderid Order ID
firstname Billing first name, should be from 1-100 characters
lastname Billing last name, should be from 1-100 characters
company Billing Company
address1 Billing address. Should be from 1-200 alpha-numeric characters and can include # - : ;
address2 Billing address - line 2. Should be from 1-200 alpha-numeric characters and can include # - : ;
city Billing city, should be 1-50 alpha characters
state Billing state (2 character abbreviation)
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country cc Billing country (ie. US)
phone Billing phone number, 10 digits
email Billing email address
shipfirstname Shipping first name, should be from 1-100 characters. Required for PayPal processor if shipping address is entered.
shiplastname Shipping last name, should be from 1-100 characters. Required for PayPal processor if shipping address is entered.
shipcompany Shipping company
shipaddress1 Shipping address. Should be from 1-200 alpha-numeric characters and can include # - : ;
shipaddress2 Shipping address - line 2. Should be from 1-200 alpha-numeric characters and can include # - : ;
shipcity Shipping city, should be 1-50 alpha characters
shipstate Shipping state, 2 character abbreviation
shipzip Shipping postal code. If the country is US the zip code format must be: [5 digits: XXXXX] or [9 digits XXXXX-XXXX]
shipcountry cc Shipping country (ie. US)
shipphone Shipping phone number, 10 digits
shipemail Shipping email
saveclient true/false If parameter 'saveclient' = true and the customer is identified as new, then a new Data Vault client will be created with payment/contact info from the transaction data and DV token will be generated. The payment transaction will be assigned to this new DV client.
updateclient If the parameter 'updateclient' = true and the DataVault finds the client according to customer identification rules, then the payment transaction will be assigned to the DataVault client and the DataVault client payment/contact info will be updated according to the transaction's data.
opt_amount_type_# tip Type of additional amount (tip)
opt_amount_value_# d.dd Value of the additional amount (10.00)
opt_amount_percentage_# Percentage of additional amount (20)
birthdate MM/DD/YYYY Birthdate of the customer
checknumber Check number. 1-15 alphanumeric characters
driverlicensenumber Drivers license number, 1-50 alphanumeric characters
driverlicensecountry cc Drivers license country
driverlicensestate cc Drivers license state
courtesycardid [a-z, A-Z, 0-9] This field is optional only for GETI ACH, for other processors can be ignored. From 1 to 50 characters.
sendtransreceipttobillemail true/false If true, this will send a transaction receipt to the billing email if present
sendtransreceipttoshipemail true/false If true, this will send a transaction receipt to the shipping email if present
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=123456789&account=11111999&achaccounttype=checking&achaccountsubtype=personal&firstname=Henry&lastname=Johnson&phone=8526547896&email=hjohnson@test.com

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=123456789&account=11111999&achaccounttype=checking&achaccountsubtype=business&company=CompanyName&firstname=Henry&lastname=Johnson&phone=8526547896&email=hjohnson@test.com

Command Line:

curl -d "transtype=sale&\
mkey=$ACH_M_KEY&\
bankname=First Test Bank&\
routing=110000000&\
account=1234567890123&\
achaccounttype=checking&\
achaccountsubtype=personal&\
amount=9.95&\
orderdesc=Order Description&\
orderid=11111&\
firstname=John&\
lastname=Doe&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
phone=7025551234&\
email=john@norepy.com&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com&\
saveclient=true&\
updateclient=true&\
opt_amount_type_1=surcharge&\
opt_amount_value_1=1.01&\
opt_amount_percentage_1=18&\
birthdate=01/31/2000&\
checknumber=123&\
driverlicensenumber=1234567890&\
driverlicensecountry=US&\
driverlicensestate=AZ&\
sendtransreceipttobillemail=true&\
sendtransreceipttoshipemail=true&\
paymentdescriptor=Custom Payment Descriptor" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=00&
textresponse=SUCCESS%2c+Customer+with+token+%27I07IO05HGP0NXIQM%27+successfully+updated%2c+Payment+transaction+successfully+assigned+to+the+customer+with+token+%27I07IO05HGP0NXIQM%27&
transid=10750811&
xref=3829708723&
authcode=123456&
orderid=11111&
type=sale&
avsresponse=&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200&
token=I07IO05HGP0NXIQM

CODE:

var result = await _sparrow.AdvancedACH(
    bankAccount: new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal },
    amount: 9.99m,
    contactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" });

RESULT:

result.Status;    // 200
result.TextResponse;    // SUCCESS
result.TransId;    // 11032419
result.XRef;    // 3876731375
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:

api.sale({
  bankname: 'First Test Bank',
  routing: '110000000',
  account: '1234567890123',
  achaccounttype: 'checking',
  achaccountsubtype: 'personal',
  amount: '9.95',
  orderdesc: 'Order Description',
  orderid: '11111',
  firstname: 'John',
  lastname: 'Doe',
  company: 'Sparrow One',
  address1: '16100 N 71st Street',
  address2: 'Suite 170',
  city: 'Scottsdale',
  state: 'AZ',
  zip: '85254',
  country: 'US',
  phone: '7025551234',
  email: 'john@norepy.com',
  shipaddress1: '16100 N 72nd Street',
  shipaddress2: 'Suite 171',
  shipcity: 'Pheonix',
  shipstate: 'AZ',
  shipzip: '85004',
  shipcountry: 'US',
  shipphone: '6025551234',
  shipemail: 'jane@noreply.com',
  saveclient: 'true',
  updateclient: 'true',
  opt_amount_type_1: 'surcharge',
  opt_amount_value_1: '1.01',
  opt_amount_percentage_1: '18',
  birthdate: '01/31/2000',
  checknumber: '123',
  driverlicensenumber: '1234567890',
  driverlicensecountry: 'US',
  driverlicensestate: 'AZ',
  sendtransreceipttobillemail: 'true',
  sendtransreceipttoshipemail: 'true',
  paymentdescriptor: 'Custom Payment Descriptor',
})

RESULT:

result.response # => '00'
result.textresponse # => 'SUCCESS, Customer with token 'LS8W4RO5S7SZKZCN' successfully updated, Payment transaction successfully assigned to the customer with token 'LS8W4RO5S7SZKZCN''
result.transid # => '11037939'
result.xref # => '3877926149'
result.authcode # => '123456'
result.orderid # => '11111'
result.type # => 'sale'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'
result.token # => 'LS8W4RO5S7SZKZCN'

CODE:

sale = sparrowone.SaleInfo(
    amount=9.95,
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
    ),
    ship_to=sparrowone.Contact(
        first_name="Julianne",
        last_name="Stingray",
        address1="16100 N 72nd Street",
        address2="Suite 171",
        city="Glitch City",
        zip="220000",
        country="XX",
        email="noreply@sparrowone.com",
    ),
    products=[
        sparrowone.Product(skunumber=1999,
                        description="Blue whale",
                        amount=1.99,
                        quantity=4)
    ],
    ip_addr="192.168.12.34",
)
ach_account = sparrowone.ACHInfo(
    bank_name="First Test Bank",
    routing="110000000",
    account="1234567890123",
    type="checking",
    subtype="personal",
)
resp = sprw.sale(sale, ach_account)

RESULT:

{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "00",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150236",
    "type": "sale",
    "xref": "3900968778"
}

$$language: php$$ CODE:

$paramsAdvancedACH = new AdvancedACHParams();
$paramsAdvancedACH->bankAccount->bankName = "First Test Bank";
$paramsAdvancedACH->bankAccount->routing = "110000000";
$paramsAdvancedACH->bankAccount->account = "1234567890123";
$paramsAdvancedACH->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsAdvancedACH->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsAdvancedACH->amount = 9.99;
$paramsAdvancedACH->contactInfo->firstName = "John";
$paramsAdvancedACH->contactInfo->lastName = "Doe";

$resultAdvancedACH = self::$sparrow->AdvancedACH($paramsAdvancedACH)->wait();

RESULT AdvancedACH:

$resultAdvancedACH.isSuccess;    // 1
$resultAdvancedACH.status;    // 200
$resultAdvancedACH.textResponse;    // SUCCESS
$resultAdvancedACH.transId;    // 11284982
$resultAdvancedACH.xRef;    // 3923165760
$resultAdvancedACH.authCode;    // 123456
$resultAdvancedACH.type;    // sale
$resultAdvancedACH.codeResponse;    // 100
$resultAdvancedACH.codeDescription;    // Transaction was Approved

Simple eCheck

VariableName Format Description
transtype sale/ refund sale- transaction sale, refund- transaction refund
mkey Secured merchant account key
bankname​ Customers bank name
routing Customers bank routing number
account Customers bank account number
achaccounttype business/personal Customers type of eCheck account
amount d.dd Total amount to be charged
company Billing Company
firstname Billing first name
lastname Billing last name
address1 Billing address
city Billing city
state Billing state (2 character abbreviation)
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country cc Billing country (ie. US

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=110000000&account=1234567890123&achaccounttype=personal&firstname=Henry&lastname=Johnson&address1=Main+Street+45&city=Scottsdale&zip=12345&country=US&state=AZ

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=110000000&account=1234567890123&achaccounttype=business&company=CompanyName&firstname=Henry&lastname=Johnson&address1=Main+Street+45&city=Scottsdale&zip=12345&country=US&state=AZ

CODE:

var result = await _sparrow.SimpleECheck(
    bankAccount: new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal }, 
    amount: 9.99m, 
    contactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe", Company = "Sparrow One", Address = new Sparrow.Address{ Address1 = "16100 N 71st Street", City = "Scottsdale", State = "AZ", Zip = "85254", Country = "US" } });

RESULT:

result.Status;    // 200
result.TextResponse;    // SUCCESS
result.TransId;    // 11032421
result.XRef;    // 3876731391
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.sale({
  amount: '9.95',
  bankname: 'BankofAmerica',
  routing: '110000000',
  account: '1234567890123',
  achaccounttype: 'checking',
  achaccountsubtype: 'business',
  company: 'CompanyName',
  firstname: 'Henry',
  lastname: 'Johnson',
  address1: 'Main Street 45',
  city: 'Scottsdale',
  zip: '12345',
  country: 'US',
  state: 'AZ',
})

RESULT:



result.response # => '00'
result.textresponse # => 'SUCCESS'
result.transid # => '11037947'
result.xref # => '3877926400'
result.authcode # => '123456'
result.type # => 'sale'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


sale = sparrowone.SaleInfo(
    amount=7.95,
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
        address1="Main Street 45",
        city="Scottsdale",
        zip="12345",
        country="US",
        state="AZ",
    ),
)

echeck = sparrowone.ECheck(
    bank_name="First Test Bank",
    routing="110000000",
    account="1234567890123",
    type="checking",
    subtype="personal",
)
resp = sprw.sale(sale, echeck)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "00",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150237",
    "type": "sale",
    "xref": "3900968815"
}

CODE:

$paramsSimpleECheck = new SimpleECheckParams();
$paramsSimpleECheck->bankAccount->bankName = "First Test Bank";
$paramsSimpleECheck->bankAccount->routing = "110000000";
$paramsSimpleECheck->bankAccount->account = "1234567890123";
$paramsSimpleECheck->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsSimpleECheck->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsSimpleECheck->amount = 9.99;
$paramsSimpleECheck->contactInfo->firstName = "John";
$paramsSimpleECheck->contactInfo->lastName = "Doe";
$paramsSimpleECheck->contactInfo->company = "Sparrow One";
$paramsSimpleECheck->contactInfo->address->address1 = "16100 N 71st Street";
$paramsSimpleECheck->contactInfo->address->city = "Scottsdale";
$paramsSimpleECheck->contactInfo->address->state = "AZ";
$paramsSimpleECheck->contactInfo->address->zip = "85254";
$paramsSimpleECheck->contactInfo->address->country = "US";

$resultSimpleECheck = self::$sparrow->SimpleECheck($paramsSimpleECheck)->wait();

RESULT SimpleECheck:

$resultSimpleECheck.isSuccess;    // 1
$resultSimpleECheck.status;    // 200
$resultSimpleECheck.textResponse;    // SUCCESS
$resultSimpleECheck.transId;    // 11284984
$resultSimpleECheck.xRef;    // 3923165804
$resultSimpleECheck.authCode;    // 123456
$resultSimpleECheck.type;    // sale
$resultSimpleECheck.codeResponse;    // 100
$resultSimpleECheck.codeDescription;    // Transaction was Approved

Advanced eCheck

VariableName Format Description
transtype sale/ refund/ credit sale- transaction sale, refund- transaction refund, credit- transaction credit
mkey Secured merchant account key
bankname​ Customers bank name
routing Customers bank routing number
account Customers bank account number
achaccounttype business/personal Customers type of eCheck account
amount d.dd Total amount to be charged
firstname Billing first name
lastname Billing last name
company Billing Company
address1 Billing address
city Billing city
state Billing state (2 character abbreviation)
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country cc Billing country (ie. US)
address2 Billing address - line 2
phone Billing phone number, 10 digits
email Billing email address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping address
shipaddress2 Shipping address - line 2
shipcity Shipping city
shipstate Shipping state, 2 character abbreviation
shipzip Shipping postal code. If the country is US the zip code format must be: [5 digits: XXXXX] or [9 digits XXXXX-XXXX]
shipcountry cc Shipping country (ie. US)
shipphone Shipping phone number, 10 digits
shipemail Shipping email
orderdesc Order Description
orderid Order ID
saveclient true/false If parameter 'saveclient' = true and the customer is identified as new, then a new Data Vault client will be created with payment/contact info from the transaction data and DV token will be generated. The payment transaction will be assigned to this new DV client.
updateclient If the parameter 'updateclient' = true and the DataVault finds the client according to customer identification rules, then the payment transaction will be assigned to the DataVault client and the DataVault client payment/contact info will be updated according to the transaction's data.
opt_amount_type_# tip Type of additional amount (tip)
opt_amount_value_# d.dd Value of the additional amount (10.00)
opt_amount_percentage_# Percentage of additional amount (20)
sendtransreceipttobillemail true/false If true, this will send a transaction receipt to the billing email if present
sendtransreceipttoshipemail true/false If true, this will send a transaction receipt to the shipping email if present
sendtransreceipttoemails email@email.com Send multiple transaction receipts to customers. Multiple email must be separated by commas.

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=110000000&account=1234567890123&achaccounttype=personal&firstname=Henry&lastname=Johnson&address1=Main+Street+45&city=Scottsdale&zip=12345&country=US&state=AZ&phone=8526547896&email=hjohnson@test.com

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&bankname=BankofAmerica&routing=110000000&account=1234567890123&achaccounttype=business&company=CompanyName&firstname=Henry&lastname=Johnson&address1=Main+Street+45&city=Scottsdale&zip=12345&country=US&state=AZ&phone=8526547896&email=hjohnson@test.com

CODE:

var result = await _sparrow.AdvancedECheck(
    bankAccount: new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal }, 
    amount: 9.99m, 
    contactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe", Company = "Sparrow One", Address = new Sparrow.Address{ Address1 = "16100 N 71st Street", City = "Scottsdale", State = "AZ", Zip = "85254", Country = "US" } });

RESULT:

result.Status;    // 200
result.TextResponse;    // SUCCESS
result.TransId;    // 11032418
result.XRef;    // 3876731357
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:

api.sale({
  amount: '9.95',
  bankname: 'BankofAmerica',
  routing: '110000000',
  account: '1234567890123',
  achaccounttype: 'checking',
  achaccountsubtype: 'business',
  company: 'CompanyName',
  firstname: 'Henry',
  lastname: 'Johnson',
  address1: 'Main Street 45',
  city: 'Scottsdale',
  zip: '12345',
  country: 'US',
  state: 'AZ',
  phone: '8526547896',
  email: 'hjohnson@test.com',
})

RESULT:

result.response # => '00'
result.textresponse # => 'SUCCESS'
result.transid # => '11037948'
result.xref # => '3877926406'
result.authcode # => '123456'
result.type # => 'sale'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:

sale = sparrowone.SaleInfo(
    amount=9.95,
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
        address1="Main Street 45",
        city="Scottsdale",
        zip="12345",
        country="US",
        state="AZ",
    ),
    ship_to=sparrowone.Contact(
        first_name="Julianne",
        last_name="Stingray",
        address1="16100 N 72nd Street",
        address2="Suite 171",
        city="Glitch City",
        zip="220000",
        country="XX",
        email="noreply@sparrowone.com",
    ),
    products=[
        sparrowone.Product(skunumber=1999,
                           description="Blue whale",
                           amount=1.99,
                           quantity=4)
    ],
    ip_addr="192.168.12.34",
)
ach_account = sparrowone.ECheck(
    bank_name="First Test Bank",
    routing="110000000",
    account="1234567890123",
    type="checking",
    subtype="personal",
)
resp = sprw.sale(sale, ach_account)

RESULT:

{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "00",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150236",
    "type": "sale",
    "xref": "3900968778"
}

$$language: php$$ CODE:

$paramsAdvancedECheck = new AdvancedECheckParams();
$paramsAdvancedECheck->bankAccount->bankName = "First Test Bank";
$paramsAdvancedECheck->bankAccount->routing = "110000000";
$paramsAdvancedECheck->bankAccount->account = "1234567890123";
$paramsAdvancedECheck->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsAdvancedECheck->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsAdvancedECheck->amount = 9.99;
$paramsAdvancedECheck->contactInfo->firstName = "John";
$paramsAdvancedECheck->contactInfo->lastName = "Doe";
$paramsAdvancedECheck->contactInfo->company = "Sparrow One";
$paramsAdvancedECheck->contactInfo->address->address1 = "16100 N 71st Street";
$paramsAdvancedECheck->contactInfo->address->city = "Scottsdale";
$paramsAdvancedECheck->contactInfo->address->state = "AZ";
$paramsAdvancedECheck->contactInfo->address->zip = "85254";
$paramsAdvancedECheck->contactInfo->address->country = "US";

$resultAdvancedECheck = self::$sparrow->AdvancedECheck($paramsAdvancedECheck)->wait();

RESULT AdvancedECheck:

$resultAdvancedECheck.isSuccess;    // 1
$resultAdvancedECheck.status;    // 200
$resultAdvancedECheck.textResponse;    // SUCCESS
$resultAdvancedECheck.transId;    // 11284981
$resultAdvancedECheck.xRef;    // 3923165741
$resultAdvancedECheck.authCode;    // 123456
$resultAdvancedECheck.type;    // sale
$resultAdvancedECheck.codeResponse;    // 100
$resultAdvancedECheck.codeDescription;    // Transaction was Approved

eWallet

An eWallet is a device, website, software system or database which facilitates transactions securely by storing a consumers credit card or bank account within a password protected system.

SPARROW currently supports the PayPal eWallet. eWallet operations can be processed via both the Services API and Checkout API.

  • The Services API can be used to process credit operations only

  • The Checkout API must be used for Sale transactions. The customer must be directed to the PayPal Express Checkout page where they will login to their PayPal account to pay securely

eWallet Simple Credit

VariableName Format Description
transtype credit credit- funds being pushed to the customer
mkey Secured merchant account key
ewalletaccount​ eWallet account credentials (ie email address associated with the customers paypal account)
ewallet type​ PayPal Currently PayPal is the only eWallet type supported
amount d.dd Total amount to be charged (i.e. 10.00)
currency ccc Code of the payment currency. If not currency is specified, the default is USD

transtype=credit&mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&amount=9.95&ewalletaccount=user@example.com&ewallettype=paypal&currency=USD

Command Line:

curl -d "transtype=credit&\
mkey=$E_WALLET_M_KEY&\
ewalletaccount=user@example.com&\
ewallet type=PayPal&\
amount=9.95&\
currency=USD" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Successful&
transid=10750788&
xref=KYAN63Z749J92&
authcode=&
orderid=&
type=credit&
avsresponse=&
cvvresponse=&
coderesponse=&
codedescription=&
status=200

CODE:

var result = await _sparrow.EWalletSimpleCredit(
    ewallet: new Sparrow.Ewallet{ EwalletAccount = "user@example.com" }, 
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // Successful
result.TransId;    // 11032427
result.XRef;    // A2M3983N76ZKS
result.Type;    // credit

CODE:


api.credit({
  ewalletaccount: 'user@example.com',
  ewallet_type: 'PayPal',
  amount: '9.95',
  currency: 'USD',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Successful'
result.transid # => '11037949'
result.xref # => '3RBFE4Q3T5XBJ'
result.type # => 'credit'
result.status # => '200'

CODE:

ewallet = sparrowone.EWallet("user@example.com")
resp = sprw.credit(9.95, ewallet)

RESULT:

{
    "response": "1",
    "textresponse": "Successful",
    "transid": "11032427",
    "xref": "A2M3983N76ZKS",
    "type": "credit",
    "status": "200",
}

CODE:

$paramsEWalletSimpleCredit = new EWalletSimpleCreditParams();
$paramsEWalletSimpleCredit->ewallet->ewalletAccount = "user@example.com";
$paramsEWalletSimpleCredit->amount = 9.99;

$resultEWalletSimpleCredit = self::$sparrow->EWalletSimpleCredit($paramsEWalletSimpleCredit)->wait();

RESULT EWalletSimpleCredit:

$resultEWalletSimpleCredit.isSuccess;    // 1
$resultEWalletSimpleCredit.status;    // 200
$resultEWalletSimpleCredit.response;    // 1
$resultEWalletSimpleCredit.textResponse;    // Successful: SUCCESS
$resultEWalletSimpleCredit.transId;    // 11284992
$resultEWalletSimpleCredit.xRef;    // Y5JESRJ5MU3XE
$resultEWalletSimpleCredit.type;    // credit
$resultEWalletSimpleCredit.codeDescription;    // SUCCESS

Fiserv

Fiserv provides a private label, closed loop line of credit for its partners.

Fiserv Simple Sale

VariableName Format Description
transtype sale sale = Transaction Sale
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0711 = 7/2011)
amount d.dd Total amount to be charged (i.e. 10.00)

transtype=sale&mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&amount=9.95&cardnum=000123456789002&cardexp=1010

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750802&
xref=3829708633&
authcode=123456&
orderid=&
type=sale&
avsresponse=&
cvvresponse=&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.FiservSimpleSale(
    cardNum: "4111111111111111",
    cardExp: new DateTime(2019,10,21),
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032429
result.XRef;    // 3876731632
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.sale({
  cardnum: '4111111111111111',
  cardexp: '1019',
  amount: '9.95',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '11037950'
result.xref # => '3877926499'
result.authcode # => '123456'
result.type # => 'sale'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


card = sparrowone.FiservCard(
    number="4111111111111111",
    expiration="1019"
)
resp = sprw.sale(10.0, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150073",
    "type": "sale",
    "xref": "3900948523"
}

CODE:

$paramsFiservSimpleSale = new FiservSimpleSaleParams();
$paramsFiservSimpleSale->cardNum = "4111111111111111";
$paramsFiservSimpleSale->cardExp = new DateTime("2019-10-21");
$paramsFiservSimpleSale->amount = 9.99;

$resultFiservSimpleSale = self::$sparrow->FiservSimpleSale($paramsFiservSimpleSale)->wait();

RESULT FiservSimpleSale:

$resultFiservSimpleSale.isSuccess;    // 1
$resultFiservSimpleSale.status;    // 200
$resultFiservSimpleSale.response;    // 1
$resultFiservSimpleSale.textResponse;    // SUCCESS
$resultFiservSimpleSale.transId;    // 11284996
$resultFiservSimpleSale.xRef;    // 3923166556
$resultFiservSimpleSale.authCode;    // 123456
$resultFiservSimpleSale.type;    // sale
$resultFiservSimpleSale.codeResponse;    // 100
$resultFiservSimpleSale.codeDescription;    // Transaction was Approved

Advanced Fiserv Sale

Variable Name Format Description
transtype sale Transaction Sale
mkey secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019
amount d.dd Total amount to be charged (ie. 10.00)
cvv card security code
currency CCC (ISO 4217 alphabetic code) Code of the payment currency. If currency is not specified, the default currency (USD) is assumed.
firstname Billing first name
lastname Billing last name
skunumber_# SKU number of the product being purchased (skunumber_1, skunumber_2, etc)
description_# Description of the product being purchased
amount_# Price of the single unit of a product being purchased
quantity_# Number of units of a product being purchased
orderdesc Order Description
orderid Order ID
cardipaddress ddd.ddd.ddd.ddd IP address of the customer, can be used for fraud prevention in FBI Tools
tax d.dd Total tax amount
shipamount d.dd Total shipping amount
ponumber Original Purchase Order
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email

transtype=sale&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=57.85&cardnum=4000123456789002&cardexp=1010&skunumber_1=5558779&description_1=menssweaterblue&amount_1=50.00&quantity_1=1&tax=2.85&shipamount=5.00&firstname=John&lastname=Smith&address1=888+test+address&city=Los+Angeles&country=US&state=CA&phone=222-444-2938&shipfirstname=John&shiplastname=Smith&shipaddress1=888+test+address&shipcity=Los+Angeles&shipstate=CA&shipphone=2224442938

Command Line:

curl -d "transtype=sale&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=9.95&\
cvv=999&\
currency=USD&\
firstname=John&\
lastname=Doe&\
skunumber_1=123&\
skunumber_2=456&\
description_1=Blue widget&\
description_2=Brown widget&\
amount_1=1.99&\
amount_2=2.99&\
quantity_1=1&\
quantity_2=2&\
orderdesc=Order Description&\
orderid=11111&\
cardipaddress=8.8.8.8&\
tax=0.25&\
shipamount=1.25&\
ponumber=22222&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
transid=10750809&
xref=3829708566&
authcode=123456&
orderid=11111&
type=sale&
avsresponse=N&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
status=200

CODE:

var result = await _sparrow.AdvancedFiservSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) },
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032428
result.XRef;    // 3876731622
result.AuthCode;    // 123456
result.Type;    // sale
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:


api.sale({
  cardnum: '4111111111111111',
  cardexp: '1019',
  amount: '9.95',
  cvv: '999',
  currency: 'USD',
  firstname: 'John',
  lastname: 'Doe',
  skunumber_1: '123',
  skunumber_2: '456',
  description_1: 'Blue widget',
  description_2: 'Brown widget',
  amount_1: '1.99',
  amount_2: '2.99',
  quantity_1: '1',
  quantity_2: '2',
  orderdesc: 'Order Description',
  orderid: '11111',
  cardipaddress: '8.8.8.8',
  tax: '0.25',
  shipamount: '1.25',
  ponumber: '22222',
  company: 'Sparrow One',
  address1: '16100 N 71st Street',
  address2: 'Suite 170',
  city: 'Scottsdale',
  state: 'AZ',
  zip: '85254',
  country: 'US',
  email: 'john@norepy.com',
  shipfirstname: 'Jane',
  shiplastname: 'Doe',
  shipcompany: 'Sparrow Two',
  shipaddress1: '16100 N 72nd Street',
  shipaddress2: 'Suite 171',
  shipcity: 'Pheonix',
  shipstate: 'AZ',
  shipzip: '85004',
  shipcountry: 'US',
  shipphone: '6025551234',
  shipemail: 'jane@noreply.com',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '11037951'
result.xref # => '3877926535'
result.authcode # => '123456'
result.orderid # => '11111'
result.type # => 'sale'
result.avsresponse # => 'N'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:


sale = sparrowone.SaleInfo(
    amount=7.96,
    currency="USD",
    billing_contact=sparrowone.Contact(
        first_name="Dana",
        last_name="Zane",
    ),
    ship_to=sparrowone.Contact(
        first_name="Julianne",
        last_name="Stingray",
        address1="16100 N 72nd Street",
        address2="Suite 171",
        city="Glitch City",
        zip="220000",
        country="XX",
        email="noreply@sparrowone.com",
    ),
    products=[
        sparrowone.Product(skunumber=1999,
                        description="Blue whale",
                        amount=1.99,
                        quantity=4)
    ],
    ip_addr="192.168.12.34",
)

card = sparrowone.FiservCard(
    number="4111111111111111",
    expiration="1019",
    cvv="999",
)

resp = sprw.sale(sale, card)

RESULT:


{
    "authcode": "123456",
    "codedescription": "Transaction was Approved",
    "coderesponse": "100",
    "cvvresponse": "M",
    "response": "1",
    "status": "200",
    "textresponse": "SUCCESS",
    "transid": "11150072",
    "type": "sale",
    "xref": "3900948475"
}

CODE:

$paramsAdvancedFiservSale = new AdvancedFiservSaleParams();
$paramsAdvancedFiservSale->creditCard->cardNum = "4111111111111111";
$paramsAdvancedFiservSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsAdvancedFiservSale->amount = 9.99;

$resultAdvancedFiservSale = self::$sparrow->AdvancedFiservSale($paramsAdvancedFiservSale)->wait();

RESULT AdvancedFiservSale:

$resultAdvancedFiservSale.isSuccess;    // 1
$resultAdvancedFiservSale.status;    // 200
$resultAdvancedFiservSale.response;    // 1
$resultAdvancedFiservSale.textResponse;    // SUCCESS
$resultAdvancedFiservSale.transId;    // 11284994
$resultAdvancedFiservSale.xRef;    // 3923166531
$resultAdvancedFiservSale.authCode;    // 123456
$resultAdvancedFiservSale.type;    // sale
$resultAdvancedFiservSale.codeResponse;    // 100
$resultAdvancedFiservSale.codeDescription;    // Transaction was Approved

Chargeback Entry

The Chargeback operation changes the transaction status from **successful **to **dispute. **This operation also updates the Customer Scoring system and removes the transaction amount from the successful transactions total within the Reports module.

Marking a successful transaction as a Chargeback

Variable Name Format Description
transtype chargeback Chargeback will mark the transaction as “disputed”
mkey Secured merchant account key
transid Original payment gateway transaction ID
reason alphanumeric Description of the reason for the chargeback

transtype=chargeback&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transid=12345678&reason=fraudulent+transaction

Command Line:

curl -d "transtype=chargeback&\
mkey=$M_KEY&\
transid=10750804&\
reason=Reason for chargeback" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Reason+for+chargeback&
transid=10750804&
xref=3829708661&
authcode=123456&
orderid=&
type=chargeback&
avsresponse=&
cvvresponse=M&
coderesponse=&
codedescription=&
status=200

CODE:

var resultSimpleSale = await _sparrow.SimpleSale(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) }, 
    amount: 9.99m);
var result = await _sparrow.MarkSuccessfulTransactionAsChargeback(
    transId: resultSimpleSale.TransId, 
    reason: "Testing for Success");

RESULT SimpleSale:

resultSimpleSale.Status;    // 200
resultSimpleSale.Response;    // 1
resultSimpleSale.TextResponse;    // SUCCESS
resultSimpleSale.TransId;    // 11032423
resultSimpleSale.XRef;    // 3876731424
resultSimpleSale.AuthCode;    // 123456
resultSimpleSale.Type;    // sale
resultSimpleSale.CodeResponse;    // 100
resultSimpleSale.CodeDescription;    // Transaction was Approved

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // Testing for Success
result.TransId;    // 11032423
result.XRef;    // 3876731424
result.AuthCode;    // 123456
result.Type;    // chargeback

CODE:


api.chargeback({
  transid: '10934104',
  reason: 'Card reported lost',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Card reported lost'
result.transid # => '10934104'
result.xref # => '3865091326'
result.authcode # => '123456'
result.type # => 'chargeback'
result.cvvresponse # => 'M'
result.status # => '200'

CODE:


resp = sprw.chargeback(transid='10934104', reason='Card reported lost')

RESULT:


{
  "response": "1",
  "textresponse": "Card reported lost",
  "transid": "10934104",
  "xref": "3865091326",
  "authcode": "123456",
  "type": "chargeback",
  "cvvresponse": "M",
  "status": "200"
}

CODE:

$paramsSimpleSale = new SimpleSaleParams();
$paramsSimpleSale->creditCard->cardNum = "4111111111111111";
$paramsSimpleSale->creditCard->cardExp = new DateTime("2019-10-21");
$paramsSimpleSale->amount = 9.99;

$resultSimpleSale = self::$sparrow->SimpleSale($paramsSimpleSale)->wait();

$paramsMarkSuccessfulTransactionAsChargeback = new MarkSuccessfulTransactionAsChargebackParams();
$paramsMarkSuccessfulTransactionAsChargeback->transId = $resultSimpleSale->transId;
$paramsMarkSuccessfulTransactionAsChargeback->reason = "Testing for Success";

$resultMarkSuccessfulTransactionAsChargeback = self::$sparrow->MarkSuccessfulTransactionAsChargeback($paramsMarkSuccessfulTransactionAsChargeback)->wait();

RESULT SimpleSale:

$resultSimpleSale.isSuccess;    // 1
$resultSimpleSale.status;    // 200
$resultSimpleSale.response;    // 1
$resultSimpleSale.textResponse;    // SUCCESS
$resultSimpleSale.transId;    // 11284986
$resultSimpleSale.xRef;    // 3923165886
$resultSimpleSale.authCode;    // 123456
$resultSimpleSale.type;    // sale
$resultSimpleSale.codeResponse;    // 100
$resultSimpleSale.codeDescription;    // Transaction was Approved

RESULT MarkSuccessfulTransactionAsChargeback:

$resultMarkSuccessfulTransactionAsChargeback.isSuccess;    // 1
$resultMarkSuccessfulTransactionAsChargeback.status;    // 200
$resultMarkSuccessfulTransactionAsChargeback.response;    // 1
$resultMarkSuccessfulTransactionAsChargeback.textResponse;    // Testing for Success
$resultMarkSuccessfulTransactionAsChargeback.transId;    // 11284986
$resultMarkSuccessfulTransactionAsChargeback.xRef;    // 3923165886
$resultMarkSuccessfulTransactionAsChargeback.authCode;    // 123456
$resultMarkSuccessfulTransactionAsChargeback.type;    // chargeback

Balance Inquiry

The Balance Inquiry operation returns the available card balance

Retrieve Card Balance

VariableName Format Description
transtype balanceinquire Balanceinquire returns the available card balance
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019)
transtype=balanceinquire&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&amount=9.95&cardnum=4111111111111111&cardexp=0719

Command Line:

curl -d "transtype=balanceinquire&\
mkey=$M_KEY&\
cardnum=4005562231212149&\
cardexp=1225" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Operation+type+is+not+supported+by+payment+processor&
type=balanceinquire&
coderesponse=&
codedescription=&
status=500

CODE:

var result = await _sparrow.RetrieveCardBalance(
    cardNum: "4111111111111111");

RESULT:

result.Status;    // 500
result.Response;    // 3
result.TextResponse;    // Operation type is not supported by payment processor
result.Type;    // balanceinquire

CODE:

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999",
)
resp = sprw.balance_inquire(card)

RESULT:

{
  "response": "3",
  "textresponse": "Operation type is not supported by payment processor",
  "type": "balanceinquire",
  "coderesponse": "",
  "codedescription": "",
  "status": "500"
}

CODE:

$paramsRetrieveCardBalance = new RetrieveCardBalanceParams();
$paramsRetrieveCardBalance->cardNum = "4111111111111111";

$resultRetrieveCardBalance = self::$sparrow->RetrieveCardBalance($paramsRetrieveCardBalance)->wait();

RESULT RetrieveCardBalance:

$resultRetrieveCardBalance.response;    // 3
$resultRetrieveCardBalance.textResponse;    // Required payment field cardexp is missing

Decrypting Custom Fields

The merchant has the ability to decrypt custom fields via the API using the Data Vault client and the name of the custom field. Commonly encrypted fields may be:

  • Social Security Number

    • Drivers License Number

    • Custom Identifier

Decrypting Custom Fields

VariableName Format Description
transtype decrypt The decrypt operation returns the value of the custom field
mkey Secured merchant account key
fieldname Custom field name
token alphanumeric string This is a unique Data Vault customer identifier or Data Vault payment type identifier
transtype=decrypt&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&fieldname=socialsecurity&token=H6FV89KL156

Command Line:

curl -d "transtype=decrypt&\
mkey=$M_KEY&\
fieldname=customField1&\
customertoken=CustomerToken&\
paymenttoken=PaymentToken" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Internal+processing+error

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, 
    paymentType: new []{ new Sparrow.PaymentType{ ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.DecryptCustomFields(
    fieldName: "customField1", 
    token: resultAddCustomer.CustomerToken);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'B9AOSCDWHD5UDQM0' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // B9AOSCDWHD5UDQM0
resultAddCustomer.PaymentTokens[0];    // EUWP2KMWLGJB9AZ4

RESULT:

result.Response;    // 3
result.TextResponse;    // Custom field 'customField1' not found.
result.CustomerToken;    // B9AOSCDWHD5UDQM0
result.Token;    // B9AOSCDWHD5UDQM0

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsDecryptCustomFields = new DecryptCustomFieldsParams();
$paramsDecryptCustomFields->fieldName = "customField1";
$paramsDecryptCustomFields->token = $resultAddCustomer->customerToken;

$resultDecryptCustomFields = self::$sparrow->DecryptCustomFields($paramsDecryptCustomFields)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'M69T61U6KD8O7V3D' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // M69T61U6KD8O7V3D
$resultAddCustomer.p;    // WX5U9OF7K3YBFW09

RESULT DecryptCustomFields:

$resultDecryptCustomFields.response;    // 3
$resultDecryptCustomFields.textResponse;    // Custom field 'customField1' not found.
$resultDecryptCustomFields.customerToken;    // M69T61U6KD8O7V3D
$resultDecryptCustomFields.token;    // M69T61U6KD8O7V3D

Credit Card Verification

An Account Verification transaction is used when certain aspects of the credit card are needed prior to a purchase. An Account Verification transaction is similar to an Authorization request (not a Sale) with the amount of $0. The following can be verified by the Issuer:

  • Credit Card number-Checks to see if the card number is on file with the Issuer, and if in good standing

    • AVS-Checks the address of the cardholder

    • CVN-Checks the Card verification Number of the credit card

Account Verification

Variable Name Format Description
transtype verification
mkey Secured merchant account key
cardnum Credit card number
cardexp MMYY Credit card expiration (ie 0719 = 07/2019)
amount d.dd Total amount to be charged should be 0.00
cvv Card security code
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
transtype=verification&mkey=HNJ45D23MKLO85J2D00LOP&cardnum=4111111111111111&cardexp=1019&amount=0.00&zip=85254

Command Line:

curl -d "transtype=verification&\
mkey=$M_KEY&\
cardnum=4111111111111111&\
cardexp=1019&\
amount=0.00&\
cvv=999&\
zip=85254" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=APPROVAL&
transid=10750787&
xref=&
authcode=123456&
orderid=&
type=verification&
avsresponse=Z&
cvvresponse=&
coderesponse=000&
codedescription=Approve&
status=200

CODE:

var result = await _sparrow.VerifyAccount(
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) }, 
    amount: 9.99m);

RESULT:

result.Status;    // 200
result.Response;    // 1
result.TextResponse;    // SUCCESS
result.TransId;    // 11032422
result.XRef;    // 3876731403
result.AuthCode;    // 123456
result.Type;    // auth
result.CodeResponse;    // 100
result.CodeDescription;    // Transaction was Approved

CODE:

api.balance({
  cardnum: '4111111111111111',
  cardexp: '1019',
  amount: '9.95',
  cvv: '999',
  zip: '85254"',
})

RESULT:

result.response # => '1'
result.textresponse # => 'SUCCESS'
result.transid # => '10750787'
result.xref # => '3829708536'
result.authcode # => '123456'
result.orderid # => ''
result.type # => 'auth'
result.avsresponse # => 'N'
result.cvvresponse # => 'M'
result.coderesponse # => '100'
result.codedescription # => 'Transaction was Approved'
result.status # => '200'

CODE:

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.verify(card)

RESULT:

{
    "status": "200",
    "response": "1",
    "textresponse": "SUCCESS",
    "transid": "11032422",
    "xref": "3876731403",
    "authcode": "123456",
    "type": "auth",
    "coderesponse": "100",
    "codedescription": "Transaction was Approved",
}

$$language: php$$ CODE:

$paramsVerifyAccount = new VerifyAccountParams();
$paramsVerifyAccount->creditCard->cardNum = "4111111111111111";
$paramsVerifyAccount->creditCard->cardExp = new DateTime("2019-10-21");
$paramsVerifyAccount->amount = 9.99;

$resultVerifyAccount = self::$sparrow->VerifyAccount($paramsVerifyAccount)->wait();

RESULT VerifyAccount:

$resultVerifyAccount.isSuccess;    // 1
$resultVerifyAccount.status;    // 200
$resultVerifyAccount.response;    // 1
$resultVerifyAccount.textResponse;    // SUCCESS
$resultVerifyAccount.transId;    // 11284985
$resultVerifyAccount.xRef;    // 3923165840
$resultVerifyAccount.authCode;    // 123456
$resultVerifyAccount.type;    // auth
$resultVerifyAccount.codeResponse;    // 100
$resultVerifyAccount.codeDescription;    // Transaction was Approved

Data Vault

The Data Vault is designed to store and recall client’s payment information for efficient, repeatable transactions. Through using tokenization, all necessary consumer information is stored adhering to PCI Level 1 compliance.

Adding a Customer

Variable Name Format Description
transtype addcustomer Add customer will create a new Data Vault entry
mkey secured merchant account key
firstname Customer’s first name
lastname Customer’s last name
customerid External customer identifier
note Customer note
address1 Default address
address2 Default address2
city Default city
state 2 character abbreviation Default state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Default Country (ie. US)
phone Default billing phone number
email Default Email Address
shipfirstname Default Shipping first name
shiplastname Default Shipping last name
shipcompany Default Shipping company
shipaddress1 Default Shipping Address
shipaddress2 Default Shipping Address - line 2
shipcity Default Shipping City
shipstate 2 character abbreviation Default Shipping State
shipzip Default Shipping Zip Code
shipcountry CC (ISO - 3166) Default Shipping Country, ie US
shipphone Default Shipping Phone Number
shipemail Default Shipping Email
username Client user name. This field is required if the Client Service Portal is enabled and ‘password’ or ‘clientuseremail’ is specified
password Client user password. This field is required if the Client Service Portal is enabled and ‘username’ or ‘clientuseremail’ is specified
clientuseremail Client user email. This field is required if the Client Service Portal is enabled and ‘password’ or ‘username’ is specified
paytype_# creditcard/check/ach/starcard/ewallet Type of payment info
company_# Company name, specific to the payment type
firstname_# Billing first name, specific to the payment type
lastname_# Billing last name, specific to the payment type
address1_# Billing address, specific to the payment type
address2_# Billing address-line 2, specific to the payment type
city_# Billing city, specific to the payment type
state_# Billing state, 2 character abbreviation, specific to the payment type
zip_# Billing zip, specific to payment type
country_# Billing Country, specific to payment type
phone_# Billing phone, specific to payment type
email_# Billing email, specific to payment type
cardnum_# Credit card number
cardexp_# MMYY Credit card expiration
bankname_# ACH bank name
routing_# ACH routing number
account_# ACH account number
achaccounttype_# checking/savings ACH account type
achaccountsubtype_# business/personal ACH account sub type
payno_# positive integer Priority of the payment type among others when sending payment using the customertoken
ewalletaccount_# eWallet account credentials, ie; email
ewallettype_# paypal Type of eWallet

transtype=addcustomer&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&firstname=Samantha&lastname=Simmons&address1=1234+N+Wells+street&city=Phoenix&state=AZ&zip=85254&email@sam@test.com&phone=4801234567&paytype_1=creditcard&cardnum_1=4111111111111111&cardexp_1=0220

$$language: curl$$

Command Line:

curl -d "transtype=addcustomer&\
mkey=$M_KEY&\
firstname=John&\
lastname=Doe&\
note=Customer Note&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com&\
username=JohnDoe17101717530877&\
password=Password123&\
clientuseremail=john@norepy.com&\
paytype_1=creditcard&\
paytype_2=check&\
firstname_1=John&\
firstname_2=John&\
lastname_1=Doe&\
lastname_2=Doe&\
address1_1=123 Main Street&\
address1_2=321 1st Street&\
address2_1=Suite 1&\
address2_2=Suite 2&\
city_1=Pheonix&\
city_2=Scottsdale&\
state_1=AZ&\
state_2=AZ&\
zip_1=85111&\
zip_2=85222&\
country_1=US&\
country_2=US&\
phone_1=6025551234&\
phone_2=6025554321&\
email_1=john@norepy.com&\
email_2=jane@noreploy.com&\
cardnum_1=4111111111111111&\
cardnum_2=4111111111111111&\
cardexp_1=1019&\
cardexp_2=1019&\
bankname_1=&\
bankname_2=First Test Bank&\
routing_1=&\
routing_2=110000000&\
account_1=&\
account_2=1234567890123&\
achaccounttype_1=&\
achaccounttype_2=personal&\
payno_1=1&\
payno_2=2" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Customer+with+token+%27F6OE0IN0I5HSV6AJ%27+successfully+created&
type=addcustomer&
customertoken=F6OE0IN0I5HSV6AJ&
paymenttoken_1=9K7US80YUQ1LPN27&
paymenttoken_2=OZA3QU7CYG57D88R

CODE:

var result = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });

RESULT:

result.Response;    // 1
result.TextResponse;    // Customer with token 'MDQE3APBQWNPLB0N' successfully created
result.Type;    // addcustomer
result.CustomerToken;    // MDQE3APBQWNPLB0N
result.PaymentTokens[0];    // L5UM9ALNJR2XWQH5

CODE:

api.addcustomer({
  firstname: 'John',
  lastname: 'Doe',
  paytype_1: 'starcard',
  cardnum_1: '6019440000011111',
  CID: '52347800001',
})

RESULT:

result.response # => '1'
result.textresponse # => 'Customer with token 'LDX59BK4441R46J7' successfully created'
result.type # => 'addcustomer'
result.customertoken # => 'LDX59BK4441R46J7'
result.paymenttoken_1 # => 'I5ZVHNONDI5YIGKG'

CODE:

resp = sprw.customers.create(data=dict(
    firstname="John",
    lastname="Doe",
    note="Customer Note",
    address1="16100 N 71st Street",
    address2="Suite 170",
    city="Scottsdale",
    state="AZ",
    zip="85254",
    country="US",
    email="john@norepy.com",
    shipfirstname="Jane",
    shiplastname="Doe",
    shipcompany="Sparrow Two",
    shipaddress1="16100 N 72nd Street",
    shipaddress2="Suite 171",
    shipcity="Pheonix",
    shipstate="AZ",
    shipzip="85004",
    shipcountry="US",
    shipphone="6025551234",
    shipemail="jane@noreply.com",
    username=str(uuid.uuid1()),
    password="Password123",
    clientuseremail="john@norepy.com",
    paytype_1="creditcard",
    firstname_1="John",
    lastname_1="Doe",
    address1_1="123 Main Street",
    address2_1="Suite 1",
    city_1="Pheonix",
    state_1="AZ",
    zip_1="85111",
    country_1="US",
    phone_1="6025551234",
    email_1="john@norepy.com",
    cardnum_1="4111111111111111",
    cardexp_1="1019",
    paytype_2="check",
    firstname_2="John",
    lastname_2="Doe",
    address1_2="321 1st Street",
    address2_2="Suite 2",
    city_2="Scottsdale",
    state_2="AZ",
    zip_2="85222",
    country_2="US",
    phone_2="6025554321",
    email_2="jane@noreploy.com",
    cardnum_2="4111111111111111",
    cardexp_2="1019",
    bankname_2="First Test Bank",
    routing_2="110000000",
    account_2="1234567890123",
    achaccounttype_2="personal",
    payno_2="2",
))

RESULT:

{
    "customertoken": "UOLL9K0L2YU7N1I3",
    "paymenttoken_1": "65EQ73QMHFMVUS19",
    "response": "00",
    "textresponse": "Customer with token 'UOLL9K0L2YU7N1I3' successfully created",
    "type": "addcustomer"
}

$$language: php$$ CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'PE4WB9TIYLXCZXIV' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // PE4WB9TIYLXCZXIV
$resultAddCustomer.p;    // PTGX8RBJ9GJ1MM9Z

Add Customer by Payment Type:

Below are the minimum fields required to add a new Data Vault customer for each supported payment type.

Credit Card

Variable Name Format Description
mkey Secured merchant account key
transtype addcustomer Add a new Data Vault Customer
token alphanumeric string Unique customer or payment info identifier
firstname Customer’s first nam
lastname Customer’s last name
paytype_# creditcard Type of payment info
cardnum_# Credit card number
cardexp_# MMYY Credit card expiration
paytypeblocked_# true / false If true payment type will be marked as paused. Payments will not be processed via paused payment type.

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=addcustomer&firstname=John&lastname=Doe&paytype_1=creditcard&cardnum_1=4111111111111111&cardexp_1=0220

ACH

Variable Name Format Description
mkey Secured merchant account key
transtype addcustomer Add a new Data Vault Customer
token alphanumeric string Unique customer or payment info identifier
firstname Customer’s first name
lastname Customer’s last name
paytype_# ach Type of payment info
bankname_# Bank name
routing_# Bank routing number
account_# Bank account number
achaccounttype_# checking / savings Type of ACH account
achaccountsubtype_# business / personal Subtype of ACH account

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=addcustomer&firstname=John&lastname=Doe&paytype_1=ach&bankname_1=wellsfargo&achaccounttype_1=checking&achaccountsubtype_1=personal&routing_1=223456&account_1=123456789

Star Card

Variable Name Format Description
mkey Secured merchant account key
transtype addcustomer Add a new Data Vault Customer
token alphanumeric string Unique customer or payment info identifier
firstname Customer’s first name
lastname Customer’s last name
paytype_# starcard Type of payment info
cardnum_# Credit Card number
CID custom field 11 digit numerical

transtype=addcustomer&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&firstname=John&lastname=Doe&paytype_1=starcard&cardnum_1=6019440000011111&CID=52347800001

eWallet

Variable Name Format Description
mkey Secured merchant account key
transtype addcustomer Add a new Data Vault Customer
token alphanumeric string Unique customer or payment info identifier
firstname Customer’s first name
lastname Customer’s last name
paytype_# ewallet Type of payment info
ewallettype_# paypal Type of eWallet
ewalletaccount_# email eWallet credentials (email)

transtype=addcustomer&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&firstname=John&lastname=Doe&paytype_1=ewallet&ewallettype_1=paypal&ewalletaccount_1=email@email.com

Command Line:

curl -d "mkey=$ACH_M_KEY&\
transtype=addcustomer&\
firstname=John&\
lastname=Doe&\
paytype_1=creditcard&\
cardnum_1=4111111111111111&\
cardexp_1=1019" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=00&
textresponse=Customer+with+token+%27OZMGG9YB5DPF663X%27+successfully+created&
type=addcustomer&
customertoken=OZMGG9YB5DPF663X&
paymenttoken_1=WSJE7RYNRQPLJIRC

Update Customer

Variable Name Format Description
mkey Secured merchant key
transtype updatecustomer This transaction type will update the current client information with any new data fields provided
token alphanumericstring Unique customer identifier
firstname Billing first name
lastname Billing last name
address1 Billing address
address2 Billing address, line 2
city Billing city
state 2 character abbreviation Billing state
zip Billing zip
country CC (ISO-3166) Billing country
phone Billing phone
email Billing email
shipfirstname Shipping first name
shiplastname Shipping last name
shipaddress1 Shipping address1
shipaddress2 Shipping address2
shipcity Shipping city
shipstate Shipping state
shipzip Shipping zip
shipcountry Shipping country
shipphone Shipping phone
shipemail Shipping email
username Client Service Portal username
password Client Service Portal password
clientuseremail Client Service Portal email

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updatecustomer&token=B31388EA20ABF2776C93&address1=939+St.+Winnie’s+st.&city=Forest+City

Command Line:

curl -d "mkey=$M_KEY&\
transtype=updatecustomer&\
token=O3BEZTT2UHCS7USA&\
firstname=John&\
lastname=Doe&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
phone=7025551234&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Customer+with+token+%27O3BEZTT2UHCS7USA%27+successfully+updated&
type=updatecustomer&
customertoken=O3BEZTT2UHCS7USA

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.UpdateCustomer(
    token: resultAddCustomer.CustomerToken);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'G7HJV1U70S1290OZ' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // G7HJV1U70S1290OZ
resultAddCustomer.PaymentTokens[0];    // 2HXUOE6WDW6ZBER2

RESULT:

result.Response;    // 1
result.TextResponse;    // Customer with token 'G7HJV1U70S1290OZ' successfully updated
result.Type;    // updatecustomer
result.CustomerToken;    // G7HJV1U70S1290OZ

CODE:


api.updatecustomer({
  token: 'B31388EA20ABF2776C93',
  address1: '939 St. Winnie’s st.',
  city: 'Forest City',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Customer with token 'O3BEZTT2UHCS7USA' successfully updated'
result.type # => 'updatecustomer'
result.customertoken # => 'O3BEZTT2UHCS7USA'

CODE:


resp = sprw.customers.update_payment_type(
    customer_token,
    payment_token,
    data={
        "cardnum": "4111111111111112",
    }
)

RESULT:


{
    "customertoken": "UR1W59V45NY7AY5C",
    "paymenttoken_1": "93WACVAMONXJWLAD",
    "response": "1",
    "textresponse": "Customer with token 'UR1W59V45NY7AY5C' successfully updated",
    "type": "updatecustomer"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsUpdateCustomer = new UpdateCustomerParams();
$paramsUpdateCustomer->token = $resultAddCustomer->customerToken;

$resultUpdateCustomer = self::$sparrow->UpdateCustomer($paramsUpdateCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token '6V6AH643CTREHEEX' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // 6V6AH643CTREHEEX
$resultAddCustomer.p;    // BTLTOL2KZ8CRW6QI

RESULT UpdateCustomer:

$resultUpdateCustomer.isSuccess;    // 1
$resultUpdateCustomer.response;    // 1
$resultUpdateCustomer.textResponse;    // Customer with token '6V6AH643CTREHEEX' successfully updated
$resultUpdateCustomer.type;    // updatecustomer
$resultUpdateCustomer.customerToken;    // 6V6AH643CTREHEEX

Adding Payment Types to a Customer

Variable Name Format Description
mkey Secured merchant key
transtype updatecustomer This transaction type will update the current client information with any new data fields provided
token alphanumericstring Unique customer identifier
operationtype_# addpaytype

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updatecustomer&token=B31388EA20ABF2776C93&operationtype_1=addpaytype&paytype_1=creditcard&cardnum_1=4111111111111111&cardexp_1=0226&firstname_1=John&lastname_1=Smith&operationtype_2=addpaytype&paytype_2=creditcard&cardnum_2=5454545454545454&cardexp_2=0720&firstname_2=John&lastname_2=Smith
No content for this section.

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.AddPaymentTypesToCustomer(
    token: resultAddCustomer.CustomerToken,
    paymentTypeToAdd: new []{ new Sparrow.PaymentTypeToAdd{ PaymentType = new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) }, BankAccount = new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal }, Ewallet = new Sparrow.Ewallet{ EwalletAccount = "user@example.com" } } } });

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token '645GRTD1SIXLJ5U5' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // 645GRTD1SIXLJ5U5
resultAddCustomer.PaymentTokens[0];    // QEU8KSUON36XUWLI

RESULT:

result.Response;    // 1
result.TextResponse;    // Customer with token '645GRTD1SIXLJ5U5' successfully updated
result.Type;    // updatecustomer
result.CustomerToken;    // 645GRTD1SIXLJ5U5
result.PaymentTokens[0];    // 76XRTBDSCGBYBGAA

CODE:

api.addcustomer({
  firstname: 'John',
  lastname: 'Doe',
  paytype_1: 'ewallet',
  ewallettype_1: 'paypal',
  ewalletaccount_1: 'email@email.com',
})

RESULT:


result.response # => '1'
result.textresponse # => 'Customer with token 'NA2TF8AJGI5CAKCB' successfully created'
result.type # => 'addcustomer'
result.customertoken # => 'NA2TF8AJGI5CAKCB'
result.paymenttoken_1 # => '48TXLSRFTOAQK680'

CODE:


resp = sprw.customers.add_payment_type(
    customer_token,
    data={
        "paytype": "creditcard",
        "cardnum": "4111111111111112",
        "cardexp": "1019",
    }
)

RESULT:


{
    "customertoken": "A312JPG1C9AEK6FX",
    "paymenttoken_1": "YDAJV4CTWR6KOZKA",
    "response": "1",
    "textresponse": "Customer with token 'A312JPG1C9AEK6FX' successfully updated",
    "type": "updatecustomer"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsAddPaymentTypesToCustomer = new AddPaymentTypesToCustomerParams();
$paramsAddPaymentTypesToCustomer->token = $resultAddCustomer->customerToken;
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0] = new PaymentTypeToAdd();
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->payType = PayType::CREDITCARD;
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->creditCard->cardNum = "4111111111111111";
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->creditCard->cardExp = new DateTime("2019-10-21");
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->bankAccount->bankName = "First Test Bank";
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->bankAccount->routing = "110000000";
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->bankAccount->account = "1234567890123";
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsAddPaymentTypesToCustomer->paymentTypeToAdds[0]->paymentType->ewallet->ewalletAccount = "user@example.com";

$resultAddPaymentTypesToCustomer = self::$sparrow->AddPaymentTypesToCustomer($paramsAddPaymentTypesToCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'UEON6IEAJI0L41TP' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // UEON6IEAJI0L41TP
$resultAddCustomer.p;    // 98GDPLFHEE51AUHX

RESULT AddPaymentTypesToCustomer:

$resultAddPaymentTypesToCustomer.isSuccess;    // 1
$resultAddPaymentTypesToCustomer.response;    // 1
$resultAddPaymentTypesToCustomer.textResponse;    // Customer with token 'UEON6IEAJI0L41TP' successfully updated
$resultAddPaymentTypesToCustomer.type;    // updatecustomer
$resultAddPaymentTypesToCustomer.customerToken;    // UEON6IEAJI0L41TP
$resultAddPaymentTypesToCustomer.p;    // 1ED1OV0K9FI7XAKX

Update Payment Type

Variable Name Format Description
mkey Secured merchant key
transtype updatecustomer This transaction type will update the current client information with any new data fields provided
token alphanumericstring Unique customer identifier
operationtype_# updatepaytype
token_# alphanumericstring Unique payment type identifier

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updatecustomer&token=B31388EA20ABF2776C93&operationtype_1=updatepaytype&token_1=0HEUX6NFECQG8QCQ&cardnum_1=4111111111111112&operationtype_2=updatepaytype&token_2=4K8NSZSGGPMHGEW4&cardexp_2=0421
No content for this section.

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, 
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.UpdatePaymentType(
    token: resultAddCustomer.CustomerToken, 
    paymentTypeToUpdate: new []{ new Sparrow.PaymentTypeToUpdate{ Token = resultAddCustomer.PaymentTokens[0], PaymentType = new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } } });

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token '1UILWG9UZ3AQKMRL' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // 1UILWG9UZ3AQKMRL
resultAddCustomer.PaymentTokens[0];    // DWLGPFIBBUG8555V

RESULT:

result.Response;    // 1
result.TextResponse;    // Customer with token '1UILWG9UZ3AQKMRL' successfully updated
result.Type;    // updatecustomer
result.CustomerToken;    // 1UILWG9UZ3AQKMRL
result.PaymentTokens[0];    // DWLGPFIBBUG8555V

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsUpdatePaymentType = new UpdatePaymentTypeParams();
$paramsUpdatePaymentType->token = $resultAddCustomer->customerToken;
$paramsUpdatePaymentType->paymentTypeToUpdates[0] = new PaymentTypeToUpdate();
$paramsUpdatePaymentType->paymentTypeToUpdates[0]->token = $resultAddCustomer->paymentTokens[0];
$paramsUpdatePaymentType->paymentTypeToUpdates[0]->paymentType->payType = PayType::CREDITCARD;
$paramsUpdatePaymentType->paymentTypeToUpdates[0]->paymentType->creditCard->cardNum = "4111111111111111";
$paramsUpdatePaymentType->paymentTypeToUpdates[0]->paymentType->creditCard->cardExp = new DateTime("2019-10-21");

$resultUpdatePaymentType = self::$sparrow->UpdatePaymentType($paramsUpdatePaymentType)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token '4S0911NIPAIX47IN' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // 4S0911NIPAIX47IN
$resultAddCustomer.p;    // N6J9Y6I6LZW1RQWJ

RESULT UpdatePaymentType:

$resultUpdatePaymentType.isSuccess;    // 1
$resultUpdatePaymentType.response;    // 1
$resultUpdatePaymentType.textResponse;    // Customer with token '4S0911NIPAIX47IN' successfully updated
$resultUpdatePaymentType.type;    // updatecustomer
$resultUpdatePaymentType.customerToken;    // 4S0911NIPAIX47IN
$resultUpdatePaymentType.p;    // N6J9Y6I6LZW1RQWJ

Delete Payment Type

Variable Name Format Description
mkey Secured merchant key
transtype updatecustomer This transaction type will update the current client information with any new data fields provided
token alphanumericstring Unique customer identifier
token_# alphanumericstring Token of the payment type to be deleted
operationtype_# deletepaytype Delete a specific payment type

Command Line:

curl -d "mkey=$M_KEY&\
transtype=updatecustomer&\
token_1=SXZ27VYHGBSMYDNH&\
operationtype_1=deletepaytype&\
token=EBVX61KPEIUZXV7B" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Customer+with+token+%27EBVX61KPEIUZXV7B%27+successfully+updated&
type=updatecustomer&
customertoken=EBVX61KPEIUZXV7B&
paymenttoken_1=SXZ27VYHGBSMYDNH

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.DeletePaymentType(
    token: resultAddCustomer.CustomerToken,
    paymentTypeToDelete: new []{ new Sparrow.PaymentTypeToDelete{ Token = resultAddCustomer.PaymentTokens[0] } });

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'YKFAA8JWGNX0GLLV' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // YKFAA8JWGNX0GLLV
resultAddCustomer.PaymentTokens[0];    // A7E9RB07JBCD0MYP

RESULT:

result.Response;    // 1
result.TextResponse;    // Customer with token 'YKFAA8JWGNX0GLLV' successfully updated
result.Type;    // updatecustomer
result.CustomerToken;    // YKFAA8JWGNX0GLLV
result.PaymentTokens[0];    // A7E9RB07JBCD0MYP

CODE:


api.delete_payment_type({
  token: 'LFC0KIYV18APRLCH',
  operationtype_1: 'deletepaytype',
  token_1: 'QQ8TR7J8P0IQ9TOL',
  achaccounttype_1: 'savings',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Customer with token 'LFC0KIYV18APRLCH' successfully updated'
result.type # => 'updatecustomer'
result.customertoken # => 'LFC0KIYV18APRLCH'
result.paymenttoken_1 # => 'QQ8TR7J8P0IQ9TOL'

$ language: python

language: php $$ CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsDeletePaymentType = new DeletePaymentTypeParams();
$paramsDeletePaymentType->token = $resultAddCustomer->customerToken;
$paramsDeletePaymentType->paymentTypeToDeletes[0] = new PaymentTypeToDelete();
$paramsDeletePaymentType->paymentTypeToDeletes[0]->token = $resultAddCustomer->paymentTokens[0];

$resultDeletePaymentType = self::$sparrow->DeletePaymentType($paramsDeletePaymentType)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'BC5Z67O9P8ODXDRQ' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // BC5Z67O9P8ODXDRQ
$resultAddCustomer.p;    // 5JMQNUZ8CVX4015M

RESULT DeletePaymentType:

$resultDeletePaymentType.isSuccess;    // 1
$resultDeletePaymentType.response;    // 1
$resultDeletePaymentType.textResponse;    // Customer with token 'BC5Z67O9P8ODXDRQ' successfully updated
$resultDeletePaymentType.type;    // updatecustomer
$resultDeletePaymentType.customerToken;    // BC5Z67O9P8ODXDRQ
$resultDeletePaymentType.p;    // 5JMQNUZ8CVX4015M

Delete Data Vault Customer

Variable Name Format Description
mkey Secured merchant key
transtype deletecustomer This transaction type will update the current client information with any new data fields provided
token alphanumericstring Unique customer identifier
mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=deletecustomer&token=B31388EA20ABF2776C93

Command Line:

curl -d "mkey=$M_KEY&\
transtype=deletecustomer&\
token=FX60NPVJY2Y18KZA" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
type=deletecustomer

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.DeleteDataVaultCustomer(
    token: resultAddCustomer.CustomerToken);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'BY7F1K0J4252GRGD' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // BY7F1K0J4252GRGD
resultAddCustomer.PaymentTokens[0];    // UBY9KEP6DXUOUOFX

RESULT:

result.Response;    // 1
result.TextResponse;    // SUCCESS
result.Type;    // deletecustomer

CODE:


api.delete_customer({
  token: 'LFC0KIYV18APRLCH',
})

RESULT:



result.response # => '1'
result.textresponse # => 'SUCCESS'
result.type # => 'deletecustomer'

CODE:


resp = sprw.customers.delete(customer_token)

RESULT:


{
    "response": "1",
    "textresponse": "SUCCESS",
    "type": "deletecustomer"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsDeleteDataVaultCustomer = new DeleteDataVaultCustomerParams();
$paramsDeleteDataVaultCustomer->token = $resultAddCustomer->customerToken;

$resultDeleteDataVaultCustomer = self::$sparrow->DeleteDataVaultCustomer($paramsDeleteDataVaultCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'CVOXWSYCS003CW1M' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // CVOXWSYCS003CW1M
$resultAddCustomer.p;    // YYMNPGJYB4AIQJN3

RESULT DeleteDataVaultCustomer:

$resultDeleteDataVaultCustomer.isSuccess;    // 1
$resultDeleteDataVaultCustomer.response;    // 1
$resultDeleteDataVaultCustomer.textResponse;    // SUCCESS
$resultDeleteDataVaultCustomer.type;    // deletecustomer

Retrieve Customer

Variable Name Format Description
mkey Secured merchant account key
transtype getcustomer
token alphanumeric string Unique customer identifier

Response from the gateway will be as follows:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
CustomerStatus Customer status
CustomerID External customer identifier
company Billing company name
firstname Billing first name
lastname Billing last name
address1 Billing address
address2 Billing address – line 2
city Billing city
zip Billing postal code
country CC (ISO-3166) Billing country (ie. US)
state 2 character abbreviation Billing state
phone Billing phone number
fax Billing fax number
email Billing email address
shipcompany Shipping company name
shipfirstname Shipping first name
shiplastname Shipping last name
shipaddress1 Shipping address
shipaddress2 Shipping address – line 2
shipcity Shipping city
shipzip Shipping postal code
shipcountry CC (ISO-3166) Billing country (ie. US)
shipstate 2 character abbreviation Shipping state
shipphone Shipping phone number
shipfax Shipping fax number
shipemail Shipping email address
token_# alphanumeric string Payment Type unique identifier
paytype_# creditcard / check / ach / starcard / cash /ewallet Type of payment info
payno_# positive integer Priority of the payment type among others, when sending payment using customer’s token
account_# Masked account number
paymentdescription_# alphanumeric string Description of Data Vault payment info
cardexp_# MMYY Credit card expiration date (ie. 0719 = 7/2019)
useAccountUpdater_# true / false If true, the account updater updates this payment info
company_# Billing company name, specific for the payment type
firstname_# Billing first name, specific for the payment type
lastname_# Billing last name , specific for the payment type
address1_# Billing address , specific for the payment type
address2_# Billing address – line 2, specific for the payment type
city_# Billing city, specific for the payment type
zip_# Billing postal code, specific for the payment type
country_# CC (ISO-3166) Billing country (ie. US), specific for the payment type
state_# 2 character abbreviation Billing state, specific for the payment type
phone_# Billing phone number, specific for the payment type
fax_# Billing fax number, specific for the payment type
email_# Billing email address, specific for the payment type


mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=getcustomer&token=VGHBVEKS8TDRKUC2

Expected Response

response=1&textresponse=Processed&customertoken=VGHBVEKS8TDRKUC2&CustomerStatus=Active&company=&firstname=John&lastname=Smith&address1=330+Stewart+Street&address2=&city=Indianapolis&email=&country=US&state=IN&phone=&fax=&zip=46268&shipcompany=&shipfirstname=&shiplastname=&shipaddress1=&shipaddress2=&shipcity=&shipemail=&shipphone=&shipfax=&shipzip=&paytype_1=CreditCard&payno_1=1&paymentdescription_1=&cardexp_1=1221&account_1=411111******1111&company_1=&firstname_1=John&lastname_1=Smith&address1_1=1947+Sumner+Street&address2_1=&city_1=Rancho+Dominguez&email_1=&country_1=US&state_1=CA&phone_1=&fax_1=&zip_1=90220&useAccountUpdater_1=True&token_1=6AWRPCF8C4DZ6UU2
No content for this section.

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, 
    paymentType: new []{ new Sparrow.PaymentType{ ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.RetrieveCustomer(
    token: resultAddCustomer.CustomerToken);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'XIE6MFCW2C26RYZ1' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // XIE6MFCW2C26RYZ1
resultAddCustomer.PaymentTokens[0];    // M9NWKGFXTI195F54

RESULT:

result.Response;    // 1
result.TextResponse;    // Processed
result.CustomerToken;    // XIE6MFCW2C26RYZ1
result.FirstName;    // John
result.LastName;    // Doe

CODE:


api.get_customer({
  token: 'LFC0KIYV18APRLCH',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Processed'
result.customertoken # => 'LFC0KIYV18APRLCH'
result.CustomerStatus # => 'Active'
result.firstname # => 'Dude'
result.lastname # => 'Fella'
result.paytype_1 # => 'CreditCard'
result.payno_1 # => '1'
result.cardexp_1 # => '1019'
result.account_1 # => '411111******1111'
result.useAccountUpdater_1 # => 'False'
result.token_1 # => 'QQ8TR7J8P0IQ9TOL'

CODE:


resp = sprw.customers.get("LFC0KIYV18APRLCH")

RESULT:


{
  "response": "1",
  "textresponse": "Processed",
  "customertoken": "LFC0KIYV18APRLCH",
  "CustomerStatus": "Active",
  "firstname": "Dude",
  "lastname": "Fella",
  "paytype_1": "CreditCard",
  "payno_1": "1",
  "cardexp_1": "1019",
  "account_1": "411111******1111",
  "useAccountUpdater_1": "False",
  "token_1": "QQ8TR7J8P0IQ9TOL"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsRetrieveCustomer = new RetrieveCustomerParams();
$paramsRetrieveCustomer->token = $resultAddCustomer->customerToken;

$resultRetrieveCustomer = self::$sparrow->RetrieveCustomer($paramsRetrieveCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'L8BW1SYRFGI9C8V6' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // L8BW1SYRFGI9C8V6
$resultAddCustomer.p;    // Z26C9TLQN7XLKUJX

RESULT RetrieveCustomer:

$resultRetrieveCustomer.isSuccess;    // 1
$resultRetrieveCustomer.response;    // 1
$resultRetrieveCustomer.textResponse;    // Processed
$resultRetrieveCustomer.customerToken;    // L8BW1SYRFGI9C8V6
$resultRetrieveCustomer.firstName;    // John
$resultRetrieveCustomer.lastName;    // Doe

Retrieve Payment Type

Variable Name Format Description
mkey Secured merchant account key
transtype getcustomer
token alphanumeric string Unique payment type identifier

Response from the gateway will be as follows:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token Payment Type unique identifier
paytype creditcard / check / ach / starcard / cash /ewallet Type of payment info
payno positive integer Priority of the payment type among others, when sending payment using customer’s token
account Masked account number
paymentdescription alphanumeric string Description of Data Vault payment info
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019)
useAccountUpdater true / false If true, the account updater updates this payment info
company Billing company name
firstname Billing first name
lastname Billing last name
address1 Billing address
address2 Billing address – line 2
city Billing city
zip Billing postal code
country CC (ISO-3166) Billing country (ie. US)
state 2 character abbreviation Billing state
phone Billing phone number
fax Billing fax number
email Billing email address

mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=getcustomer&token=6AWRPCF7C4DZ6UU2

Expected Response

response=1&textresponse=Processed&paytype=CreditCard&payno=1&paymentdescription=&cardexp=1221&account=411111******1111&company=&firstname=John&lastname=Smith&address1=1947+Sumner+Street&address2=&city=Rancho+Dominguez&email=&country=US&state=CA&phone=&fax=&zip=90220&useAccountUpdater=True&token=6AWRPCF7C4DZ6UU2&customertoken=VGHBVEKS1TDRKUC2
No content for this section.

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, 
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var result = await _sparrow.RetrievePaymentType(
    token: resultAddCustomer.PaymentTokens[0]);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'YHD8GOI55SHOJ4PU' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // YHD8GOI55SHOJ4PU
resultAddCustomer.PaymentTokens[0];    // LK118CERCRMEND0W

RESULT:

result.Response;    // 1
result.TextResponse;    // Processed
result.CustomerToken;    // YHD8GOI55SHOJ4PU
result.FirstName;    // John
result.LastName;    // Doe
result.PayType;    // CreditCard
result.PayNo;    // 1
result.CardExp;    // 1019
result.Account;    // 411111******1111
result.Token;    // LK118CERCRMEND0W

CODE:


api.get_payment_type({
  token: 'QQ8TR7J8P0IQ9TOL',
})

RESULT:



result.response # => '1'
result.textresponse # => 'Processed'
result.paytype # => 'CreditCard'
result.payno # => '1'
result.cardexp # => '1019'
result.account # => '411111******1111'
result.useAccountUpdater # => 'False'
result.token # => 'QQ8TR7J8P0IQ9TOL'
result.customertoken # => 'LFC0KIYV18APRLCH'

CODE:


resp = sprw.customers.get_payment_type("QQ8TR7J8P0IQ9TOL")

RESULT:


{
    "response": "1",
    "textresponse": "Processed",
    "paytype": "CreditCard",
    "payno": "1",
    "cardexp": "1019",
    "account": "411111******1111",
    "useAccountUpdater": "False",
    "token": "QQ8TR7J8P0IQ9TOL",
    "customertoken": "LFC0KIYV18APRLCH"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsRetrievePaymentType = new RetrievePaymentTypeParams();
$paramsRetrievePaymentType->token = $resultAddCustomer->paymentTokens[0];

$resultRetrievePaymentType = self::$sparrow->RetrievePaymentType($paramsRetrievePaymentType)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'DC1ZB5ZMV4LHLZ5D' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // DC1ZB5ZMV4LHLZ5D
$resultAddCustomer.p;    // 90F752M2WUI35NHV

RESULT RetrievePaymentType:

$resultRetrievePaymentType.isSuccess;    // 1
$resultRetrievePaymentType.response;    // 1
$resultRetrievePaymentType.textResponse;    // Processed
$resultRetrievePaymentType.customerToken;    // DC1ZB5ZMV4LHLZ5D
$resultRetrievePaymentType.firstName;    // John
$resultRetrievePaymentType.lastName;    // Doe
$resultRetrievePaymentType.payType;    // CreditCard
$resultRetrievePaymentType.payNo;    // 1
$resultRetrievePaymentType.cardExp;    // 1019
$resultRetrievePaymentType.account;    // 411111******1111
$resultRetrievePaymentType.token;    // 90F752M2WUI35NHV

Decrypt Payment Type

Variable Name Format Description
mkey Secured merchant account key
transtype decrypt
token alphanumeric string Unique payment type identifier

Response for Credit Card payment type:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token alphanumeric string Payment Type unique identifier
paytype creditcard Type of payment info
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019)
mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=decrypt&token=6AWRPCF7C2DZ6UU2

Expected Response

response=1&textresponse=Processed&cardnum=4111111111111111&cardexp=1221&customertoken=VGHBVEKS2TDRKUC1&token=6AWRPCF7C2DZ6UU2&paytype=CreditCard

Response for ACH payment type:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token alphanumeric string Payment Type unique identifier
paytype ach Type of payment info
bankname Bank name
routing Bank routing number
account Bank account number
achaccounttype checking / savings Type of account
achaccountsubtype business / personal Subtype of account
checknumber Check Number
company Company name
firstname Billing first name
lastname Billing last name
mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=decrypt&token=LZCBU040WXKKXHR1

Expected Response

response=1&textresponse=Processed&bankname=Bank+name&routing=123456&account=987654321&achaccounttype=Checking&achaccountsubtype=Personal&checknumber=5678&customertoken=VGHBVEKS1TDRKUC1&token=LZCBU040WXKKXHR1&paytype=Ach&firstname=John&lastname=Smith

Response for eCheck payment type:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token alphanumeric string Payment Type unique identifier
paytype check Type of payment info
bankname Bank name
routing Bank routing number
account Bank account number
achaccounttype business / personal Type of account
company Company name
firstname Billing first name
lastname Billing last name
mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=decrypt&token=A5MQFQPQ9KY8B5E1

Expected Response

response=1&textresponse=Processed&bankname=Bank+name&routing=123456789&account=987654321&achaccounttype=Business&customertoken=VGHBVEKS1TDRKUC1&token=A5MQFQPQ9KY8B5E1&paytype=Check&company=Beasts+of+Beauty

Response for Star Card payment type:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token alphanumeric string Payment Type unique identifier
paytype starcard Type of payment info
cardnum Credit card number
mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=decrypt&token=ODUFV8P12KRM8QK1

Expected Response

response=1&textresponse=Processed&cardnum=6019451602641830&customertoken=VGHBVEKS1TDRKUC1&token=ODUFV8P12KRM8QK1&paytype=StarCard

Response for eWallet payment type:

Variable Name Format Description
response Operation result code
textresponse Textual response
customertoken alphanumeric string Customer unique identifier
token alphanumeric string Payment Type unique identifier
paytype ewallet Type of payment info
ewalletaccount eWallet account credentials
ewallettype paypal Type of eWallet

mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=decrypt&token=3MK4184FCER633W1

Expected Response

response=1&textresponse=Processed&ewallettype=PayPal&ewalletaccount=test%40email.com&customertoken=VGHBVEKS1TDRKUC1&token=3MK4184FCER633W1&paytype=EWallet
No content for this section.

Tokenized Payments

Sale, Auth and Credit operations could be processed using Data Vault client info. For tokenized payment you can use token of the payment type or Data Vault client's token. If client's token is used then the first client's payment type will be used to process the payment. Please see an example below.

mkey=MTA6MzM6NTYgUE0tLVBheVRhY3RpeALO&transtype=sale&token=0558050763310762&amount=10

Expected Response

response=1&textresponse=SUCCESS&transid=1007397&xref=3393966934&authcode=123456&orderid=&type=sale&avsresponse=N&cvvresponse=&coderesponse=100&codedescription=Transaction+was+Approved&status=200

Merchant can check “Allow to override Billing information for tokenized payments” option on the Configuration Values page (Merchant portal ⇢ Data Vault ⇢ Administration ⇢ Configuration Settings) to allow system to override billing and shipping information with information from the tokenized API request.

If option is checked billing and shipping fields can be present in the request even when token is specified. Parameters specified in the request will override corresponding client's parameters for the payment. So payment will be processed with specified parameters but Data Vault client's info won’t be updated.

No content for this section.

Creating Custom Payment Plans

Unique payment plans can be created to automatically bill customer using custom amounts and frequencies

Creating a Payment Plan

First we must describe our plan

Variable Name Format Description
mkey Secured merchant account key
transtype addplan
planname string Payment plan name
plandesc string Payment plan description
startdate MM/DD/YYYY Starting day of the plan
defaultachmkey Merchant key of ACH account with which plan payments should be processed by default
defaultcreditcardmkey Merchant key of Credit Card account with which plan payments should be processed by default
defaultecheckmkey Merchant key of eCheck account with which plan payments should be processed by default
defaultstartcardmkey Merchant key of Star Card account with which plan payments should be processed by default
defaultewalletmkey Merchant key of eWallet account with which plan payments should be processed by default

Command Line:

curl -d "mkey=$M_KEY&\
transtype=addplan&\
planname=PaymentPlan1&\
plandesc=1st Payment Plan&\
startdate=01/31/2017&\
defaultachmkey=$ACH_M_KEY&\
defaultcreditcardmkey=$M_KEY&\
defaultcheckmkey=$M_KEY&\
defaultstarcardmkey=$M_KEY&\
defaulte_walletmkey=$M_KEY&\
sequence_1=1&\
sequence_2=2&\
amount_1=1.99&\
amount_2=2.99&\
scheduletype_1=custom&\
scheduletype_2=monthly&\
scheduleday_1=7&\
scheduleday_2=1&\
duration_1=365&\
duration_2=-1&\
productid_1=abc&\
productid_2=123&\
description_1=Weekly&\
description_2=Monthly&\
notifyfailures=false&\
userecycling=true&\
retrycount=2&\
retrytype=daily&\
retryperiod=1&\
autocreateclientaccounts=true" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
type=addplan&
plantoken=76Y5QQT2LV54J5SE

CODE:

var result = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });

RESULT:

result.Response;    // 1
result.TextResponse;    // SUCCESS
result.Type;    // addplan
result.PlanToken;    // C17KAJUGB2SWV0OW

CODE:


resp = sprw.plans.create(data=dict(
    mkey=M_KEY,
    planname="PaymentPlan1",
    plandesc="1st Payment Plan",
    startdate="01/31/2017",
    sequence_1=1,
    amount_1=1.99,
    scheduletype_1="custom",
    scheduleday_1=7,
    duration_1=365,
))

RESULT:


{
    "plantoken": "6S0ZJGIQGL1T2XXQ",
    "response": "1",
    "textresponse": "SUCCESS",
    "type": "addplan"
}

CODE:

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // 1PAXMAY2TEILKDSC

Updating a Payment Plan

Payment Plans can be updated by using the transaction type “updateplan”.

Variable Name Format Description
mkey Secured merchant account key
transtype updateplan
token Unique payment plan identifier
planname string Payment plan name
plandesc string Payment plan description
startdate MM/DD/YYYY Starting day of the plan
defaultachmkey Merchant key of ACH account with which plan payments should be processed by default
defaultcreditcardmkey Merchant key of Credit Card account with which plan payments should be processed by default
defaultecheckmkey Merchant key of eCheck account with which plan payments should be processed by default
defaultstartcardmkey Merchant key of Star Card account with which plan payments should be processed by default
defaultewalletmkey Merchant key of eWallet account with which plan payments should be processed by default
userecycling true/false Specifies whether to reprocess failed transactions in this plan
notifyfailures true/false Sends notification emails to the client in case of failed payments
retrycount positive integer Number of times to retry each failed transaction. This field is required if transaction recycling is activated, and ignored otherwise
retrytype daily / weekly / monthly Specifies the type of retry schedule
retryperiod positive integer Number of days between retry attempts. This field is required if retrytype=daily
retrydayofweek string This field is required if retrytype=weekly (monday, tuesday etc.)
retryfirstdayofmonth positive integer First date of retry schedule. This field is required if retrytype=monthly
retryseconddayofmonth positive integer Second date of retry schedule. This field is required if retrytype=monthly
autocreateclientaccounts true / false Creates username and password for Client Portal automatically when plan is assigned to the client
mkey=HMNK8687DVJHG45D4D3KL90&transtype=updateplan&token=HJFK87G5JBN0&userecycling=false&senderemail=accounting@test.com&reviewonassignment=false

Command Line:

curl -d "mkey=$M_KEY&\
transtype=updateplan&\
token=I4LYCSV3FMGDTA9G&\
planname=PaymentPlan1&\
plandesc=1st Payment Plan&\
startdate=01/31/2017&\
defaultachmkey=$ACH_M_KEY&\
defaultcreditcardmkey=$M_KEY&\
defaultcheckmkey=$M_KEY&\
defaultstarcardmkey=$M_KEY&\
defaulte_walletmkey=$M_KEY&\
userrecycling=true&\
notifyfailures=true&\
retrycount=2&\
retrytype=daily&\
retryperiod=2&\
autocreateclientaccounts=true" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
type=updateplan

CODE:

var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 10.00m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var result = await _sparrow.UpdatePaymentPlan(
    token: resultCreatePaymentPlan.PlanToken,
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 20.00m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12, OperationType = Sparrow.OperationType.Updatesequence } });

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // 0GHHZ4TB1FAUVVCN

RESULT:

result.Response;    // 1
result.TextResponse;    // SUCCESS
result.Type;    // updateplan

CODE:


resp = sprw.plans.update(plan_token, data=dict(
    planname="PaymentPlan1Updated",
))

RESULT:


{
    "response": "1",
    "textresponse": "SUCCESS",
    "type": "updateplan"
}

CODE:

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 10.00;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsUpdatePaymentPlan = new UpdatePaymentPlanParams();
$paramsUpdatePaymentPlan->token = $resultCreatePaymentPlan->planToken;
$paramsUpdatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsUpdatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsUpdatePaymentPlan->sequenceStepss[0]->amount = 20.00;
$paramsUpdatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsUpdatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsUpdatePaymentPlan->sequenceStepss[0]->duration = 12;
$paramsUpdatePaymentPlan->sequenceStepss[0]->operationType = OperationType::UPDATESEQUENCE;

$resultUpdatePaymentPlan = self::$sparrow->UpdatePaymentPlan($paramsUpdatePaymentPlan)->wait();

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // 2CYQTFQRH3UZ1FV7

RESULT UpdatePaymentPlan:

$resultUpdatePaymentPlan.isSuccess;    // 1
$resultUpdatePaymentPlan.response;    // 1
$resultUpdatePaymentPlan.textResponse;    // SUCCESS
$resultUpdatePaymentPlan.type;    // updateplan

Building a Sequence

Now we define the sequences within the plan which determine how much the customer will be charged and when

Variable Name Format Description
sequence_# positive integer The sequence number defines which set of payments should occur first, second third, etc; if multiple sequences are present
amount_#​ d.dd Amount to be paid
scheduletype_# monthly/ custom/ annual Specifies the type of payment schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
scheduleday_#​ positive integer Day of the month for processing payments (scheduletype=monthly) or number of days between payments (scheduletype=custom)
duration_# integer Positive number of charges or -1 if no limit
productid_# string External ID for the product
description_# string Description of the sequence
notifyfailures true/false Sends notification emails to the client if failed payments occur
userecycling true/false Specifies whether to reprocess failed transactions for this plan
defaultewalletmkey Merchant key of eWallet account with which plan payments should be processed by default
retrycount positive integer Number of times to retry each failed transaction. This field is required if transaction recycling is activated, and ignored otherwise
retrytype daily/ weekly/ monthly Specifies the type of retry schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
retryperiod positive integer Number of days between retry attempts. This field is required if retrytype=daily
retrydayofweek string This field is required if retrytype=weekly (monday, tuesday etc.)
retryfirstdayofmonth positive integer First date of retry schedule. This field is required if retrytype=monthly
retryseconddayofmonth positive integer Second date of retry schedule. This field is required if retrytype=monthly
autocreateclientaccounts true/false Creates username and password for Client Portal automatically when plan is assigned to the client

Command Line:

curl -d "amount_#=1.99;2.99&\
scheduletype_#=monthly;custom&\
duration=-1;-1&\
productid_#=123;321&\
description_#=Blue widget;Brown widget&\
notifyfailures=true&\
userecycling=true&\
defaultewalletmkey=T6YQTCA3RK3IEW8R14ITSJBI&\
retrycount=2&\
retrytype=daily&\
retryperiod=2&\
autocreateclientaccounts=true" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Required+payment+field+transtype+is+missing

Notification Settings

We must also set notification settings to alert customers of successful payments, passed due payment, plan changes, etc.

Variable Name Format Description
reviewonassignment true/false If “true” this will set the payment plan to pending until it is reviewed by the merchant admin
processimmediately true/false Specifies if new payments should be processed immediately or end of day
overridesender true/false Specifies whether to override sender email for customers notifications
senderemail email Sender email. This field is required if overridesender = true
notifyupcomingpayment true/false Specifies whether to notify customer about upcoming payment
notifydaysbeforeupcomingpayment positive integer Number of days before notification about upcoming payment should be sent to the client. This field is required if notifyupcomingpayment = true
notifyplansummary true/false Specifies whether to send merchant a Summarized Plan Report
notifyplansummaryinterval daily / weekly / monthly / quaterly Interval of plan summary notifications. This field is required if notifyplansummary = true
notifyplansummaryemails Multiple addresses are separated by comma. This field is required if notifyplansummary = true
notifydailystats true/false Specifies whether to send merchant a Daily Plan Processing Statistics Report
notifydailystatsemails Multiple addresses are separated by comma. This field is required if notifydailystats = true
notifyplancomplete true/false Specifies whether to notify merchant about plan completion
notifyplancompleteemails Multiple addresses are separated by comma. This field is required if notifyplancomplete = true
notifydecline true/false Specifies whether to notify merchant about failed payments
notifydeclineemails Multiple addresses are separated by comma. This field is required if notifydecline = true
notifyviaftp true/false Specifies whether to transfer transaction file via ftp
notifyviaftpurl true/false FTP address on which transaction file is transferred. This field is required if notifyviaftp = true
notifyviaftpusername Username to access FTP address. This field is required if notifyviaftp = true
notifyviaftppassword Password to access FTP address. This field is required if notifyviaftp = true
notifyflagged true/false Specifies whether to notify merchant about flagged for review payments
notifyflaggedemails Multiple addresses are separated by comma. This field is required if notifyflagged = true

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=addplan&planname=Monthly+fees&plandesc=Some+long+description.&startdate=4/13/2017&sequence_1=1&amount_1=12.45&scheduletype_1=monthly&scheduleday_1=5&duration_1=10

***This request will create a new payment plan starting on April 13, 2017 with one sequence, defining 10 payments, each on 5th day of the month (i.e. payments will be made on May 5, June 5, July 5, and so on).

Command Line:

curl -d "" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Required+payment+field+transtype+is+missing&
errorcode=

Adding or Updating a Sequence

We can also add a new sequence or update an existing plan sequence.

Variable Name Format Description
operationtype_# addsequence/updatesequence Addsequence will add a new sequence, whereas Updatesequence will update an existing sequence
sequence_#​ positive integer The sequence number defines which set of payments should occur first, second third, etc; if multiple sequences are present
amount_#​ d.dd Amount to be paid
scheduletype_# monthly/ custom/ annual Specifies the type of payment schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
scheduleday_#​ positive integer Day of the month for processing payments (scheduletype=monthly) or number of days between payments (scheduletype=custom)
duration_# integer Positive number of charges or -1 if no limit
productid_# string External ID for the product
description_# string Description of the sequence
newsequence_# positive integer New number for the sequence
notifyfailures true/false Sends notification emails to the client if failed payments occur
userecycling true/false Specifies whether to reprocess failed transactions for this plan
defaultewalletmkey Merchant key of eWallet account with which plan payments should be processed by default
retrycount positive integer Number of times to retry each failed transaction. This field is required if transaction recycling is activated, and ignored otherwise
retrytype daily/ weekly/ monthly Specifies the type of retry schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
retryperiod positive integer Number of days between retry attempts. This field is required if retrytype=daily
retrydayofweek string This field is required if retrytype=weekly (monday, tuesday etc.)
retryfirstdayofmonth positive integer First date of retry schedule. This field is required if retrytype=monthly
retryseconddayofmonth positive integer Second date of retry schedule. This field is required if retrytype=monthly
autocreateclientaccounts true/false Creates username and password for Client Portal automatically when plan is assigned to the client

Add Sequence

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updateplan&token=HJFK87G5JBN0&operationtype_1=addsequence&sequence_1=2&amount_1=9.99&scheduletype_1=monthly&scheduleday_1=5&duration_1=12

Update Sequence

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updateplan&token=HJFK87G5JBN0&operationtype_1=updatesequence&sequence_1=2&amount_1=10.99&scheduletype_1=monthly&scheduleday_1=5&duration_1=12

Command Line:

curl -d "amount_#=1.99;2.99&\
scheduletype_#=monthly;custom&\
duration=-1;-1&\
productid_#=123;321&\
description_#=Blue widget;Brown widget&\
notifyfailures=true&\
userecycling=true&\
defaultewalletmkey=T6YQTCA3RK3IEW8R14ITSJBI&\
retrycount=2&\
retrytype=daily&\
retryperiod=2&\
autocreateclientaccounts=true" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Required+payment+field+transtype+is+missing&
errorcode=

Deleting a Sequence

We can also delete a sequence.

Variable Name Format Description
operationtype_# deletesequence This will delete a sequence
sequence_# positive integer Sequence to be deleted
mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=updateplan&token=HJFK87G5JBN0&operationtype_1=deletesequence&sequence_1=2

Command Line:

curl -d "" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=3&
textresponse=Required+payment+field+transtype+is+missing&
errorcode=&

CODE:

var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1", 
    planDesc: "1st Payment Plan", 
    startDate: new DateTime(2019,10,21), 
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var result = await _sparrow.DeleteSequence(
    deleteSequenceSteps: new []{ new Sparrow.SequenceStepToDelete{ Sequence = 1 } }, 
    token: resultCreatePaymentPlan.PlanToken);

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // X16TGWE4V6Z5X90W

RESULT:

result.Response;    // 1
result.TextResponse;    // SUCCESS
result.Type;    // updateplan

CODE:


resp = sprw.plans.update(plan_token, data=dict(
    operationtype_1="deletesequence",
    sequence_1=2,
))

RESULT:


{
    "response": "1",
    "textresponse": "SUCCESS",
    "type": "updateplan"
}

CODE:

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsDeleteSequence = new DeleteSequenceParams();
$paramsDeleteSequence->deleteSequenceStepss[0] = new SequenceStepToDelete();
$paramsDeleteSequence->deleteSequenceStepss[0]->sequence = 1;
$paramsDeleteSequence->token = $resultCreatePaymentPlan->planToken;

$resultDeleteSequence = self::$sparrow->DeleteSequence($paramsDeleteSequence)->wait();

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // RRR4A4H85CE86SFI

RESULT DeleteSequence:

$resultDeleteSequence.isSuccess;    // 1
$resultDeleteSequence.response;    // 1
$resultDeleteSequence.textResponse;    // SUCCESS
$resultDeleteSequence.type;    // updateplan

Deleting a Plan

We can also delete an entire plan.

Variable Name Format Description
mkey Secured merchant account key
transtype deleteplan
token alphanumeric string Payment plan unique identifier
cancelpayments true/false Specifies whether to cancel pending payments caused by assignments of this plan. Default value is false
mkey=HMNK8687DVJHG45D4D3KL90&transtype=deleteplan&token=HJFK87G5JBN0&cancelpayments=true

Command Line:

curl -d "mkey=$M_KEY&\
transtype=deleteplan&\
token=315KMHH74U690DS5&\
cancelpayments=true" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=SUCCESS&
type=deleteplan

CODE:

var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var result = await _sparrow.DeletePlan(
    token: resultCreatePaymentPlan.PlanToken);

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // DRJWXFITUP47M13F

RESULT:

result.Response;    // 1
result.TextResponse;    // SUCCESS
result.Type;    // deleteplan

CODE:


resp = sprw.plans.delete(plan_token)

RESULT:


{
    "response": "1",
    "textresponse": "SUCCESS",
    "type": "deleteplan"
}

CODE:

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsDeletePlan = new DeletePlanParams();
$paramsDeletePlan->token = $resultCreatePaymentPlan->planToken;

$resultDeletePlan = self::$sparrow->DeletePlan($paramsDeletePlan)->wait();

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // 9056DMDZBUPL6TTZ

RESULT DeletePlan:

$resultDeletePlan.isSuccess;    // 1
$resultDeletePlan.response;    // 1
$resultDeletePlan.textResponse;    // SUCCESS
$resultDeletePlan.type;    // deleteplan

Assigning a Payment Plan to a Customer

Payment plans can be assigned to multiple Data Vault customers

Variable Name Format Description
mkey Secure merchant account key
transtype assignplan
customertoken alphanumeric string Customer unique identifier
plantoken alphanumeric string Recurring payment plan unique identifier; used when assigning existing plan to the customer
paymenttoken alphanumeric string Token of the customer’s payment type, if they have multiple
startdate MM/DD/YYYY Day of the first payment of the plan; if not present the plan’s start date (if it exists) is used.
productid string External ID for the product
description string Description of plan assignment
amount d.dd Amount purchased. This field is required for layaway plan assignment and ignored otherwise
notifyfailures true/false Sends notification emails to the client if failed payments occur
userecycling true/false Specifies whether to reprocess failed transactions for this plan
retrycount positive integer Number of times to retry each failed transaction. This field is required if transaction recycling is activated, and ignored otherwise
retrytype daily/ weekly/ monthly Specifies the type of retry schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
retryperiod positive integer Number of days between retry attempts. This field is required if retrytype=daily
retrydayofweek string This field is required if retrytype=weekly (monday, tuesday etc.)
retryfirstdayofmonth positive integer First date of retry schedule. This field is required if retrytype=monthly
retryseconddayofmonth positive integer Second date of retry schedule. This field is required if retrytype=monthly
proratedpayment true / false Specifies whether to add prorated payment in this plan
routingkey Merchant key of account with which plan payments should be processed by default. This account must be of the same type as selected customer’s payment type

mkey=JHG48D3V6N8HKFF3W221AA&transtype=assignplan&customertoken=HJG543D321HJK&&paymenttoken=9K7US80YUQ1LPN27&plantoken=JHG78HJGF55&startdate=10/01/2017&notifyfailures=true

Command Line:

curl -d "mkey=$M_KEY&\
transtype=assignplan&\
customertoken=F6OE0IN0I5HSV6AJ&\
plantoken=76Y5QQT2LV54J5SE&\
paymenttoken=9K7US80YUQ1LPN27&\
startdate=01/31/2017&\
notifyfailures=true&\
userecycling=true&\
retrycount=2&\
retrytype=daily&\
retryperiod=2&\
notifyfailuresemails=jdoe@example.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Success&
type=assignplan&
assignmenttoken=JCXG572GBX20NFDF

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var result = await _sparrow.AssignPaymentPlanToCustomer(
    customerToken: resultAddCustomer.CustomerToken,
    planToken: resultCreatePaymentPlan.PlanToken,
    paymentToken: resultAddCustomer.PaymentTokens[0]);

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token '7P8FPQCQYSSYEFCL' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // 7P8FPQCQYSSYEFCL
resultAddCustomer.PaymentTokens[0];    // DTLYC9IM2C4MH1PA

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // 7OOKMD2ATZ8MKX8V

RESULT:

result.Response;    // 1
result.TextResponse;    // Success
result.Type;    // assignplan
result.AssignmentToken;    // OSS6DU853EXQSWID

CODE:


resp = sprw.plans.assign(plan_token,
                        customer_token,
                        payment_token)

RESULT:


{
    "assignmenttoken": "4CVWUY1VSQA4OHEX",
    "response": "1",
    "textresponse": "Success",
    "type": "assignplan"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsAssignPaymentPlanToCustomer = new AssignPaymentPlanToCustomerParams();
$paramsAssignPaymentPlanToCustomer->customerToken = $resultAddCustomer->customerToken;
$paramsAssignPaymentPlanToCustomer->planToken = $resultCreatePaymentPlan->planToken;
$paramsAssignPaymentPlanToCustomer->paymentToken = $resultAddCustomer->paymentTokens[0];

$resultAssignPaymentPlanToCustomer = self::$sparrow->AssignPaymentPlanToCustomer($paramsAssignPaymentPlanToCustomer)->wait();

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'M8A8K5F8GJIWYU9R' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // M8A8K5F8GJIWYU9R
$resultAddCustomer.p;    // 38FWR7OMZMG7POS2

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // DYIC0DZC1VZ3ADEM

RESULT AssignPaymentPlanToCustomer:

$resultAssignPaymentPlanToCustomer.isSuccess;    // 1
$resultAssignPaymentPlanToCustomer.response;    // 1
$resultAssignPaymentPlanToCustomer.textResponse;    // Success
$resultAssignPaymentPlanToCustomer.type;    // assignplan
$resultAssignPaymentPlanToCustomer.assignmentToken;    // WAI93BPANGWL3WJG

Update Payment Plan Assignment

Payment Plan assignments may be updated

Variable Name Format Description
mkey Secure merchant account key
transtype updateassignment
assignmenttoken alphanumeric string Unique identifier of payment plan assignment
paymenttoken alphanumeric string Token of the customer’s payment type, if they have multiple
startdate MM/DD/YYYY Day of the first payment of the plan; if not present the plan’s start date (if it exists) is used.
productid string External ID for the product
description string Description of plan assignment
notifyfailures true/false Sends notification emails to the client if failed payments occur
userecycling true/false Specifies whether to reprocess failed transactions for this plan
retrycount positive integer Number of times to retry each failed transaction. This field is required if transaction recycling is activated, and ignored otherwise
retrytype daily/ weekly/ monthly Specifies the type of retry schedule. Supported types are: every month of a specified date, every N days, every year on a specified date
retryperiod positive integer Number of days between retry attempts. This field is required if retrytype=daily
retrydayofweek string This field is required if retrytype=weekly (monday, tuesday etc.)
retryfirstdayofmonth positive integer First date of retry schedule. This field is required if retrytype=monthly
retryseconddayofmonth positive integer Second date of retry schedule. This field is required if retrytype=monthly
proratedpayment true / false Specifies whether to add prorated payment in this plan
routingkey Merchant key of account with which plan payments should be processed by default. This account must be of the same type as selected customer’s payment type

mkey=JHG48D3V6N8HKFF3W221AA&transtype=updateassignment&assignmenttoken=HJG54VKJ888&startdate=11/01/2017&proratedpayment=true

Command Line:

curl -d "mkey=$M_KEY&\
transtype=updateassignment&\
assignmenttoken=4STIQWYX5NM9ZDKJ&\
paymenttoken=E25BCVW6GPAY7LPA&\
startdate=1/1/2018&\
notifyfailures=true&\
userecycling=true&\
retrycount=3&\
retrytype=daily&\
retryperiod=2" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Success&
type=updateassignment&
assignmenttoken=4STIQWYX5NM9ZDKJ

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var resultAssignPaymentPlanToCustomer = await _sparrow.AssignPaymentPlanToCustomer(
    customerToken: resultAddCustomer.CustomerToken,
    planToken: resultCreatePaymentPlan.PlanToken,
    paymentToken: resultAddCustomer.PaymentTokens[0]);
var result = await _sparrow.UpdatePaymentPlanAssignment(
    assignmentToken: resultAssignPaymentPlanToCustomer.AssignmentToken,
    startDate: new DateTime(2019,10,21));

RESULT AssignPaymentPlanToCustomer:

resultAssignPaymentPlanToCustomer.Response;    // 1
resultAssignPaymentPlanToCustomer.TextResponse;    // Success
resultAssignPaymentPlanToCustomer.Type;    // assignplan
resultAssignPaymentPlanToCustomer.AssignmentToken;    // KB5UMCK91864GH2W

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'CPEEHDA9OGDMOPBL' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // CPEEHDA9OGDMOPBL
resultAddCustomer.PaymentTokens[0];    // ONAUCBX8EXRO6A55

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // 4170HM56ZU0RGVJD

RESULT:

result.Response;    // 1
result.TextResponse;    // Success
result.Type;    // updateassignment
result.AssignmentToken;    // KB5UMCK91864GH2W

CODE:


resp = sprw.plans.assign(
    plan_token,
    customer_token,
    payment_token
)
assignment_token = resp["assignmenttoken"]

resp = sprw.plans.update_assignment(
    assignment_token,
    startdate="1/1/2018"
)

RESULT:


{
    "assignmenttoken": "8827HG7JG2URMIXE",
    "response": "1",
    "textresponse": "Success",
    "type": "updateassignment"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsAssignPaymentPlanToCustomer = new AssignPaymentPlanToCustomerParams();
$paramsAssignPaymentPlanToCustomer->customerToken = $resultAddCustomer->customerToken;
$paramsAssignPaymentPlanToCustomer->planToken = $resultCreatePaymentPlan->planToken;
$paramsAssignPaymentPlanToCustomer->paymentToken = $resultAddCustomer->paymentTokens[0];

$resultAssignPaymentPlanToCustomer = self::$sparrow->AssignPaymentPlanToCustomer($paramsAssignPaymentPlanToCustomer)->wait();

$paramsUpdatePaymentPlanAssignment = new UpdatePaymentPlanAssignmentParams();
$paramsUpdatePaymentPlanAssignment->assignmentToken = $resultAssignPaymentPlanToCustomer->assignmentToken;
$paramsUpdatePaymentPlanAssignment->startDate = new DateTime("2019-10-21");

$resultUpdatePaymentPlanAssignment = self::$sparrow->UpdatePaymentPlanAssignment($paramsUpdatePaymentPlanAssignment)->wait();

RESULT AssignPaymentPlanToCustomer:

$resultAssignPaymentPlanToCustomer.isSuccess;    // 1
$resultAssignPaymentPlanToCustomer.response;    // 1
$resultAssignPaymentPlanToCustomer.textResponse;    // Success
$resultAssignPaymentPlanToCustomer.type;    // assignplan
$resultAssignPaymentPlanToCustomer.assignmentToken;    // FF4XM5XOBS3TVT9B

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'DA5XFNOR32OE2RMF' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // DA5XFNOR32OE2RMF
$resultAddCustomer.p;    // W4TNWV3BCQVJ65ER

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // NETYSCNIR50HT6AD

RESULT UpdatePaymentPlanAssignment:

$resultUpdatePaymentPlanAssignment.isSuccess;    // 1
$resultUpdatePaymentPlanAssignment.response;    // 1
$resultUpdatePaymentPlanAssignment.textResponse;    // Success
$resultUpdatePaymentPlanAssignment.type;    // updateassignment
$resultUpdatePaymentPlanAssignment.assignmentToken;    // FF4XM5XOBS3TVT9B

Cancel Plan Assignment

Payment Plan assignments may be cancelled both before and after the plan has begun.

Variable Name Format Description
mkey Secure merchant account key
transtype cancelassignment
assignment​token alphanumeric string Unique identifier of payment plan assignment

mkey=JHG48D3V6N8HKFF3W221AA&transtype=cancelassignment&assignmenttoken=HJG54VKJ888

Command Line:

curl -d "mkey=$M_KEY&\
transtype=cancelassignment&\
assignmenttoken=JCXG572GBX20NFDF" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

response=1&
textresponse=Success&
type=cancelassignment

CODE:

var resultAddCustomer = await _sparrow.AddCustomer(
    defaultContactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" },
    paymentType: new []{ new Sparrow.PaymentType{ PayType = Sparrow.PayType.Creditcard, ContactInfo = new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" }, CreditCard = new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) } } });
var resultCreatePaymentPlan = await _sparrow.CreatePaymentPlan(
    planName: "PaymentPlan1",
    planDesc: "1st Payment Plan",
    startDate: new DateTime(2019,10,21),
    sequenceSteps: new []{ new Sparrow.SequenceStep{ Sequence = 1, Amount = 9.99m, ScheduleType = Sparrow.ScheduleType.Monthly, ScheduleDay = 5, Duration = 12 } });
var resultAssignPaymentPlanToCustomer = await _sparrow.AssignPaymentPlanToCustomer(
    customerToken: resultAddCustomer.CustomerToken,
    planToken: resultCreatePaymentPlan.PlanToken,
    paymentToken: resultAddCustomer.PaymentTokens[0]);
var result = await _sparrow.CancelPlanAssignment(
    assignmentToken: resultAssignPaymentPlanToCustomer.AssignmentToken);

RESULT AssignPaymentPlanToCustomer:

resultAssignPaymentPlanToCustomer.Response;    // 1
resultAssignPaymentPlanToCustomer.TextResponse;    // Success
resultAssignPaymentPlanToCustomer.Type;    // assignplan
resultAssignPaymentPlanToCustomer.AssignmentToken;    // IY3TGPWQVYX89QHS

RESULT AddCustomer:

resultAddCustomer.Response;    // 1
resultAddCustomer.TextResponse;    // Customer with token 'IP3KIQ30XODM2BWH' successfully created
resultAddCustomer.Type;    // addcustomer
resultAddCustomer.CustomerToken;    // IP3KIQ30XODM2BWH
resultAddCustomer.PaymentTokens[0];    // OAXYBBOB2W5DLALY

RESULT CreatePaymentPlan:

resultCreatePaymentPlan.Response;    // 1
resultCreatePaymentPlan.TextResponse;    // SUCCESS
resultCreatePaymentPlan.Type;    // addplan
resultCreatePaymentPlan.PlanToken;    // PRUDES37GWNMVZI6

RESULT:

result.Response;    // 1
result.TextResponse;    // Success
result.Type;    // cancelassignment

CODE:


resp = sprw.plans.cancel_assignment(assignment_token)

RESULT:


{
    "response": "1",
    "textresponse": "Success",
    "type": "cancelassignment"
}

CODE:

$paramsAddCustomer = new AddCustomerParams();
$paramsAddCustomer->defaultContactInfo->firstName = "John";
$paramsAddCustomer->defaultContactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0] = new PaymentType();
$paramsAddCustomer->paymentTypes[0]->payType = PayType::CREDITCARD;
$paramsAddCustomer->paymentTypes[0]->contactInfo->firstName = "John";
$paramsAddCustomer->paymentTypes[0]->contactInfo->lastName = "Doe";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardNum = "4111111111111111";
$paramsAddCustomer->paymentTypes[0]->creditCard->cardExp = new DateTime("2019-10-21");

$resultAddCustomer = self::$sparrow->AddCustomer($paramsAddCustomer)->wait();

$paramsCreatePaymentPlan = new CreatePaymentPlanParams();
$paramsCreatePaymentPlan->planName = "PaymentPlan1";
$paramsCreatePaymentPlan->planDesc = "1st Payment Plan";
$paramsCreatePaymentPlan->startDate = new DateTime("2019-10-21");
$paramsCreatePaymentPlan->sequenceStepss[0] = new SequenceStep();
$paramsCreatePaymentPlan->sequenceStepss[0]->sequence = 1;
$paramsCreatePaymentPlan->sequenceStepss[0]->amount = 9.99;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleType = ScheduleType::MONTHLY;
$paramsCreatePaymentPlan->sequenceStepss[0]->scheduleDay = 5;
$paramsCreatePaymentPlan->sequenceStepss[0]->duration = 12;

$resultCreatePaymentPlan = self::$sparrow->CreatePaymentPlan($paramsCreatePaymentPlan)->wait();

$paramsAssignPaymentPlanToCustomer = new AssignPaymentPlanToCustomerParams();
$paramsAssignPaymentPlanToCustomer->customerToken = $resultAddCustomer->customerToken;
$paramsAssignPaymentPlanToCustomer->planToken = $resultCreatePaymentPlan->planToken;
$paramsAssignPaymentPlanToCustomer->paymentToken = $resultAddCustomer->paymentTokens[0];

$resultAssignPaymentPlanToCustomer = self::$sparrow->AssignPaymentPlanToCustomer($paramsAssignPaymentPlanToCustomer)->wait();

$paramsCancelPlanAssignment = new CancelPlanAssignmentParams();
$paramsCancelPlanAssignment->assignmentToken = $resultAssignPaymentPlanToCustomer->assignmentToken;

$resultCancelPlanAssignment = self::$sparrow->CancelPlanAssignment($paramsCancelPlanAssignment)->wait();

RESULT AssignPaymentPlanToCustomer:

$resultAssignPaymentPlanToCustomer.isSuccess;    // 1
$resultAssignPaymentPlanToCustomer.response;    // 1
$resultAssignPaymentPlanToCustomer.textResponse;    // Success
$resultAssignPaymentPlanToCustomer.type;    // assignplan
$resultAssignPaymentPlanToCustomer.assignmentToken;    // VVV129I7WJ9IFVWF

RESULT AddCustomer:

$resultAddCustomer.isSuccess;    // 1
$resultAddCustomer.response;    // 1
$resultAddCustomer.textResponse;    // Customer with token 'W25KLGC8CR8DPWV9' successfully created
$resultAddCustomer.type;    // addcustomer
$resultAddCustomer.customerToken;    // W25KLGC8CR8DPWV9
$resultAddCustomer.p;    // 8D91I61K49JSON9Q

RESULT CreatePaymentPlan:

$resultCreatePaymentPlan.isSuccess;    // 1
$resultCreatePaymentPlan.response;    // 1
$resultCreatePaymentPlan.textResponse;    // SUCCESS
$resultCreatePaymentPlan.type;    // addplan
$resultCreatePaymentPlan.planToken;    // B1IENEHPUYI7YIT2

RESULT CancelPlanAssignment:

$resultCancelPlanAssignment.isSuccess;    // 1
$resultCancelPlanAssignment.response;    // 1
$resultCancelPlanAssignment.textResponse;    // Success
$resultCancelPlanAssignment.type;    // cancelassignment

Invoicing

Through the gateway, invoices can be created, stored and paid using a secure payment page.

Creating an Invoice

Variable Name Format Description
mkey Secured merchant account key
transtype createmerchantinvoice
customertoken alphanumeric string Unique data vault client identifier
invoicedate MM/DD/YYYY The date of the invoice
currency CCC (ISO 4217 alphabetic code) Code of the payment currency
invoicestatus draft / active The status of the invoice. Only active invoices can be paid
invoicesource CheckoutApi / DataVault The source of the invoice. If not specified, the default value is DataVault
invoiceamount d.dd Total amount of invoice (i.e. 10.00). Required if product list is not specified
invoiceitemsku_# alphanumeric SKU number of the product being purchased. Required if one of the following fields is specified: invoiceitemdescription_#, invoiceitemprice_#, invoiceitemquantity_#
invoiceitemdescription_# alphanumeric Description of the product being purchased. Field supports 3000 characters. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemprice_#, invoiceitemquantity_#
invoiceitemprice_# d.dd Price of the single unit of a product being purchased. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemdescription_#, invoiceitemquantity_#
invoiceitemquantity_# d.ddd Number of units of a product being purchased. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemdescription_#, invoiceitemprice_#
sendpaymentlinkemail email@email.com If Invoice status is 'Active' email with Pay Invoice URL will be sent to specified email.

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=createmerchantinvoice&customertoken=SBTQTLGTL2F31JPO&invoicedate=12/30/2017&currency=USD&invoicestatus=Draft&invoiceitemsku_1=123&invoiceitemdescription_1=Services+Rendered&invoiceitemprice_1=121.24&invoiceitemquantity_1=1.253&invoiceitemsku_2=223&invoiceitemdescription_2=desc2&invoiceitemprice_2=41.48&invoiceitemquantity_2=2.653

Command Line:

curl -d "mkey=$M_KEY&\
transtype=createmerchantinvoice&\
customertoken=YWVEUMYXUNARZ3VK&\
invoicedate=12/01/2017&\
currency=USD&\
invoicestatus=draft&\
invoicesource=DataVault&\
invoiceamount=10.00&\
invoiceitemsku_1=123&\
invoiceitemsku_2=456&\
invoiceitemdescription_1=Widget 1&\
invoiceitemdescription_2=Widget 2&\
invoiceitemprice_1=2.00&\
invoiceitemprice_2=4.00&\
invoiceitemquantity_1=1&\
invoiceitemquantity_2=2" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=invoice+has+been+successfully+created&
invoicenumber=Inv-39031

CODE:

var result = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);

RESULT:

result.TextResponse;    // invoice has been successfully created
result.InvoiceNumber;    // Inv-39706

CODE:


api.create_invoice({
  invoicedate: '10/15/2018',
  currency: 'USD',
  invoiceamount: '212.95',
  invoicestatus: 'draft',
})

RESULT:



result.textresponse # => 'invoice has been successfully created'
result.invoicenumber # => 'Inv-39746'

CODE:


resp = sprw.invoices.create(data=dict(
    customertoken=CUSTOMER_TOKEN,
    invoicedate="12/12/2017",
    currency="USD",
    invoicestatus="draft",
    invoicesource="DataVault",
    invoiceamount="10.00",
    invoiceitemsku_1="123",
    invoiceitemsku_2="456",
    invoiceitemdescription_1="Widget 1",
    invoiceitemdescription_2="Widget 2",
    invoiceitemprice_1="2.00",
    invoiceitemprice_2="4.00",
    invoiceitemquantity_1="1",
    invoiceitemquantity_2="2"
))

RESULT:


{
    "invoicenumber": "Inv-39877",
    "textresponse": "invoice has been successfully created"
}

CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40003

Update Invoice

Variable Name Format Description
mkey Secured merchant account key
transtype updateinvoice
invoicenumber Inv- [0-9] Unique invoice identifier
customertoken alphanumeric string Unique data vault client identifier
invoicedate MM/DD/YYYY The date of the invoice
currency CCC (ISO 4217 alphabetic code) Code of the payment currency
invoicestatus draft / active The status of the invoice. Only active invoices can be paid
invoicesource CheckoutApi / DataVault The source of the invoice. If not specified, the default value is DataVault
invoiceamount d.dd Total amount of invoice (i.e. 10.00). Required if product list is not specified
invoiceitemsku_# alphanumeric SKU number of the product being purchased. Required if one of the following fields is specified: invoiceitemdescription_#, invoiceitemprice_#, invoiceitemquantity_#
invoiceitemdescription_# alphanumeric Description of the product being purchased. Field supports 3000 characters. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemprice_#, invoiceitemquantity_#
invoiceitemprice_# d.dd Price of the single unit of a product being purchased. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemdescription_#, invoiceitemquantity_#
invoiceitemquantity_# d.ddd Number of units of a product being purchased. Required if one of the following fields is specified: invoiceitemsku_#, invoiceitemdescription_#, invoiceitemprice_#
sendpaymentlinkemail email@email.com If Invoice status is 'Active' email with Pay Invoice URL will be sent to specified email.

If any parameter is missing in the update invoice request system deletes it from the invoice.

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=updateinvoice&invoicenumber=Inv-80794&invoicedate=12/30/2017&currency=USD&invoicestatus=Active&invoiceitemsku_1=12345&invoiceitemdescription_1=desc1&invoiceitemprice_1=22.33&invoiceitemquantity_1=1&invoiceitemsku_2=223&invoiceitemdescription_2=desc2&invoiceitemprice_2=41.48&invoiceitemquantity_2=2.653

Command Line:

curl -d "mkey=$M_KEY&\
transtype=updateinvoice&\
invoicenumber=Inv-39031&\
invoicedate=12/15/2017&\
currency=USD&\
invoicestatus=active&\
invoicesource=DataVault&\
invoiceamount=15.00" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=Invoice+has+been+successfully+updated&
invoicenumber=Inv-39031

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Draft,
    invoiceAmount: 10.00m);
var result = await _sparrow.UpdateInvoice(
    invoiceNumber: resultCreateInvoice.InvoiceNumber,
    invoiceStatus: Sparrow.InvoiceStatus.Active);

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39710

RESULT:

result.TextResponse;    // Invoice has been successfully updated
result.InvoiceNumber;    // Inv-39710

CODE:


api.update_invoice({
  invoicenumber: 'Inv-39744',
  invoicestatus: 'active',
})

RESULT:



result.textresponse # => 'Invoice has been successfully updated'
result.invoicenumber # => 'Inv-39744'

CODE:


resp = sprw.invoices.update(invoice_id, data=dict(
    invoicedate="12/15/2017",
    invoiceamount="15.00",
    invoicestatus="active",
))

RESULT:


{
    "invoicenumber": "Inv-39888",
    "textresponse": "Invoice has been successfully updated"
}

CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::DRAFT;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsUpdateInvoice = new UpdateInvoiceParams();
$paramsUpdateInvoice->invoiceNumber = $resultCreateInvoice->invoiceNumber;
$paramsUpdateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;

$resultUpdateInvoice = self::$sparrow->UpdateInvoice($paramsUpdateInvoice)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40007

RESULT UpdateInvoice:

$resultUpdateInvoice.isSuccess;    // 1
$resultUpdateInvoice.textResponse;    // Invoice has been successfully updated
$resultUpdateInvoice.invoiceNumber;    // Inv-40007

Retrieve Invoice

Variable Name Format Description
mkey Secured merchant account key
transtype getinvoice
invoicenumber Inv- [0-9] Unique invoice identifier

Response from the gateway will be as follows:

Variable Name Format Description
textresponse Textual response
invoicenumber Inv-[0-9] Unique invoice identifier
invoiceamount d.dddd Total amount of invoice (10.0000)
currency CCC Code of the payment currency (ISO 4217 alphabetic code)
invoicedate MM/DD/YYYY The date of the invoice
invoicestatus draft / active / canceled / canceledbycustomer / paid / failed The date of the invoice. Only active invoices can be paid
invoicepaymentlink URL Payment link for the customer
invoiceitemid_# numeric Unique invoice item identifier
invoiceitemprice_# d.dddd Price of the single unit of a product being purchased
invoiceitemquantity_# d.ddd Number of units of a product being purchased
invoiceitemsku_# alphanumeric SKU number of the product being purchased
invoiceitemdescription_# alphanumeric Description of the product being purchased
invoiceitemamount_# d.dddd Amount of invoice item (10.0000)

Item variables are required if invoice contains products.

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=getinvoice&invoicenumber=Inv-80794

Expected Response

textresponse=Successful&invoicenumber=Inv-80794&invoiceamount=132.3800&currency=USD&invoicedate=12%2f30%2f2014&invoicestatus=Active&invoiceitemid_1=40464&invoiceitemprice_1=22.3300&invoiceitemquantity_1=1.000&invoiceitemsku_1=12345&invoiceitemdescription_1=desc1&invoiceitemid_2=40465&invoiceitemprice_2=41.4800&invoiceitemquantity_2=2.653&invoiceitemsku_2=223&invoiceitemdescription_2=desc2

Command Line:

curl -d "mkey=$M_KEY&\
transtype=getinvoice&\
invoicenumber=Inv-39030" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=Success&
invoicenumber=Inv-39030&
invoiceamount=10.0000&
currency=USD&
invoicedate=12%2f01%2f2017&
invoicestatus=Draft&
invoiceitemid_1=3251&
invoiceitemprice_1=2.0000&
invoiceitemquantity_1=1.000&
invoiceitemamount_1=2.0000&
invoiceitemsku_1=123&
invoiceitemdescription_1=Widget+1&
invoiceitemid_2=3252&
invoiceitemprice_2=4.0000&
invoiceitemquantity_2=2.000&
invoiceitemamount_2=8.0000&
invoiceitemsku_2=456&
invoiceitemdescription_2=Widget+2&
customertoken=3F4JAWXXFDYSJ1JX

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);
var result = await _sparrow.RetrieveInvoice(
    invoiceNumber: resultCreateInvoice.InvoiceNumber);

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39707

RESULT:

result.TextResponse;    // Success
result.InvoiceNumber;    // Inv-39707
result.InvoiceAmount;    // 10.0000
result.Currency;    // USD
result.InvoiceDate;    // 10/21/2019
result.InvoiceStatus;    // Active
result.InvoicePaymentLink;    // https://secure.sparrowone.com/Payments/Payment.aspx?token=D5A731D92F086B1C

CODE:


api.get_invoice({
  invoicenumber: 'Inv-39744',
})

RESULT:



result.textresponse # => 'Success'
result.invoicenumber # => 'Inv-39744'
result.invoiceamount # => '212.9500'
result.currency # => 'USD'
result.invoicedate # => '10/15/2018'
result.invoicestatus # => 'Draft'

CODE:


card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.invoices.pay(invoice_id, card)

RESULT:


{
    "invoicenumber": "Inv-39912",
    "textresponse": "Invoice has been successfully paid",
    "transid": "11188453"
}

CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsRetrieveInvoice = new RetrieveInvoiceParams();
$paramsRetrieveInvoice->invoiceNumber = $resultCreateInvoice->invoiceNumber;

$resultRetrieveInvoice = self::$sparrow->RetrieveInvoice($paramsRetrieveInvoice)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40004

RESULT RetrieveInvoice:

$resultRetrieveInvoice.isSuccess;    // 1
$resultRetrieveInvoice.textResponse;    // Success
$resultRetrieveInvoice.invoiceNumber;    // Inv-40004
$resultRetrieveInvoice.invoiceAmount;    // 10.0000
$resultRetrieveInvoice.currency;    // USD
$resultRetrieveInvoice.invoiceDate;    // 10/21/2019
$resultRetrieveInvoice.invoiceStatus;    // Active
$resultRetrieveInvoice.invoicePaymentLink;    // https://secure.sparrowone.com/Payments/Payment.aspx?token=068A72B58B9B2DDA

Cancel Invoice

Variable Name Format Description
mkey Secured merchant account key
transtype cancelinvoice
invoicenumber Inv- [0-9] Unique invoice identifier
invoicestatusreason alphanumeric The reason of canceling the invoice

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=cancelinvoice&invoicenumber=Inv-80794&invoicestatusreason=end+of+contract

Expected Response

textresponse=invoice+has+been+successfully+canceled&invoicenumber=Inv-80794

Command Line:

curl -d "mkey=$M_KEY&\
transtype=cancelinvoice&\
invoicenumber=Inv-39028&\
invoicestatusreason=Testing Cancel Feature" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=invoice+has+been+successfully+canceled&
invoicenumber=Inv-39028

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);
var result = await _sparrow.CancelInvoice(
    invoiceNumber: resultCreateInvoice.InvoiceNumber,
    invoiceStatusReason: "Testing");

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39705

RESULT:

result.TextResponse;    // invoice has been successfully canceled
result.InvoiceNumber;    // Inv-39705

CODE:


api.cancel_invoice({
  invoicenumber: 'Inv-39745',
  invoicestatusreason: 'Customer allergic to product',
})

RESULT:



result.textresponse # => 'invoice has been successfully canceled'
result.invoicenumber # => 'Inv-39745'

CODE:


resp = sprw.invoices.cancel(invoice_id, "test")

RESULT:


{
    "invoicenumber": "Inv-39886",
    "textresponse": "invoice has been successfully canceled"
}

CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsCancelInvoice = new CancelInvoiceParams();
$paramsCancelInvoice->invoiceNumber = $resultCreateInvoice->invoiceNumber;
$paramsCancelInvoice->invoiceStatusReason = "Testing";

$resultCancelInvoice = self::$sparrow->CancelInvoice($paramsCancelInvoice)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40002

RESULT CancelInvoice:

$resultCancelInvoice.isSuccess;    // 1
$resultCancelInvoice.textResponse;    // invoice has been successfully canceled
$resultCancelInvoice.invoiceNumber;    // Inv-40002

Cancel Invoice by Customer

Variable Name Format Description
mkey Secured merchant account key
transtype cancelinvoicebycustomer
invoicenumber Inv- [0-9] Unique invoice identifier
invoicestatusreason alphanumeric The reason of canceling the invoice

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=cancelinvoicebycustomer&invoicenumber=Inv-80794&invoicestatusreason=ending+contract

Expected Response

textresponse=invoice+has+been+successfully+canceled&invoicenumber=Inv-80794

Command Line:

curl -d "mkey=$M_KEY&\
transtype=cancelinvoicebycustomer&\
invoicenumber=Inv-39026&\
invoicestatusreason=Cancel Invoice By Customer" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=invoice+has+been+successfully+canceled&
invoicenumber=Inv-39026

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);
var result = await _sparrow.CancelInvoiceByCustomer(
    invoiceNumber: resultCreateInvoice.InvoiceNumber,
    invoiceStatusReason: "Testing");

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39704

RESULT:

result.TextResponse;    // invoice has been successfully canceled
result.InvoiceNumber;    // Inv-39704

CODE:


resp = sprw.invoices.cancel(invoice_id, "test", by_customer=True)

RESULT:


{
    "invoicenumber": "Inv-39887",
    "textresponse": "invoice has been successfully canceled"
}

CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsCancelInvoiceByCustomer = new CancelInvoiceByCustomerParams();
$paramsCancelInvoiceByCustomer->invoiceNumber = $resultCreateInvoice->invoiceNumber;
$paramsCancelInvoiceByCustomer->invoiceStatusReason = "Testing";

$resultCancelInvoiceByCustomer = self::$sparrow->CancelInvoiceByCustomer($paramsCancelInvoiceByCustomer)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40001

RESULT CancelInvoiceByCustomer:

$resultCancelInvoiceByCustomer.isSuccess;    // 1
$resultCancelInvoiceByCustomer.textResponse;    // invoice has been successfully canceled
$resultCancelInvoiceByCustomer.invoiceNumber;    // Inv-40001

Paying an Invoice with a Credit Card

Variable Name Format Description
mkey Secured merchant account key
transtype payinvoice
invoicenumber​ Inv-[0-9] Unique invoice identifier
cardnum Credit card number
cardexp MMYY Credit card expiration (ie. 0719 = 7/2019)
cvv Card security code
firstname Billing first name
lastname Billing last name
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
phone Billing phone number
fax Billing fax number
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email

transtype=payinvoice&mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&invoicenumber=Inv-123456&cardnum=4111111111111111&cardexp=1010&cvv=999&firstname=John&lastname=Smith&address1=888+test+address&city=Los+Angeles&country=US&state=CA&phone=222-444-2938&shipfirstname=John&shiplastname=Smith&shipaddress1=888+test+address&shipcity=Los+Angeles&shipstate=CA&shipphone=2224442938

Command Line:

curl -d "mkey=$M_KEY&\
transtype=payinvoice&\
invoicenumber=Inv-39025&\
cardnum=4111111111111111&\
cardexp=1019&\
cvv=999&\
firstname=John&\
lastname=Doe&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=Invoice+has+been+successfully+paid&
transid=10750812&
invoicenumber=Inv-39025

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);
var result = await _sparrow.PayInvoiceWithCreditCard(
    invoiceNumber: resultCreateInvoice.InvoiceNumber,
    creditCard: new Sparrow.CreditCard{ CardNum = "4111111111111111", CardExp = new DateTime(2019,10,21) });

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39709

RESULT:

result.TextResponse;    // Invoice has been successfully paid
result.TransId;    // 11032431
result.InvoiceNumber;    // Inv-39709

CODE:

sprw.invoices.update(invoice_id, data=dict(
    invoicestatus="active",
))

card = sparrowone.CardInfo(
    number="4111111111111111",
    expiration="1019",
    cvv="999"
)
resp = sprw.invoices.pay(invoice_id, card)

RESULT:

{
    "invoicenumber": "Inv-39888",
    "textresponse": "Invoice has been successfully paid",
    "transid": "11150347"
}

$$language: php$$ CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsPayInvoiceWithCreditCard = new PayInvoiceWithCreditCardParams();
$paramsPayInvoiceWithCreditCard->invoiceNumber = $resultCreateInvoice->invoiceNumber;
$paramsPayInvoiceWithCreditCard->creditCard->cardNum = "4111111111111111";
$paramsPayInvoiceWithCreditCard->creditCard->cardExp = new DateTime("2019-10-21");

$resultPayInvoiceWithCreditCard = self::$sparrow->PayInvoiceWithCreditCard($paramsPayInvoiceWithCreditCard)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40006

RESULT PayInvoiceWithCreditCard:

$resultPayInvoiceWithCreditCard.isSuccess;    // 1
$resultPayInvoiceWithCreditCard.textResponse;    // Invoice has been successfully paid
$resultPayInvoiceWithCreditCard.transId;    // 11284999
$resultPayInvoiceWithCreditCard.invoiceNumber;    // Inv-40006

Paying an Invoice with a Bank Account

Variable Name Format Description
mkey Secured merchant account key
transtype payinvoice
invoicenumber​ Inv-[0-9] Unique invoice identifier
bankname The customer’s bank name
routing The customer’s bank routing number
account The customer’s bank account number
achaccounttype checking / savings The customer’s type of ACH account
achaccountsubtype business / personal The customer’s ACH account entity
firstname Billing first name
lastname Billing last name
company Billing company
address1 Billing address
address2 Billing address2
city Billing city
state 2 character abbreviation Billing state
zip Billing postal code. If the country is US zip code format must be 5 digits or 9 digits. Example xxxxx, xxxxxxxxx or xxxxx-xxxx
country CC (ISO-3166) Billing Country (ie. US)
phone Billing phone number
fax Billing fax number
email Billing Email Address
shipfirstname Shipping first name
shiplastname Shipping last name
shipcompany Shipping company
shipaddress1 Shipping Address
shipaddress2 Shipping Address - line 2
shipcity Shipping City
shipstate 2 character abbreviation Shipping State
shipzip Shipping Zip Code
shipcountry CC (ISO - 3166) Shipping Country, ie US
shipphone Shipping Phone Number
shipemail Shipping Email

mkey=8VG63HD1LPBMIR5TPS7R52YV&transtype=payinvoice&invoicenumber=Inv-80782&bankname=Bank&routing=122000496&account=122000496&achaccounttype=checking&achaccountsubtype=personal&firstname=Jake&lastname=Tred&address1=123+Feeed&city=New+York&state=NY&country=US&zip=12345&company=Comp

Command Line:

curl -d "mkey=$ACH_M_KEY&\
transtype=payinvoice&\
invoicenumber=Inv-39040&\
bankname=First Test Bank&\
routing=110000000&\
account=1234567890123&\
achaccounttype=checking&\
achaccountsubtype=personal&\
firstname=John&\
lastname=Doe&\
company=Sparrow One&\
address1=16100 N 71st Street&\
address2=Suite 170&\
city=Scottsdale&\
state=AZ&\
zip=85254&\
country=US&\
email=john@norepy.com&\
shipfirstname=Jane&\
shiplastname=Doe&\
shipcompany=Sparrow Two&\
shipaddress1=16100 N 72nd Street&\
shipaddress2=Suite 171&\
shipcity=Pheonix&\
shipstate=AZ&\
shipzip=85004&\
shipcountry=US&\
shipphone=6025551234&\
shipemail=jane@noreply.com" \
https://secure.sparrowone.com/Payments/Services_api.aspx

Response:

textresponse=Invoice+has+been+successfully+paid&
transid=10750925&
invoicenumber=Inv-39040

CODE:

var resultCreateInvoice = await _sparrow.CreateInvoice(
    invoiceDate: new DateTime(2019,10,21),
    currency: "USD",
    invoiceStatus: Sparrow.InvoiceStatus.Active,
    invoiceAmount: 10.00m);
var result = await _sparrow.PayInvoiceWithBankAccount(
    invoiceNumber: resultCreateInvoice.InvoiceNumber,
    bankAccount: new Sparrow.BankAccount{ BankName = "First Test Bank", Routing = "110000000", Account = "1234567890123", AchAccountType = Sparrow.AchAccountType.Checking, AchAccountSubType = Sparrow.AchAccountSubType.Personal },
    contactInfo: new Sparrow.ContactInfo{ FirstName = "John", LastName = "Doe" });

RESULT CreateInvoice:

resultCreateInvoice.TextResponse;    // invoice has been successfully created
resultCreateInvoice.InvoiceNumber;    // Inv-39708

RESULT:

result.TextResponse;    // Invoice has been successfully paid
result.TransId;    // 11032430
result.InvoiceNumber;    // Inv-39708

CODE:

ach_account = sparrowone.ACHInfo(
    bank_name="First Test Bank",
    routing="110000000",
    account="1234567890123",
    type="checking",
    subtype="personal",
    first_name="Alma",
    last_name="Armas"
)
resp = sprw.invoices.pay(invoice_id, ach_account)

RESULT:

{
    "invoicenumber": "Inv-39914",
    "textresponse": "Invoice has been successfully paid",
    "transid": "11188537"
}

$$language: php$$ CODE:

$paramsCreateInvoice = new CreateInvoiceParams();
$paramsCreateInvoice->invoiceDate = new DateTime("2019-10-21");
$paramsCreateInvoice->currency = "USD";
$paramsCreateInvoice->invoiceStatus = InvoiceStatus::ACTIVE;
$paramsCreateInvoice->invoiceAmount = 10.00;

$resultCreateInvoice = self::$sparrow->CreateInvoice($paramsCreateInvoice)->wait();

$paramsPayInvoiceWithBankAccount = new PayInvoiceWithBankAccountParams();
$paramsPayInvoiceWithBankAccount->invoiceNumber = $resultCreateInvoice->invoiceNumber;
$paramsPayInvoiceWithBankAccount->bankAccount->bankName = "First Test Bank";
$paramsPayInvoiceWithBankAccount->bankAccount->routing = "110000000";
$paramsPayInvoiceWithBankAccount->bankAccount->account = "1234567890123";
$paramsPayInvoiceWithBankAccount->bankAccount->achAccountType = AchAccountType::CHECKING;
$paramsPayInvoiceWithBankAccount->bankAccount->achAccountSubType = AchAccountSubType::PERSONAL;
$paramsPayInvoiceWithBankAccount->contactInfo->firstName = "John";
$paramsPayInvoiceWithBankAccount->contactInfo->lastName = "Doe";

$resultPayInvoiceWithBankAccount = self::$sparrow->PayInvoiceWithBankAccount($paramsPayInvoiceWithBankAccount)->wait();

RESULT CreateInvoice:

$resultCreateInvoice.isSuccess;    // 1
$resultCreateInvoice.textResponse;    // invoice has been successfully created
$resultCreateInvoice.invoiceNumber;    // Inv-40005

RESULT PayInvoiceWithBankAccount:

$resultPayInvoiceWithBankAccount.isSuccess;    // 1
$resultPayInvoiceWithBankAccount.textResponse;    // Invoice has been successfully paid
$resultPayInvoiceWithBankAccount.transId;    // 11284998
$resultPayInvoiceWithBankAccount.invoiceNumber;    // Inv-40005

Forget Customer

Forget Customer

VariableName Format Description
transtype forgetcustomer Delete data for Regular Customer or Data Vault Client.
mkey Secured merchant account key.
transid number Payment Gateway Transaction ID. This field is required if ‘token’ is not specified. System identifies regular customer assigned to the transaction and deletes data for the customer and for all associated transactions. Please note that system does not delete data for assigned Data Vault client.
token alphanumeric string Unique Data Vault client or payment info identifier. This field is required if ‘transid’ is not specified. System deletes Contact info and payment info for the Data Vault client; Data related to Client Portal; Values for Custom fields marked as personal; Data for all associated transactions; Data for all associated regular customers. Also, the system unassigns plans assigned to the Data Vault client.

If merchant sends Transaction ID in the request, system deletes data for the regular customer and transaction data.

If merchant sends token, system deletes data for the data vault client, regular customer and transaction data.

Response from the gateway will be as follows:

VariableName Format Description
response 1 = Successful; 2 = Declined; 3 = Internal Error
textresponse text Textual response
requestID integer GDPR Request ID

Request example for Data Vault Client:

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=ForgetCustomer&transid=1272231

Expected Response

response=1&textresponse=The+request+is+registered+and+will+be+processed.&requestID=9

Request example for Regular Customer:

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=ForgetCustomer&token=4RGMO40I0ASWG1UM

Expected Response

response=1&textresponse=The+request+is+registered+and+will+be+processed.&requestID=10

Inquiry GDPR Request

Merchant could check status of the GDPR request via API using “Inquiry Gdpr Request” operation.

VariableName Format Description
transtype InquiryGdrpRequest Check status of the GDPR request.
mkey Secured merchant account key.
requestID integer GDPR request ID.

Response from the gateway will be as follows:

VariableName Format Description
response 1 = Successful; 2 = Declined; 3 = Internal Error
textresponse text Textual response.
requestID integer GDPR Request ID.
status text GDPR Request status.

Request example:

mkey=KewO4GI%2B64I8Vg6xCCuqvAkuAkq9cbJH&transtype=InquiryGdrpRequest&requestid=14

Expected Response

response=1&textresponse=Successful&status=InternalError&requestID=14

Dynamic Descriptors

This feature enables to submit merchant descriptor values that are displayed on a cardholder’s statement.

Chase Processor

Services:

  • Sale

  • Authorization

  • Capture

  • Credit

VariableName Format Description
dba_merch_name text (12) Merchant name. Format text (12) if fields dba_merch_name, dba_merch_city OR dba_merch_phone are entered.
text (38) Format text (38) if fields dba_merch_name, dba_merch_zip, dba_merch_city, dba_merch_country, dba_merch_mcc, dba_merch_id, dba_merch_addr, dba_merch_state are entered.
dba_merch_city text (13) Merchant City. Format text (13) if fields dba_merch_name, dba_merch_city OR dba_merch_phone are entered.
text (21) Format text (21) if fields dba_merch_name, dba_merch_zip, dba_merch_city, dba_merch_country, dba_merch_mcc, dba_merch_id, dba_merch_addr, dba_merch_state are entered.
dba_merch_phone text (13) Merhcant Phone. Specified format if fields dba_merch_name, dba_merch_city OR dba_merch_phone are entered. Format: NNN-NNN-NNNN (U.S. and Canada); NNN-AAAAAAA (U.S. and Canada); NNN-NNNNNNN (U.S. and Canada).
dba_merch_country Country Alpha 2 Code Merchant Country
dba_merch_zip text (15) Merchant Postal Code
dba_merch_state text (3) Merchant State
dba_merch_id text (15) Merchant ID
dba_merch_mcc digit (4) Merchant Category Code
dba_merch_addr text (38) Merchant Address (street)

MeS Processors

Services:

  • Sale

  • Authorization

  • Offline

VariableName Format Description
dba_merch_name text (25) from account settings only Merchant Name
dba_merch_city text (13) from merchant company info Merchant City
dba_merch_phone text (13) from merchant settings only Merchant Phone
dba_merch_state text (2) from merchant company info Merchant State

First Data Processor

Services:

  • Sale

  • Authorization

  • Capture

  • Credit

VariableName Format Description
dba_merch_name text (38) This field contains the merchant name/product/service to be used in lieu of the DBA name on the First Data Merchant File.
dba_merch_city text (20) This field contains the merchant city to be used in lieu of the city on the First Data Merchant File.
dba_merch_country Country Alpha 3 Code; Country Digit 3 Code This field contains the merchant county to be used in lieu of the merchant county on the First Data Merchant File.
dba_merch_zip text (9) This field contains the merchant postal code to be used in lieu of the merchant postal code on the First Data Merchant File.
dba_merch_state text (2) This field contains the merchant state code to be used in lieu of the state code on the First Data Merchant File.
dba_merch_addr text (30) This field contains the merchant address to be used in lieu of the merchant address on the First Data Merchant File.

MIMS Processor

Services:

  • Sale

  • Authorization

  • Offline

  • Credit

VariableName Format Description
dba_merch_name Not specified Merchant Name

GlobalOne Processor

Services:

  • Sale

  • Authorization

VariableName Format Description
dba_merch_name Not specified A summary of the Merchant

Please note Custom field paymentdescriptor should be created in the GlobalOne system. Please request Dynamic Descripription Guide from GlobaOne support.

TSYS Processor

Services:

  • Sale

  • Authorization

  • Offline

VariableName Format Description
paymentdescriptor Not specified A summary of the Merchant

Response Variables

Transaction Response Variables

Variable Name Format Description
status alphanumeric string See the table below with statuses list
response alphanumeric string See the table below with responses list
textresponse string Textual response
authcode string Transaction authorization or approval code, depending on the payment processor
type string Type of transaction
transid number Sparrow transaction ID
xref string External transaction ID from the payment processor
avsresponse C AVS Response Code
cvvresponse C CVV Response Code
coderesponse C Numeric mapping of the processor response
orderid The original order ID passed in the transaction request
customertoken alphanumeric string Token of the newly created Data Vault customer
paymenttoken_# alphanumeric string Token of the newly created Data Vault payment information set
assignmenttoken alphanumeric string Token of the newly assigned Data Vault payment plan assignment
plantoken alphanumeric string Token of the newly created Data Vault plan
codedescription string Describes the meaning of the response code
availablecreditbalance d.dd Available card balance
origtransid number Sparrow transaction id of an original transaction. System returns this field if the transaction has been Rejected or Flagged for review by FBI rule
origresponse alphanumeric string Response of an original transaction
origtextresponse string Textual response of an original transaction

Gateway Status

Statuses for Credit Card payments:

Value Transaction Status
1 Approved
2 Declined
3 Error

Statuses for ACH payments:

Value Transaction Status
00 Approved
05 Declined
ER Error

Statuses for eCheck payments:

Value Transaction Status
520 Approved
530, 540 Declined
550 Error

Statuses for Star Card payments:

Value Transaction Status
A Approved
D Declined
X Error

Statuses for eWallet payments:

Value Transaction Status
1 Approved
2 Declined
3 Error

Statuses for Cash payments:

Value Transaction Status
100 Approved
500 Declined

Status

Status field can have the following values:

Value Operation Status Description
200 Successful No Errors
201 Wait For Response For Checkout processors only (Eirth Gate, PayGate, etc.). This is a temporary status. It means that the request was sent to the processor and there are no errors, however, the response has not been received yet
254 Rejected By Accertify Fraud Control System
300 Flagged For Review Fraud Control System
301 Rejected By Policy Fraud Control System
400 Declined Errors occurred on processor side
401 Processor Error Errors occurred on processor side
500 Internal Error Unexpected error

Processor Response Codes

AVS Response Codes

Value Description
A Address match only
B -
C -
D -
E Not a mail/phone order
G Non-U.S. Issuer does not participate
I -
K -
L -
M -
N No address or ZIP match
0 AVS Not Available
O -
P -
R Issuer system unavailable
S Service not supported
T -
U Address unavailable
W 9-character numeric ZIP match only
X Exact match, 9-character numeric ZIP
Y Exact match, 5-character numeric ZIP
Z 5-character Zip match only

CVV Response Codes

Value Description
M CVV2/CVC2 Match
N CVV2/CVC2 No Match
P Not Processed
S Merchant has indicated that CVV2/CVC2 is not present on card
U Issuer is not certified and/or has not provided Visa encryption keys
R Retry for AmEx

Military Star Responses

Listed below are possible values that be returned in the textresponse field. Any messages not indicated below should be reported to your AAFES contact.

Validation Messages

“Internal Error: Amount cannot contain decimals (.)”

This message is returned when the amount field contains at least one decimal. Correct the field and send the transaction again.

“Internal Error: Amount is not numeric”

This message is returned when the amount field contains non-numeric data. Correct the field and send the transaction again.

“Internal Error: Amount cannot be zero”

This message is returned when the amount field is equal to zero. Correct the field and send the transaction again.

“Internal Error: Credit card number is required”

This message is returned when the cardnum field is blank. Correct the field and send the transaction again.

“Internal Error: Invalid Card Number”

This message is returned when the data in the cardnum field is a invalid card.

Declined Messages

“Declined, Please try another payment method”

This message is returned when the transaction is declined. The response field will contain a “2”.

“Internal Error: Credit is larger than available amount”

This message is returned when the amount field in a credit transaction is greater than the amount settled on the previous transactions. Correct the field and send the transactions again. The response field will contain a “2”.

“Internal Error: Not authorized for given amount”

This message is returned when the amount in a settlement transaction is greater than the amount that was approved. Correct the field and send the transaction again. The response field will contain a “2”.

Misc. Messages

“TimeOut: Unable to verify transaction.”

This message is returned when there was a communication timeout. The transaction will be queued and processed when communication is back online. For an approval, you will need to make another request. For settlement and credits the transaction will get processed as soon as communications are back online.

“MQ: This method is not available at this time.”

This message is returned when there was a critical failure in the processing of the transactions. If this error continues, report it to your AAFES contact. All transactions will need to be sent again.

“COM: This method is not available at this time.”

This message is returned when there was a critical failure in the communication of the transaction. If this error continues, report it to your AAFES contact. All transactions will need to be sent again.

“System is down for maintenance”

This message is returned when the system has been brought down for upgrades or scheduled maintenance. All transactions will need to be sent again.

“COM: This method is abending, if problem continues notify your AAFES POC.”

This message is returned when there was a critical failure in the processing of the transactions. If this error continues, report it to your AAFES contact. All transactions will need to be sent again.

“DB Error: System currently down, try again later”

This message is returned when there is a critical error in accessing a database. All transaction will need to be sent again.

Payment Redirect

Custom white-label redirect page for uComm Global, Inc. uComm’s redirect page will communicate with CardinalCommerce and associated banks to process 3DS cards.

Architecture

The architecture will remain the same way the current redirect exists today.

Interaction with the service should be performed through the POST Http Request.

Process Workflow

Here is the URL for the method

  1. Cardholder enters in payment information into the custom redirect page

  2. The data is sent as a lookup request to CardinalCommerce to valid enrollment.

    1. If card is not enrolled:

      Cardinal will return an enrollment status of ‘N’ back with an ECI value.

      Redirect page will append the ECI value to the transaction and process the payment for the merchant.

    2. If card is enrolled:

      • Cardinal will return parameters which represent the URL for the issuing bank (ACS URL) and the Payer Authentication Request (PaReq).

      • Request page will POST the form data to the ACS URL. This form POST will include the PaReq payload, a TermURL and an MD value (if no MD, you can leave blank but the field still needs to be there). Through the posting to the ACS URL, the cardholder will be redirected to the bank page to enter in their bank password.

      • Once submitted, the ACS will post the cardholder and the encrypted data back to the TermURL (on the Sparrow server).

      • The Sparrow server will then take the encrypted value which is the PaRes (Payer Authentication Response) and send that in the Authenticate Request message to CardinalCommerce to decrypt.

      • CardinalCommerce will decrypt and send back the Authenticate Response which will include the PaResStatus, the Signature Status along with the ECI, CAVV and XID values.

      • The redirect page will append the ECI, CAVV and XID values to the transaction and then process the payment for the merchant.

      (Sample code will be provided that represents this process)

Integration

Setting up the Account

Before attempting to process checkout payments, the merchant account which will be receiving payments must be additionally setup.

To do that, visit the Integration page available from the Administration menu, select the account you want to setup, and enter the URL of the page where customers will be redirected after processing the payment.

The page available at the entered URL should have the functionality of checking the result of the payment. The details can be found below in Getting the Payment Result section. Note that it is critical to have this URL field filled or otherwise payments will not be processed via redirect method.

To integrate an account:

  1. Select the Merchant Account to integrate

  2. Enter the Return URL

  3. Check the “Allow user to enter quantity” checkbox if you would like to allow customers to enter custom quantity for the products they’re buying

  4. If you want to customize the look of the redirect page, you can upload your own CSS File

  5. Click Save

Checkout Process

Getting the Token

First action to initiate the checkout process is getting the checkout token. This is achieved by calling GetCheckoutToken method of Checkout API web service. This method has the following parameters:

FIELD FORMAT DESCRIPTION
transactionKey String Private key of the merchant account that will receive the payment
amount Decimal Total amount of the payment
items XML Products forming the payment. This is an optional parameter. See Appendix A for detailed description of items format
variableQuantity Boolean This is an optional flag signaling a redirect page if the customer is allowed to change the quantity of each product in the purchase. Changing the quantity will affect the total amount of the payment. The default value is false.

The returned token consists of the following fields:

FIELD FORMAT DESCRIPTION
Public key String, 16..128 characters This is the public part of the token key which can be exposed to end users. Public key will be specified as an URL query parameter two times during the checkout process
Private key String, 16..128 characters This is the private part of the token key which must be kept secret. Private key will be used to retrieve the results of the payment
Expiration Date <date>T<time> This is the date and time of the moment when the checkout token will expire and all further actions with it will not be possible

Processing Payment

To process the payment, redirect the customer to the payment URL with public token key as a parameter. Here is an example of the resulting URL:

https://secure.sparrowone.com/Payments/Payment.aspx?Token=214A3E3C8265F6EE

The Checkout Payment page will then ask the customer of his payment, billing and shipping information and allow him to process the payment. In the end, the customer will be redirected to the page set up in the merchant account settings, with public token key as a parameter.

https://secure.sparrowone.com/Payments/Payment.aspx?Token=eAaNOpIu7DH5h58E3qDNLewDTayu+4Fz

Getting the Payment Result

The results of the payment will not be provided to the merchant page during the redirect. To get the results, call the GetCheckoutPaymentResult method of the Checkout API. This method requires the private token key as a parameter. The fields returned by this method are the following:

FIELD FORMAT DESCRIPTION
ResultCode Integer Result code of the GetCheckoutPaymentResult operation. See Appendix B for all possible codes
Message String Message describing the result of this operation, i.e. “Success”. This is not the description of payment result
PaymentInfo XML A structure containing information about payment result. See the table below for field explanations

PaymentInfo element contains the following fields (see full description in XML schema, examples can be found in Appendix A):

FIELD FORMAT DESCRIPTION
Amount Decimal Total payment amount (sum of prices for all products)
FailedPaymentAttempts Integer Amount of payment attempts made by customer which were declined by the processor
PaymentStatus String Status of the payment. See Appendix B for the list of possible values
PaymentDate <date>T<time> Date of the transaction, if applicable
PaymentMessage String Message returned by the processor
PaymentTransactionId 64-bit integer The gateway’s ID of the transaction, if the transaction exists
Items XML A copy of product list provided to GetCheckoutToken  method

If the method runs successfully (i.e. specified token exists, is not expired etc.), it returns the ResultCode of 0. Note that even if the method is successful, this does not mean that the payment was successful. Check the <PaymentInfo> element contents to get the result of the payment itself. Result codes different from zero mean that an error has happened, and <PaymentInfo> element of the response won’t contain any data. You can find the full list of result codes and their meanings in the Appendix B.

Appendix A – Web Methods Description

This section contains request and response formats for both Checkout API methods. Full schema can be found at https://secure.sparrowone.com/Services/CheckoutApi.asmx?wsdl

GetCheckoutToken

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutToken xmlns="https://secure.sparrowone.com/Services/">
      <transactionKey>string</transactionKey>
      <amount>decimal</amount>
      <items>
        <CheckoutPaymentItem>
          <Description>string</Description>
          <SkuNumber>string</SkuNumber>
          <UnitPrice>decimal</UnitPrice>
          <Quantity>int</Quantity>
        </CheckoutPaymentItem>
        <CheckoutPaymentItem>
          <Description>string</Description>
          <SkuNumber>string</SkuNumber>
          <UnitPrice>decimal</UnitPrice>
          <Quantity>int</Quantity>
        </CheckoutPaymentItem>
        ...
      </items>
      <variableQuantity>boolean</variableQuantity>
    </GetCheckoutToken>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutTokenResponse xmlns="https://secure.sparrowone.com/Services/">
      <GetCheckoutTokenResult>
        <ResultCode>int</ResultCode>
        <Message>string</Message>
        <Token>
          <PublicKey>string</PublicKey>
          <PrivateKey>string</PrivateKey>
          <ExpirationTime>dateTime</ExpirationTime>
        </Token>
      </GetCheckoutTokenResult>
    </GetCheckoutTokenResponse>
  </soap:Body>
</soap:Envelope>

GetCheckoutPaymentResult

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutPaymentResult xmlns="https://secure.sparrowone.com/Services/">
      <privateKey>string</privateKey>
    </GetCheckoutPaymentResult>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutPaymentResultResponse xmlns="https://secure.sparrowone.com/Services/">
      <GetCheckoutPaymentResultResult>
        <ResultCode>int</ResultCode>
        <Message>string</Message>
        <PaymentInfo>
          <Amount>decimal</Amount>
          <Items>
            <CheckoutPaymentItem>
              <Description>string</Description>
              <SkuNumber>string</SkuNumber>
              <UnitPrice>decimal</UnitPrice>
              <Quantity>int</Quantity>
            </CheckoutPaymentItem>
            <CheckoutPaymentItem>
              <Description>string</Description>
              <SkuNumber>string</SkuNumber>
              <UnitPrice>decimal</UnitPrice>
              <Quantity>int</Quantity>
            </CheckoutPaymentItem>
            ...
          </Items>
          <FailedPaymentAttempts>int</FailedPaymentAttempts>
          <PaymentTransactionId>long</PaymentTransactionId>
          <PaymentDate>dateTime</PaymentDate>
          <PaymentStatus>string</PaymentStatus>
          <PaymentMessage>string</PaymentMessage>
        </PaymentInfo>
      </GetCheckoutPaymentResultResult>
    </GetCheckoutPaymentResultResponse>
  </soap:Body>
</soap:Envelope>

Appendix B – Return Values

ReturnCode

The following table describes possible values of ReturnCode field in all web method responses.

RETURN CODE DESCRIPTION
0 Success
9 Transaction Key parameter is missing
10 Invalid Transaction Key specified
11 Private Key parameter is missing
12 Specified checkout token was not found (invalid private key)
13 Checkout token has expired
14 Invalid checkout amount: sum of prices for each product is not equal to the total payment amount
15 Specified account cannot process transactions. Possible reason is that account is closed
100 Unknown processing error, contact support for details

PaymentStatus

The following table describes possible values of PaymentStatus subelement of PaymentInfo element in GetCheckoutPaymentResult method’s response.

STATUS DESCRIPTION
Successful Payment was successful. Transaction has been created.
Declined Processor has declined the payment. PaymentMessage contains details. Transaction has been created.
Error There was an error processing the message, either at gateway or processor’s side. Transaction may or may not exist in the case of this payment status.

3DS Checkout API

The Payment Checkout Method allows merchants to send consumers to a secure payment page for payment.

Architecture

Here is the URL for the method of integration:

https://secure.sparrowone.com/Payments/Checkout.aspx

The Checkout.aspx is a secure payment page hosted on the Sparrow gateway.  Consumers can be redirected from the merchant website to the payment gateway for customer information collection and payment processing.

There is an additional web service used to provide information for checkout payments. It is located at the following URL:

https://secure.sparrowone.com/Services/CheckoutApi.asmx

Description of all its methods can be found in Appendix A and in sections below.

Merchant Private Key and Payment Types

When sending a payment transaction request to Sparrow (on either implementation) a Merchant Private Key is required.  A sample Merchant Private Key follows:

MTA6MzM6NTYgUE0tLVBheVRhY3RpeA

Further, each Private Key represents a merchant account targeted for processing the transaction.  This methodology allows merchants to have multiple merchant accounts for processing transactions.

To generate a private key, select Add Transaction Routing and enter the appropriate information on the Transaction Routing Management page:

Transaction Routing Management page

The following image shows the account management page in the Merchant Accounts section:

Merchant Accounts page

Integration

Setting up the Account

Please contact the administrator for setting a merchant account.

Checkout Process

Getting the Token

First action to initiate the checkout process is getting the checkout token. This is achieved by calling GetCheckoutToken method of Checkout API web service.

GetCheckoutToken method

GetCheckoutToken method has the following parameters:

VARIABLENAME FORMAT DESCRIPTION
transactionKey string Private key of the merchant account that will receive the payment
amount decimal Total amount of the payment
currency string Code of the payment currency. If the currency is not specified, the default currency (USD) is assumed
items XML Products forming the payment. This is an optional parameter. See Appendix A for detailed description of items format
apiFields XML Additional api fields such as order, billing and shipping information. See Appendix A for detailed description of Web Methods. See Appendix C for description of fields format. See Appendix D for description of integration with eWallet account
variableQuantity boolean This is an optional flag and it is not used in the Checkout API integration. The default value is false

The response consists of the following fields:

VARIABLENAME FORMAT DESCRIPTION
Public key string, 16..128 characters This is the public part of the token key which can be exposed to end users. Public key will be specified as an URL query parameter during the checkout process
Private key string, 16..128 characters This is the private part of the token key which must be kept secret. Private key will be used to retrieve the results of the payment
Expiration Date <date>T<time> This is the date and time of the moment when the checkout token will expire and all further actions with it will not be possible

Processing Payment

To process the payment, redirect the customer to the checkout URL with public token key as a parameter. Here is an example of the resulting URL:

https://secure.sparrowone.com/Payments/Checkout.aspx?Token=214A3E3C8265F6EE

The Checkout Payment page will then ask the customer of his payment information and allow him to process the payment. In the end, system will redirect customer to the page set up in the merchant account settings on Merchant Portal > Administration > Redirect Settings > Edit Account Settings. The customer will be redirected to the page with the following parameters in the query string:

VARIABLENAME FORMAT DESCRIPTION
response alphanumeric string See the table below for possible responses list
textresponse string Textual response
transid number Sparrow transaction ID
orderid alphanumeric string The original order id passed in the transaction request
status alphanumeric string See the table below for possible statuses list

Gateway response field can have the following values:

VALUE TRANSACTION STATUS​ DESCRIPTION
1 Approved Transaction has been processed successfully
2 Declined Transaction has been declined
3 Undefined Please see status field for details. Status of the transaction is “Wait For Response”, “Processor Error” or “Internal Error”

Gateway status field can have the following values:

VALUE OPERATION STATUS​ DESCRIPTION
200 Successful No Errors
201 Wait For Response This is a temporary status. It means that the request was sent to the processor and there are no errors, however, the response has not been received yet
400 Declined Transaction has been declined by processor
401 Processor Error Errors occurred on the processor side
500 Internal Error Unexpected errors

Getting the Payment Result

To get the results, call the GetCheckoutPaymentResult method of the Checkout API. This method requires the private token key as a parameter. The fields returned by this method are the following:

VARIABLENAME FORMAT DESCRIPTION
ResultCode integer Result code of the GetCheckoutPaymentResult operation. See Appendix B for all possible codes
Message string Message describing the result of this operation, i.e. “Success”. This is not the description of payment result
PaymentInfo XML A structure containing information about payment result. See the table below for field explanations

PaymentInfo element contains the following fields (see full description in XML schema, examples can be found in Appendix A):

VARIABLENAME FORMAT DESCRIPTION
Amount decimal Total payment amount (sum of prices for all products)
FailedPaymentAttempts integer Amount of payment attempts made by customer which were declined by the processor
PaymentStatus string Status of the payment. See Appendix B for the list of possible values
PaymentDate <date>T<time> Date of the transaction, if applicable
PaymentMessage string Message returned by the processor
PaymentTransactionId 64-bit integer The gateway’s ID of the transaction, if the transaction exists
Items XML A copy of product list provided to GetCheckoutToken method

If the method runs successfully (i.e. specified token exists, is not expired etc.), it returns the ResultCode of 0. Note that even if the method is successful, this does not mean that the payment was successful. Check the <PaymentInfo> element contents to get the result of the payment itself. Result codes different from zero mean that an error has happened, and <PaymentInfo> element of the response won’t contain any data. You can find the full list of result codes and their meanings in the Appendix B.

Appendix A – Web Methods Description

This section contains request and response formats for both Checkout API methods. Full schema can be found at https://secure.sparrowone.com/Services/CheckoutApi.asmx?wsdl

GetCheckoutToken

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutToken xmlns="https://secure.5thdl.com/Services/">
      <transactionKey>string</transactionKey>
      <amount>decimal</amount>
      <items>
        <CheckoutPaymentItem>
          <Description>string</Description>
          <SkuNumber>string</SkuNumber>
          <UnitPrice>decimal</UnitPrice>
          <Quantity>int</Quantity>
        </CheckoutPaymentItem>
        <CheckoutPaymentItem>
          <Description>string</Description>
          <SkuNumber>string</SkuNumber>
          <UnitPrice>decimal</UnitPrice>
          <Quantity>int</Quantity>
        </CheckoutPaymentItem>
        ...
      </items>
      <apiFields>
        <CheckoutApiField>
            <Name>see Appendix C</Name>
            <Value>see Appendix C</Value>
        </CheckoutApiField>
        ...
      </apiFields>
    </GetCheckoutToken>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutTokenResponse xmlns="https://secure.5thdl.com/Services/">
      <GetCheckoutTokenResult>
        <ResultCode>int</ResultCode>
        <Message>string</Message>
        <Token>
          <PublicKey>string</PublicKey>
          <PrivateKey>string</PrivateKey>
          <ExpirationTime>dateTime</ExpirationTime>
        </Token>
      </GetCheckoutTokenResult>
    </GetCheckoutTokenResponse>
  </soap:Body>
</soap:Envelope>

GetCheckoutPaymentResult

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutPaymentResult xmlns="https://secure.5thdl.com/Services/">
      <privateKey>string</privateKey>
    </GetCheckoutPaymentResult>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCheckoutPaymentResultResponse xmlns="https://secure.5thdl.com/Services/">
      <GetCheckoutPaymentResultResult>
        <ResultCode>int</ResultCode>
        <Message>string</Message>
        <PaymentInfo>
          <Amount>decimal</Amount>
          <Items>
            <CheckoutPaymentItem>
              <Description>string</Description>
              <SkuNumber>string</SkuNumber>
              <UnitPrice>decimal</UnitPrice>
              <Quantity>int</Quantity>
            </CheckoutPaymentItem>
            <CheckoutPaymentItem>
              <Description>string</Description>
              <SkuNumber>string</SkuNumber>
              <UnitPrice>decimal</UnitPrice>
              <Quantity>int</Quantity>
            </CheckoutPaymentItem>
            ...
          </Items>
          <FailedPaymentAttempts>int</FailedPaymentAttempts>
          <PaymentTransactionId>long</PaymentTransactionId>
          <PaymentDate>dateTime</PaymentDate>
          <PaymentStatus>string</PaymentStatus>
          <PaymentMessage>string</PaymentMessage>
        </PaymentInfo>
      </GetCheckoutPaymentResultResult>
    </GetCheckoutPaymentResultResponse>
  </soap:Body>
</soap:Envelope>

Appendix B – Return Values

ReturnCode

The following table describes possible values of ReturnCode field in all web method responses.

RETURN CODE DESCRIPTION
0 Success
9 Transaction Key parameter is missing
10 Invalid Transaction Key specified
11 Private Key parameter is missing
12 Specified checkout token was not found (invalid private key)
13 Checkout token has expired
14 Invalid checkout amount: sum of prices for each product is not equal to the total payment amount
15 Specified account cannot process transactions. Possible reason is that account is closed
100 Unknown processing error, contact support for details

PaymentStatus

The following table describes possible values of PaymentStatus sub element of PaymentInfo element in GetCheckoutPaymentResult method’s response.

STATUS DESCRIPTION
Successful Payment was successful. Transaction has been created.
Declined Processor has declined the payment. PaymentMessage contains details. Transaction has been created.
Error There was an error processing the message, either at gateway or processor’s side. Transaction may or may not exist in the case of this payment status.
NotProcessed User has not completed payment or payment has not been processed by processor yet. Status of the transaction in this case is “Wait For Response”.

transtype=

Appendix C – API Fields Description

The following table describes possible values of apiFields parameter for GetCheckoutToken method.

VARIABLENAME FORMAT DESCRIPTION
firstname string Billing first name
lastname string Billing last name
company string Billing company
address1 string Billing address
address2 string Billing address – line 2
city string Billing city
state CC Billing state (2 character abbrev.)
zip Billing postal code. If the country is US zip code format must be: 5 digits; 9 digits or xxxxx-xxxx (9 digits with -)
country CC (ISO-3166) Billing country (i.e. US)
phone integer Billing phone number
fax string Billing fax number
email string Billing email address
shipfirstname string Shipping first name
shiplastname string Shipping last name
shipcompany string Shipping company
shipaddress1 string Shipping address
shipaddress2 string Shipping address – line 2
shipcity string Shipping city
shipstate CC Shipping state (2 character abbrev.)
shipzip Shipping zip. If the country is US zip code format must be: 5 digits; 9 digits or xxxxx-xxxx (9 digits with -)
shipcountry CC (ISO-3166) Shipping country (i.e. US)
shipphone integer Shipping phone number
shipemail string Shipping email address (single or comma separated emails)
orderdesc string Order description
orderid string Order ID
ponumber string Original Purchase Order
shipamount d.dd Total shipping amount
tax d.dd Total tax amount
ewallettype PayPal This field is optional. It is valid only for eWallet payments. Default value (if the field is messing in the request) is “PayPal”.

Appendix D – Example of Request for eWallet

This section contains an example of the GetCheckoutToken request for integration with eWallet account.

GetCheckoutToken

Request:

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetCheckoutToken xmlns="https://secure.5thdl.com/Services/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <transactionKey>xxxxxxxxxxxxxxxxxxx</transactionKey>
      <amount>5</amount>
      <currency>USD</currency>
      <variableQuantity i:nil="true"/>
      <apiFields>
        <CheckoutApiField>
          <Name>ewallettype</Name>
          <Value>paypal</Value>
        </CheckoutApiField>
        <CheckoutApiField>
          <Name> firstname</Name>
          <Value> Sheila</Value>
          <Name> lastname</Name>
          <Value> Johnson</Value>
        </CheckoutApiField>
      </apiFields>
    </GetCheckoutToken>
  </s:Body>
</s:Envelope>

Code Samples

Here are all the code samples we support.

curl https://examples.com/v1/charges \
-u example_test_DTbaf9757982a9e738f05d249b:

Aliquam sed risus -u vitae tellus venenatis vulputate non id ante. Nullam facilisis placerat ligula non pulvinar. Donec nec purus.

Donec congue pharetra ligula, a porta nulla semper vel. Donec egestas fermentum augue ac ultricies. Aliquam sed risus vitae tellus venenatis vulputate non id ante. Nullam facilisis placerat ligula non pulvinar.

The following is an example of a simple usage of the Sparrow Sdk.

using System.Threading.Tasks;
using SparrowSdk;

namespace SampleClient
{
    class Sample
    {
        private static Sparrow _sparrow = new Sparrow("SPARROW_API_KEY");

        public async Task CreateSparrowSale()
        {
            var result = await _sparrow.SimpleSale("4111111111111111", "01/18", 9.97m, "123");

            if (result.IsSuccess)
            {
                var transactionId = result.TransId;

                // Do something ...
            }
            else
            {
                var textResponse = result.TextResponse;

                // Handle the Failure ...
            }
        }

        public async Task CreateSparrowSale_WithNamedArguments()
        {
            var result = await _sparrow.SimpleSale(cardNum: "4111111111111111", cardExp: "01/18", amount: 9.97m, cvv: "123");

            if (result.IsSuccess)
            {
                var transactionId = result.TransId;

                // Do something ...
            }
            else
            {
                var textResponse = result.TextResponse;

                // Handle the Failure ...
            }
        }

    }
}
require "example"
example.api_key = "example_test_DTbaf9757982a9e738f05d249b"

You can also set a per-request key like in the example below. This is often useful for Connect applications that use multiple API keys during the lifetime of a process.

Authentication is transparently handled for you in subsequent method calls on the returned object.

example::Charge.retrieve(
  "ex_GE47fb22eZvKYlo2Cc0fo87EHa",
  :api_key => "example_test_DTbaf9757982a9e738f05d249b"
)

A sample test API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.

import example
example.api_key = "example_test_DTbaf9757982a9e738f05d249b"

You can also set a per-request key like in the example below. This is often useful for Connect applications that use multiple API keys during the lifetime of a process.

Authentication is transparently handled for you in subsequent method calls on the returned object.

example.Charge.retrieve(
   "ex_GE47fb22eZvKYlo2Cc0fo87EHa",
   api_key="example_test_DTbaf9757982a9e738f05d249b"
)

A sample test API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.

\example\example::setApiKey("example_test_DTbaf9757982a9e738f05d249b");

You can also set a per-request key like in the example below. This is often useful for Connect applications that use multiple API keys during the lifetime of a process.

Authentication is transparently handled for you in subsequent method calls on the returned object.

\example\Charge::retrieve(
   "ex_GE47fb22eZvKYlo2Cc0fo87EHa",
   array('api_key' => "example_test_DTbaf9757982a9e738f05d249b")
)

A sample test API key is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.