Create Transaction

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:
  • Debit Card
  • Prepaid Card
  • Credit Card
  • Cash
  • Deposit Account
  • Credit Account
  • Mobile Money Account
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:
  • S: Savings
  • C: Checking
  • L: Loan
  • A: Business Savings
  • B: Business Checking
SA ACH
card
object
Hide Object
CR Either Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
or MobilePay (Restricted Usage):
  • accountNumber
  • expirationDate
  • cryptogram
  • transactionID
  • eciIndicator
  • network
  • type
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:
  • S: Savings
  • C: Checking
  • L: Loan
  • A: Business Savings
  • B: Business Checking
DA ACH
card
object
Hide Object
CR Either Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
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)
  • N: Next Day Settlement (Coming soon)
  • S: Same Day Settlement (Coming soon)
  • R: RTP
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.