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 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. Airline Passenger Sale
    1. Passenger Sale
  10. Military Star Card
    1. Simple Star Card
    2. Advanced Star Card
  11. Automated Clearing House (ACH)/ eCheck
    1. Simple ACH
    2. Advanced ACH
    3. Simple eCheck
    4. Advanced eCheck
  12. eWallet
    1. eWallet Simple Credit
  13. Fiserv
    1. Fiserv Simple Sale
    2. Advanced Fiserv Sale
  14. Chargeback Entry
    1. Mark as Chargeback
  15. Balance Inquiry
    1. Retrieve Card Balance
  16. Decrypt Custom Fields
    1. Decrypt Data
  17. Credit Card Verification
    1. Account Verification
  18. 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
  19. 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
  20. 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
  21. Response Variables
    1. Transaction Response Variables
    2. Gateway Status
    3. Status
  22. Processor Response Codes
    1. AVS Response Codes
    2. CVV Response Codes
    3. Military Star Responses
  23. 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

Sample request:

$c = new Connection('<your Sparrow API key>');

$ci = new CardInfo([
  'number'=>'4111111111111111',
  'expiration'=>'1013',
  'cvv'=>'999',
]);
$res = $c->simpleSale(9.95, $ci);

echo $res->response; // 1
echo $res->transid; // 12345
echo $res->type; // sale

Sample API response:

object(Sparrow\Response)#51 (12) {
  ["response"]=>
  int(1)
  ["textresponse"]=>
  string(7) "SUCCESS"
  ["transid"]=>
  string(8) "10497840"
  ["xref"]=>
  string(10) "3779305439"
  ["authcode"]=>
  string(6) "123456"
  ["orderid"]=>
  string(0) ""
  ["type"]=>
  string(4) "sale"
  ["avsresponse"]=>
  string(0) ""
  ["cvvresponse"]=>
  string(1) "M"
  ["coderesponse"]=>
  string(3) "100"
  ["codedescription"]=>
  string(24) "Transaction was Approved"
  ["status"]=>
  string(3) "200"
}

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

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'

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'

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'

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

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 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'

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

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'

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'

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

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.

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'

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

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

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'

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_# 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'

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'

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_# 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'

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'

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'

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'

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'

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

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

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 would be sent in as a normal Authorization request (not a Sale) with the amount of $0, and the following can be checked 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 auth auth
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=auth&mkey=HNJ45D23MKLO85J2D00LOP&cardnum=4111111111111111&cardexp=1019&amount=0.00&zip=85254

Command Line:

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

Response:

response=1&
textresponse=SUCCESS&
transid=10750787&
xref=3829708536&
authcode=123456&
orderid=&
type=auth&
avsresponse=N&
cvvresponse=M&
coderesponse=100&
codedescription=Transaction+was+Approved&
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'

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

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'

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

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'

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'

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

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'

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'

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'

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'

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

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

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

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

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

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

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

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'

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'

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'

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'

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

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

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

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.

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.