Creates a Transaction.
If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID (see notes below).
URL:
https://<FQDN>/v1/clients/<ClientIDISO>/transactions
Request:
JSON Name | Value | Required | Default | Description | Choice | ||||
---|---|---|---|---|---|---|---|---|---|
referenceID | String 1-15 characters |
R | Your unique Reference ID | ||||||
correspondingID | String 22 characters |
O | Either Corresponding TransactionID or Corresponding (For a Pull Transaction, this would be the corresponding Push Transaction or For a Push Transaction, this would be the corresponding Pull Transaction) |
CID | |||||
corresponding | object Hide Object
|
O | Either Corresponding or Corresponding TransactionID (For a Push Transaction, this would be the corresponding Pull Transaction) |
C | |||||
ofacValue | String | O | Sender OFAC Value from Query OFAC... | C | |||||
name | object Hide Object
|
R | Sender Name | C | |||||
first | String | R | First Name | C | |||||
last | String | R | Last Name | C | |||||
address | object Hide Object
|
O | Sender Address | C | |||||
line | String | O | Address Line | C | |||||
city | String | O | City | C | |||||
state | String 2-character code |
O | State Code | C | |||||
zipcode | String | O | Zip Code | C | |||||
country | String 3-digit code |
O | 840 | ISO 3166-1 Country Code | C | ||||
accountNumber | String | O | Sender Account Number | C | |||||
sourceOfFunds | String | O | Sender Source of Funds:
|
C | |||||
type | String 4 characters Either push or pull |
R | Transaction Type This is used to verify that your Source and Destination Accounts are valid. |
||||||
accounts | object Hide Object
|
R | Accounts | ||||||
sourceAccountID | String 22 characters |
CR | Either Source AccountID or Source Account | SAID | |||||
sourceAccount | object Hide Object
|
CR | Either Source Account or Source AccountID | SA | |||||
bank | object Hide Object
|
CR | Either Bank or Card | SA ACH | |||||
routingNumber | String 9 digits |
R a | Routing Number | SA ACH | |||||
accountNumber | String 4-17 digits |
R a | Account Number | SA ACH | |||||
accountType | String 1-character code |
R a | Account Type:
|
SA ACH | |||||
card | object Hide Object
|
CR | Either Bank or Card
Either Payment Card Not Encrypted:
|
SA PC | |||||
accountNumber | String 13-19 digits |
R n | Payment Card Account Number | SA PC Not Encrypted |
|||||
expirationDate | String YYYYMM Format |
R n | Expiration Date | SA PC Not Encrypted |
|||||
securityCode | String 3-4 digits |
O n | Security Code | SA PC Not Encrypted |
|||||
keyID | String 22 characters |
R e | KeyID | SA PC Encrypted |
|||||
data | String | R e | Encrypted Card Data, see below encoded in Base64 URL-Safe Character Set |
SA PC Encrypted |
|||||
token | String | ® t | Card Token (from SSO) Restricted Usage |
SA PC Token |
|||||
device | object Hide Object
|
® d | Card Data from P2PE Device Restricted Usage |
SA PC Device |
|||||
id | String | R d | Device Identifier | SA PC Device |
|||||
blob | Hex String | R d | Blob in Hex | SA PC Device |
|||||
mobilePay | object Hide Object
|
® m | Card Data from Mobile Payment Restricted Usage |
SA PC Mobile Pay |
|||||
accountNumber | String 13-19 digits |
R m | Pseudo Payment Card Account Number | SA PC Mobile Pay |
|||||
expirationDate | String YYYYMM Format |
R m | Expiration Date | SA PC Mobile Pay |
|||||
cryptogram | Base64 String 28 characters |
R m | Payment Data Cryptogram | SA PC Mobile Pay |
|||||
transactionID | Hex String 64 characters |
R m | Transaction Identifier in Hex | SA PC Mobile Pay |
|||||
eciIndicator | String 1 character |
O m | Usually only Visa cards | SA PC Mobile Pay |
|||||
network | String | R m | Card Network (Visa, MasterCard, Amex, Discover, etc...) |
SA PC Mobile Pay |
|||||
type | String | R m | Card Type (Debit, Credit, PrePaid, etc...) |
SA PC Mobile Pay |
|||||
processor | object Hide Object
|
® p | Processor Restricted Usage |
SA PC Processor |
|||||
name | String | R p | Name | SA PC Processor |
|||||
token | String | R p | Token | SA PC Processor |
|||||
owner | object Hide Object
|
R | Account Owner | SA | |||||
name | object Hide Object
|
R | Name
Either Company or First, Middle, Last, and Suffix |
SA | |||||
company | String | R c | Company Name | SA | |||||
first | String | R n | First Name | SA | |||||
middle | String | O n | Middle Name or Initial | SA | |||||
last | String | R n | Last Name | SA | |||||
suffix | String | O n | Suffix | SA | |||||
address | object Hide Object
|
O | Address | SA | |||||
line1 | String | O | Address Line 1 | SA | |||||
line2 | String | O | Address Line 2 | SA | |||||
city | String | O | City | SA | |||||
state | String 2-character code |
O | State Code | SA | |||||
zipcode | String | O | Zip Code | SA | |||||
country | String 3-digit code |
O | 840 | ISO 3166-1 Country Code | SA | ||||
phone | object Hide Object
|
O | Phone Number (E.164 Numbering) | SA | |||||
countryCode | String 1-3 digits |
O | 1 | Country Calling Code | SA | ||||
number | String Min: 4 digits Max: 12-14 digits |
R | Phone Number | SA | |||||
destinationAccountID | String 22 characters |
CR | Either Destination AccountID or Destination Account | DAID | |||||
destinationAccount | object Hide Object
|
CR | Either Destination Account or Destination AccountID | DA | |||||
bank | object Hide Object
|
CR | Either Bank or Card | DA ACH | |||||
routingNumber | String 9 digits |
R a | Routing Number | DA ACH | |||||
accountNumber | String 4-17 digits |
R a | Account Number | DA ACH | |||||
accountType | String 1-character code |
R a | Account Type:
|
DA ACH | |||||
card | object Hide Object
|
CR | Either Bank or Card
Either Payment Card Not Encrypted:
|
DA PC | |||||
accountNumber | String 13-19 digits |
R n | Payment Card Account Number | DA PC Not Encrypted |
|||||
expirationDate | String YYYYMM Format |
R n | Expiration Date | DA PC Not Encrypted |
|||||
securityCode | String 3-4 digits |
O n | CVV2 | DA PC Not Encrypted |
|||||
keyID | String 22 characters |
R e | KeyID | DA PC Encrypted |
|||||
data | String | R e | Encrypted Card Data, see below encoded in Base64 URL-Safe Character Set |
DA PC Encrypted |
|||||
token | String | ® t | Card Token (from SSO) Restricted Usage |
DA PC Token |
|||||
device | object Hide Object
|
® d | Card Data from P2PE Device Restricted Usage |
DA PC Device |
|||||
id | String | ® d | Device Identifier | DA PC Device |
|||||
blob | Hex String | ® d | Blob in Hex | DA PC Device |
|||||
processor | object Hide Object
|
® p | Processor Restricted Usage |
SA PC Processor |
|||||
name | String | R p | Name | SA PC Processor |
|||||
token | String | R p | Token | SA PC Processor |
|||||
owner | object Hide Object
|
R | Account Owner | DA | |||||
name | object Hide Object
|
R | Name
Either Company or First, Middle, Last, and Suffix |
DA | |||||
company | String | R c | Company Name | DA | |||||
first | String | R n | First Name | DA | |||||
middle | String | O n | Middle Name or Initial | DA | |||||
last | String | R n | Last Name | DA | |||||
suffix | String | O n | Suffix | DA | |||||
address | object Hide Object
|
O | Address | DA | |||||
line1 | String | O | Address Line 1 | DA | |||||
line2 | String | O | Address Line 2 | DA | |||||
city | String | O | City | DA | |||||
state | String 2-character code |
O | State Code | DA | |||||
zipcode | String | O | Zip Code | DA | |||||
country | String 3-digit code |
O | 840 | ISO 3166-1 Country Code | DA | ||||
phone | object Hide Object
|
O | Phone Number (E.164 Numbering) | DA | |||||
countryCode | String 1-3 digits |
O | 1 | Country Calling Code | DA | ||||
number | String Min: 4 digits Max: 12-14 digits |
R | Phone Number | DA | |||||
currency | String 3 digits |
O | 840 | ISO 4217 Currency Number | |||||
amount | String Amount |
R | Transaction Amount | ||||||
ofacValue | String | O | OFAC Value from Query OFAC... | ||||||
memo | String Max of 32 characters |
O | Memo | ||||||
achOptions | String 1-character code |
O R>ACH |
ACH Options: (Required for ACH)
|
ACH | |||||
pullOptions | object Hide Object
|
O | Additional Pull Options | ||||||
securityCode | String 3-4 digits |
O | CVV2 Valid only when using sourceAccountID (Pull) |
||||||
recurring | Boolean | O | Recurring Pull Transaction | ||||||
3DSecure | Object | O | 3D Secure | ||||||
version | String | O RMasterCard |
Version Required by MasterCard |
||||||
ECI | String | R | ECI (Electronic Commerce Indicator) | old: 3dsECI | |||||
UCAF | String | R | UCAF (Universal Cardholder Authentication Field) | old: 3dsUCAF | |||||
XID | String | O | XID (Transaction ID) | old: 3dsXID | |||||
dsTransactionID | String | O RMasterCard |
Directory Server TransactionID Required by MasterCard |
||||||
level2TaxExempt | boolean | O | Level 2: Tax Exempt | Level 2 | |||||
level2TaxAmount | String Amount |
O | Level 2: Tax
Amount (Currency is the same as the Transaction Amount) |
Level 2 | |||||
level3 | Object | O | Level 3 | Level 3 | |||||
amountTax | String Amount |
R | Tax Amount (Currency is the same as the Transaction Amount) |
Level 3 | |||||
tax | Code 1 digit |
R | 0 = Sales Tax Not Included 1 = Sales Tax Included 2 = Tax Exempt |
Level 3 | |||||
taxRate | Number Max 2 decimal places |
R | Tax Rate | Level 3 | |||||
amountDiscount | String Amount |
R | Discount Amount | Level 3 | |||||
amountShipping | String Amount |
R | Shipping Amount | Level 3 | |||||
amountDuty | String Amount |
R | Duty Amount | Level 3 | |||||
itemCommodityCode | String | R | Item Commodity Code | Level 3 | |||||
itemDescription | String | R | Item Description | Level 3 | |||||
productCode | String | R | Product Code | Level 3 | |||||
quantity | Number | R | Quantity | Level 3 | |||||
unitOfMeasure | String | R | Unit of Measure | Level 3 | |||||
amountUnitCost | String Amount |
R | Unit Cost | Level 3 | |||||
amountItemDiscount | String Amount |
R | Discount per Line Item | Level 3 | |||||
amountTotal | String Amount |
R | Total | Level 3 | |||||
poNumber | String | R | Purchase Order Number | Level 3 | |||||
softDescriptor | object Hide Object
|
® | Soft Descriptor Restricted Usage |
® | |||||
name | String | R | Name | ® | |||||
address | object Hide Object
|
R | Address | ® | |||||
line1 | String | R | Address Line 1 | ® | |||||
line2 | String | O | Address Line 2 | ® | |||||
city | String | R | City | ® | |||||
county | String 3 characters |
R | County | ® | |||||
state | String 2-character code |
R | State Code | ® | |||||
zipcode | String | R | Zip Code | ® | |||||
country | String 3-digit code |
O | 840 | ISO 3166-1 Country Code | ® | ||||
phone | object Hide Object
|
O | Phone Number (E.164 Numbering) | ® | |||||
countryCode | String 1-3 digits |
O | 1 | Country Calling Code | ® | ||||
number | String Min: 4 digits Max: 12-14 digits |
R | Phone Number | ® | |||||
email
|
String | O RAmex |
Email Address
For American Express Bill Pay Provider program: Seller Email Address (max of 40 characters) |
® | |||||
id
|
String | O RAmex |
ID
For American Express Bill Pay Provider program: Seller ID (max of 20 digits) |
® | |||||
location | object Hide Object
|
O | Location of the Origination of Transaction | ||||||
name | String | R | Location Name | ||||||
address | object Hide Object
|
R | Location Address | ||||||
line1 | String | R | Address Line 1 | ||||||
line2 | String | O | Address Line 2 | ||||||
city | String | R | City | ||||||
state | String 2-character code |
R | State Code | ||||||
zipcode | String | R | Zip Code | ||||||
country | String 3-digit code |
O | 840 | ISO 3166-1 Country Code |
(Encrypted) Card Data
Field | Required | Description | UnEncrypted Card Data Format |
---|---|---|---|
Card Number | R | 13-19 digit Card Number | CardNumber | Expiration Date | Security Code (no spaces, pipe symbol separated) see samples |
Expiration Date | R | Expiration date in YYYYMM Format | |
Security Code | O | 3 or 4 digit CVV2 |
Sample Request:
Pack your Request, the following Samples shown here are unpacked only for human readability:
Create Transaction:
{
"referenceID": "1",
"type": "push",
"accounts":
{
"sourceAccountID": "TabaPay_AccountID_22-c",
"destinationAccountID": "TabaPay_AccountID_22-c"
},
"amount": "1.00"
}
-----
Create Pull Transaction:
{
"referenceID": "1",
"type": "pull",
"accounts":
{
"sourceAccount":
{
"card":
{
"accountNumber": "9999999999999999",
"expirationDate": "202012"
},
"owner":
{
"name":
{
"first": "John",
"last": "Benson"
},
"address":
{
"line1": "465 Fairchild Drive",
"line2": "Suite #222",
"city": "Mountain View",
"state": "CA",
"zipcode": "94043"
},
"phone":
{
"number": "4159808222"
}
}
},
"destinationAccountID": "TabaPay_AccountID_22-c"
},
"amount": "0.10"
}
-----
Create Push Transaction:
{
"referenceID": "1",
"type": "push",
"accounts":
{
"sourceAccountID": "TabaPay_AccountID_22-c",
"destinationAccount":
{
"card":
{
"accountNumber": "9999999999999999",
"expirationDate": "202012"
},
"owner":
{
"name":
{
"first": "John",
"last": "Benson"
},
"address":
{
"line1": "465 Fairchild Drive",
"line2": "Suite #222",
"city": "Mountain View",
"state": "CA",
"zipcode": "94043"
},
"phone":
{
"number": "4159808222"
}
}
}
},
"amount": "0.10"
}
-----
Unencrypted Card Data:
1111111111111111|203001|
where
Card Number: 1111111111111111
Expiration Date: January 2030
Security Code: None
-----
1111111111111111|203001|333
where
Card Number: 1111111111111111
Expiration Date: January 2030
Security Code: 333
Response:
Status Codes:
Status Code | Description | |
---|---|---|
200 | OK | A Transaction is created and processing is completed. |
201 | Created | A Transaction is created, but the transaction is waiting to be processed (batch). |
207 | Multi-Status | One or more Failures occurred while processing the Request. |
429 | Too Many Requests | Over your Daily (24-hour rolling) Approximation Limit. |
See Status Codes for other possible Status Codes that might be returned.
Response Data:
JSON Name | Value | Description | Status Code | |||||
---|---|---|---|---|---|---|---|---|
200 | 201 | 207 | Other | |||||
SC | Integer 3-digit code |
HTTP Status Code | ✔ | ✔ | ✔ | O | ||
EC | String 1 or 8 characters |
Internal Error Code | ✔ | ✔ | ✔ | O | ||
EM | String | Error Message | O | O | ||||
transactionID | String 22 characters |
TransactionID | ✔ | ✔ | ✔ | |||
network | String | Network | ✔ | ✔ | ✔ | |||
networkRC | String 2 or 3-character code |
Network Response Code | ✔ | O | ||||
networkID | String | NetworkID (Network TransactionID) |
O | |||||
status | String | Status | ✔ | ✔ | ✔ | |||
approvalCode | String 6 characters |
Approval Code | ✔ | O | ||||
errors | Array of 8 characters Strings |
Array of Internal Error Codes | ✔ | |||||
AVS | object | AVS Results | C | |||||
codeAVS | String | AVS Response Code | O | |||||
codeSecurityCode | String | Security Code Response Code | O | |||||
fees | object | Estimated Fees | O | O | ||||
interchange | String Amount |
Interchange Fees | ✔ | ✔ | ||||
network | String Amount |
Network Fees | ✔ | ✔ | ||||
tabapay | String Amount |
TabaPay Fees | ✔ | ✔ | ||||
card | object | Card | O | O | ||||
last4 | String 4 digits |
Last 4 of Card Account Number (PAN) | ✔ | ✔ | ||||
expirationDate | String 6 digits |
Expiration Date YYYYMM Format |
O | O |
Sample Responses:
Transaction created:
{
"SC": 200,
"EC": "0",
"transactionID": "TabaPay_TransactionID_",
"network": "Visa",
"networkRC": "00",
"status": "COMPLETED",
"approvalCode": "000000"
}
-----
Transaction created but waiting to be processing (batch):
{
"SC": 201,
"EC": "0",
"transactionID": "TabaPay_TransactionID_",
"network": "CreditCards",
"status": "PENDING"
}
Notes:
For Clients who are an ISO (Independent Sales Organization), to specify your ClientID and a SubClientID, use the underscore character ("_") to separate the two values: <ClientID>_<SubClientID>
where:
- ClientID is your unique 22-character string and
- SubClientID is an assigned 4, 6 or 8-digit value.
One of the accounts in the Request, Source Account or Destination Account, must be your Settlement Account. If disbursing funds (push) the Source Account should be your Settlement Account. If collecting funds (pull) the Destination Account should be your Settlement Account.
On a Pull Transaction, specifying at least the Owner Address Line 1 and/or Owner Zip Code will result in an automatic AVS check which may result in lower fees. However, a bad AVS will not stop the Transaction. You should have previously done a Query Card with AVS to check the Card.
A Timeout does not STOP the Transaction from continuing to be processed. It does mean that the Transaction Status will be temporarily in an UNKNOWN status. The SC (Status Code) in the Response will be 207.
Once the Transaction finished processing, the Actual Status of the Transaction will be reflected. You can do a Retrieve Transaction to check on the actual Transaction Status. However, do not poll, otherwise you will get SC=429.
After 90 seconds, the Transaction Status will NOT change. We have given up waiting for a response. Most likely, the Transaction Status will remain in an UNKNOWN status. Contact TabaPay Support if you need us to investigate what really happened with this Transaction.
The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.