TabaPay
Developers
APIReferenceSamplesFAQProduct DocsLogin
API
Notices and Versions
Overview
Resources / Services
Client
● Retrieve
Key
● Create
● Retrieve
● Delete
Card
● Query
Bank
● Query
OFAC
● Query
Account
● Create
● Retrieve
● Update
● Update v2
● Delete
Transaction
● Create
● Retrieve
● Delete
TransactionRequest
● Create
3D Secure
● Initialize
● Lookup
● Authenticate
FXRate
● Query
SubClient
● Create
● Retrieve
● Update
● Delete
Reference
Networks
Network Response Codes
AVS Response Codes
Internal Error Codes
Status Codes
Currency Numbers
Country Codes
State Codes
Resource Statuses
Samples
Test Cards
Sample Flows
Code Samples
● curl
● wget
● openssl s_client
● Java
● JavaScript
● Go
● Python
● Ruby
PCI Helpers
● PCI Helper - SSO
● PCI Helper - RSA
FAQ
General
Data
Errors
Coding
Sandbox Environment
UAT Environment
Production Environment
PCI / SOC
PCI Helper - SSO
PCI Helper - RSA
3D Secure
GooglePay
ACH / RTP
Clients WebSite
Anti-Pattern
Duplicate Card Check
Future
Product Docs
List of Available Docs

Notices and Versions

Come here often and look for important information, including information about current and future releases... You might have to do a browser refresh to get the latest version of this WebSite.
Important Notices


Between November and January is time for our Annual PCI Tasks and Audit.

Between March and June is time for our Annual SOC Audits.


Doing a lot (or constant API Call) of Retrieves, either:

is NOT the correct way to use our API. Please contact support@TabaPay.com.


We have enabled Rate Limiting on the Sandbox Environment. Sandbox is a Shared Environment used by many Clients and meant only for Development purposes...

SSO Token will Expire after 5-10 minutes and will therefore be rendered invalid.

CreateKey will be deprecating soon. When the CreateKey replacement becomes available, CreateKey will be disabled...

RetrieveAccount by ReferenceID is deprecated and should only be used in the case of a HTTP Communications Error where an AccountID was not returned back.

RetrieveTransaction by ReferenceID is deprecated and should only be used in the case of a HTTP Communications Error where a TransactionID was not returned back.

    If you continue to use Retrieve by ReferenceID, the API will return a Status Code of 421 Misdirected Request:


ReferenceID Change:

ReferenceID will no longer be required to be UNIQUE on a CreateAccount. If you do a Retrieve by ReferenceID, you will get the last one (the most recently added).

If you continue to use Retrieve by ReferenceID, at certain times (like during maintenance), you may occasionally get SC=404 (Not Found). Retrieve by ReferenceID was meant to be used only in the case of a HTTP communication error and you did not receive a ResourceID (AccountID) in the Response. You should always use Retrieve by ResourceID (AccountID).


Anti-Pattern Detection:

See the Anti-Pattern FAQ...

Anti-Pattern or incorrect use of TabaPay’s API is not permitted on Sandbox, UAT, or Production Environments as they can impact the overall Environment. Examples of incorrect use of TabaPay’s API:

Incorrect use of TabaPay’s API will result in the IP Addresses being immediately blocked.


We will only keep transactions accessible to the TabaPay API for approximately 120 days. This means that Delete Transaction will only work for transactions within approximately 120 days. However, we archive transactions for many years (as legally required).

Inactive IP Addresses will be disabled in the Sandbox Environment. Contact TabaPay Support if you need to reenable a disabled IP Address. If you need more IP Addresses whitelisted, consider using a Proxy (or our Proxy).

Creating too many Keys in the Sandbox and/or Production Environment will cause your CreateKey to be disabled.

Inactive and Duplicate Accounts, created with the Account Create API in the Sandbox, UAT, or Production Environment, may result in these inactive and duplicate accounts being deleted and/or additional charges will be charged for these accounts.

Please inform us of possible Volume Spikes.
If you do not inform us of unexpected Volume Spikes, our systems may detect it as abnormal and our systems may block all IP Addresses causing this unexpected Volume Spikes. Volume Spikes that are all (or mostly) Errors, like:

will expedite this block of IP Addresses. Also see the Anti-Pattern FAQ...

There should be no expectations on the Sandbox or UAT Environments, see the FAQ for the Sandbox Environment and see the FAQ for the UAT Environment. The Sandbox and UAT Environments use Simulators, so the accuracy of these Simulators may not be exactly the same as you will see in Production. For example, AVS calls will most likely always return a Network Response Code of 85, we will change the Simulator in the near future to reflect this.

Ready for Production? Please read the Production FAQ.

We have multiple Environments:

The last two Environments are for TabaPay Internal Use Only.

We will try not to update this WebSite before the corresponding Code Release to the Sandbox Environment. However, this WebSite might be slightly ahead of the Code Release to the Sandbox and Production Environments. So some things that are described on this WebSite may not yet be available and working in the Environment you are using.


Operations Notes

On Sandbox and UAT Environments, your Client will now be limited to the IPs Whitelisted for that Client. If you have more than one Client, you will need to specify the IPs to be Whitelisted for each Client separately. This will also be implemented on the Production Environment soon...


Questions of the Month (or Answers of the Month):
Creating unused and/or inactive Accounts will result in:


The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.


If you need help, please contact support@TabaPay.com with the following:

In order to help us help you, please be as accurate as possible. Also, see the Coding FAQ.


SLA / Outages

See the Environments' Status and SLA / Outages Page.


WebSite Updates

This WebSite was last updated on 03/21/2022 at 11:55 PDT.

Sandbox/UAT Maintenance

EnvironmentMaintenance
DateTask
UAT02/28/2021Database Cleaned Up*
Sandbox02/28/2021Database Cleaned Up*
Sandbox05/26/2020 - 08/03/2020Migrate to New Sandbox Environment
UAT05/24/2020Database Cleaned Up*
Sandbox05/24/2020Database Cleaned Up*

* There should be no expectations on the Sandbox or UAT Environments.
   Nothing is unlimited, this includes the database, so the database was cleaned up.

Versions

EnvironmentCurrent
VersionDeployment Date
Production USE1v22.012401/29/2022
Production USE2v22.012401/29/2022
UATv22.012402/01/2022
Sandboxv22.012402/01/2022


Developers WebSite

This WebSite is a SPA (Single Page Application), which means:If you use this WebSite offline, please be sure to check for any updates, WebSite Updates, above...


Terms and Conditions

By using this WebSite and/or using the software (API), you agree that neither this WebSite nor the information disclosed therein nor the software nor any part thereof shall be reproduced or transferred to other WebSites or documents nor used or disclosed for any purpose except as specifically authorized in writing by TabaPay.

This WebSite is preliminary and is subject to change.

TabaPay makes no representation or warranties, expressed or implied, as to the truth or accuracy of any information contain herein. This WebSite may include typographical errors and technical inaccuracies. This WebSite is provided "as is" and all expressed or implied conditions, representations and warranties, including any implied warranty of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed; except to the extent that such disclaimers are held to be legally invalid.

The URLs and ResourceIDs specified on this WebSite are only used for illustrative purposes (temporary place holders and/or samples) and does not reflect the actual URLs and ResourceIDs to be used (in Sandbox or Production). Please contact TabaPay Support for the actual URLs and ResourceIDs to be used for your situation.

Overview

The TabaPay Web Service (API) is just a simple RESTful Web Service that uses standard HTTPS to:where the Request Data and the Response Data are formatted using standard JSON.

HTTP Header

Authorization: Bearer <TokenValue>
Content-type: application/json

HTTP Cookies

No cookies are used.

IP Whitelisting

Only the IP Addresses that you specify to us will work. Our Firewalls will block all non-whitelisted IP Addresses.

You will need to reverify your IP Addresses every year, otherwise they will be removed.

Client Certificate

Possible future support, but from past experience, no one really wanted to use Client Certificates.


API Descriptions Notations

Request:
CodeDescription
RRequired
OOptional
CConditional
®Restricted Usage (Permissions Required)
CRConditional Required - Choice
CodeDescription
R nRequired if chosing Non-Encrypted Card Data
O nOptional if chosing Non-Encrypted Card Data
R eRequired if chosing Encrypted Card Data
O eOptional if chosing Encrypted Card Data
RAVSRequired if AVS
® tRestricted Usage (Permissions Required) if chosing Token
® mRestricted Usage (Permissions Required) if chosing MobilePay
R mRequired if chosing MobilePay
O mOptional if chosing MobielPay
R aRequired if chosing Bank Data (ACH)
R cRequired if chosing Company Name
R nRequired if chosing Name
O nOptional if chosing Name

Response:

CodeDescription
Returned
OOptional

Resources

The TabaPay Web Service (API) consist of the following resources and operations (methods):Some characteristics of a Resource are:

Resource IDs

Some characteristics of a ResourceID are:

Services

The TabaPay Web Service (API) also consist of the following services:

Client

This resource represents a Client.

The only operation available for this resource is:

●   Retrieve
Retrieves the attributes of a Client

Only TabaPay can:

●   Create
●   Update
including locking a Client
●   Delete
a Client. If you need to Update your Client Information, please contact TabaPay support.

Retrieve Client

Retrieves the attributes of a Client.
URL
https://<FQDN>/v1/clients/<ClientID>
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Client's Attributes are returned.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
labelString
(no whitespaces)
Client Label
networksobjectList of Available Networks
pullarray
of Strings
For Pull Transactions
Array can be empty or is a List of Network Names
pusharray
of Strings
For Push Transactions
Array can be empty or is a List of Network Names
limitsobject
currencyString
3-digit code
ISO 4217 Currency Number
pullobject
transactionString
Amount
Pull Transaction Limit
dailyString
Amount
Approximate Pull Daily Limit
networksarray
of objects
List of Network Limits
Network is listed only if different from above Pull Limits
O
networkStringNetwork Name
transactionString
Amount
Network Pull Transaction Limit
dailyString
Amount
Approximate Network Pull Daily Limit
pushobject
transactionString
Amount
Push Transaction Limit
dailyString
Amount
Approximate Push Daily Limit
networksarray
of objects
List of Network Limits
Network is listed only if different from above Push Limits
O
networkStringNetwork Name
transactionString
Amount
Network Push Transaction Limit
dailyString
Amount
Approximate Network Push Daily Limit
View
Hide
  Samples
Client's Attributes returned:
{
  "SC": 200,
  "EC": "0",
  "label": "ClientLabel",
  "networks":
  {
    "pull":
    [
      "STAR",
      "Visa"
    ],
    "push":
    [
      "STAR",
      "CU24",
      "Visa"
    ]
  },
  "limits":
  {
    "currency": "840",
    "pull":
    {
      "transaction": "0.25",
      "daily": "1.00"
    },
    "push":
    {
      "transaction": "0.25",
      "daily": "1.00",
      "networks":
      [
        {
          "network": "CU24",
          "transaction": "0.20",
          "daily": "1.00"
        }
      ]
    }
  }
}

Client not found:
{
  "SC": 404,
  "EC": "3A100000",
  "EM": "Not Found"
}

Client locked:
{
  "SC": 423,
  "EC": "3A100000",
  "EM": "Locked"
}
Notes
The Client Label is the human readable identifier used to identify you versus using your ClientID. It may be used:
  • in part of the file name for various Reports we generate for you, and
  • in part of the URL for access to the Client WebSite.

Key

This resource represents a RSA Encryption Key.

The operations that are available for this resource are:

●   Create
Creates a Key
●   Retrieve
Retrieves a Key
●   Delete
Deletes a Key

Create Key

Creates a Key.
URL
https://<FQDN>/v1/clients/<ClientID>/keys
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
formatStringRPublic Key Response Format, either:
  • ASN.1
  • Raw (Modulus and Public Exponent)
expirationInteger
Between 30 and 365
R365Key Expiration Time:
  • Minimum of 30 days
  • Maximum of 365 days
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

ASN.1

{
  "format": "ASN.1",
  "expiration": 365
}
Raw (Modulus and Public Exponent)
{
  "format": "Raw",
  "expiration": 365
}
Response
Status Codes
Status CodeDescription
200OKA Key is created.
429Too Many RequestsCreated too many Keys
See Notes Below...

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
ASN.1RawOther
200200
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
keyIDString
22 characters
KeyID
keyStringASN.1
encoded in Base64 URL-Safe Character Set
keyModulusStringModulus
encoded in Base64 URL-Safe Character Set
keyExponentStringPublic Exponent
encoded in Base64 URL-Safe Character Set
expirationStringKey Expiration in yyyy-MM-ddTHH:mm:ssZ Format.
noticesStringImportant NoticesOOO
View
Hide
  Samples
Key created returned in ASN.1 format:
{
  "SC": 200,
  "EC": "0",
  "keyID": "TabaPay_KeyID_22-chars",
  "key": "Base64_Encoded_Key",
  "expiration": "2017-04-03T00:00:00Z"
}
Key created returned in Raw format:
{
  "SC": 200,
  "EC": "0",
  "keyID": "TabaPay_KeyID_22-chars",
  "keyModulus": "Base64_Encoded_Modulus",
  "keyExponent": "Base64_Encoded_Exponent",
  "expiration": "2017-04-03T00:00:00Z"
}
Notes
Keys are valid for 365 days. Key Expiration is now deprecated.

You should only have at most 2 keys active at any one time. If you create more than 2 keys that are currently active (expiration date), you might get a return of SC=429, Too Many Requests. However, if the system detects that there are more than 2 keys that are currently active (expiration date), the system may automatically delete the older keys until there are at most 2 keys that are currently active.

Retrieve Key

Retrieves the Key.
URL
https://<FQDN>/v1/clients/<ClientID>/keys/<KeyID>
https://<FQDN>/v1/clients/<ClientID>/keys/<KeyID>?Format=ASN.1
https://<FQDN>/v1/clients/<ClientID>/keys/<KeyID>?Format=Raw
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Key is returned.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
ASN.1RawOther
200200
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
keyStringASN.1
encoded in Base64 URL-Safe Character Set
keyModulusStringModulus
encoded in Base64 URL-Safe Character Set
keyExponentStringPublic Exponent
encoded in Base64 URL-Safe Character Set
expirationStringKey Expiration in yyyy-MM-ddTHH:mm:ssZ Format.
View
Hide
  Samples
Key returned in ASN.1 format:
{
  "SC": 200,
  "EC": "0",
  "keyID": "TabaPay_KeyID_22-chars",
  "key": "Base64_Encoded_Key",
  "expiration": "2017-04-03T00:00:00Z"
}
Key returned in Raw format:
{
  "SC": 200,
  "EC": "0",
  "keyID": "TabaPay_KeyID_22-chars",
  "keyModulus": "Base64_Encoded_Modulus",
  "keyExponent": "Base64_Encoded_Exponent",
  "expiration": "2017-04-03T00:00:00Z"
}
Notes
The default Format is Raw.

Delete Key

Deletes a Key.
URL
https://<FQDN>/v1/clients/<ClientID>/keys/<KeyID>
HTTP Method
DELETE
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Key is marked for deletion.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Key deleted:
{
  "SC": 200,
  "EC": "0"
}

Key not found:
{
  "SC": 404,
  "EC": "10000000"
}

Key already marked for deletion:
{
  "SC": 410,
  "EC": "50000000"
}
Notes
Keys are automatically deleted after their expiration.

Card

This resource represents a Payment Card (Debit Card, PrePaid Card, or Credit Card).

The only operation available for this resource is:

●   Query
Returns the attributes for the requested Payment Card

Query Card

Returns the attributes for the requested Payment Card. Optionally:

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/cards

https://<FQDN>/v1/clients/<ClientIDISO>/cards?AVS
https://<FQDN>/v1/clients/<ClientIDISO>/cards?Fees
https://<FQDN>/v1/clients/<ClientIDISO>/cards?AVS+Fees

https://<FQDN>/v1/clients/<ClientIDISO>/cards?Verify
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescriptionConditional
networksStringOList of Network Codes
For ISOs, please contact TabaPay Support for details on when and how to use.
cardTypesPullStringOList of Card Type Codes
For ISOs, please contact TabaPay Support for details on when and how to use.
cardTypesPushStringO
account
object
View Object
CREither Account or CardAccount
accountIDString
22 characters
RAccountIDAccount
securityCodeString
3-4 digits
OCVV2Account
AVS
card
object
View Object
CREither Account or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • mode
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
or MobilePay (Restricted Usage):
  • accountNumber
  • expirationDate
  • cryptogram
  • transactionID
  • eciIndicator
  • network
  • type
Card
Data Encrypted?
accountNumberString
13-19 digits
R nPayment Card Account NumberCard
Not Encrypted
expirationDateString
YYYYMM Format
O n
RAVS
Expiration DateCard
Not Encrypted
AVS
securityCodeString
3-4 digits
O nCVV2Card
Not Encrypted
AVS
keyIDString
22 characters
R eKeyIDCard
Encrypted
modeInteger
0, 1, or 2
D e2Encryption Mode (Transformation)
0 = PKCS#1 v1.5
1 = Java OAEP
2 = OAEP SHA-256
Card
Encrypted
dataStringR eEncrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
Card
Encrypted
tokenString® tCard Token (from SSO)
Restricted Usage
Card
Token
device
object
View Object
® dCard Data from P2PE Device
Restricted Usage
Card
Device
idString® dDevice IdentifierCard
Device
blobHex String® dBlob in HexCard
Device
mobilePay
object
View Object
® mCard Data from Mobile Payment
Restricted Usage
SA PC
Mobile Pay
accountNumberString
13-19 digits
R mPseudo Payment Card Account NumberSA PC
Mobile Pay
expirationDateString
YYYYMM Format
R mExpiration DateSA PC
Mobile Pay
cryptogramBase64 String
28 characters
R mPayment Data CryptogramSA PC
Mobile Pay
transactionIDHex String
64 characters
R mTransaction Identifier in HexSA PC
Mobile Pay
eciIndicatorString
1 character
O mUsually only Visa cardsSA PC
Mobile Pay
networkStringR mCard Network
(Visa, MasterCard, Amex, Discover, etc...)
SA PC
Mobile Pay
typeStringR mCard Type
(Debit, Credit, PrePaid, etc...)
SA PC
Mobile Pay
owner
object
View Object
CCard HolderAVS / Verify
name
object
View Object
CName on CardVerify
firstStringRFirst NameVerify
middleStringOMiddle Name or InitialVerify
lastStringRLast NameVerify
suffixStringOSuffixVerify
address
object
Hide Object
CBilling AddressAVS
line1StringOAddress Line 1, for AVS, see notes belowAVS
line2StringOAddress Line 2AVS
cityStringOCityAVS
stateString
2-character code
OState CodeAVS
zipcodeStringRZip CodeAVS
countryString
3-digit code
O840ISO 3166-1 Country CodeAVS
phone
object
View Object
CPhone Number (E.164 Numbering)Verify
countryCodeString
1-3 digits
O1Country Calling CodeVerify
numberString
Min: 4 digits
Max: 12-14 digits
RPhone NumberVerify
currencyString
3-digits
O840ISO 4217 Currency NumberFees Check
amountString
Amount
CAmount of TransactionFees Check
timeoutNumber
Between 15 and 50
O39Maximum time to wait for AVS and/or Verify ResponseAVS / Verify
(Encrypted) Card Data
FieldRequiredDescriptionUnEncrypted Card Data Format
Card NumberR13-19 digit Card NumberCardNumber | Expiration Date | Security Code

(no spaces, pipe symbol separated)
see samples
Expiration DateO
RAVS
Expiration date in YYYYMM Format
Security CodeO3 or 4 digit CVV2
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Query Card:

{
  "card":
  {
    "accountNumber": "9999999999999999"
  }
}
Query Card using Encrypted Data:
{
  "card":
  {
    "keyID": "TabaPay_KeyID_22-chars",
    "data": "Base64_Encoded_Encrypted_Data"
  }
}
Query Card using AccountID:
{
  "account":
  {
    "accountID": "TabaPay_AccountID_22ch"
  }
}

Query Card and Fees Check:
{
  "card":
  {
    "accountNumber": "9999999999999999"
  },
  "amount": "0.50"
}

Unencrypted Card Data:
1111111111111111||

where

Card Number:     1111111111111111
Expiration Date: None
Security Code:   None

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

1111111111111111||333

where

Card Number:     1111111111111111
Expiration Date: None
Security Code:   333
Response
Status Codes
Status CodeDescription
200OKThe Payment Card's Attributes are returned.
207Multi-StatusOne or more Failures occurred while processing the Request.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus CodeConditional
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
cardobjectCard Attributes
pullobjectDebit Transaction
enabledBoolean
networkStringOO
typeStringCredit, Debit, PrepaidOO
regulatedBooleanOO
currencyString
3-digit code
ISO 4217 Currency NumberOO
countryString
3-digit code
ISO 3166-1 Country CodeOO
pushobjectCredit Transaction
enabledBoolean
networkStringOO
typeStringCredit, Debit, PrepaidOO
availabilityStringEstimated Funds AvailabilityOO
regulatedBooleanOO
currencyString
3-digit code
ISO 4217 Currency NumberOO
countryString
3-digit code
ISO 3166-1 Country CodeOO
AVSobjectAVS ResultsCCAVS
networkRCString
2 or 3-character code
Network Response CodeOAVS
authorizeIDStringIDOAVS
resultTextStringAVS Result TextOOAVS
codeAVSStringAVS Response CodeOAVS
codeSecurityCodeStringSecurity Code Response CodeOAVS
ECString
1 or 8 characters
Internal Error CodeOAVS
feesobjectFees CheckCCFees Check
pullobjectDebit TransactionOOFees Check
interchangeString
Amount
Interchange FeesFees Check
networkString
Amount
Network FeesFees Check
tabapayString
Amount
TabaPay FeesFees Check
pushobjectCredit TransactionOOFees Check
interchangeString
Amount
Interchange FeesFees Check
networkString
Amount
Network FeesFees Check
tabapayString
Amount
TabaPay FeesFees Check
View
Hide
  Samples
Query Card:
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840"
    },
    "push":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840",
      "availability": "Immediate"
    }
  }
}

Query Card (pull disabled):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": false
    },
    "push":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840",
      "availability": "Immediate"
    }
  }
}

Query Card (push disabled):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840"
    },
    "push":
    {
      "enabled": false
    }
  }
}

Query Card (disabled/unsupported):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": false
    },
    "push":
    {
      "enabled": false
    }
  }
}
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.


There is an extra charge (fee) for using Query Card and there is also an additional charge (fee) for using AVS.


Creating an Account just to do a Query Card is not the valid way to use our API (it is an Anti-Pattern). As we try to show in the Sample Flows: Query Card should be done first before Creating an Account, this is the correct Pattern (or use of our API).

Creating unused and/or inactive Accounts will result in:

  • These Accounts incurring an extra charge (fee)
  • These Accounts being automatically deleted
Excessive Anti-Pattern behavior will result in:
  • Your Requests failing
  • Your Client being locked


If using Account, only:
  • Card Account Number
  • Expiration Date (for AVS)
are obtained from the Account for use.

For AVS:

  • Security Code
  • Owner Address
are obtained from the request.

For Verify:
  • Owner Name
  • Owner Phone
are obtained from the request.


For AVS, Address Line 1 is optional, but you will get an AVS Code that says only Zip Code was matched (or not) and Address was not matched.


The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.


card.modeDescription
0RSA with PKCS#1 v1.5 Padding, however this is considered to be insecure
1Java RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding
2(non-Java) RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Unfortunately, for RSA/ECB/OAEPWithSHA-256AndMGF1Padding, Java's implementation (as of Java 1.8) is currently incompatible with other implementations.

Bank

This resource represents a Bank.

The only operation available for this resource is:

●   Query
Returns the attributes for the requested Bank

Query Bank

Returns the attributes for the requested Bank.
URL
https://<FQDN>/v1/clients/<ClientIDISO>/banks
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
routingNumberString
9 digits
RRouting Number
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Query Bank:

{
  "routingNumber": "999999999"
}
Response
Status Codes
Status CodeDescription
200OKThe Bank's Attributes are returned.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
RTPBooleanRTP
View
Hide
  Samples
Query Bank:
{
  "SC": 200,
  "EC": "0",
  "RTP": true
}
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.

OFAC

This resource represents a Name on the OFAC Sanctions List.

The only operation available for this resource is:

●   Query
Returns the OFAC Match Codes

Query OFAC

Returns the OFAC Match Codes.
URL
https://<FQDN>/v1/clients/<ClientIDISO>/ofac
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
nameobjectRName
firstStringRFirst Name
lastStringRLast Name
addressobjectOAddress
requestIDString
up to 32 Characters
OWatchDog Request Identifier
This is Required if the Bank requires the use of WatchDog
birthYearString
YYYY Format
OBirth Year
This is Optional if the Bank requires the use of WatchDog
countryString
3-digit code
OISO 3166-1 Country Code
This is Optional if the Bank requires the use of WatchDog
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Query OFAC:

{
  "name":
  {
    "first": "John",
    "last": "Smith"
  }
}
Query OFAC (using WatchDog):
{
  "name":
  {
    "first": "John",
    "last": "Smith"
  },
  "requestID": "ABC123"
}
Response
Status Codes
Status CodeDescription
200OKThe OFAC Match Codes are returned.
207Multi-StatusUnable to contact WatchDog.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
ofacMatchCodesStringOFAC Match Codes
ofacValueStringOFAC Value to be used in Create Transaction
errorsArray of
8 characters
Strings
Array of Internal Error Codes
View
Hide
  Samples
Query OFAC:
{
  "SC": 200,
  "EC": "0",
  "ofacMatchCodes": "LN",
  "ofacValue": "7nGfHHedKNe1aw"
}
Query OFAC (using WatchDog):
{
  "SC": 200,
  "EC": "0",
  "ofacMatchCodes": "H",
  "ofacValue": "8oHgIIfeLOf2bx"
}
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.


OFAC Match CodesDescription
LNLast Name did Not Match
LMLast Name Matched, but First Name did Not Match
LMFMLast Name Matched and First Name Matched
LMFPLast Name Matched, but First Name was just a Partial Match
LMFOLast Name Matched, but First Name was just a Partial (out of order) Match
LPLast Name was just a Partial Match and First Name did Not Match
LPFMLast Name was just Partial Match, but First Name Matched
LPFPLast Name and First Name were both just a Partial Match
LPFOLast Name partial Match and First Name Out Of Order
LOFMLast Name was just a Partial (out of order) Match, but First Name Matched
LOFPLast Name was just a Partial (out of order) Match and First Name was just a Partial Match
LOFOLast Name and First Name were both just a Partial (out of order) Match
 
NNo Hit
HHit
HNHit by Name


Please speak to your Bank to determine if this is required in Create Transaction.

Account

This resource represents a Client's Account.

The operations that are available for this resource are:

●   Create
Creates an Account containing a Payment Card Account Number
●   Retrieve
Retrieves an Account, but the full Payment Card Account Number is never returned
●   Update
Updates an Account
●   Update v2
Update specific fields of an Account
●   Delete
Deletes an Account

Create Account

Creates an Account.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/accounts
https://<FQDN>/v1/clients/<ClientIDISO>/accounts?RejectDuplicateCard
https://<FQDN>/v1/clients/<ClientIDISO>/accounts?OKToAddDuplicateCard
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescriptionConditional
referenceIDString
1-15 characters
RYour unique Reference ID
bankobjectCREither Bank or CardACH
routingNumberString
9 digits
R aRouting NumberACH
accountNumberString
4-17 digits
R aAccount NumberACH
accountTypeString
1-character code
R aAccount TypeACH
cardobjectCREither Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
or Payment Card Encrypted:
  • keyID
  • mode
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
Payment Card
accountNumberString
13-19 digits
R nPayment Card Account NumberPayment Card
Not Encrypted
expirationDateString
YYYYMM Format
R n
O n
Expiration DatePayment Card
Not Encrypted
keyIDString
22 characters
R eKeyIDPayment Card
Encrypted
modeInteger
0, 1, or 2
D e2Encryption Mode (Transformation)
0 = PKCS#1 v1.5
1 = Java OAEP
2 = OAEP SHA-256
Payment Card
Encrypted
dataStringR eEncrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
Payment Card
Encrypted
tokenString® tCard Token (from SSO)
Restricted Usage
Payment Card
Token
deviceobject® dCard Data from P2PE Device
Restricted Usage
Payment Card
Device
idString® dDevice IdentifierPayment Card
Device
blobHex String® dBlob in HexPayment Card
Device
ownerobjectRAccount Owner
nameobjectRName
Either Company or First, Middle, Last, and Suffix
companyStringR cCompany Name
firstStringR nFirst Name
middleStringO nMiddle Name or Initial
lastStringR nLast Name
suffixStringO nSuffix
addressobjectOAddress
line1StringRAddress Line 1
line2StringOAddress Line 2
cityStringRCity
stateString
2-character code
RState Code840
zipcodeStringRZip Code840
countryString
3-digit code
O840ISO 3166-1 Country Code840
phoneobjectOPhone Number (E.164 Numbering)840
countryCodeString
1-3 digits
O1Country Calling Code840
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number840
(Encrypted) Card Data
FieldRequiredDescriptionUnEncrypted Card Data Format
Card NumberR13-19 digit Card NumberCardNumber | Expiration Date |

(no spaces, pipe symbol separated)
see samples
Expiration DateRExpiration date in YYYYMM Format
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Create Payment Card Account:

{
  "referenceID": "1",
  "card":
  {
    "accountNumber": "9999999999999999",
    "expirationDate": "202012"
  },
  "owner":
  {
    "name":
    {
      "first": "John",
      "last": "Customer"
    },
    "address":
    {
      "line1": "465 Fairchild Drive",
      "line2": "Suite #222",
      "city": "Mountain View",
      "state": "CA",
      "zipcode": "94043"
    },
    "phone":
    {
      "number": "4159808222"
    }
  }
}

Unencrypted Card Data:
1111111111111111|203001|

where

Card Number:     1111111111111111
Expiration Date: January 2030
Response
Status Codes
Status CodeDescription
200OKAn Account is Created.
207Multi-StatusAccount created, but Duplicate Card Check Failed.
409ConflictDuplicate Card Check Matched.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207409Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
accountIDString
22 characters
AccountID
cardobjectCardOO
last4String
4 digits
Last 4 of Card Account Number (PAN)
expirationDateString
6 digits
Expiration Date
YYYYMM Format
OO
noticesStringImportant NoticesOOO
duplicateAccountIDsArray of
Strings
AccountIDs using the same Card Account NumberO
View
Hide
  Samples
Account created:
{
  "SC": 200,
  "EC": "0",
  "accountID": "TabaPay_AccountID_22ch"
}
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.


Creating an Account just to do a Query Card is not the valid way to use our API (it is an Anti-Pattern). As we try to show in the Sample Flows: Query Card should be done first before Creating an Account, this is the correct Pattern (or use of our API).

Creating unused and/or inactive Accounts will result in:

  • These Account incurring an extra charge (fee)
  • These Account being automatically deleted
Excessive Anti-Pattern behavior will result in:
  • Your Requests failing
  • Your Client being locked


card.modeDescription
0RSA with PKCS#1 v1.5 Padding, however this is considered to be insecure
1Java RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding
2(non-Java) RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Unfortunately, for RSA/ECB/OAEPWithSHA-256AndMGF1Padding, Java's implementation (as of Java 1.8) is currently incompatible with other implementations.

Retrieve Account

Retrieves the Account.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Account is retrieved.
421Misdirected RequestToo late to Retrieve Account by ReferenceID, use AccountID.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
referenceIDStringReferenceID
bankobjectBankO
routingNumberString
9 digits
Routing NumberO
last4String
4 digits
Last 4 of Account NumberO
accountTypeString
1-character code
Account TypeO
cardobjectCardO
last4String
4 digits
Last 4 of Card NumberO
expirationDateString
6 digits
Expiration DateO
ownerobjectAccount Owner
nameobjectName
firstStringFirst Name
middleStringMiddle Name or InitialO
lastStringLast Name
suffixStringSuffixO
addressobjectAddressO
line1StringAddress Line 1
line2StringAddress Line 2O
cityStringCity
stateString
2-character code
State Code
zipcodeStringZip Code
countryString
3-digit code
ISO 3166-1 Country CodeO
phoneobjectPhone Number (E.164 Numbering)O
countryCodeString
1-3 digits
Country Calling CodeO
numberString
Min: 4 digits
Max: 12-14 digits
Phone Number
View
Hide
  Samples
Account retrieved:
{
  "SC": 200,
  "EC": "0",
  "referenceID": "1",
  "card":
  {
    "last4": "9990",
    "expirationDate": "202012"
  },
  "owner":
  {
    "name":
    {
      "first": "John",
      "last": "Customer"
    },
    "address":
    {
      "line1": "465 Fairchild Drive",
      "line2": "Suite #222",
      "city": "Mountain View",
      "state": "CA",
      "zipcode": "94043"
    },
    "phone":
    {
      "number": "4159808222"
    }
  }
}
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.


See Anti-Pattern FAQ for proper usage of Retrieve by ReferenceID.


If there was a HTTP communication error and you did not get back an AccountID, you can try to Retrieve the AccountID using the ReferenceID.

Retrieve Account by ReferenceID

Retrieves the Account by ReferenceID. This should only be used in the case of a HTTP communication error and you did not get back the AccountID in the response. Using this for any other purposes is Anti-Pattern and is subject to failing and/or locking of your Client for all requests. You should use Retrieve Account with the AccountID to retrieve Account Information.

This request is only valid if the Account was created within 24 hours ago, otherwise SC=421 will be returned, use Retrieve by AccountID.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/accounts?referenceID=<ReferenceID>   See Notes below and Anti-Pattern FAQ
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Account is retrieved.
421Misdirected RequestToo late to Retrieve Account by ReferenceID, use AccountID.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
accountIDString
22 characters
AccountID
bankobjectBankO
routingNumberString
9 digits
Routing NumberO
last4String
4 digits
Last 4 of Account NumberO
accountTypeString
1-character code
Account TypeO
cardobjectCardO
last4String
4 digits
Last 4 of Card NumberO
expirationDateString
6 digits
Expiration DateO
ownerobjectAccount Owner
nameobjectName
firstStringFirst Name
middleStringMiddle Name or InitialO
lastStringLast Name
suffixStringSuffixO
addressobjectAddressO
line1StringAddress Line 1
line2StringAddress Line 2O
cityStringCity
stateString
2-character code
State Code
zipcodeStringZip Code
countryString
3-digit code
ISO 3166-1 Country CodeO
phoneobjectPhone Number (E.164 Numbering)O
countryCodeString
1-3 digits
Country Calling CodeO
numberString
Min: 4 digits
Max: 12-14 digits
Phone Number
View
Hide
  Samples
Account retrieved:
{
  "SC": 200,
  "EC": "0",
  "accountID": "TabaPay_AccountID_22ch",
  "owner":
  {
    "name":
    {
      "first": "John",
      "last": "Customer"
    },
    "address":
    {
      "line1": "465 Fairchild Drive",
      "line2": "Suite #222",
      "city": "Mountain View",
      "state": "CA",
      "zipcode": "94043"
    },
    "phone":
    {
      "number": "4159808222"
    }
  }
}
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.


See Anti-Pattern FAQ for proper usage of Retrieve by ReferenceID.


You should use Retrieve Account with the AccountID to retrieve Account Information.

Update Account

Updates the Account.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>?RejectDuplicateCard
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>?OKToUpdateDuplicateCard
HTTP Method
PUT
Request
Request Data
JSON NameValueRequiredDefaultDescriptionConditional
bankobjectCREither Bank or CardACH
routingNumberString
9 digits
R aRouting NumberACH
accountNumberString
4-17 digits
R aAccount NumberACH
accountTypeString
1-character code
R aAccount TypeACH
cardobjectCREither Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
or Payment Card Encrypted:
  • keyID
  • mode
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
Payment Card
accountNumberString
13-19 digits
R nPayment Card Account NumberPayment Card
Not Encrypted
expirationDateString
YYYYMM Format
R n
O n
ExpirationDatePayment Card
Not Encrypted
keyIDString
22 characters
R eKeyIDPayment Card
Encrypted
modeInteger
0, 1, or 2
D e2Encryption Mode (Transformation)
0 = PKCS#1 v1.5
1 = Java OAEP
2 = OAEP SHA-256
Payment Card
Encrypted
dataStringR eEncrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
Payment Card
Encrypted
tokenString® tCard Token (from SSO)
Restricted Usage
Payment Card
Token
deviceobject® dCard Data from P2PE Device
Restricted Usage
Payment Card
Device
idString® dDevice IdentifierPayment Card
Device
blobHex String® dBlob in HexPayment Card
Device
ownerobjectRAccount Owner
nameobjectRName
Either Company or First, Middle, Last, and Suffix
companyStringR cCompany Name
firstStringR nFirst Name
middleStringO nMiddle Name or Initial
lastStringR nLast Name
suffixStringO nSuffix
addressobjectOAddress
line1StringRAddress Line 1
line2StringOAddress Line 2
cityStringRCity
stateString
2-character code
RState Code840
zipcodeStringRZip Code840
countryString
3-digit code
O840ISO 3166-1 Country Code840
phoneobjectOPhone Number (E.164 Numbering)840
countryCodeString
1-3 digits
O1Country Calling Code840
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number840
(Encrypted) Card Data
FieldRequiredDescriptionUnEncrypted Card Data Format
Card NumberR13-19 digit Card NumberCardNumber | Expiration Date |

(no spaces, pipe symbol separated)
see samples
Expiration DateRExpiration date in YYYYMM Format
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Update Payment Card Account:

{
  "card":
  {
    "accountNumber": "9999999999999999",
    "expirationDate": "202012"
  },
  "owner":
  {
    "name":
    {
      "first": "John",
      "last": "Customer"
    },
    "address":
    {
      "line1": "465 Fairchild Drive",
      "line2": "Suite #222",
      "city": "Mountain View",
      "state": "CA",
      "zipcode": "94043"
    },
    "phone":
    {
      "number": "4159808222"
    }
  }
}

Unencrypted Card Data:
1111111111111111|203001|

where

Card Number:     1111111111111111
Expiration Date: January 2030
Response
Status Codes
Status CodeDescription
200OKThe Account is Updated.
207Multi-StatusAccount updated, but Update Duplicate Card Check Failed.
409ConflictDuplicate Card Check Matched.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207409Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
duplicateAccountIDsArray of
Strings
AccountIDs using the same Card Account NumberO
View
Hide
  Samples
Account updated:
{
  "SC": 200,
  "EC": "0"
}
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.


Update will delete the previous Account Data and replace the Account Data with the new Data in the Request. An Update Account is basically a Create Account but reusing the AccountID and the ReferenceID. The previous Account Data is deleted and is no longer usable or recoverable.


card.modeDescription
0RSA with PKCS#1 v1.5 Padding, however this is considered to be insecure
1Java RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding
2(non-Java) RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Unfortunately, for RSA/ECB/OAEPWithSHA-256AndMGF1Padding, Java's implementation (as of Java 1.8) is currently incompatible with other implementations.

Update Account v2

Coming Soon

Update specific fields in the Account. Currently does not work with DuplicateCardCheck. Currently only works with Unencrypted Cards (Card in the Clear) and/or Bank Accounts.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v2/clients/<ClientIDISO>/accounts/<AccountID>
HTTP Method
PUT
Request
Request Data
JSON NameValueRequiredDefaultDescriptionConditional
bankobjectCOEither Bank or CardACH
routingNumberString
9 digits
O aRouting NumberACH
accountNumberString
4-17 digits
O aAccount NumberACH
accountTypeString
1-character code
O aAccount TypeACH
cardobjectCOEither Bank or CardPayment Card
accountNumberString
13-19 digits
O nPayment Card Account NumberPayment Card
Not Encrypted
expirationDateString
YYYYMM Format
O nExpirationDatePayment Card
Not Encrypted
ownerobjectOAccount Owner
nameobjectOName
Either Company or First, Middle, Last, and Suffix
companyStringO cCompany Name
firstStringO nFirst Name
middleStringO nMiddle Name or Initial
lastStringO nLast Name
suffixStringO nSuffix
addressobjectOAddress
line1StringOAddress Line 1
line2StringOAddress Line 2
cityStringOCity
stateString
2-character code
OState Code840
zipcodeStringOZip Code840
countryString
3-digit code
O840ISO 3166-1 Country Code840
phoneobjectOPhone Number (E.164 Numbering)840
countryCodeString
1-3 digits
O1Country Calling Code840
numberString
Min: 4 digits
Max: 12-14 digits
OPhone Number840
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Update First Name on Account:

  {
    "owner":
    {
      "name":
      {
        "first": "Jane"
      }
    }
  }
   
Update Address on Account:
  {
    "owner":
    {
      "address":
      {
        "line1": "605 Ellis St",
        "line2": "Suite #110",
      }
    }
  }
   
Response
Status Codes
Status CodeDescription
200OKThe Account is Updated.
207Multi-StatusAccount updated, but Update Duplicate Card Check Failed.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Account updated:
  {
    "SC": 200,
    "EC": "0"
  }
   
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.


WARNING

Updating specific fields must make logical sense, here are some examples of illogical updates that will fail with SC=400 Bad Request:

Current Account StateUpdate WantedReason for Failure
Account is a Cardbank.accountNumberIn order to Change an Account from Card to Bank, you will need to provide all the Bank Fields:
  • bank.routingNumber
  • bank.accountNumber
  • bank.accountType
Account Owner's Address is Country 840Postal Code of "A1A 1A1"The Postal Code is not a US Zip Code
Account Owner's Address is Country 124State Code of "CA"The State Code is not a Canadian Province
Account Name is a CompanyLast Name of "Smith"In order to change the Name, you will need to provide at least:
  • owner.name.first
  • owner.name.last

Delete Account

The Account is marked for Deletion.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>
https://<FQDN>/v1/clients/<ClientIDISO>/accounts/<AccountID>?DeleteDuplicateCard
HTTP Method
DELETE
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Account is marked for deletion.
207Multi-StatusAccount marked for deletion, but Delete Duplicate Card Check Failed.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Account marked for deletion:
{
  "SC": 200,
  "EC": "0"
}
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.

Transaction

This resource represents a Client's Transaction.

The operations that are available for this resource are:

●   Create
Creates a Transaction
●   Retrieve
Retrieves a Transaction
●   Delete
Deletes a Transaction

Create Transaction

Creates a Transaction.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/transactions
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescriptionChoice
referenceIDString
1-15 characters
RYour unique Reference ID
correspondingIDString
22 characters
OEither 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
View Object
OEither Corresponding or Corresponding TransactionID
(For a Push Transaction, this would be the corresponding Pull Transaction)
C
ofacValueStringOSender OFAC Value from Query OFAC...C
name
object
Hide Object
RSender NameC
firstStringRFirst NameC
lastStringRLast NameC
address
object
Hide Object
OSender AddressC
lineStringOAddress LineC
cityStringOCityC
stateString
2-character code
OState CodeC
zipcodeStringOZip CodeC
countryString
3-digit code
O840ISO 3166-1 Country CodeC
accountNumberStringOSender Account NumberC
sourceOfFundsStringOSender Source of Funds:
  • Debit Card
  • Prepaid Card
  • Credit Card
  • Cash
  • Deposit Account
  • Credit Account
  • Mobile Money Account
C
typeString
4 characters
Either push or pull
RTransaction Type
This is used to verify that your Source and Destination Accounts are valid.
networksStringOList of Network Codes
For ISOs, please contact TabaPay Support for details on when and how to use.
cardTypesStringOList of Card Type Codes
For ISOs, please contact TabaPay Support for details on when and how to use.
accounts
object
Hide Object
RAccounts
sourceAccountIDString
22 characters
CREither Source AccountID or Source AccountSAID
sourceAccount
object
View Object
CREither Source Account or Source AccountIDSA
bank
object
View Object
CREither Bank or CardSA ACH
routingNumberString
9 digits
R aRouting NumberSA ACH
accountNumberString
4-17 digits
R aAccount NumberSA ACH
accountTypeString
1-character code
R aAccount Type:
  • S: Savings
  • C: Checking
  • L: Loan
  • A: Business Savings
  • B: Business Checking
SA ACH
card
object
View Object
CREither Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • mode
  • 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
accountNumberString
13-19 digits
R nPayment Card Account NumberSA PC
Not Encrypted
expirationDateString
YYYYMM Format
R nExpiration DateSA PC
Not Encrypted
securityCodeString
3-4 digits
O nSecurity CodeSA PC
Not Encrypted
keyIDString
22 characters
R eKeyIDSA PC
Encrypted
modeInteger
0, 1, or 2
D e2Encryption Mode (Transformation)
0 = PKCS#1 v1.5
1 = Java OAEP
2 = OAEP SHA-256
SA PC
Encrypted
dataStringR eEncrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
SA PC
Encrypted
tokenString® tCard Token (from SSO)
Restricted Usage
SA PC
Token
device
object
View Object
® dCard Data from P2PE Device
Restricted Usage
SA PC
Device
idStringR dDevice IdentifierSA PC
Device
blobHex StringR dBlob in HexSA PC
Device
mobilePay
object
View Object
® mCard Data from Mobile Payment
Restricted Usage
SA PC
Mobile Pay
accountNumberString
13-19 digits
R mPseudo Payment Card Account NumberSA PC
Mobile Pay
expirationDateString
YYYYMM Format
R mExpiration DateSA PC
Mobile Pay
cryptogramBase64 String
28 characters
R mPayment Data CryptogramSA PC
Mobile Pay
transactionIDHex String
64 characters
R mTransaction Identifier in HexSA PC
Mobile Pay
eciIndicatorString
1 character
O mUsually only Visa cardsSA PC
Mobile Pay
networkStringR mCard Network
(Visa, MasterCard, Amex, Discover, etc...)
SA PC
Mobile Pay
typeStringR mCard Type
(Debit, Credit, PrePaid, etc...)
SA PC
Mobile Pay
processor
object
View Object
® pProcessor
Restricted Usage
SA PC
Processor
nameStringR pNameSA PC
Processor
tokenStringR pTokenSA PC
Processor
owner
object
View Object
RAccount OwnerSA
name
object
View Object
RName
Either Company or First, Middle, Last, and Suffix
SA
companyStringR cCompany NameSA
firstStringR nFirst NameSA
middleStringO nMiddle Name or InitialSA
lastStringR nLast NameSA
suffixStringO nSuffixSA
address
object
View Object
OAddressSA
line1StringOAddress Line 1SA
line2StringOAddress Line 2SA
cityStringOCitySA
stateString
2-character code
OState CodeSA
zipcodeStringOZip CodeSA
countryString
3-digit code
O840ISO 3166-1 Country CodeSA
phone
object
View Object
OPhone Number (E.164 Numbering)SA
countryCodeString
1-3 digits
O1Country Calling CodeSA
numberString
Min: 4 digits
Max: 12-14 digits
RPhone NumberSA
destinationAccountIDString
22 characters
CREither Destination AccountID or Destination AccountDAID
destinationAccount
object
View Object
CREither Destination Account or Destination AccountIDDA
bank
object
View Object
CREither Bank or CardDA ACH
routingNumberString
9 digits
R aRouting NumberDA ACH
accountNumberString
4-17 digits
R aAccount NumberDA ACH
accountTypeString
1-character code
R aAccount Type:
  • S: Savings
  • C: Checking
  • L: Loan
  • A: Business Savings
  • B: Business Checking
DA ACH
card
object
View Object
CREither Bank or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • mode
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
DA PC
accountNumberString
13-19 digits
R nPayment Card Account NumberDA PC
Not Encrypted
expirationDateString
YYYYMM Format
R nExpiration DateDA PC
Not Encrypted
securityCodeString
3-4 digits
O nCVV2DA PC
Not Encrypted
keyIDString
22 characters
R eKeyIDDA PC
Encrypted
modeInteger
0, 1, or 2
D e2Encryption Mode (Transformation)
0 = PKCS#1 v1.5
1 = Java OAEP
2 = OAEP SHA-256
DA PC
Encrypted
dataStringR eEncrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
DA PC
Encrypted
tokenString® tCard Token (from SSO)
Restricted Usage
DA PC
Token
device
object
View Object
® dCard Data from P2PE Device
Restricted Usage
DA PC
Device
idString® dDevice IdentifierDA PC
Device
blobHex String® dBlob in HexDA PC
Device
processor
object
View Object
® pProcessor
Restricted Usage
SA PC
Processor
nameStringR pNameSA PC
Processor
tokenStringR pTokenSA PC
Processor
owner
object
View Object
RAccount OwnerDA
name
object
View Object
RName
Either Company or First, Middle, Last, and Suffix
DA
companyStringR cCompany NameDA
firstStringR nFirst NameDA
middleStringO nMiddle Name or InitialDA
lastStringR nLast NameDA
suffixStringO nSuffixDA
address
object
View Object
OAddressDA
line1StringOAddress Line 1DA
line2StringOAddress Line 2DA
cityStringOCityDA
stateString
2-character code
OState CodeDA
zipcodeStringOZip CodeDA
countryString
3-digit code
O840ISO 3166-1 Country CodeDA
phone
object
View Object
OPhone Number (E.164 Numbering)DA
countryCodeString
1-3 digits
O1Country Calling CodeDA
numberString
Min: 4 digits
Max: 12-14 digits
RPhone NumberDA
currencyString
3 digits
O840ISO 4217 Currency Number
amountString
Amount
RTransaction Amount
ofacValueStringOOFAC Value from Query OFAC...
memoString
Max of 32 characters
OMemo
achOptionsString
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
overridesStringO
RISO
Overrides
For ISOs, please contact TabaPay Support for details on when and how to use.

Required for ISOs
pullOptions
object
View Object
OAdditional Pull Options
lenderBooleanOLender - deprecating, use overrides
quasiCashBooleanOQuasi-Cash - deprecating, use overrides
securityCodeString
3-4 digits
OCVV2
Valid only when using sourceAccountID (Pull)
recurringBooleanORecurring Pull Transaction
3DSecureObjectO3D Secure
versionStringO
RMasterCard
Version
Required by MasterCard
ECIStringRECI (Electronic Commerce Indicator)old: 3dsECI
UCAFStringRUCAF (Universal Cardholder Authentication Field)old: 3dsUCAF
XIDStringOXID (Transaction ID)old: 3dsXID
dsTransactionIDStringO
RMasterCard
Directory Server TransactionID
Required by MasterCard
level2TaxExemptbooleanOLevel 2: Tax ExemptLevel 2
level2TaxAmountString
Amount
OLevel 2: Tax Amount
(Currency is the same as the Transaction Amount)
Level 2
level3ObjectOLevel 3Level 3
amountTaxString
Amount
RTax Amount
(Currency is the same as the Transaction Amount)
Level 3
taxCode
1 digit
R0 = Sales Tax Not Included
1 = Sales Tax Included
2 = Tax Exempt
Level 3
taxRateNumber
Max 2 decimal places
RTax RateLevel 3
amountDiscountString
Amount
RDiscount AmountLevel 3
amountShippingString
Amount
RShipping AmountLevel 3
amountDutyString
Amount
RDuty AmountLevel 3
itemCommodityCodeStringRItem Commodity CodeLevel 3
itemDescriptionStringRItem DescriptionLevel 3
productCodeStringRProduct CodeLevel 3
quantityNumberRQuantityLevel 3
unitOfMeasureStringRUnit of MeasureLevel 3
amountUnitCostString
Amount
RUnit CostLevel 3
amountItemDiscountString
Amount
RDiscount per Line ItemLevel 3
amountTotalString
Amount
RTotalLevel 3
poNumberStringRPurchase Order NumberLevel 3
softDescriptor
object
View Object
®Soft Descriptor
Restricted Usage
®
nameStringRName®
address
object
Hide Object
RAddress®
line1StringRAddress Line 1®
line2StringOAddress Line 2®
cityStringRCity®
countyString
3 characters
RCounty®
stateString
2-character code
RState Code®
zipcodeStringRZip Code®
countryString
3-digit code
O840ISO 3166-1 Country Code®
phone
object
Hide Object
OPhone Number (E.164 Numbering)®
countryCodeString
1-3 digits
O1Country Calling Code®
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number®
email
StringO

RAmex
Email Address
For American Express Bill Pay Provider program:
  Seller Email Address (max of 40 characters)
®
id
StringO

RAmex
ID
For American Express Bill Pay Provider program:
  Seller ID (max of 20 digits)
®
location
object
View Object
OLocation of the Origination of Transaction
nameStringRLocation Name
address
object
Hide Object
RLocation Address
line1StringRAddress Line 1
line2StringOAddress Line 2
cityStringRCity
stateString
2-character code
RState Code
zipcodeStringRZip Code
countryString
3-digit code
O840ISO 3166-1 Country Code
timeoutInteger
Between 15 and 39
O39Time to wait for a response
Default is 39 seconds
See Notes Below...
(Encrypted) Card Data
FieldRequiredDescriptionUnEncrypted Card Data Format
Card NumberR13-19 digit Card NumberCardNumber | Expiration Date | Security Code

(no spaces, pipe symbol separated)
see samples
Expiration DateRExpiration date in YYYYMM Format
Security CodeO3 or 4 digit CVV2
View
Hide
  Samples
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 CodeDescription
200OKA Transaction is created and processing is completed.
201CreatedA Transaction is created, but the transaction is waiting to be processed (batch).
207Multi-StatusOne or more Failures occurred while processing the Request.
429Too Many RequestsOver your Daily (24-hour rolling) Approximation Limit.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200201207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
transactionIDString
22 characters
TransactionID
networkStringNetwork
networkRCString
2 or 3-character code
Network Response CodeO
networkIDStringNetworkID
(Network TransactionID)
O
statusStringStatus
approvalCodeString
6 characters
Approval CodeO
errorsArray of
8 characters
Strings
Array of Internal Error Codes
AVSobjectAVS ResultsC
codeAVSStringAVS Response CodeO
codeSecurityCodeStringSecurity Code Response CodeO
feesobjectEstimated FeesOO
interchangeString
Amount
Interchange Fees
networkString
Amount
Network Fees
tabapayString
Amount
TabaPay Fees
cardobjectCardOO
last4String
4 digits
Last 4 of Card Account Number (PAN)
expirationDateString
6 digits
Expiration Date
YYYYMM Format
OO
View
Hide
  Samples
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.


card.modeDescription
0RSA with PKCS#1 v1.5 Padding, however this is considered to be insecure
1Java RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding
2(non-Java) RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding

Unfortunately, for RSA/ECB/OAEPWithSHA-256AndMGF1Padding, Java's implementation (as of Java 1.8) is currently incompatible with other implementations.

Retrieve Transaction

Retrieves the Transaction.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/transactions/<TransactionID>
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Transaction is retrieved.
421Misdirected RequestToo late to Retrieve Transaction by ReferenceID, use TransactionID.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
referenceIDStringReferenceID
networkStringNetworkO
networkRCString
2 or 3-character code
Network Response CodeO
statusStringStatus
originallyStringOriginal StatusO
approvalCodeString
6 characters
Approval CodeO
errorsArray of
8 characters
Strings
Array of Internal Error CodesO
currencyString
3-digit code
ISO 4217 Currency NumberO
amountStringAmount in Currency
amountUSDStringAmount in USD if Currency is not 840 (USD)O
last4StringLast 4 of Card Account Number (PAN)
or
Last 4 of Bank Account Number
memoStringMemoO
feesobjectFeesO
interchangeString
Amount
Interchange Fees
networkString
Amount
Network Fees
tabapayString
Amount
TabaPay Fees
reversalStatusStringReversal StatusO
reversalobjectReversalO
networkRCString
2 or 3-character code
Network Response CodeO
networkRC2String
2 or 3-character code
Network Response CodeO
errorString
1 or 8 characters
Internal Error CodeO
View
Hide
  Samples
Transaction retrieved using TransactionID:
{
  "SC": 200,
  "EC": "0",
  "referenceID": "1",
  "network": "Visa",
  "networkRC": "00",
  "status": "COMPLETED",
  "approvalCode": "000000",
  "amount": "0.10",
  "fees":
  {
    "interchange": "0.50",
    "network": "0.50",
    "tabapay": "0.25"
  }
}
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.


The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.


See Anti-Pattern FAQ for proper usage of Retrieve by ReferenceID.


If there was a HTTP communication error and you did not get back a TransactionID, you can try to Retrieve the TransactionID using the ReferenceID.

Retrieve Transaction by ReferenceID

Retrieves the Transaction by ReferenceID. This should only be used in the case of a HTTP communication error and you did not get back the TransactionID in the response. Using this for any other purposes is Anti-Pattern and is subject to failing and/or locking of your Client for all requests. You should use Retrieve Transaction with the TransactionID to retrieve Transaction Information.

This request is only valid if the Transaction was created within 24 hours ago, otherwise SC=421 will be returned, use Retrieve by TransactionID.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/transactions?referenceID=<ReferenceID>   See Notes below and Anti-Pattern FAQ
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Transaction is retrieved.
421Misdirected RequestToo late to Retrieve Transaction by ReferenceID, use TransactionID.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
transactionIDString
22 characters
TransactionID
networkStringNetworkO
networkRCString
2 or 3-character code
Network Response CodeO
statusStringStatus
originallyStringOriginal StatusO
approvalCodeString
6 characters
Approval CodeO
errorsArray of
8 characters
Strings
Array of Internal Error CodesO
currencyString
3-digit code
ISO 4217 Currency NumberO
amountStringAmount in Currency
amountUSDStringAmount in USD if Currency is not 840 (USD)O
last4StringLast 4 of Card Account Number (PAN)
or
Last 4 of Bank Account Number
memoStringMemoO
feesobjectFeesO
interchangeString
Amount
Interchange Fees
networkString
Amount
Network Fees
tabapayString
Amount
TabaPay Fees
reversalStatusStringReversal StatusO
reversalobjectReversalO
networkRCString
2 or 3-character code
Network Response CodeO
networkRC2String
2 or 3-character code
Network Response CodeO
errorString
1 or 8 characters
Internal Error CodeO
View
Hide
  Samples
Transaction retrieved:
{
  "SC": 200,
  "EC": "0",
  "transactionID": "TransactionID_22chars_",
  "network": "Visa",
  "networkRC": "00",
  "status": "COMPLETED",
  "approvalCode": "000000",
  "amount": "0.10",
  "fees":
  {
    "interchange": "0.50",
    "network": "0.50",
    "tabapay": "0.25"
  }
}
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.


The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.


See Anti-Pattern FAQ for proper usage of Retrieve by ReferenceID.


You should use Retrieve Transaction with the TransactionID to retrieve Transaction Information.

Delete Transaction

Try to request a reverse of a previous Pull Transaction.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v1/clients/<ClientIDISO>/transactions/<TransactionID>?reversal
https://<FQDN>/v1/clients/<ClientIDISO>/transactions/<TransactionID>?void
HTTP Method
DELETE
Request
No Request Data or Overrides Required for ISOs or Optional Partial Reversal
JSON NameValueRequiredDefaultDescriptionChoice
overridesStringO
RISO
Overrides
For ISOs, please contact TabaPay Support for details on when and how to use.

Required for ISOs
currencyString
3 digits
O840ISO 4217 Currency Number
amountString
Amount
OPartial Reversal Amount
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Partial Reversal:

{
  "amount": "1.00"
}
Response
Status Codes
Status CodeDescription
200OKA Request for a Reversal of the previous Transaction is successful.
207Multi-StatusOne or more Failures occurred while processing the Request.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
statusStringStatus
reversalobjectReversalO
networkRCString
2 or 3-character code
Void
Network Response Code
O
networkRC2String
2 or 3-character code
Refund after failed Void
Network Response Code
O
View
Hide
  Samples
Transaction reversed:
{
  "SC": 200,
  "EC": "0",
  "status": "COMPLETED",
  "reversal":
  {
    "networkRC": "00"
  }
}
Dual Message Network:
{
  "SC": 200,
  "EC": "0",
  "status": "COMPLETED",
  "reversal":
  {
    "networkRC": "21",
    "networkRC2": "00"
  }
}
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.


You can only Delete (reverse) a Pull Transaction. A Delete is just only a request for a reversal. Dual Message Networks may cause a networkRC2 if:
  • the networkRC was non-zero.

A status of COMPLETED and either networkRC equals to 00 or networkRC2 equals to 00 means a successful request for a reversal.


We will only keep transactions accessible to the TabaPay API for approximately 120 days. This means that Delete Transaction will only work for transactions within approximately 120 days. However, we archive transactions for many years (as legally required).

TransactionRequest (OTPP)

This resource represents a TransactionRequest (OTPP).

The operations that are available for this resource are:

●   Create
Creates a TransactionRequest (OTPP)

Create TransactionRequest (OTPP)

Creates a TransactionRequest (OTPP).

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v2/clients/<ClientIDISO>/transactionrequests
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescriptionChoice
typeString
4 characters
Either pull or push
RTransaction Type
user1String
1-15 characters
OUser1
user2String
1-15 characters
OUser2
currencyString
3 digits
O840ISO 4217 Currency Number
amountString
Amount
RTransaction Amount
customer
object
View Object
RCustomer
name
object
View Object
RName
firstStringRFirst Name
lastStringRLast Name
address
object
View Object
OAddress
line1StringRAddress Line 1
line2StringOAddress Line 2
cityStringRCity
stateString
2-character code
RState Code
zipcodeStringRZip Code
countryString
3-digit code
R840ISO 3166-1 Country Code
callback
object
View Object
OCallback, contact TabaPay
typeStringRURL
valueStringRURL String
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

{
  "type": "pull",
  "user1": "123456789",
  "amount": "1000.00",
  "customer":
  {
    "name":
    {
      "first": "TabaPay",
      "last": "Inc",
    },
    "address":
    {
      "line1": "605 Ellis Street",
      "line2": "Suite 110",
      "city": "Mountain View",
      "state": "CA",
      "zipcode": "94043",
    }
  }
}
With Callback:
  {
    "type": "pull",
    "user1": "123456789",
    "amount": "1000.00",
    "customer":
    {
      "name":
      {
        "first": "TabaPay",
        "last": "Inc",
      },
      "address":
      {
        "line1": "605 Ellis Street",
        "line2": "Suite 110",
        "city": "Mountain View",
        "state": "CA",
        "zipcode": "94043",
      }
    },
    "callback":
    {
      "type": "URL",
      "value": "https://somewhere.com"
    }
  }
   
Response
Status Codes
Status CodeDescription
200OKA Transaction is created and processing is completed.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
otppIDString
22 characters
TransactionRequestID
(OTPPID)
linkString
URL
URL
View
Hide
  Samples
{
  "SC": 200,
  "EC": "0",
  "otppid": "TabaPay_OTPPID_22Chars",
  "link": "https://link/?ID=TabaPay_OTPPID_22Chars"
}
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.

If using URL Callback, the Callback URL will get a POST Request with the following data:
{
  "request":
  {
    "amount": "1000.00",
    "card":
    {
      "last4": "1234",
      "expirationDate": "202512"
    },
    "user1":  "123456789",
    "name":
    {
      "first": "TabaPay",
      "last":  "Inc"
    },
    "address":
    {
      "line1":   "605 Ellis Street",
      "line2":   "Suite 110",
      "city":    "Mountain View",
      "state":   "CA",
      "zipcode": "94043",
    }
  },
  "response":
  {
    "SC":            "200",
    "EC":            "0",
    "transactionID": "TabaPay_TransactionID_",
    "network":       "Visa",
    "networkRC":     "00",
    "status":        "COMPLETED",
    "approvalCode":  "230402",
    "AVS":
    {
      "codeAVS":          "Y",
      "codeSecurityCode": "M"
    }
  }
}

3D Secure

This represents the 3D Secure Service.

The functions that are available for this service are:

●   Initialize
Creates a JWT for 3D Secure Card Authentication
●   Lookup
3D Secure Lookup
3D Secure Authenticate

Also please read the 3D Secure FAQ.

3D Secure Initialize

Initializes a 3D Secure Card Authentication Request.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v2/clients/<ClientIDISO>/3ds/init
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
accountobjectRAccount
accountIDString
22 characters
RAccountID
ownerobjectOOwner
phoneobjectOPhone Number (E.164 Numbering)
countryCodeString
1-3 digits
O1Country Calling Code
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number
orderobjectROrder
orderIDString
1-50 characters
ROrder Number
currencyString
3 digits
O840ISO 4217 Currency Number
amountString
Amount
RTransaction Amount
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

{
  "account": {
    "accountID": "TabaPay_AccountID_22-c"
  },
  "order": {
    "orderID": "12345678",
    "amount": "0.10"
  }
}
Response
Status Codes
Status CodeDescription
200OKA JWT is created.
207Multi-StatusOne or more Failures occurred while processing the Request.
404Not FoundThe AccountID does not point to a valid Account.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
3dsIDStringAn identifier representing this Request
jwtStringJWT (JSON Web Token)
deviceCollectionURLString
URL
URL for Device Data Collection
View
Hide
  Samples
{
  "SC": 200,
  "EC": "0",
  "3dsID": "ID_BASE64-URL-SAFE-VALUE",
  "jwt": "JWT-BASE64-URL-SAFE-VALUE",
  "deviceCollectionURL": "https://someplace.somewhere.com/DeviceCollect"
}
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.


Also please read the 3D Secure FAQ.

3D Secure Lookup

3D Secure Card Lookup.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v2/clients/<ClientIDISO>/3ds/lookup
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
3dsIDStringR3dsID from 3D Secure Initialize
authenticationIndicatorString
2 digits
R
transactionModeString
1 character
O
transactionTypeString
1 character
R
productCodeString
3 characters
R
accountobjectRAccount
accountIDString
22 characters
RAccountID
ownerobjectROwner
emailStringREmail Address
phoneobjectOPhone Number (E.164 Numbering)
countryCodeString
1-3 digits
O1Country Calling Code
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number
orderobjectROrder
orderIDString
1-50 characters
ROrder Number
currencyString
3 digits
O840ISO 4217 Currency Number
amountString
Amount
RTransaction Amount
browserobjectRBrowser Info
javascriptEnabledbooleanO
userAgentStringO
headerStringO
javaEnabledbooleanO
languageStringO
colorDepthStringO
screenHeightStringO
screenWidthStringO
ipAddressStringO
deviceChannelStringREither:
  • Browser
  • SDK
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

{
  "3dsID": "ID_BASE64-URL-SAFE-VALUE",
  "authenticationIndicator": "01",
  "transactionType": "C",
  "productCode": "ACF",
  "account": {
    "accountID": "TabaPay_AccountID_22-c",
    "owner": {
      "email": "support@tabapay.com"
    }
  },
  "order": {
    "orderID": "12345678",
    "amount": "0.10"
  },
  "browser": {
    "deviceChannel": "Browser"
  }
}
Response
Status Codes
Status CodeDescription
200OKA Lookup Response is returned.
207Multi-StatusOne or more Failures occurred while processing the Request.
404Not FoundThe AccountID does not point to a valid Account.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200200
Challenge
207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
3dsVersionStringThe 3D Secure Version that was used to process this request
enrolledStringAuthentication Eligibility Status
processorTransactionIDStringProcessor Transaction Identifier
dsTransactionIDStringDirectory Server Transaction IdentifierOO
statusStringStatus
ECIStringECI (Electronic Commerce Indicator)
UCAFStringUCAF (Universal Cardholder Authentication Field)
  • Visa uses CAVV (Cardholder Authentication Verification Value)
  • MasterCard uses AAV (Accountholder Authentication Value)
XIDStringXID (Transaction ID)O
challengeURLStringConsumer Authentication URL
payloadStringEncoded Payment Request
View
Hide
  Samples
No Challenge:
{
  "SC": 200,
  "EC": "0",
  "3dsVersion": "2.1.0",
  "enrolled": "Y",
  "processorTransactionID":"11111111111111111111",
  "dsTransactionID": "11111111-2222-3333-4444-555555555555",
  "status": "Y",
  "ECI": "05",
  "UCAF": "1111111111111111111111111111"
}
Challenge:
{
  "SC": 200,
  "EC": "0",
  "3dsVersion": "2.1.0",
  "enrolled": "Y",
  "processorTransactionID": "11111111111111111111",
  "dsTransactionID": "11111111-2222-3333-4444-555555555555",
  "challengeURL":"https://someplace.somewhere.com/challenge",
  "payload":"A_LONG_PAYLOAD"
}
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.


Also please read the 3D Secure FAQ.

3D Secure Authenticate

3D Secure Card Challenge Authentication.

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID.

URL
https://<FQDN>/v2/clients/<ClientIDISO>/3ds/authenticate
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
3dsIDStringR3dsID from 3D Secure Initialize
jwtStringRJWT (JSON Web Token) from Challenge
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

{
  "3dsID": "ID_BASE64-URL-SAFE-VALUE",
  "jwt": "JWT-BASE64-URL-SAFE-VALUE"
}
Response
Status Codes
Status CodeDescription
200OKA Lookup Response is returned.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
actionCodeStringResult: Action Code
errorNumberStringResult: Error Number
errorDescriptionStringResult: Error DescriptionO
3dsVersionStringThe 3D Secure Version that was used to process this request
processorTransactionIDStringProcessor Transaction Identifier
statusStringStatus
ECIStringECI (Electronic Commerce Indicator)
UCAFStringUCAF (Universal Cardholder Authentication Field)
  • Visa uses CAVV (Cardholder Authentication Verification Value)
  • MasterCard uses AAV (Accountholder Authentication Value)
XIDStringXID (Transaction ID)O
View
Hide
  Samples
{
  "SC": 200,
  "EC": "0",
  "actionCode": "SUCCESS",
  "errorNumber": "0",
  "errorDescription": "Success"
  "3dsVersion": "2.1.0",
  "processorTransactionID":"11111111111111111111",
  "status": "Y",
  "ECI": "05",
  "UCAF": "1111111111111111111111111111"
}
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.


Also please read the 3D Secure FAQ.

FXRate

Coming Soon

This resource represents an FX Rate.

The operations that are available for this resource are:

●   Query
Returns a real-time currency Exchange Rate from Visa or MasterCard

Query FXRate

Coming Soon

Returns the real-time FX-Rate and the amount in the beneficiary currency.
URL
https://<FQDN>/v4/clients/<ClientIDISO>/fx
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
typeString
4 characters
Either push or pull
RTransaction Type
The direction of the transaction impacts the FX Rate
sourceCurrencyString
3-digit code
RISO 4217 Currency Number
The source currency.
On a push, the originator's currency.
On a pull, the beneficiary's currency
destinationCurrencyString
3-digit code
RISO 4217 Currency Number
The destination currency.
On a push, the beneficiary's currency.
On a pull, the originator's currency
amountString
Amount
RTransaction Amount
networkString
Either visa, mastercard, or bank
RTransaction Network
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Query FXRate:

{
  "type": "push",
  "sourceCurrency": "840",
  "destinationCurrency": "826",
  "amount": "10.00",
  "network" "visa"
}
Response
Status Codes
Status CodeDescription
200OKThe FX Rate has been queried and the process is complete.
207Multi-StatusOne or more failures occurred while processing the Request.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200207Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageOO
sourceAmountString
Amount
On a push, this is the transaction amount.
On a pull, this is the settlement amount.
sourceCurrencyString
3-digit code
ISO 4217 Currency Number
The source currency code.
On a push, the originator's currency.
On a pull, the beneficiary's currency
destinationAmountString
Amount
On a push, this is the settlement amount.
On a pull, this is the transaction amount.
destinationCurrrencyString
3-digit code
ISO 4217 Currency Number
The destination currency.
On a push, the beneficiary's currency.
On a pull, the originator's currency
conversionRateString
Decimal
Conversion Rate without markup applied.
markupString
Decimal
Markup Rate applied to the transaction amount.
rateExpirationString
yyyy-MM-ddTHH:mm:ssZ Format.
All FX Rates expire 00:00:00 GMT the following calander day.
errorsArray of
8 characters
Strings
Array of Internal Error Codes
View
Hide
  Samples
Query FXRate:
{
  "SC": 200,
  "EC": "0",
  "sourceAmount": "10.70",
  "sourceCurrency":"840",
  "destinationAmount": "8.22",
  "destinationCurrency": "826",
  "conversionRate": "0.7682243",
  "markup": "0.07"
  "rateExpiration": "2022-01-29 00:00:00 GMT"
}
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.

SubClient

Coming Soon

This resource represents a Client's SubClient.

The operations that are available for this resource are:

●   Create
Creates a new SubClient Registration for a Client
●   Retrieve
Retrieves a SubClient Registration for a Client
●   Update
Updates a SubClient Registration for a Client
●   Delete
Deletes a SubClient Registration for a Client

Create a SubClient

Coming Soon

Creates a Client's SubClient Registration.

For ISOs (Independent Sales Organization) only.

URL
https://<FQDN>/v4/clients/<ClientID>/subclients/<SubClientID>
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescription
nameStringRCompany Name
tinString
9 digits
RTaxpayer Identification Number (EIN or SSN)
typeStringRCompany Type:
  • LLC
  • LLP
  • C-Corp
  • S-Corp
  • SoleProprieter
  • Nonprofit
  • Charitable
  • Other
urlStringOURL
emailStringREmail
addressobjectRAddress
line1StringRAddress Line 1
line2StringOAddress Line 2
cityStringRCity
stateString
2-character code
RState Code
zipcodeStringRZip Code
countryString
3-digit code
O840ISO 3166-1 Country Code
phoneobjectRPhone Number (E.164 Numbering)
countryCodeString
1-3 digits
O1Country Calling Code
numberString
Min: 4 digits
Max: 12-14 digits
RPhone Number
mccString
4 digits
RMerchant Category Code
mvvString
6 digits
OVisa Merchant Verification Code - requires Visa registration
maidString
6 digits
OMasterCard Identification - requires MasterCard registration
settlementobjectOSettlement Accounts
purchaseobjectRPurchase
routingNumberString
9 digits
RRouting Number
accountNumberString
4-17 digits
RAccount Number
disbursementobjectRDisbursement
routingNumberString
9 digits
RRouting Number
accountNumberString
4-17 digits
RAccount Number
feeobjectRFee
routingNumberString
9 digits
RRouting Number
accountNumberString
4-17 digits
RAccount Number
exceptionobjectRException
routingNumberString
9 digits
RRouting Number
accountNumberString
4-17 digits
RAccount Number
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Client's SubClient:

{
  "name":  "TabaPay",
  "tin":   "123456789",
  "type":  "Corp",
  "url":   "www.tabapay.com",
  "email": "help@tabapay.com",
  "address":
  {
    "line1":   "605 Ellis Street",
    "line2":   "Suite 110",
    "city":    "Mountain View",
    "state":   "CA",
    "zipcode": "94043"
  },
  "phone":
  {
    "number": "4159808222"
  },
  "mcc": 1234,
  "mvv": 1234,
  "maid": 1234,
  "settlement":
  {
    "purchase":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "disbursement":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "fee":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "exception":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    }
  }
}
Response
Status Codes
Status CodeDescription
200OKClient's SubClient Registration Created.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Client's SubClient:
{
  "SC": 200,
  "EC": "0"
}
Notes
Only for Clients who are ISO (Independent Sales Organization) where:
  • ClientID is your unique 22-character string and
  • SubClientID is an assigned 4, 6 or 8-digit value.

Retrieve SubClient

Coming Soon

Retrieves a Client's SubClient Registration.

For ISOs (Independent Sales Organization) only.

URL
https://<FQDN>/v4/clients/<ClientID>/subclients/<SubClientID>
HTTP Method
GET
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Transaction is retrieved.
404Not FoundSubClient Registration not found.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
nameStringCompany Name
tinString
9 digits
Taxpayer Identification Number (EIN or SSN)
typeStringCompany Type
urlStringURLO
emailStringEmail
addressobjectAddress
line1StringAddress Line 1
line2StringAddress Line 2O
cityStringCity
stateString
2-character code
State Code
zipcodeStringZip Code
countryString
3-digit code
ISO 3166-1 Country CodeO
phoneobjectPhone Number (E.164 Numbering)
countryCodeString
1-3 digits
Country Calling CodeO
numberString
Min: 4 digits
Max: 12-14 digits
Phone Number
mccString
4 digits
Merchant Category Code
mvvString
6 digits
Visa Merchant Verification CodeO
maidString
6 digits
MasterCard IdentificationO
settlementobjectSettlement AccountsO
purchaseobjectPurchase
routingNumberString
9 digits
Routing Number
accountNumberString
4-17 digits
Account Number
disbursementobjectDisbursement
routingNumberString
9 digits
Routing Number
accountNumberString
4-17 digits
Account Number
feeobjectFee
routingNumberString
9 digits
Routing Number
accountNumberString
4-17 digits
Account Number
exceptionobjectException
routingNumberString
9 digits
Routing Number
accountNumberString
4-17 digits
Account Number
View
Hide
  Samples
Client's SubClient:
{
  "SC": 200,
  "EC": "0",
  "name":  "TabaPay",
  "tin":   "123456789",
  "type":  "Corp",
  "url":   "www.tabapay.com",
  "email": "help@tabapay.com",
  "address":
  {
    "line1":   "605 Ellis Street",
    "line2":   "Suite 110",
    "city":    "Mountain View",
    "state":   "CA",
    "zipcode": "94043"
  },
  "phone":
  {
    "number": "4159808222"
  },
  "mcc": 1234,
  "mvv": 1234,
  "maid": 1234,
  "settlement":
  {
    "purchase":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "disbursement":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "fee":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "exception":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    }
  }
}
Notes
Only for Clients who are ISO (Independent Sales Organization) where:
  • ClientID is your unique 22-character string and
  • SubClientID is an assigned 4, 6 or 8-digit value.

Update a SubClient

Coming Soon

Updates a Client's SubClient Registration.

For ISOs (Independent Sales Organization) only.

URL
https://<FQDN>/v4/clients/<ClientID>/subclients/<SubClientID>
HTTP Method
PUT
Request
Request Data
JSON NameValueRequiredDefaultDescription
nameStringOCompany Name
tinString
9 digits
OTaxpayer Identification Number (EIN or SSN)
typeStringOCompany Type:
  • LLC
  • LLP
  • C-Corp
  • S-Corp
  • SoleProprieter
  • Nonprofit
  • Charitable
  • Other
urlStringOURL
emailStringOEmail
addressobjectOAddress
line1StringOAddress Line 1
line2StringOAddress Line 2
cityStringOCity
stateString
2-character code
OState Code
zipcodeStringOZip Code
countryString
3-digit code
O840ISO 3166-1 Country Code
phoneobjectOPhone Number (E.164 Numbering)
countryCodeString
1-3 digits
O1Country Calling Code
numberString
Min: 4 digits
Max: 12-14 digits
OPhone Number
mccString
4 digits
OMerchant Category Code
mvvString
6 digits
OVisa Merchant Verification Code - requires Visa registration
maidString
6 digits
OMasterCard Identification - requires MasterCard registration
settlementobjectOSettlement Accounts
purchaseobjectOPurchase
routingNumberString
9 digits
ORouting Number
accountNumberString
4-17 digits
OAccount Number
disbursementobjectODisbursement
routingNumberString
9 digits
ORouting Number
accountNumberString
4-17 digits
OAccount Number
feeobjectOFee
routingNumberString
9 digits
ORouting Number
accountNumberString
4-17 digits
OAccount Number
exceptionobjectOException
routingNumberString
9 digits
ORouting Number
accountNumberString
4-17 digits
OAccount Number
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

Client's SubClient:

{
  "name":  "TabaPay",
  "tin":   "123456789",
  "type":  "Corp",
  "url":   "www.tabapay.com",
  "email": "help@tabapay.com",
  "address":
  {
    "line1":   "605 Ellis Street",
    "line2":   "Suite 110",
    "city":    "Mountain View",
    "state":   "CA",
    "zipcode": "94043"
  },
  "phone":
  {
    "number": "4159808222"
  },
  "mcc": 1234,
  "mvv": 1234,
  "maid": 1234,
  "settlement":
  {
    "purchase":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "disbursement":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "fee":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    },
    "exception":
    {
      "routingNumber": 121140399,
      "accountNumber": 12345
    }
  }
}
Response
Status Codes
Status CodeDescription
200OKClient's SubClient Registration Updated.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Client's SubClient:
{
  "SC": 200,
  "EC": "0"
}
Notes
Only for Clients who are ISO (Independent Sales Organization) where:
  • ClientID is your unique 22-character string and
  • SubClientID is an assigned 4, 6 or 8-digit value.

Delete a SubClient

Coming Soon

Deletes a Client's SubClient Registration.

For ISOs (Independent Sales Organization) only.

URL
https://<FQDN>/v4/clients/<ClientID>/subclients/<SubClientID>
HTTP Method
DELETE
Request
No Request Data
Response
Status Codes
Status CodeDescription
200OKThe Transaction is deleted.
404Not FoundSubClient Registration not found.

See Status Codes for other possible Status Codes that might be returned.
Response Data
JSON NameValueDescriptionStatus Code
200Other
SCInteger
3-digit code
HTTP Status CodeO
ECString
1 or 8 characters
Internal Error CodeO
EMStringError MessageO
View
Hide
  Samples
Client's SubClient:
{
  "SC": 200,
  "EC": "0"
}
Notes
Only for Clients who are ISO (Independent Sales Organization) where:
  • ClientID is your unique 22-character string and
  • SubClientID is an assigned 4, 6 or 8-digit value.

Networks

Network Name
STAR
Pulse
NYCE
CU24
Accel
Visa
VisaFF
MasterCard
MasterCardSend (MoneySend)
Discover
Amex
CCPay
IntlVisa
IntlMasterCard

Network Response Codes


A Financial Institution may decide to return a Network Response Code that may not match the ISO Code meaning.

ISO CODEDescription
00Approved or completed successfully
01Refer to card issuer
02Refer to card issuers special conditions
03Invalid merchant
04Pick-up
05Do not honor
06Error
07Pick-up card, special conditions
08Honor with identification
09Request in progress
10Approved for partial amount
11Approved (VIP)
12Invalid transaction
13Invalid amount
14Invalid card number (no such number)
15No such issuer
16Approved, update track 3
17Customer cancellation, reversal (unsupported)
18Customer dispute, chargeback (future)
19Re-enter transaction
20Invalid response
21No action taken, reversal (unsupported)
22Suspected malfunction, reversal (unsupported)
23Unacceptable transaction fee
24File update not supported by receiver
25Unable to locate record on file
26Duplicate file update record, no action
27File update field edit error
28File update record locked out
29File update not successful, contact acquirer
30Format error (may also be a reversal)
31Bank not supported by switch
32Completed partially, reversal (unsupported)
33Expired card, pick-up
34Suspected fraud, pick-up
35Card acceptor contact acquirer, pick-up
36Restricted card, pick-up
37Card acceptor call acquirer security, pick-up
38Allowable PIN tries exceeded, pick-up
39No credit account
40Requested function not supported
41Lost card, pick-up
42No universal account
43Stolen card, pick-up
44No investment account
45Reserved for ISO use
46Reserved for ISO use
47Reserved for ISO use
48Reserved for ISO use
49Reserved for ISO use
50Reserved for ISO use
51Insufficient funds
52No checking account
53No savings account
54Expired card
55Incorrect PIN
56No card record
57Transaction not permitted to cardholder
58Transaction not permitted to terminal (may also be a chargeback)
59Suspected fraud
60Card acceptor contact acquirer
61Exceeds withdrawal amount limit
62Restricted card
63Security violation (may also be a chargeback)
64Original amount incorrect, reversal (unsupported)
65Exceeds withdrawal frequency limit
66Card acceptor call acquirer security
67Hard capture, pick-up
68Response received too late, reversal (unsupported)
69Reserved for ISO
70Reserved for ISO
71Reserved for ISO
72Reserved for ISO
73Reserved for ISO
74Reserved for ISO
75Allowable number of PIN tries exceeded
76Key synchronization error (FIS)
77Reserved for private use
78Customer not eligible for POS (Star SM )
79Invalid digital signature
80Stale dated transaction (Star SM )
81Issuer requested standin
82Count exceeds limit (VISANet)
83Reserved for private use
84Time limit for pre-authorization reached (VISANet)
85*Issuer has no reason to decline the transaction (Account Verification)
86Cannot verify PIN (VISANet)
87Check already posted
88Information not on file
89Card verification value (CVV) verification failed (no pickup)
90Cutoff is in progress
91Issuer or switch is inoperative
92Financial institution or intermediate network unknown for routing
93Transaction cannot be completed, violation of law
94Duplication transaction
95Reconcile error
96System malfunction
97Reserved for national use
98Reserved for national use
99*Card network fault error
0Z-9ZReserved for ISO use
C2-E0Reserved for national use (X9.2)
E1*Invalid or unsupported SEC
E2*AVS data required
E3*CVV2 data required
E4*Service not allowed. Transaction not permitted to cardholder.
E5*Service not allowed. Transaction not permitted to cardholder.
E6*Issuer country is blocked
E7*Incorrect MAC was sent
E8*Standard Entry Class requirements were not met
E9*System time out
EA*Account length error
EB*Check digit error
EC*CID format error
ED*Authorization is too old to capture
EE*Card product code is blocked Card product code is blocked
EF*Attempt to process a BRIC transaction on a prior PIN based transaction
EG*CyberSource Time Out Connection to CyberSource timed out
EH*CARD_ENT_METH supplied is not valid or required additional data not provided as defined
EI*CARD_ID is not valid
EJ*Required PIN block not present
EK*Bin is not valid for pinless routing
EL*Signature store did not complete
EM*Debit PIN transactions must be swiped
EN*DB proxy response was not processed within the time out period
EO*Transaction was declined by merchant due to mismatch of CVV2 data
EP*Transaction not allowed as per a validation rule
EQ*There were no available gateway nodes to route transaction
EZ-MZReserved for national use (X9.2)
N0Authorization life cycle unacceptable
N1Authorization life cycle expired
N2Non-receipt of requested item (future)
N3Non-receipt of requested item, illegible copy (future)
N4Transaction exceeds floor limit (future)
N5Declined authorization (future)
N6Non-matching account numbers (future)
N7 Error in addition (future)
N8Altered amount (future)
N9Incorrect account number (future)
P0Missing signature (future)
P1Slip without card imprint (future)
P2Imprinting of multiple slips (future)
P3Canceled pre-authorization transaction (future)
P4Delinquent settlement (future)
P5Currency conversion error (future)
P6Credit posted as a debit (sale) (future)
P7Claim or defense (future)
P8Non-receipt of goods (future)
P9Defective merchandise (future)
Q1*Card authentication failed
R0Fraudulent transaction prior to embossed valid date (future)
R1Credit not received (future)
R2Allowable PAN entries warning -- approved
R3Approved with overdraft protection
R4Bad CVV3
RR*Unknown Backend Processing Error
S0Check not acceptable for cash
S1Check not acceptable
S2Check deposit limit exceeded
S3Cash back limit exceeded
S4Check amount does not match courtesy amount
S5PIN not selected
S6PIN already selected
S7Unmatched voucher information
S8Allowable PAN entries exceeded -- denial
S9Expiration date mismatch
SAInactive card
SBExpiration date mismatch (card pickup)
SCItem suspected for stop pay
SDAccount closed
SEIneligible account
SFItem submitted more than two times
SGNo account on file - absolute
SHUnable to locate
SIGeneral denial
SJItem settled via ACH
SKCross-reference card not found
SLCategory limit exceeded
SMTransaction limit exceeded
SNDaily limit exceeded
SOMonthly limit exceeded
SPInvalid secret code
SQPIN key sync error
SRBad CVV2
SSStop payment order
STRevocation of authorization order
SVStop reoccurring payments
T3Lost card (no pickup)
T4Closed account
T5Dormant account
T6Special conditions (no pick-up)
T7Purchase only approval for purchase with cash back transaction.
T9Insufficient funds for fees
TAARQC validation failed for chip card
TBUnsafe PIN
U0-YZReserved for private use
ZD*MasterCard Send (MoneySend) Error due to Expiration Date
ZN*MasterCard Send (MoneySend) Decline due to Card was Declined
ZR*MasterCard Send (MoneySend) Decline due to Unsupported Card
ZU*MasterCard Send (MoneySend) Error due to an Unknown Reason
ZX*MasterCard Send (MoneySend) Decline due to an Unknown Reason
ZY*MasterCard Send (MoneySend) Request in Unknown Status
ZZ*Used by TabaPay for Testing

Notes:

*   Not all Networks may return this Network Response Code.


Accel Action CodeDescription
000Approved
001Approved with identification
002Approved for partial amount
003Approved (VIP)
100, 200Do not honor
101, 201Expired card
102, 202Suspected fraud
103, 203Card acceptor contact acquirer
104, 204Restricted card
105, 205Card acceptor call acquirer’s security department
106, 206Allowable PIN tries exceeded
107Refer to card issuer
108Refer to card issuer’s special condition
109Invalid merchant
110Invalid amount
111Invalid card number
112PIN data required
113Unacceptable fee
114, 214No account of type requested
115Requested function not supported (invalid transaction)
116, 216Insufficient funds
117, 217Incorrect PIN
118No card record
119Transaction not permitted to cardholder
120Transaction not permitted to terminal
121Exceeds withdrawal amount limit
122Security violation
123Exceeds withdrawal limit frequency
124Violation of law
126Invalid PIN block
127PIN length error
128PIN key synchronization error (sanity error)
129Suspected counterfeit card
130Transaction failed OFAC check
131Check not acceptable
180Limit exceeded due to cashback amount
181Enter lesser amount
182Institution not supported by switch
183Balances not available for inquiry
184Resubmission in violation of network rules
185Stop payment on check (shared branch only)
207Special conditions
208Lost card
209Stolen card
210Suspected counterfeit card
907Card issuer or switch inoperative
908Transaction destination cannot be found for routing
909System malfunction
999Used by TabaPay for Testing


RTP Response CodeDescription
P01Insufficient Funds
P02Unknown customer, account closed
P04Debtor/Creditor Account invalid
P07Account blocked
P11Transaction forbidden on this account
P14Deceased customer
P18Invalid Date
P21Incorrect Agent
P23Amount not agreed upon or invalid
P24Duplicate message
P26Missing or invalid mandatory field
P27See narrative information for more detail about error
P28Incorrect RTN
P34Suspended account
Z01Internal RTP error
Z02Timeout
Z03Token error
Z0UUnknown Network Error

AVS Response Codes

CodeVisaMasterCardDiscoverAmerican Express
YAddress & 5-digit or 9-digit ZIP matchAddress & 5-digit ZIP matchAddress only matchesAddress & ZIP match
AAddress matches, ZIP does notAddress matches, ZIP does notAddress & 5-digit ZIP matchAddress only matches
SAVS not supportedAVS not supportedAVS not supportedAVS not supported
RSystem unavailable, retrySystem unavailable, retryNot applicableSystem unavailable, retry
UInformation not availableInformation not availableSystem unavailable, retryInformation not available
ZEither 5-digit or 9-digit ZIP match, address does not5-digit ZIP matches, address does not5-digit ZIP matches, address does notZIP code only matches
NNeither ZIP nor address matchNeither ZIP nor address matchNeither ZIP nor address matchNeither ZIP nor address match
WNot applicableFor U.S., 9-digit ZIP matches, address does not. For non-U.S., ZIP matches, address does notInformation not availableNot applicable
XNot applicableFor U.S., all digits match. For non-U.S., ZIP and address match.Address & 9-digit ZIP matchNot applicable
BAddress matches, ZIP not verifiedNot applicableNot applicableNot applicable
TNot applicableNot applicable9-digit ZIP matches, address does notNot applicable
PZIP matches, address not verifiedNot applicableNot applicableNot applicable
CAddress and ZIP not verifiedNot applicableNot applicableNot applicable
DAddress & ZIP match (International only)Not applicableNot applicableNot applicable
GAddress not verified for International transaction (International only)Not applicableNot applicableNot applicable
IAddress not verified (International only)Not applicableNot applicableNot applicable
MAddress & ZIP match (International only)Not applicableNot applicableNot applicable
FAddress & ZIP match (UK only)Not applicableNot applicableNot applicable

Security Code Response Codes

Response Code
for Securtiy Code
Description
MSecurity Code was matched
NSecurity Code was not matched

Internal Error Codes

These are Internal Error Codes used only for debugging. These are subject to change at any time and without any notice. You should be using SC and EM to determine what might be wrong if you are getting an error.
ECDescription
0OK
!= 0Error

If you need to contact TabaPay Support, be sure to send:

Status Codes

Status CodeDescription
200OKThe API Request was successfully processed.
201CreatedTransaction Created, but Transaction Processing is Pending (batch).
207Multi-StatusOne or more upstream processing failed.
400Bad RequestThe ResourceID is invalid
or
The Request Data is invalid.
401UnAuthorizedThe Authorization Token is invalid
or
The IP Address is invalid (not whitelisted).
403ForbiddenInvalid permissions to access the Resource, please contact TabaPay support.
404Not FoundThe ResourceID does not point to a valid Resource.
405Method Not AllowedRequest Method Not Allowed for the Requested Resource.
406Not AcceptableOur Web Application Firewall (WAF) found something invalid in your request.
409ConflictReferenceID already used
or
Conflicting Request Parameters.
410GoneThe Resource pointed to by the ResourceID has been marked for deletion.
415Unsupported Media TypeContent-type must be application/json.
421Misdirected RequestToo late to Retrieve by ReferenceID, use AccountID or TransactionID.
422Unprocessable EntityThe Resource pointed to by the ResourceID is in an invalid state
or
The Transaction Amount exceeded one or more Limits.
423LockedThe Resource pointed to by the ResourceID is locked.
429Too Many RequestsRetrieve: Too many requests, please do not poll.
Create Transaction: Over your Daily (24-hour rolling) Approximation Limit.
431Request Header Fields Too LargeToo many HTTP Header Lines and/or HTTP Header Lines too big.
500Server ErrorThere was a problem processing the Request.
502Bad GatewayProblem connecting to an Application Server.
503Service UnavailableYour request cannot be processed, should be only a Temporary Condition.
504Gateway TimeoutConnection to an Application Server timed out.

A 400 Series Error is usually something that you can fix by changing something in your request. A 500 Series Error is usually something that you need to contact us (support@TabaPay.com) to look at. If we determine that a 500 Series Error can be fixed by you, we will try to change this error situation to a 400 Series Error in a future code release.

Currency Numbers

We are using ISO 4217 Currency Numbers.
Currency NumberDecimal PlacesDecimal SeparatorCurrency CodeCurrency Name
7842. (period)AEDUnited Arab Emirates dirham
9712. (period)AFNAfghan afghani
0082, (comma)ALLAlbanian lek
0512, (comma)AMDArmenian dram
5322. (period)ANGNetherlands Antillean guilder
9732, (comma)AOAAngolan kwanza
0322, (comma)ARSArgentine peso
0362. (period)AUDAustralian dollar
5332. (period)AWGAruban florin
9442, (comma)AZNAzerbaijani manat
9772, (comma)BAMBosnia and Herzegovina convertible mark
0522. (period)BBDBarbados dollar
0502. (period)BDTBangladeshi taka
9752, (comma)BGNBulgarian lev
0483. (period)BHDBahraini dinar
1080N/ABIFBurundian franc
0602. (period)BMDBermudian dollar
0962. (period)BNDBrunei dollar
0682, (comma)BOBBoliviano
9862, (comma)BRLBrazilian real
0442. (period)BSDBahamian dollar
0642. (period)BTNBhutanese ngultrum
0722. (period)BWPBotswana pula
9332, (comma)BYNBelarusian ruble
0842. (period)BZDBelize dollar
1242. (period)CADCanadian dollar
9762. (period)CDFCongolese franc
7562. (period)CHFSwiss franc
1520N/ACLPChilean peso
1562. (period)CNYRenminbi yuan
1702, (comma)COPColombian peso
1882, (comma)CRCCosta Rican colon
9312, (comma)CUCCuban convertible peso
1922, (comma)CUPCuban peso
1322. (period)CVECape Verdean escudo
2032. (period)CZKCzech koruna
2620N/ADJFDjiboutian franc
2082, (comma)DKKDanish krone
2142. (period)DOPDominican peso
0122, (comma)DZDAlgerian dinar
8182. (period)EGPEgyptian pound
2322. (period)ERNEritrean nakfa
2302. (period)ETBEthiopian birr
9782, (comma)EUREuro
2422. (period)FJDFiji dollar
2382. (period)FKPFalkland Islands pound
8262. (period)GBPPound sterling
9812, (comma)GELGeorgian lari
9362. (period)GHSGhanaian cedi
2922. (period)GIPGibraltar pound
2702. (period)GMDGambian dalasi
3240N/AGNFGuinean franc
3202. (period)GTQGuatemalan quetzal
3282. (period)GYDGuyanese dollar
3442. (period)HKDHong Kong dollar
3402. (period)HNLHonduran lempira
1912. (period)HRKCroatian kuna
3322. (period)HTGHaitian gourde
3482, (comma)HUFHungarian forint
3602, (comma)IDRIndonesian rupiah
3762. (period)ILSIsraeli new shekel
3562. (period)INRIndian rupee
3683. (period)IQDIraqi dinar
3642. (period)IRRIranian rial
3520N/AISKIcelandic króna
3882. (period)JMDJamaican dollar
4003. (period)JODJordanian dinar
3920N/AJPYJapanese yen
4042. (period)KESKenyan shilling
4172, (comma)KGSKyrgyzstani som
1162. (period)KHRCambodian riel
1740N/AKMFComoro franc
4082. (period)KPWNorth Korean won
4100N/AKRWSouth Korean won
4143. (period)KWDKuwaiti dinar
1362. (period)KYDCayman Islands dollar
3982, (comma)KZTKazakhstani tenge
4182. (period)LAKLao kip
4222. (period)LBPLebanese pound
1442. (period)LKRSri Lankan rupee
4302. (period)LRDLiberian dollar
4262. (period)LSLLesotho loti
4343. (period)LYDLibyan dinar
5042, (comma)MADMoroccan dirham
4982, (comma)MDLMoldovan leu
9692. (period)MGAMalagasy ariary
8072, (comma)MKDMacedonian denar
1042. (period)MMKMyanmar kyat
4962. (period)MNTMongolian tögrög
4462, (comma)MOPMacanese pataca
9292. (period)MRUMauritanian ouguiya
4802. (period)MURMauritian rupee
4622. (period)MVRMaldivian rufiyaa
4542. (period)MWKMalawian kwacha
4842. (period)MXNMexican peso
4582. (period)MYRMalaysian ringgit
9432, (comma)MZNMozambican metical
5162. (period)NADNamibian dollar
5662. (period)NGNNigerian naira
5582. (period)NIONicaraguan córdoba
5782, (comma)NOKNorwegian krone
5242. (period)NPRNepalese rupee
5542. (period)NZDNew Zealand dollar
5123. (period)OMROmani rial
5902. (period)PABPanamanian balboa
6042, (comma)PENPeruvian sol
5982. (period)PGKPapua New Guinean kina
6082. (period)PHPPhilippine peso
5862. (period)PKRPakistani rupee
9852, (comma)PLNPolish złoty
6000N/APYGParaguayan guaraní
6342. (period)QARQatari riyal
9462, (comma)RONRomanian leu
9412, (comma)RSDSerbian dinar
6432, (comma)RUBRussian ruble
6460N/ARWFRwandan franc
6822. (period)SARSaudi riyal
0902. (period)SBDSolomon Islands dollar
6902. (period)SCRSeychelles rupee
9382. (period)SDGSudanese pound
7522, (comma)SEKSwedish krona/kronor
7022. (period)SGDSingapore dollar
6542. (period)SHPSaint Helena pound
6942. (period)SLLSierra Leonean leone
7062. (period)SOSSomali shilling
9682, (comma)SRDSurinamese dollar
7282. (period)SSPSouth Sudanese pound
9302. (period)STNSão Tomé and Príncipe dobra
2222. (period)SVCSalvadoran colón
7602. (period)SYPSyrian pound
7482. (period)SZLSwazi lilangeni
7642. (period)THBThai baht
9722. (period)TJSTajikistani somoni
9342, (comma)TMTTurkmenistan manat
7883, (comma)TNDTunisian dinar
7762. (period)TOPTongan paʻanga
9492, (comma)TRYTurkish lira
7802. (period)TTDTrinidad and Tobago dollar
9012. (period)TWDNew Taiwan dollar
8342. (period)TZSTanzanian shilling
9802, (comma)UAHUkrainian hryvnia
8000N/AUGXUgandan shilling
8402. (period)USDUnited States dollar
8582, (comma)UYUUruguayan peso
9274, (comma)UYWUnidad previsional
8602, (comma)UZSUzbekistan som
9282, (comma)VESVenezuelan bolívar soberano
7040N/AVNDVietnamese đồng
5480N/AVUVVanuatu vatu
8822. (period)WSTSamoan tala
9500N/AXAFCFA franc BEAC
9512. (period)XCDEast Caribbean dollar
9520N/AXOFCFA franc BCEAO
9530N/AXPFCFP franc
8862. (period)YERYemeni rial
7102. (period)ZARSouth African rand
9672. (period)ZMWZambian kwacha
9322. (period)ZWLZimbabwean dollar

Country Codes

We are using ISO 3166-1 numeric (or numeric-3) codes.
Country CodeCountry Name
004Afghanistan
248Åland Islands
008Albania
012Algeria
016American Samoa
020Andorra
024Angola
660Anguilla
010Antarctica
028Antigua and Barbuda
032Argentina
051Armenia
533Aruba
036Australia
040Austria
031Azerbaijan
044Bahamas
048Bahrain
050Bangladesh
052Barbados
112Belarus
056Belgium
084Belize
204Benin
060Bermuda
064Bhutan
068Bolivia, Plurinational State of
535Bonaire, Sint Eustatius and Saba
070Bosnia and Herzegovina
072Botswana
074Bouvet Island
076Brazil
086British Indian Ocean Territory
096Brunei Darussalam
100Bulgaria
854Burkina Faso
108Burundi
132Cabo Verde
116Cambodia
120Cameroon
124Canada
136Cayman Islands
140Central African Republic
148Chad
152Chile
156China
162Christmas Island
166Cocos (Keeling) Islands
170Colombia
174Comoros
178Congo
180Congo, the Democratic Republic of the
184Cook Islands
188Costa Rica
384Côte d'Ivoire
191Croatia
192Cuba
531Curaçao
196Cyprus
203Czechia
208Denmark
262Djibouti
212Dominica
214Dominican Republic
218Ecuador
818Egypt
222El Salvador
226Equatorial Guinea
232Eritrea
233Estonia
231Ethiopia
238Falkland Islands (Malvinas)
234Faroe Islands
242Fiji
246Finland
250France
254French Guiana
258French Polynesia
260French Southern Territories
266Gabon
270Gambia
268Georgia
276Germany
288Ghana
292Gibraltar
300Greece
304Greenland
308Grenada
312Guadeloupe
316Guam
320Guatemala
831Guernsey
324Guinea
624Guinea-Bissau
328Guyana
332Haiti
334Heard Island and McDonald Islands
336Holy See
340Honduras
344Hong Kong
348Hungary
352Iceland
356India
360Indonesia
364Iran, Islamic Republic of
368Iraq
372Ireland
833Isle of Man
376Israel
380Italy
388Jamaica
392Japan
832Jersey
400Jordan
398Kazakhstan
404Kenya
296Kiribati
408Korea, Democratic People's Republic of
410Korea, Republic of
414Kuwait
417Kyrgyzstan
418Lao People's Democratic Republic
428Latvia
422Lebanon
426Lesotho
430Liberia
434Libya
438Liechtenstein
440Lithuania
442Luxembourg
446Macao
807Macedonia, the former Yugoslav Republic of
450Madagascar
454Malawi
458Malaysia
462Maldives
466Mali
470Malta
584Marshall Islands
474Martinique
478Mauritania
480Mauritius
175Mayotte
484Mexico
583Micronesia, Federated States of
498Moldova, Republic of
492Monaco
496Mongolia
499Montenegro
500Montserrat
504Morocco
508Mozambique
104Myanmar
516Namibia
520Nauru
524Nepal
528Netherlands
540New Caledonia
554New Zealand
558Nicaragua
562Niger
566Nigeria
570Niue
574Norfolk Island
580Northern Mariana Islands
578Norway
512Oman
586Pakistan
585Palau
275Palestine, State of
591Panama
598Papua New Guinea
600Paraguay
604Peru
608Philippines
612Pitcairn
616Poland
620Portugal
630Puerto Rico
634Qatar
638Réunion
642Romania
643Russian Federation
646Rwanda
652Saint Barthélemy
654Saint Helena, Ascension and Tristan da Cunha
659Saint Kitts and Nevis
662Saint Lucia
663Saint Martin (French part)
666Saint Pierre and Miquelon
670Saint Vincent and the Grenadines
882Samoa
674San Marino
678Sao Tome and Principe
682Saudi Arabia
686Senegal
688Serbia
690Seychelles
694Sierra Leone
702Singapore
534Sint Maarten (Dutch part)
703Slovakia
705Slovenia
090Solomon Islands
706Somalia
710South Africa
239South Georgia and the South Sandwich Islands
728South Sudan
724Spain
144Sri Lanka
729Sudan
740Suriname
744Svalbard and Jan Mayen
748Swaziland
752Sweden
756Switzerland
760Syrian Arab Republic
158Taiwan, Province of China
762Tajikistan
834Tanzania, United Republic of
764Thailand
626Timor-Leste
768Togo
772Tokelau
776Tonga
780Trinidad and Tobago
788Tunisia
792Turkey
795Turkmenistan
796Turks and Caicos Islands
798Tuvalu
800Uganda
804Ukraine
784United Arab Emirates
826United Kingdom
581United States Minor Outlying Islands
840United States of America
858Uruguay
860Uzbekistan
548Vanuatu
862Venezuela, Bolivarian Republic of
704Viet Nam
092Virgin Islands, British
850Virgin Islands, U.S.
876Wallis and Futuna
732Western Sahara
887Yemen
894Zambia
716Zimbabwe

State Codes

We are using the United States Postal Service 2-letter codes.
State CodeState NameState Numeric Code
ALAlabama01
AKAlaska02
AZArizona04
ARArkansas05
CACalifornia06
COColorado08
CTConnecticut09
DEDelaware10
DCDistrict of Columbia11
FLFlorida12
GAGeorgia13
HIHawaii15
IDIdaho16
ILIllinois17
INIndiana18
IAIowa19
KSKansas20
KYKentucky21
LALouisiana22
MEMaine23
MDMaryland24
MAMassachusetts25
MIMichigan26
MNMinnesota27
MSMississippi28
MOMissouri29
MTMontana30
NENebraska31
NVNevada32
NHNew Hampshire33
NJNew Jersey34
NMNew Mexico35
NYNew York36
NCNorth Carolina37
NDNorth Dakota38
OHOhio39
OKOklahoma40
OROregon41
PAPennsylvania42
RIRhode Island44
SCSouth Carolina45
SDSouth Dakota46
TNTennessee47
TXTexas48
UTUtah49
VTVermont50
VAVirginia51
WAWashington53
WVWest Virginia54
WIWisconsin55
WYWyoming56
ASAmerican Samoa00
GUGuam00
MPNorthern Mariana Islands00
PRPuerto Rico00
UMUnited States Minor Outlying Islands00
VIVirgin Islands00

Canadian Province Codes

We are using the Canadian postal abbreviations for provinces and territories.
Province CodeProvince NameProvince Numeric Code
ABAlberta60
BCBritish Columbia61
MBManitoba62
NBNew Brunswick63
NLNewfoundland and Labrador64
NSNova Scotia66
NTNorthwest Territories65
NUNunavut72
ONOntario67
PEPrince Edward Island68
QCQuebec69
SKSaskatchewan70
YTYukon71

Resource Statuses

Resource's StatusAny ResourceTransactionDescription
OKResource is in normal status.
LOCKEDResource is locked.
DELETEDResource is marked for deletion.
PENDINGTransaction processing started.
BATCHTransaction processing waiting to be processed (batch).
FAILEDTransaction processing failed.
UNKNOWNTransaction processing result is unknown.
ERRORTransaction processing error.
COMPLETEDTransaction completed processing successfully.
REVERSEDA Request to Reverse a previous PULL Transaction was requested.
REVERSALA Request to Reverse a previous PULL Transaction was tried, however the status is unknown.

Transactions

The following tables shows the various statuses a Transaction Resource undergoes:

Transaction Successful

StatusDescription
OKTransaction created.
PENDINGTransaction processing started or waiting to be processed (batch).
COMPLETEDTransaction processed successfully.

Transaction Error

StatusDescription
OKTransaction created.
PENDINGTransaction processing started.
ERRORTransaction processing error, see Network Response Code.

Transaction Processing returned a non-successful Network Response Code from a Card Network.

Transaction Failed

StatusDescription
OKTransaction created.
PENDINGTransaction processing started.
FAILEDTransaction processing failed.

Transaction Processing failed. The Transaction was unsuccessful.

Transaction Result is Unknown

StatusDescription
OKTransaction created.
PENDINGTransaction processing started.
UNKNOWNTransaction processing result is unknown.

The Transaction could have been successful or not. Manual intervention is required to determine the status of the Transaction. Please contact support@TabaPay.com.

Transaction Timed Out so Result was originally Unknown but actually Successful

StatusDescription
OKTransaction created.
PENDINGTransaction processing started.
UNKNOWNTransaction processing result is unknown.
COMPLETEDTransaction processed successfully.

The Transaction timed out so the Transaction Status was originally set to UNKNOWN. Your request returned a Status Code of 207. The Transaction Processing continue to be processed. The final and actual Transaction is COMPLETED.

Transaction Timed Out so Result was originally Unknown but actually Failed

StatusDescription
OKTransaction created.
PENDINGTransaction processing started.
UNKNOWNTransaction processing result is unknown.
FAILEDTransaction processing failed.

The Transaction timed out so the Transaction Status was originally set to UNKNOWN. Your request returned a Status Code of 207. The Transaction Processing continue to be processed. Something did go wrong and so the final and actual Transaction is FAILED.

Transaction Successful but a Request to Reverse the Transaction was requested

StatusDescription
OKTransaction created.
PENDINGTransaction processing started or waiting to be processed (batch).
COMPLETEDTransaction processed successfully.
REVERSEDTransaction Reversal was requested.

Transaction Successful but a Request to Reverse the Transaction was tried

StatusDescription
OKTransaction created.
PENDINGTransaction processing started or waiting to be processed (batch).
COMPLETEDTransaction processed successfully.
REVERSALTransaction Reversal was tried, however the status is unknown.

Batch Transaction Successful

StatusDescription
OKTransaction created.
BATCHTransaction waiting to be processed (batch).
COMPLETEDTransaction processed successfully.

Test Cards

PCI requires us and you to use Test Card Numbers when testing. You should never use a real Card Number in the Sandbox Environment. The following Card Numbers were randomly created, if they happen by chance to be a real Card Number, it is purely by coincidence only.
NetworkCard NumberRegulatedCard TypePullPush (Availability)
DebitCreditPrePaidImmediateNextFew
Visa4000056655665556✘ No
4005519200000004✔ Yes
4111111111111111✔ Yes
4012000077777777✔ Yes
4000000760000002✔ Yes
4000001240000000✔ Yes
4000004840008001✔ Yes
4500600000000061✘ No
4217651111111119✘ No
4242424242424242✘ No
MasterCard2223000048400011✘ No✘ (✔*)
5200828282828210✔ Yes✘ (✔*)
5403879999999997✔ Yes✘ (✔*)
5105105105105100✔ Yes✘ (✔*)
MoneySend2223003122003222✘ No
5555555555554444✔ Yes
American Express371449635398431✔ Yes
378282246310005✔ Yes
378734493671000✔ Yes
Discover6011111111111117✔ Yes
6011000990139424✔ Yes
6011000991300009✔ Yes
NetworkCard NumberInternational
CurrencyCountry
IntlVisa8405124124999998124124
8405840124999999840124
8405704704999995704704
8405840704999997840704
8405764764999996764764
8405840764999994840764
8405458458999996458458
8405360360999991360360
8405946946999990946946
8405978946999993978946
8405144144999992144144
8405946642999997946642
8405558558999992558558
8405340340999998340340
8405840222999990840222
8405978384999992978384
8405051051999990051051
8405981268999997981268
8405348348999993348348
8405398398999997398398
8405600600999990600600
8405949792999999949792
8405980804999990980804
IntlMasterCard8505124124999997124124
8505840124999998840124
8505704704999994704704
8505840704999996840704
8505764764999995764764
8505840764999993840764
8505458458999995458458
8505360360999990360360
8505946946999999946946
8505978946999992978946
8505144144999991144144
8505946642999996946642
8505558558999991558558
8505340340999997340340
8505840222999999840222
8505978384999991978384
8505051051999999051051
8505981268999996981268
8505348348999992348348
8505398398999996398398
8505600600999999600600
8505949792999998949792
8505980804999999980804

Sample Flows

There are only a few simple flows:

Retrieve Client's Attributes (Information)
 
API CallDescription
1Retrieve ClientClient Attributes:
  • Networks
  • Limits
 
 
Create Key (optional)
 
API CallDescription
2Create KeyEncryption Key
RSA Public Key
 
 
Transaction using an Account (Tokenization)
 
API CallDescription
3Query CardCard Attributes
API CallDescription
4Create AccountType: Card
API CallDescription
5Create Transaction
Push
Transaction:
  • Source: Settlement
  • Destination: Account
API CallDescription
6Create Transaction
Pull
Transaction:
  • Source: Account
  • Destination: Settlement
 
 
One Time Transaction
 
API CallDescription
7Query CardCard Attributes
API CallDescription
8Create Transaction
Push
Transaction:
  • Source: Settlement
  • Destination: Card
API CallDescription
9Create Transaction
Pull
Transaction:
  • Source: Card
  • Destination: Settlement
 
 
Optionally Retrieve an Account, Update an Account, or Delete an Account
 
API CallDescription
10Retrieve Account
API CallDescription
11Update AccountType: Card
API CallDescription
12Delete Account
 
 
Optionally Retrieve Transaction Information
 
API CallDescription
13Retrieve Transaction
API CallDescription
14Retrieve Transaction
  1. Retrieve Client
  2. Create Key (optional)
  3. Query Card
  4. Create Account
  5. Create Transaction - Push
  6. Create Transaction - Pull
  7. Query Card
  8. Create Transaction - Push
  9. Create Transaction - Pull
  10. Retrieve Account
  11. Update Account
  12. Delete Account
  13. Retrieve Transaction
  14. Retrieve Transaction

Code Samples

There is no SDK because the TabaPay Web Service (API) is just a simple RESTful Web Service that uses standard HTTPS to:where the Request Data and the Response Data are formatted using standard JSON.

Therefore, you can use almost any programming language. We assume that you are an expert in the language that you have selected to use.

You can also use command line utilities such as:

If you need help in using the TabaPay Web Service (API), we recommend using one of the command line utilities first. By doing this first, it eliminates any language specific issues or uniquenesses, and since there are so many programming languages available today, we may not be an expert in (or even have used) the language that you are trying to use. Also, by doing this first, it can help eliminate networking issues such as firewalls blocking the requests and/or responses.

We do provide some simple samples in various common programming languages:

These are meant to be simple samples and are not meant for production use.

curl

A GET Request (Retrieve Client):
curl https://<FQDN>/v1/clients/<ClientID>
     -H "Authorization: Bearer <TokenValue>"
A POST Request (Query Card):
curl https://<FQDN>/v1/clients/<ClientID>/cards
     -H "Authorization: Bearer <TokenValue>"
     -H "Content-type: application/json"
     -X POST
     -d "{\"card\":{\"accountNumber\":\"9999999999999999\"}}"
These were last tested successfully using:

wget

A GET Request (Retrieve Client):
wget -qO-
     https://<FQDN>/v1/clients/<ClientID>
     --header "Authorization: Bearer <TokenValue>"
A POST Request (Query Card):
wget -qO-
     https://<FQDN>/v1/clients/<ClientID>/cards
     --header "Authorization: Bearer <TokenValue>"
     --header "Content-type: application/json"
     --post-data "{\"card\":{\"accountNumber\":\"9999999999999999\"}}"
These were last tested successfully using:

openssl s_client

A GET Request (Retrieve Client):
openssl s_client -connect <FQDN>:443

GET /v1/clients/<ClientID> HTTP/1.0
Authorization: Bearer <TokenValue>

A POST Request (Query Card):
openssl s_client -connect <FQDN>:443

POST /v1/clients/<ClientID>/cards HTTP/1.0
Authorization: Bearer <TokenValue>
Content-type: application/json
Content-length: 45

{"card":{"accountNumber":"9999999999999999"}}
These were last tested successfully using:

Java

A GET Request (Retrieve Client):
import java.io.InputStream;
import java.net.URL;

import javax.net.ssl.HttpsURLConnection;

public class Sample
{
    public static void main( String[] asArgs )
    {
        try
        {
            URL urlService = new URL( "https://<FQDN>/v1/clients/<ClientID>" );

            HttpsURLConnection connectionService =
                (HttpsURLConnection) urlService.openConnection();

            connectionService.setRequestMethod( "GET" );
            connectionService.setRequestProperty(
                "Authorization", "Bearer " + "<TokenValue>"
            );

            int iStatusCode = connectionService.getResponseCode();
            System.out.println( "TabaPay API Call, SC=" + iStatusCode );

            InputStream insResponse = iStatusCode == 200
                                    ? connectionService.getInputStream()
                                    : connectionService.getErrorStream();

            byte[] abResponse  = new byte[1024];
            int    iLengthRead = insResponse.read( abResponse );
            insResponse.close();

            System.out.println( new String( abResponse, 0, iLengthRead, "UTF-8" ) );
        }
        catch ( Throwable t )
        {
            t.printStackTrace();
        }
    }
}
A POST Request (Query Card):
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URL;

import javax.net.ssl.HttpsURLConnection;

public class Sample
{
    public static void main( String[] asArgs )
    {
        try
        {
            URL urlService = new URL( "https://<FQDN>/v1/clients/<ClientID>/cards" );

            HttpsURLConnection connectionService =
                (HttpsURLConnection) urlService.openConnection();

            connectionService.setRequestMethod( "POST" );
            connectionService.setRequestProperty(
                "Authorization", "Bearer " + "<TokenValue>"
            );
            connectionService.setRequestProperty(
                "Content-type", "application/json"
            );

            byte[] abDataRequest =
                "{\"card\":{\"accountNumber\":\"9999999999999999\"}}".getBytes( "UTF-8" );

            connectionService.setDoOutput( true );
            OutputStream outsRequest = connectionService.getOutputStream();
            outsRequest.write( abDataRequest, 0, abDataRequest.length );
            outsRequest.close();

            int iStatusCode = connectionService.getResponseCode();
            System.out.println( "TabaPay API Call, SC=" + iStatusCode );

            InputStream insResponse = iStatusCode == 200
                                    ? connectionService.getInputStream()
                                    : connectionService.getErrorStream();

            byte[] abResponse  = new byte[1024];
            int    iLengthRead = insResponse.read( abResponse );
            insResponse.close();

            System.out.println( new String( abResponse, 0, iLengthRead, "UTF-8" ) );
        }
        catch ( Throwable t )
        {
            t.printStackTrace();
        }
    }
}
These were last tested successfully using Java 1.8 on 05/30/2017 and reverified on 08/08/2017.


RSA Encryption using CryptoRSA Class in TabaPayAPIHelpers.jar:

import com.tabapay.api.helpers.security.rsa.CryptoRSA;
import com.tabapay.samples.CallTabaPay;
import com.tabapay.samples.CallTabaPay.KeyData;

public class APIHelpers
{
    public static void main( String[] asArgs )
    {
        String sCardData = "9999999999999999|202012|";                          // Card Number | Expiration Date | CVV2

        try
        {
            int iExpirationInDays = 365;

            KeyData dataKey = CallTabaPay.CreateKey( iExpirationInDays );       // You Provide

            String sEncodedEncryptedData = CryptoRSA.encryptUsingPublicKey(     // TabaPayAPIHelpers.jar
                dataKey.m_sPublicKey,                                           //   Public Key from Create Key
                sCardData                                                       //   Card Data
            );

            CallTabaPay.QueryCard( dataKey.m_sKeyID, sEncodedEncryptedData );   // You provide
        }
        catch ( Throwable t )
        {
            t.printStackTrace();
        }
    }
}

JavaScript

A GET Request (Retrieve Client):
var https = require( "https" );

var options =
{
    host:    "<FQDN>",
    port:    443,
    path:    "/v1/clients/<ClientID>",
    method:  "GET",
    headers:
    {
        "Authorization": " Bearer <TokenValue>"
    }
};

var req = https.request( options, function( res )
{
    console.log( "statusCode: ", res.statusCode );

    res.on( "data", function( d )
    {
        process.stdout.write( d );
    });
}).on( "error", function( e )
{
    console.error( e );
});

req.end();
A POST Request (Query Card):
var https = require( "https" );

var options =
{
    host:    "<FQDN>",
    port:    443,
    path:    "/v1/clients/<ClientID>/cards",
    method:  "POST",
    headers:
    {
        "Authorization": " Bearer <TokenValue>",
        "Content-type": "application/json",
        "Content-length": "45"
    }
};

var req = https.request( options, function( res )
{
    console.log( "statusCode: ", res.statusCode );

    res.on( "data", function( d )
    {
        process.stdout.write( d );
    });
}).on( "error", function( e )
{
    console.error( e );
});

req.write( '{"card":{"accountNumber":"9999999999999999"}}' );
req.end();
These were last tested successfully using NodeJS 6.10.3 on 05/31/2017.

Go

A GET Request (Retrieve Client):
package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest(
        "GET",
        "https://<FQDN>/v1/clients/<ClientID>",
        nil)
    if err != nil {
        panic(err)
    }
    req.Header.Add("Authorization", "Bearer <TokenValue>")
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    fmt.Println(string(body))
}
A POST Request (Query Card):
package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
  "strings"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest(
        "POST",
        "https://<FQDN>/v1/clients/<ClientID>/cards",
        strings.NewReader("{\"card\":{\"accountNumber\":\"9999999999999999\"}}"))
    if err != nil {
        panic(err)
    }
    req.Header.Add("Authorization", "Bearer <TokenValue>")
    req.Header.Add("Content-type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    fmt.Println(string(body))
}
These were last tested successfully using go 1.9.2 on 11/30/2017.

Python

A GET Request (Retrieve Client):
import httplib

conn = httplib.HTTPSConnection( '<FQDN>' )
conn.putrequest( 'GET', '/v1/clients/<ClientID>' )
conn.putheader( 'Authorization', 'Bearer <TokenValue>' )
conn.endheaders()
response = conn.getresponse()
print response.read()
A POST Request (Query Card):
import httplib

conn = httplib.HTTPSConnection( '<FQDN>' )
conn.putrequest( 'POST', '/v1/clients/<ClientID>/cards' )
conn.putheader( 'Authorization', 'Bearer <TokenValue>' )
conn.putheader( 'Content-type', 'application/json' )
conn.putheader( 'Content-length', '45' )
conn.endheaders()
conn.send( '{"card":{"accountNumber":"9999999999999999"}}' )
response = conn.getresponse()
print response.read()
These were tested successfully using Python 2.7.10 on 05/30/2017.

Ruby

A GET Request (Retrieve Client):
require 'net/https'

uri = URI.parse( 'https://<FQDN>/v1/clients/<ClientID>' )
http = Net::HTTP.new( uri.host, uri.port )
http.use_ssl = true
request = Net::HTTP::Get.new( uri.request_uri )
request.add_field( "Authorization", "Bearer <TokenValue>")
response = http.request( request )

puts response.body
A POST Request (Query Card):
require 'net/https'
require 'json'

uri = URI.parse( 'https://<FQDN>/v1/clients/<ClientID>/cards' )
http = Net::HTTP.new( uri.host, uri.port )
http.use_ssl = true
request = Net::HTTP::Post.new( uri.request_uri, 'Content-Type' => 'application/json' )
request.add_field( "Authorization", "Bearer <TokenValue>")
request.body = {card:{accountNumber: '9999999999999999'}}.to_json
response = http.request( request )
puts response.body
These were tested successfully using Ruby 2.0.0p648 on 05/31/2017.

PCI Helpers

These sections are still a Work in progress...

These TabaPay features are to help our Clients with PCI, but it does not remove the PCI requirements for the Client.

PCI Helper - SSO

This section is still a Work in progress... Also see the PCI Helper - SSO FAQ. The samples and examples decribed here are now running in the Sandbox Environment.


How SSO works

See some working samples on how this might work.

The samples are only samples. We can provide a generic (plain/simple) SSO HTML Web Page; but, we think that allowing you to customize it to match your WebSite (colors, layout, errors handling, etc...) would be a much better solution, however, that means you will need to provide the HTML, CSS, and JavaScript. Please see the PCI Helper - SSO FAQ for the current status of providing a customized SSO.

The Imbedded Form Sample (currently) only shows one input method:

  1. Keyboard Entry

while the Modal Dialog Box Overlay shows 3 possible input methods:

  1. Keyboard Entry
  2. KeyPad Entry
  3. Card Swipe Entry
For the KeyPad Entry and Card Swipe Entry, please contact sales@TabaPay.com. For the Keyboard Entry, this sample allows the Customer on the Customer's browser to enter the following 3 pieces of Cardholder Data:
  1. Card Account Number
  2. Expiration Date
  3. Security Code - CVV2 (optional)
A Card Token is generated that can be used in the following API Calls:In order to use this Solution, it does require the use of a modern browser, so be sure your users are using a modern browser. We have last tested this Solution successfully using:Please ensure this browser usage by your users before deciding to use this Solution.

If you are authorized to create a Customized SSO, see SSO Samples for additional details; but, you must follow the procedures exactly, no deviations, and understand the timelines, no deviations.

View Addtional Details
Hide Addtional Details
The following is meant to be only a simple sample on how this may work and is not meant for production use or imply that it is production ready.

Client Web Page

Add a Listener for the Return from TabaPay SSO

window.addEventListener( "message", pfReceivedMessage, false );

Function to handle Return from TabaPay SSO

var pfReceivedMessage = function( event )
{
  if ( event.data != "Close" )
  {
    if ( event.data.slice( 0, 7 ) == "Error: " )
    {
      // Error
    }
    else
    {
      var asData = event.data.split( "|" );
      if ( asData.length == 3 )
      {
        // asData[ 0 ] contains the Last 4
        // asData[ 1 ] contains the Expiration Date in YYYYMM Format
        // asData[ 2 ] contains the Card Token
      }
      else
      {
        // Data Error
      }
    }
  }
  else
  {
    // Close or Cancel
  }
}

JavaScript Code to load TabaPay SSO when needed

document.getElementById( "sso" ).src = "https://<FQDN>/<PageName>.html?<Unique>";

HTML to include TabaPay SSO

<div><iframe id="sso"></iframe></div>


Client BackEnd Server

Can use the Card Token in the following TabaPay API Calls:


Customization of SSO

If you are providing the HTML, CSS, and JavaScript to us:

  • HTML must be minifiable
  • CSS must be minifiable
  • JavaScript must be compilable (with no warnings or errors) with the Google Closure Compiler
  • No External JavaScript Libraries, No External JavaScript Frameworks
  • The Results will be a single HTML file
  • Any external images will be hosted from your servers
  • We will control and own the HTML, CSS, and JavaScript (please check with your legal department)

Clarifications (feedback from Early Users):

  • You will provide us with the HTML, CSS, JavaScript:
    • Formatted as for Development (leave spaces, indentation, whitespace, blank lines, etc...)
    • Leave Comments in as for Development
    • We have to understand the code you send to us, so keep it (very) simple...
  • We (TabaPay) will minify the HTML, CSS, JavaScript:
    • If there are issues, we will try to fix...
    • If we can't fix (easily), we may ask you to revise it...
  • Due to PCI, we cannot include external libraries or frameworks...
  • And again due to PCI, we have to own the code (HTML, CSS, JavaScript), so please check with your Legal Department...

Also see the Step-by-Step Example below of this process including our expectations of the expected file (or 3 files: HTML, CSS, and JavaScript) that we will be receiving from you.

Common sense (real world) facts about this customization:

  • Take advantage of this (almost) complete control of this customization and the ability for you to customize it, but:
    • Be Simple
    • Be Reasonable
    • Understand some of the Restrictions, if any
    • If we say we cannot do something, show us how to do it simply and we will take another look
    • If we say no, please accept that it can't be done or we can't do it
  • Due to time constraints, we can only do minor tweaks after the initial delivery of the HTML, CSS, and JavaScript.


Other Notes:
  • Expiration of the Card Token?
    • The Card Token will expire in 5-10 minutes.
View Step-by-Step Example
Hide Step-by-Step Example
The following is only a very simple example and is not meant for production use or imply that it is production ready. Also see the PCI Helper - SSO FAQ.

(1) My Custom SSO Web Page

It is:
  • (Very) Simple
  • Reasonable (in complexity and size)
  • Easy to understand
  • No External Libraries or Frameworks

and it is nicely formatted for a developer to read:

  • Code is Indented
  • Source is Commented

<!DOCTYPE html>
<html>
<head>
<style>
/*
 * Table Header
 * 1st Column
 */
th
{
  text-align: right;
  padding-right: 10px;
}
/*
 * Form Button(s) Row
 */
.b
{
  padding-top: 10px;
  text-align: center;
}
</style>
<script>
function fCheckCardNumber( psCardNumber )
{
  //
  // Code to Check Card Number
  //
  if ( psCardNumber.length < 13 || psCardNumber.length > 19 )
  {
    return false;
  }
  //
  // More Checks?
  //   Card Range?
  //   All Digits?
  //   Luhn Checksum?
  //

  //
  // If you want use TabaPay's Common Utils,
  //   (1) remove the above check
  //   (2) and add the following if statement
  //
  // if ( ! TabaPayCommonUtils.fCheckCardNumber( psCardNumber ) )
  // {
  //    return false;
  // }
  //

  return true;
}
function fCheckExpirationDate( psExpirationDate )
{
  //
  // Code to Check Expiration Date
  //
  if ( psExpirationDate.length != 5 || psExpirationDate.slice( 2, 3 ) != "/" )
  {
    return false;
  }
  //
  // More Checks?
  //   Check Month and Year
  //

  //
  // If you want use TabaPay's Common Utils,
  //   (1) remove the above check
  //   (2) and add the following if statement
  //
  // if ( ! TabaPayCommonUtils.fCheckCardExpirationDate( psExpirationDate ) )
  // {
  //    return false;
  // }

  return true;
}
function fCheckSecurityCode( psSecurityCode )
{
  //
  // Code to Check Security Code
  //
  if ( psSecurityCode.length < 3 || psSecurityCode.length > 4 )
  {
    return false;
  }
  //
  // More Checks?
  //   Check Number
  //

  //
  // If you want use TabaPay's Common Utils,
  //   (1) remove the above check
  //   (2) and add the following if statement
  //
  // // Currently this only does minimal checking
  // // If you want a more thourogh Security Code check,
  // //   feel free to replace this with your own function
  //
  // if ( ! TabaPayCommonUtils.fCheckSecurityCode( psSecurityCode ) )
  // {
  //    return false;
  // }
  //

  return true;
}
function fClear()
{
  document.getElementById("c").value="";
  document.getElementById("e").value="";
  document.getElementById("s").value="";
}
function fSubmit()
{
  var sCardNumber     = document.getElementById("c").value.trim();
  var sExpirationDate = document.getElementById("e").value.trim();
  var sSecurityCode   = document.getElementById("s").value.trim();
  //
  // Check Card Number
  //
  if ( sCardNumber.length == 0 )
  {
    alert( "Missing Card Number" );
    return;
  }
  if ( ! fCheckCardNumber( sCardNumber ) )
  {
    alert( "Bad Card Number" );
    return;
  }
  //
  // Check Expiration Date
  //
  if ( sExpirationDate.length == 0 )
  {
    alert( "Missing Expiration Date" );
    return;
  }
  if ( ! fCheckExpirationDate( sExpirationDate ) )
  {
    alert( "Bad Expiration Date" );
    return;
  }
  //
  // Check Security Code (optional)
  //
  if ( sSecurityCode.length > 0 )
  {
    if ( ! fCheckSecurityCode( sSecurityCode ) )
    {
      alert( "Bad Security Code" );
      return;
    }
  }
  //
  // All Checks ok
  //

  // TabaPay will add code here
  //   temporarily use an alert to display the values
  alert( sCardNumber + "," + sExpirationDate + "," + sSecurityCode );
}
function fCancel()
{
  // TabaPay will add code here
  //   temporarily use an alert to indicate Cancel
  alert( "Cancelled" );
}
</script>
</head>
<body>
<form>
  <table>
    <tr>
      <th>Card Number</th>
      <td><input id="c" type="password" placeholder="13-19 digits"></td>
    </tr>
    <tr>
      <th>Expiration Date</th>
      <td><input id="e" placeholder="MM/YY Format"></td>
    </tr>
    <tr>
      <th>Security Code</th>
      <td><input id="s" placeholder="3-4 digits"></td>
    </tr>
    <tr>
      <td class="b" colspan="2">
        <input type="button" value="Clear" onclick="fClear()"/>
        &nbsp;
        <input type="button" value="Use Card Data" onclick="fSubmit()"/>
      </td>
    </tr>
    <tr>
      <td class="b" colspan="2"><input type="button" value="Cancel" onclick="fCancel()"/></td>
    </tr>
  </table>
</form>
</body>
</html>

The use of Alerts in the above example was only used to simplify the example and not clutter the JavaScript Code in the example. We recommend that you change the usage of Alerts to something more appropriate that matches your WebSite. Again, the above example is not meant for production use or imply that it is production ready.

(2) Please QA the My Custom SSO Web Page before (3)

(2a) TabaPay QA will only do a cursory check

(2b) There will be a very limited number of back and forth

(2c) It will be your responsibility for your Custom SSO Web Page

(3) Submit My Custom SSO Web Page to TabaPay

(4) Wait for TabaPay to complete the modifications to the Custom SSO Web Page

(5) TabaPay will make your Custom SSO Web Page available

(6) Test using TabaPay's Test your SSO Web Page

Goto the See some working samples link above

Use the filename: MyCustomSSOExample
and be sure to set the desired width and height
also this Example has an image that is hosted externally

(7) Include in your Web Page

Goto the View Additional Details link above on how to do this...

PCI Helper - RSA

This section is still a Work in progress... Also see the PCI Helper - RSA FAQ.


How to use RSA

Due to the number of computer languages available today, we will be using OpenSSL, the well-known and widely used cryptography library, to show how to use RSA to create the value for the data parameter in the following TabaPay API Calls:

The data contains:

Here are the steps in creating the data parameter for the TabaPay API Calls:

  1. Create a Key

    • Use the TabaPay API Call: Create Key
      • The returned format of the Public Key depends upon what language you are using and what libraries (in the language) you are using, however:
        • RAW Format (consisting of exponent and modulus) can be easily converted to ASN.1 Format
        • ASN.1 Format can be easily converted to RAW Format (consisting of exponent and modulus)
    • OpenSSL, for this example, will be using ASN.1 Format
  2. Save the keyID

  3. Convert the key (in ASN.1 Format) from Base64 URL-Safe to regular Base64 Encoding

  4. Create a file containing the Public Key, we will use PEM Format, but we could have also use DER Format instead:

    • Use an editor, like vi, and create a public.key
    • First Line contains: -----BEGIN PUBLIC KEY-----
    • Next Line contains the Base64 (not URL-Safe) Encoded Key: MIIBI...AQAB
    • Last Line contains: -----END PUBLIC KEY-----
  5. Create a file containing the Card Data, separated by "|" (pipe symbol):

    • Card Account Number
    • Card Expiration Date
    • Card Security Code

    Example is: 9400100999999993|209912|123

  6. Use OpenSSL to encrypt the Card Data, RSA with Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding:

    openssl pkeyutl -in card.data -out encrypted.data -inkey public.key -keyform PEM -pubin -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

  7. Convert the Encrypted Data in the file to Base64 URL-Safe Encoding

  8. You can now use:
    • keyID from (2)
    • data, Base64 URL-Safe Encoding, from (7)

    in the following TabaPay API Calls:

Make sure the version of OpenSSL that you are using is at least 1.0.2k.

If you are having problems, hopefully this example can help you in the language that you are using... Some languages, such as:

use the OpenSSL library.

General FAQ

Need help?
Contact us at support@TabaPay.com and someone from our support team will get back to you as quickly as possible.

Why is there no SDK?
The API is just a simple RESTful Web Service that uses standard HTTPS to:
  • connect
  • send request
  • receive response
  • disconnect
where the Request Data and the Response Data are formatted using standard JSON.

Therefore, you can use almost any programming language; however, there are so many programming languages available today, we may not be an expert in (or even have used) the language that you are trying to use. We assume that you are an expert in the language that you have selected to use.


Having connection issues?
Try using one of the command line utilities first. Usually it can help diagnose networking issues such as firewall configurations, IP whitelisting, etc... Also it helps in eliminating any language specific issues or uniquenesses, and since there are so many programming languages available today, we may not be an expert in (or even have used) the language that you are trying to use.

Curious? What do we use?
For all Production Applications (and Tools), we are currently using Go and we still have one part using Java.

We use Go for all our Testing (QA) Tools.

For Reports, the Accounting Department is currently using Python.


ISO
Unfortunately this acronym stands for:Hopefully the context where it is being used will make the definition of the acronym obvious.

Data FAQ

Is there a JSON Schema?
We allow additional JSON pairs (NVPs) to be added in a request (though we don't recommend this) and we may return back additional JSON pairs (NVPs) in a response (optional JSON pairs (NVPs) that you may not be using but another client may be using). We also allow JSON pairs (NVPs) to be sent in a request in any order and we may return back JSON pairs (NVPs) in a response in any order.

Be sure you can handle "freeform" JSON responses.


What is the type of a Data Value? Is it a String, an Integer, an Amount, a Boolean, or what?
We treat all Data Values initially as Strings. We then apply a Value Restriction to the String. So for example:
  • an Integer, we look for a string with only digits
  • an Amount, for currency number 840, USD, we look for a string with only digits and a single decimal point with two decimal digits but no commas nor currency sign
  • a Boolean, we look for a string with the value of either true or false
Therefore, we should be able to parse almost all JSON Requests without having to just return a generic error (parse error).

How to specify an Amount Value?
In order to handle international currencies, an Amount is a String. International currencies:
  • use either a point or a comma as their decimal mark and
  • might have a maximum of 0, 1, 2, 3, or 4 decimal places.
So for example, for those using currency number 840, USD, an Amount must have a decimal point (.) with 2 decimal digits and no commas (,) nor currency sign ($). Examples:
1000.20
Valid
1.20
Valid
0.20
Valid
.20
Valid

.4
Invalid, 2 decimal digits are required
1.4
Invalid, 2 decimal digits are required
1,000.21
Invalid, comma not needed
$10.21
Invalid, dollar sign not needed

Is there a size limitation to String Values?
Unless specified in the Value column, String Values can be of any reasonable size. However there is a limitation to the total number of bytes in your request. And remember, some Unicode characters, especially international characters, are more than one byte.

Are null Values valid?
JSON Values that are null are accepted, according to the JSON Specifications, but it is preferred that you just leave out the pair (NVP):

Works:

{
  "NameA": "Test",
  "NameB": null,
  "NameC": "Test"
}
Preferred:
{
  "NameA": "Test",
  "NameC": "Test"
}

What valid characters can be used for fields such as Reference IDs, Memo, Names (first and last), etc...?
The API can accept any UTF-8 character; however, to be safe for other processes that may be using this data, we recommend the use of only the Base64 URL-Safe Character Set. We will also explicitly restrict the use of these characters:
●     ,
Comma (used in csv files)
●     "
Double Quotes (used in csv files)
●     ~
Tilde
●     ^
Caret

We do recommend the use of only the Base64 URL-Safe Character Set.
Base64 Encoding
Binary Data and some Strings, that are beyond Alphanumeric, should be encoded in Base64 with no padding and using the URL-Safe Character Set:
●   A-Z
Uppercase alphabetic characters
●   a-z
Lowercase alphabetic characters
●   0-9
Digits
●   -
Minus Sign
●   _
Underscore

Format of the JSON Request and Response Data?
We required that all whitespaces are removed from the JSON Request (pack your JSON Request). We will also return a JSON Response in a packed format where all whitespaces are removed.

Nice for human:

{
  "NameA": "Test",
  "NameB": 1
}
But not so much for our Application and also it clutters our logs, so preferably:
{"NameA":"Test","NameB":1}

Errors FAQ

HTTP Status Codes?
See Status Codes for a list of HTTP Status Codes that might be returned.

A 400 Series Error is usually something that you can fix by changing something in your request. A 500 Series Error is usually something that you need to contact us (support@TabaPay.com) to look at. If we determine that a 500 Series Error can be fixed by you, we will try to change this error situation to a 400 Series Error in a future code release.

PCI does require us to be cryptic in the Error Messages that we return back; but for certain 400 Series Errors, we may return back something in the Error Message (EM) field of the JSON Response that indicates what might be wrong.


You should never get a HTTP Status Code of 400 on Production
If you are getting a HTTP Status Code of 400 on the Production Environment, that usually means you are not handling these errors correctly on your end. We strongly recommend completing the Production Certification Test in its entirety, specifically the portion where we recommend integrating your application with our API calls.

Also, please see the Coding FAQ.


Use of HTTP Status Code 207?
You might get HTTP Status Code 207, when there is an Error while processing your Transaction due to some Upstream Process.

Everything on our end processed successfully:

  • Your request passed all our checks
  • Configuration is available to process your request
  • A record is created for your request (Transaction)
But an Error occurred in some Upstream Processing.


Customer Facing Error Messages?
We are a Server-to-Server Web Services (API) and we are not Customer Facing, so:
  • We do not provide User Friendly Error Messages.
  • We do not provide Error Details (because of PCI).
  • We do not recommend showing your Customers our Error Messages or Error Codes.
Your Application should catch as many errors as possible before sending the Request to us. You should not use us (API Request) to check the Customer's Data Errors. Therefore, if your Application is catching the obvious errors and you are not exposing Error Details from your Application or from our API, then there shouldn't be a lot of unique Error Messages back to the Customer.

Also, please see the Coding FAQ.

Coding FAQ

As mentioned elsewhere multiple times:

We may not be an expert in (or even have used) the language that you are trying to use. We assume that you are an expert in the language that you have selected to use.

With that said, here are some questions that we have encountered that might be helpful to you:


My Program doesn't work?
Please provide the full Request and Response. If there was an error, the full error message (exception) and if available any stack trace. The more details, the better we can help you, and the faster we can help you.

If you contact TabaPay support, please send your Request and Response:

Request should include:

  • Date and Time of the Request and Time Zone (we have many Clients in many different parts of the world)
  • URL
  • Request Method (Get, Post, Put, or Delete)
  • Request Data (JSON), if any

Response should include:

  • HTTP Status Code
  • Response Data, if any
    • (usually) JSON
    • (but can be) HTML
  • Exception and Stack Trace, if any


SC=406
We have a WAF, Web Applicaiton Firewall, in front of all internet facing systems. So if our WAF detects something funny, such as something in the OWASP Top 10, your request will get rejected with SC=406.

SC=400
If you are getting a HTTP Status Code of 400 on the Production Environment, that usually means you are not handling these errors correctly on your end. We strongly recommend completing the Production Certification Test in its entirety, specifically the portion where we recommend integrating your application with our API calls.

Why you should never see SC=400 in Production?
All errors with a HTTP Status Code of 400 should have been caught before the API request is sent to us. We shouldn't have to return back a HTTP Status Code of 400. A HTTP Status Code of 400 means that something in your request is bad: Bad Request. You should not use us (API Request) to check for Customer entered data errors.

For example:

  • Card Account Number
  • Card Expiration Date
  • Amount
All of the above examples should have been caught on the client side (Customer's Device). It shouldn't need to travel from:
  1. the Customer's Device
  2. to your Servers
  3. to our Servers
  4. negative response (400) back to your Servers
  5. and then finally some error message back to the Customer's Device
just to inform the Customer that the Customer entered a bad:
  • Card Account Number
  • or Card Expiration Date
  • or Amount
We believe the proper way of handling errors is:
  • Immediate
  • Interactive
  • Responsive
and that means if the Customer is on a Web Browser, then there should be:
  • JavaScript code
to catch obvious errors; and if the Customer is on a Mobile Device, then there should be:
  • Swift (or Objective-C) code on iOS
  • or Java code on Android
to catch obvious errors.

Even if an error gets past the code on the Customer's Device and goes up to your Servers, your BackEnd Code on your Servers should also catch these obvious errors. That is two layers of code that should have caught the error, so that is why we say:

We should never have to return back a SC=400 in Production...

That is why you should test on the Sandbox Environment and pass the Certification Test completely.

Sandbox Environment FAQ

How quickly can we do a change (configuration) on the Sandbox Environment?
We are PCI Level 1 and SOC1 Type 1 and SOC2 Type 2 Compliant. So, what does that mean? We are procedure and process controlled.

Some companies require us to be PCI Level 1 and SOC Compliant (SOC1 Type 2 and SOC2 Type 2). And then some of those same companies still expect us to do things for them immediately (and even on Production). Here is a real life example that recently occurred:

  • A Client demanded to change their limit on a weekend night immediately
  • After changing their Limit, the same Client later demanded to change their limit again and again on a weekend night immediately
  • After changing their Limit again, we see they never reached the Limits they demanded, in fact, they never even reached their original Limit

Not everything is or can be an emergency...

Schedule for Sandbox changes:

  1. Have your request by Friday morning
  2. Changes will be implemented by end of day Monday (or Tuesday, if Monday is a Holiday)
So please plan ahead... This includes boarding new clients, changing limits, whitelisting IPs, etc...

Are there Test Card Numbers to use in the Sandbox Environment?
PCI requires us and you to use Test Card Numbers when testing. You should never use a real Card Number in the Sandbox Environment. See Samples - Test Cards where we provide various Test Card Numbers...

How to generate an error in the Sandbox Environment?
For Create Transaction, the Amount is used to trigger various errors while processing the Create Transaction request in the Sandbox Environment (Accel uses a 3-digit Network Response Code):
AmountResponseActual ResponseError Description
Status CodeNetwork Response CodeResource StatusNetwork Response CodeResource Status
0.01
11.00
200ZZ (or 999)ERRORZZ (or 999)ERRORTransaction Error
0.02
12.00
207UNKNOWNUNKNOWNTransaction Processing Failed
0.03
13.00
20000 (or 000)COMPLETED00 (or 000)COMPLETEDTransaction Successful, but upstream processing was delayed for 30 seconds
0.04
14.00
207UNKNOWN00 (or 000)COMPLETEDTransaction Successful, but upstream processing was delayed for 40 seconds
For Delete Transaction, the Create Transaction Amount is used to trigger various errors while processing the Delete Transaction request in the Sandbox Environment (Accel uses a 3-digit Network Response Code):
AmountCreate Transaction ResponseDelete Transaction ResponseError Description
Status CodeNetwork Response CodeResource StatusStatus CodeReversal Network Response CodeResource Status
0.0720000 (or 000)COMPLETED200ZZ (or 999)UNKNOWNReversal Request failed
0.0820000 (or 000)COMPLETED20021UNKNOWNReversal Request failed, the Reversal was too late.
Not available when routed to any Regional Network: Currently only STAR and Accel.
For AVS, Query Card, the Zip Code, Address, and Security Code are used to trigger various conditions while processing an AVS request in the Sandbox Environment:
RequestResponseComments
Zip CodeAddressSecurity CodeResponse TextNetwork Response CodeCode
AVS Results
Code
Security Code Results
Any*Any*NoneNOT DECLINED85YZip Code and Address were matched
Any*NoneNoneNOT DECLINED85ZZip Code was matched
Any*Any or NoneAny*DEPENDSDEPENDSDEPENDSMDepends upon if Zip Code and Address matches or not, but Security Code was matched
Any*Any or None999DECLINE05DEPENDSNDepends upon if Zip Code and Address matches or not, but Security Code was not matched
99990Any or NoneAny or NoneDECLINE05UInformation not available
99991Any or NoneAny or NoneDECLINE05RAVS unavailable, retry
99992Any*NoneDECLINE05AZip Code was not matched, but Address was matched
99992None or 999 BadNoneDECLINE05NZip Code and Address were not matched
99993Any or NoneAny or NoneDEPENDSDEPENDSDEPENDSDEPENDSAVS Request delayed for 30 seconds
99994Any or NoneAny or NoneUNKNOWNUNKNOWNUNKNOWNUNKNOWNAVS Request timed out
  • Any* - Any Zip Code that is not explicitly used to trigger a condition (99990-99994)
  • Any* - Any Address that is not explicitly used to trigger a condition (999...) - Address only checks the Street Number
  • Any* - Any Security Code that is not explicitly used to trigger a condition (999)

How to generate a RTP error in the Sandbox Environment?
For Create Transaction, the Account Number for RTP is used to trigger various errors while processing the Create Transaction request in the Sandbox Environment (RTP uses a 3-character Network Response Code):
Account NumberCreate Transaction ResponseError Description
Status CodeNetwork Response CodeResource Status
100000000...111111111200000COMPLETEDN/A
111111112200P03ERRORInvalid Account
111111113200P11ERRORSender not authorized
111111114200P07ERRORParticipant blocked
111111115200P02ERRORInvalid Account
111111116200P11ERRORTransaction forbidden on this account
111111117200P23ERRORAmount received is not the amount agreed or expected
111111118200P23ERRORAmount exceeds limits
111111120200P21ERRORIncorrect routing number
111111121200P14ERRORParticipant deceased

Is the Sandbox Environment PCI Compliant?
No.

You should be using Test Card Numbers when testing in the Sandbox Environment. You should never use a real Card Number in the Sandbox Environment. See Samples - Test Cards where we provide various Test Card Numbers...


What is the Sandbox Environment SLA?
There should be no expectations on the Sandbox Environment.

Running Performance Test?
You can not run a Performance Test in the Sandbox Environment. The Sandbox Environment is a very small fraction of the Production Environment. It would be a waste of everyone's resources to do a Preformance Test using the Sandbox Environment.

What happens if someone decides to run a Performance Test?
Your IPs will be blacklisted.

UAT Environment FAQ

UAT Environment?

What is the UAT Environment SLA?
There should be no expectations on the UAT Environment.

Running Performance Test?
You can not run a Performance Test in the UAT Environment. The UAT Environment is a very small fraction of the Production Environment. It would be a waste of everyone's resources to do a Preformance Test using the UAT Environment.

What happens if someone decides to run a Performance Test?
Your IPs will be blacklisted.

Production Environment FAQ

What is the maintenance window for the Production Environment?
There should be no outage during normal maintenance. We have activity 24x7x365 and the low points seem to be around mid-week.

How quickly can we do a change (configuration) on the Production Environment?
We are PCI Level 1 and SOC1 Type 1 and SOC2 Type 2 Compliant. So, what does that mean? We are procedure and process controlled.

Some companies require us to be PCI Level 1 and SOC Compliant (SOC1 Type 1 and SOC2 Type 2). And then some of those same companies still expect us to do things for them immediately (and on Production). Here is a real life example that recently occurred:

  • A Client demanded to change their limit on a weekend night immediately
  • After changing their Limit, the same Client later demanded to change their limit again and again on a weekend night immediately
  • After changing their Limit again, we see they never reached the Limits they demanded, in fact, they never even reached their original Limit

Not everything is or can be an emergency...

Schedule for Production changes:

  1. Have your request by Friday morning
  2. Changes will be implemented by end of day Monday (or Tuesday, if Monday is a Holiday)
So please plan ahead... This includes boarding new clients, changing limits, whitelisting IPs, etc...

Why? (in regards to the above question)
Here is a quote from one of our Clients about their PCI Environment (not ours but theirs):

Our IT department frowns upon rapid-fire changes to the PCI environment.

So I hope everyone understands the restrictions and constraints of being in a PCI Environment.

Funny, we previously have used the same word: "frown" when a Client asks us to do something outside of our normal policies and procedures.


Ready to go into Production?
In order to go into Production, we need the following things to be completed:
  1. PCI
  2. Certification Test on Sandbox
    • Just run your normal QA Tests against your Application connected to our backend (API)
    • And run various Error Conditions/Scenarios, see the Certification Test document from TabaPay Support

  3. TabaPay Boarding Sheet
    • Your Support Contact Information
    • Your Financial (Accounting) Information

Certification Test?
  • We want you to run your full QA tests on your Application that is connected to our backend (API).
  • We want to see the different types of requests that you may be sending us.
  • We can provide feedback on what we are seeing in your requests.
  • We want to catch issues during this testing versus on Production.
  • We can catch problems, here are some of the real issues we have seen before we revised our Certification Test:
    • Security Code was misspelled, so they (CVV2s) showed up in the clear in our logs which exposes us (PCI) and your customer.
    • Amounts were incorrectly formatted, so some requests were failing (.4) and others were not (0.40).
That is why we want you to run your normal QA Tests on your Application that is connected to our backend (API) in the Sandbox Environment.

You should never get a HTTP Status Code of 400 on Production
If you are getting a HTTP Status Code of 400 on the Production Environment, that usually means you are not handling these errors correctly on your end. We strongly recommend completing the Production Certification Test in its entirety, specifically the portion where we recommend integrating your application with our API calls.

Also, please see the Coding FAQ.


Locking your Client?
If the Bank and/or TabaPay detect something funny happening:
  • in your API Requests, or
  • with your Limits, or
  • with your Settlement Account
your Client may be LOCKed. We will try to contact you first, but the Bank may not.

If your Client is LOCKed, please contact TabaPay support.


Disabling your IP Address?
If TabaPay detects something funny coming from one of your IP Addresses that you requested to be whitelisted, we may have to remove that IP Address. We have WAFs and IDS/IPSs protecting all Internet Facing Systems. We shouldn't be receiving any kind of probes from your systems, so all probes will be detected as a hack attempt and will be shutdown.

If we do remove an IP Address, you have to resubmit a request to reenable the IP Address, so please contact TabaPay support.


A reason for disabling?
“Insanity is doing the same thing, over and over again, but expecting different results.”

PCI / SOC FAQ

What is PCI DSS?
PCI DSS stands for Payment Card Industry Data Security Standard. Also see PCI Security Standards Council.

What is SOC?
SOC stands for System and Organization Controls.

Are we PCI Compliant? SOC1 and SOC2 Certified?
TabaPay is a PCI Level 1 Service Provider.

TabaPay is SOC 1 Type II and SOC 2 Type II Certified.


Is the Sandbox and UAT Environments PCI Compliant?
No.

You should be using Test Card Numbers when testing in the Sandbox and UAT Environments. You should never use a real Card Number in the Sandbox and UAT Environments. See Samples - Test Cards where we provide various Test Card Numbers...


SSL/TLS Configuration?
We use Qualys SSL Server Test to check our SSL/TLS configuration on all internet facing systems:

Our configured Protocols and Cipher Suites:

TLS 1.3 is now available on all Environments.

We also removed some WEAK TLS 1.2 Cipher Suites:

We configure our Servers to the Recommended Cipher Suites as recommended by RFC 7525 and Mozilla Server Side TLS.


WAF, Web Application Firewall, protection?
We have a WAF, Web Applicaiton Firewall, in front of all internet facing systems. So if our WAF detects something funny, such as something in the OWASP Top 10, your request will get rejected with SC=406.

PCI Helper - SSO FAQ

Is it possible to customize the SSO?
We have temporarily suspended the fully Customization of the SSO. We will provide a generic SSO that you can modify only a few things like:
  • Font
  • Color
You can view the generic SSO by using the filename of SSOGeneric in the Test your SSO Web Page.

If you are authorized to create a Customized SSO, see SSO FAQ for additional details; but, you must follow the procedures exactly, no deviations, and understand the timelines, no deviations.


What is the process of submitting a customized SSO?
See PCI Helper - SSO in Samples... But to summarize:
  1. You need to create a fully working HTML Page that meets our requirements (see PCI Helper - SSO in Samples...)
    • Our QA will only do a cursory check and will reject any HTML Page that doesn't do the basic error checking:
      • Check Card Number
      • Check Expiration Date
      • Check Security Code
    • Going to your Servers or even going to our Servers to do basic error checking, in our belief, is not the correct way to handle this, see the Coding FAQ.
    • We prefer not to have to do a lot of back and forth, so please QA your HTML Page before submitting to us
      • You can contact us if you want our QA to help QA your HTML
    • Remember that this is your HTML Page that you are presenting to your Customers.
  2. Once our QA ok your HTML, your HTML Page is sent to our Build/Operations Department:
    • Add the TabaPay specific code
    • Move HTML Page to Sandbox Environment
    • Again, our QA will do a cursory check
  3. At this point you should QA (Test) your HTML Page and you can call the TabaPay API.

How long this takes will depend upon when we receive a working HTML Page. So how long is up to you. Deviating from our requirements will only cause delays.


Customization timeline and availability?
The reason why we will suspend the fully Customization of the SSO is Client Expectations... and our Expectations for the submitted SSO Web Page. Unfortunately there is a mismatch, so trying to clarify this mismatch, here are some points to consider beforehand to avoid the frustration by all sides with the process:
  • Normally we only do a build of a Client's SSO Web Page on the weekends and have it available by End-of-Day Monday, Tuesday if Monday is a holiday
  • We expect the Client to QA their own SSO Web Page
  • We will reject a Client's SSO Web Page if we find a problem
  • Like previously mention elsewhere, we do not want a lot of back and forth with the SSO Web Page
  • We hope this would be the sequence of events:
    1. The Client reads the Developers WebSite to understand the SSO Web Page
    2. The Client can ask support for any clarification
    3. The Client develops their SSO Web Page
    4. The Client tests (QA) their SSO Web Page
    5. When the Client completes their testing, the Client submits their SSO Web Page
    6. TabaPay only does a cursory QA of the Client's SSO Web Page
    7. If TabaPay QA finds a problem with the Client's SSO Web Page, it will be rejected
    8. TabaPay builds the SSO Web Page
    9. TabaPay makes the SSO Web Page available by End-of-Day Monday (Tuesday if Monday is a holiday)
    10. The Clients can now test the completed SSO Web Page
    We only expect a sequential flow and we do not expect a loop in this flow. If your SSO Web Page was rejected, it has to restart the process over again.

Please Keep it SIMPLE, the more complex your SSO Web Page is, the harder it is for us to Add our Changes and Test our Changes. And having an abnormal SSO Web Page that is hard to Test will eventually be unTested and we will have to leave it to you to test the changes. So in the future, if you do have a difficult SSO Web Page, you will need to tell us how to test it or even give us tools to test it.

Just think, how many different SSO Web Pages we get, and each so very different, so far, none are similar. Just think how hard it is for us to try to change that code and then try to test it... Just think... Be in our shoes... So this is one reason why we will suspend the fully Customization of the SSO.


Compiling with the Google Closure Compiler?
We use the following options:
          --compilation_level ADVANCED_OPTIMIZATIONS
We use Advanced Optimizations for reasons other than for size. Size is just a nice side benefit.

Just like the HTML and CSS, we actually do not minify the HTML and CSS, but we pack them.

PCI Helper - RSA FAQ

RSA?
RSA is the most widely used asymmetric algorithm.

Using Encrypted Data in the TabaPay API Calls don't seem to be working?
Make sure you are using RSA with the Transformation of RSA/ECB/OAEPWithSHA-256AndMGF1Padding and the language you are using supports the correct (common usage) implementation of that transform.

Receiving a SC=500?
If you pass in an Encrypted Data that was encrypted incorrectly, you will get a SC=500.

What languages (and libraries, if any) work (or tested)?
We have first hand knowledge that the following languages (and libraries, if any) works:
  • Java with a slight tweak using the built in RSA encryption
  • Go using the built in RSA encryption
  • JavaScript on a browser using the Web Cryptography API which is available in (all) modern browsers
and we have heard others using the following languages (and libraries, if any):
  • .NET
and other applications (or libraries):

Is there an example, a working example?
See PCI Helper - RSA in Samples...

Why only 2 active Keys?
The key you are using is just a Public Key.

Also, previously, we had Clients who were creating multiple Keys per Day and expiring the Keys in a Year. So we were holding a lot of active Keys for some Clients and the assumption is that most, if not all, of the Keys were no longer in use, see the Anti-Pattern FAQ


For Security Reasons, we want to have more than 2 active Keys?
The key you are using is just a Public Key.

TabaPay doesn't understand Mobile Payments, we need more than 2 active Keys?
The key you are using is just a Public Key.

Also, we have engineers with at least 5 years of mobile app development in the past for both iOS and Android, and they have built PCI Level 1 Compliant financial mobile apps.


Since we can only have 2 active Keys, can the Key expire in more than 1 year?
No, PCI.

3D Secure FAQ

If you are using Cardinal, this is how to use TabaPay’s 3D Secure API with Cardinal:
To help the Issuing Bank perform risk-based authentication, Device Data Collection must be executed prior to calling TabaPay's 3D Secure Lookup API. Failing to complete this step may result in the transaction being downgraded to 1.0, a less-secure version of 3DS.

While not required, including the Browser/Device data is strongly recommended. Doing so ensures the transaction will still be of 3DS 2.0, even if the Device Data Collection fails. The Device Data Collection may be done through the (Cardinal recommended) Songbird.js library or POSTing to the DDU returned in TabaPay’s 3D Secure Initialize.

Option 1: Cardinal Cruise Hybrid

The Cardinal Cruise Hybrid utilizes the Songbird.js library. Below are URLs a client can use to test various environments. Each build of Songbird is directly tied to an environment. To change environments simply edit the URL you are using.

     Production:     https://songbird.cardinalcommerce.com/edge/v1/songbird.js
     Staging:        https://songbirdstag.cardinalcommerce.com/edge/v1/songbird.js

Cardinal setup:

Setting up a transaction flow includes the following:

  1. Send a jwt object to Cardinal via Cardinal.setup(), which in turn...
  2. Triggers a payments.setupComplete() event:
<script src="https://songbirdstag.cardinalcommerce.com/edge/v1/songbird.js"></script>
Cardinal.setup("init", {
jwt: “{{Please insert JWT string here}}”
});
Cardinal.on('payments.setupComplete', function (setupCompleteData) {
// handle set up complete event
});

Option 2: POSTing to the Device Data Collection URL

If you do not want to include a 3rd party library, POST the jwt object to the Device Data Collection URL that was returned in the TabaPay's 3D Secure Initialize response:

<iframe name="collectionFrame" height="10" width="10"
           style="visibility: hidden; position: absolute; top: -1000px; left: -1000px;">
</iframe>
<form id="collectionForm" target='collectionFrame' name="devicedata"
    method="POST"
    action="https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect">
<!-- POST Parameters: is the JWT
  which is the Authentication JWT with the ReferenceId
  from the BIN Intelligence API Response -->
<input type="hidden" name="JWT" value="…" />
</form>
<script>window.onload = function () {
  // Auto submit form on page load
  document.getElementById('collectionForm').submit();
}
</script>

Google Pay FAQ

Our Google Pay Processor Page may help answer additional integration questions.


How do I support Google Pay as a merchant?
  1. You must register as a Google Pay merchant.
    • The gatewayMerchantId you register for at Google for Google Pay must be "G" with your 6-digit clientID (and if applicable 4-8 digit subclientID) appended.
    • For example:

      • A merchant with a 6-digit clientID 123456 who wants to register for Google Pay using their subClient 0001, will have a gatewayMerchantId G1234560001
      • A merchant with a 6-digit clientID 123456 who wants to register for Google Pay will have a gatewayMerchantId G123456

  2. You must use "tabapay" (case-sensitive) as your gatewayId.

What authMethod should I use for Google Pay?
The merchant can choose to support PAN_ONLY and/or CRYPTOGRAM_3DS. While the merchant can choose their authMethod, TabaPay strongly encourages the sole use of authMethod CRYPTOGRAM_3DS to mitigate fraud.

Can I decrypt my own Google Pay PaymentMethodToken?
If a merchant's PCI-compliance allows them to handle real card numbers, the merchant may decrypt the PaymentMethodToken that is produced from a Google Pay transaction.

If the authMethod is CRYPTOGRAM_3DS, then the PaymentMethodToken will be mapped to TabaPay's card.mobilePay fields. See the mapping below:
Google Pay PaymentMethodTokenTabaPay card.mobilePay
panaccountNumber
expirationMonth
expirationYear
expirationDate
YYYYMM
cryptogramcryptogram
eciIndicator (optional)eciIndicator (optional)

The network of the card used (Visa, MasterCard, etc.) is mapped to the network in the card.mobilePay. The type of card (debit, credit, prepaid, etc.) is mapped to the type in card.mobilePay.

If the authMethod is PAN_ONLY, then the Google Pay PaymentMethodToken will be mapped to TabaPay's card.accountNumber and card.expirationDate fields.
Google Pay PaymentMethodTokenTabaPay card
panaccountNumber
expirationMonth
expirationYear
expirationDate
YYYYMM

If the merchant's PCI-compliance does not allow card-handling then the merchant will rely entirely on TabaPay to decrypt the PaymentMethodToken.


How do I use a Google Pay PaymentMethodToken for Create Transaction?
  1. Use the card.device object
  2. In the card.device:
    card.device fieldValueNotes
    id"GooglePay|GooglePayMerchantID"GooglePay is a static value
    GooglePayMerchantID is the Google Pay merchantId you registered with Google
    blobunaltered, URL-safe base64 encoded, fully encrypted Google Pay PaymentMethodTokenNo padding or spaces in your blob, remove any trailing = before sending the request

  3. Fill in the remaining required information for Create Transaction.

How do I test Google Pay for Create Transaction?

You can test in our Sandbox today if you are enabled by our support and operations teams. Ensure any PaymentMethodTokens you send are produced in the ENVIRONMENT_TEST.

If you are enabled to test Google Pay in Sandbox, but are not a registered (and approved) Google Pay merchant, use GooglePayVisa or GooglePayMasterCard piped with (|) the Google Pay merchantId you will register (or have registered and waiting for approval) as the id in the card.device object. See examples below:

  • GooglePayVisa|GooglePayMerchantId
  • GooglePayMasterCard|GooglePayMerchantId

Refer to the above FAQ: How do I support Google Pay as a merchant? for formatting your Google Pay merchantId.


What does a TabaPay response contain when using Google Pay in Create Transaction?
The responses from Google Pay will stay consistent with the current Create Transaction responses.

How do I create the card.device.blob?
  1. Take the UNALTERED, encrypted PaymentMethodToken:
    {"signature":"MEUCIHDD0DQ9XYJrerxeI0LpCQyFmqFqpJgHeeLqJDhF0z8TAiEA20LF0JUwEmE1dz2BFUgii3NFHzXDDmgsvBTHcdLVZ30\u003d","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEr6dAac0eKNSjPE4er6DsMA4oTaoUXMERhL+7OOISIKhvo8K5OVrIuWfvKHYE2DNAmZkHSwitRs49gMHs5Q7aeA\\u003d\\u003d\",\"keyExpiration\":\"1606934885430\"}","signatures":["MEYCIQC/uS8hLRz8eZ2aQ4gi50HFW4IxEZcZ8Jj1hJwjaMCCHQIhAI0ry1VEAzGBu0hHrtGfvT11ZqnqFSjEupYS59+lG7NB"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"aew8n0SadRGeorqyYSQCcufpnUU1d0+9D0TaCA+WIvSmY8IKtsVzXIJ0Wzsy2dIFHABzlaO5QpB+afyBZpqxET1v5t5bdjPhIREBDL3alkL2Hpteaz5xev+MD2e+JjCpwxhsKk0c8K/7uUDMUeu5Qt4sF+GvrPw4MheAWimNUb2JF+sqEGWmlmNxkOkz0D12xFH43avRkjlctcnNDWLGYhxiROBxePd1Hc5n6O5Nfc+nfx5HhjfNwm3R2Ey2WfVTwzd9pJ7xxXS/nd71C+cCSuIdMRDqgZxzjvSIMvkA8BBDSPTIAaurXo04uQRbqt+XW1JKOGSJkv7YccEUvnYnyDhP9YFCV6K8B7iCIMsvoKy1uaCVXNosjUKb3GuS3XvB8O8pylvuOWy0WMWK7zP3hGW8k5ruKTLadr2cytaBVt+5/oe7xkH8epjoVnuaNGgzZFl0blKwVtidLxKZ5S518oaZ6wu/+KkIDXR/2gCRk+oTPO2J9w8HoFJXuGWN1wLpdJ2nWdg4U3p83w/MEx7pUHGjcMDAdKvjnYrIMJwhRJBdqSyvCPdb574Uqbp1VUstDaBmHUR5xWVV8tBEj4lPq9C93nJdK3vsK078tAPmUwCyRkX2YwCbPrF7g8kVMuVwG7bgw4pn6BtgLaqkUD2xajWweRk\\u003d\",\"ephemeralPublicKey\":\"BOhQaWVgF2TAnFeypb/wxVGGSaSGlPfprP/ajMOI59VP6P/coWpWmMHrzi3IXI2AhaIHHrwM7xhsBheb6sxh8lQ\\u003d\",\"tag\":\"BGdAtaVKKP5vv6kTw9uJCZASdy8M0BAIUdTl/y/0vgU\\u003d\"}"}
  2. URL-safe base64 encode to produce the card.device.blob
    eyJzaWduYXR1cmUiOiJNRVVDSUhERDBEUTlYWUpyZXJ4ZUkwTHBDUXlGbXFGcXBKZ0hlZUxxSkRoRjB6OFRBaUVBMjBMRjBKVXdFbUUxZHoyQkZVZ2lpM05GSHpYRERtZ3N2QlRIY2RMVlozMFx1MDAzZCIsImludGVybWVkaWF0ZVNpZ25pbmdLZXkiOnsic2lnbmVkS2V5Ijoie1wia2V5VmFsdWVcIjpcIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXI2ZEFhYzBlS05TalBFNGVyNkRzTUE0b1Rhb1VYTUVSaEwrN09PSVNJS2h2bzhLNU9Wckl1V2Z2S0hZRTJETkFtWmtIU3dpdFJzNDlnTUhzNVE3YWVBXFx1MDAzZFxcdTAwM2RcIixcImtleUV4cGlyYXRpb25cIjpcIjE2MDY5MzQ4ODU0MzBcIn0iLCJzaWduYXR1cmVzIjpbIk1FWUNJUUMvdVM4aExSejhlWjJhUTRnaTUwSEZXNEl4RVpjWjhKajFoSndqYU1DQ0hRSWhBSTByeTFWRUF6R0J1MGhIcnRHZnZUMTFacW5xRlNqRXVwWVM1OStsRzdOQiJdfSwicHJvdG9jb2xWZXJzaW9uIjoiRUN2MiIsInNpZ25lZE1lc3NhZ2UiOiJ7XCJlbmNyeXB0ZWRNZXNzYWdlXCI6XCJhZXc4bjBTYWRSR2VvcnF5WVNRQ2N1ZnBuVVUxZDArOUQwVGFDQStXSXZTbVk4SUt0c1Z6WElKMFd6c3kyZElGSEFCemxhTzVRcEIrYWZ5QlpwcXhFVDF2NXQ1YmRqUGhJUkVCREwzYWxrTDJIcHRlYXo1eGV2K01EMmUrSmpDcHd4aHNLazBjOEsvN3VVRE1VZXU1UXQ0c0YrR3ZyUHc0TWhlQVdpbU5VYjJKRitzcUVHV21sbU54a09rejBEMTJ4Rkg0M2F2UmtqbGN0Y25ORFdMR1loeGlST0J4ZVBkMUhjNW42TzVOZmMrbmZ4NUhoamZOd20zUjJFeTJXZlZUd3pkOXBKN3h4WFMvbmQ3MUMrY0NTdUlkTVJEcWdaeHpqdlNJTXZrQThCQkRTUFRJQWF1clhvMDR1UVJicXQrWFcxSktPR1NKa3Y3WWNjRVV2bllueURoUDlZRkNWNks4QjdpQ0lNc3ZvS3kxdWFDVlhOb3NqVUtiM0d1UzNYdkI4TzhweWx2dU9XeTBXTVdLN3pQM2hHVzhrNXJ1S1RMYWRyMmN5dGFCVnQrNS9vZTd4a0g4ZXBqb1ZudWFOR2d6WkZsMGJsS3dWdGlkTHhLWjVTNTE4b2FaNnd1LytLa0lEWFIvMmdDUmsrb1RQTzJKOXc4SG9GSlh1R1dOMXdMcGRKMm5XZGc0VTNwODN3L01FeDdwVUhHamNNREFkS3ZqbllySU1Kd2hSSkJkcVN5dkNQZGI1NzRVcWJwMVZVc3REYUJtSFVSNXhXVlY4dEJFajRsUHE5QzkzbkpkSzN2c0swNzh0QVBtVXdDeVJrWDJZd0NiUHJGN2c4a1ZNdVZ3RzdiZ3c0cG42QnRnTGFxa1VEMnhhald3ZVJrXFx1MDAzZFwiLFwiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJCT2hRYVdWZ0YyVEFuRmV5cGIvd3hWR0dTYVNHbFBmcHJQL2FqTU9JNTlWUDZQL2NvV3BXbU1IcnppM0lYSTJBaGFJSEhyd003eGhzQmhlYjZzeGg4bFFcXHUwMDNkXCIsXCJ0YWdcIjpcIkJHZEF0YVZLS1A1dnY2a1R3OXVKQ1pBU2R5OE0wQkFJVWRUbC95LzB2Z1VcXHUwMDNkXCJ9In0

Still have questions?

ACH / RTP FAQ

What fields are configurable in an ACH Bank Statement?
Bank Statement FieldTabaPay defaultOverride
Company NameMerchant Name
Configured during on-boarding
Soft Descriptor Name

What shows up on an RTP Bank Statement?
  1. Reference Number
  2. Date
  3. Name of Sender
  4. Name of Ultimate Sender ("Payment on behalf of...")
  5. Amount

What fields are configurable in an RTP Bank Statement?
Bank Statement FieldTabaPay defaultConfigurable?Override
Reference NumberreferenceIDNoN/A
DateDate of RTP RequestNoN/A
Name of SenderMerchant Name Configured during on-boardingYesSoft Descriptor Name
Name of Ultimate SenderN/AYesCorresponding Name
AmountamountNN/A


How can I reverse an RTP Transaction?
Send the request for reversal to help@Tabapay.com with the original Network ID. The reversal request must be no more than 24 hours from the original.

Clients WebSite FAQ

Limited availability...
Passphrase
A Passphrase must be at least 8 characters long and contain:
  • At least one lower case letter
  • At least one upper case letter
  • At least one number
We stored all Passphrases as Salted Hash values, so we can never retrieve your Passphrase.

Refreshing Transaction Data
Refreshing the Transactions Web Page at intervals below 60 seconds does not do anything and just results in the same data being returned. Transaction Data is updated on the backends every 60 seconds.

Repeating trying to refresh Transaction Data may cause our WAF and/or IDS/IPS to blacklist you and eventually your access will be revoked.


SLA
WebSiteOperational Times
Clients WebSiteMon - Fri between 6am PT - 9pm PT
ClientsOps WebSiteMon - Fri between 9am PT - 6pm PT

Anti-Pattern FAQ

We have seen many different things from Clients while using the TabaPay API. Anti-Patterns will cause your IP Addresses to be automatically blocked by our WAF and/or IDS/IPS. Certain other Anti-Patterns will cause the TabaPay API to return either SC=429 or SC=503 or SC=423.

So what are some Anti-Patterns we have seen from Clients while using the TabaPay API?


Retrieve by ReferenceID
You should only use the Retrieve by ReferenceID in the rare case when the connection is lost and you do not have:
  • the AccountID
  • the TransactionID
You should not be using Retrieve by ReferenceID to determine if you already have created the account or you already submitted a transaction.

You should always use:

  • the AccountID
  • the TransactionID
that was returned on the Create.

4XX Errors

404 Errors
Using the API to tell you that a Resource is not found:

409 Errors
Using the API to tell you that you are reusing a ReferenceID:

Other Error Behaviors
  • Repetitively retrying an API request even though you are getting a Status Code of 406...
  • Creating multiple Accounts with the same Card Number
  • Repetitively retrying the same API request with the same parameters, such as:
    • ReferenceID (for Account or Transaction)
    • KeyID
    • AccountID
    • TransactionID

What is the issue?
  • the TabaPay API System was built (and optimized) for Transaction Processing
  • the TabaPay API System was not built (and optimized) for Other Processing Tasks like:
    • Creating and Managing Accounts
    • Determining if an Account was previously created already or not
    • Determining if a Transaction was previously submitted already or not
The expected TabaPay API usage was:
APIExpected Usage
Retrieve Client0 %
Create Key0 to 1 %
Retrieve Key0 %
Delete Key0 %
Query Card39 %
Create Account5 %
Retrieve Account0 to 1 %
Update Account0 to 1 %
Delete Account0 to 1 %
Create Transaction47 %
Retrieve Transaction0 %
Delete Transaction6 %

If you are outside these expected usage, your ClientID may be detected to be performing Anti-Pattern behavior and is subject to our Anti-Pattern Behavior Detection. You might want to consider using our future TabaPay PayFac Platform, see Future FAQ.

Our Anti-Pattern Behavior Detection has actually already caught numerous bugs in a few of our clients' code. So it does really work, but unfortunately we will need to protect our Systems from a runaway bug, so we will have to stop this behavior before it causes any issues... This means:

  • Returning SC=429, Too many Requests
  • Returning SC=503, Forbidden, Permissions
  • Returning SC=423, Locked
  • Removing IPs whitelisted for the Client

What are some Real Life Issues we have seen
Here is what we have seen so far:


A client doesn't know what transactions they sent to us, so they were sending a Retrieve Transaction with ReferenceID for all the possible Transactions they have Created even those not processed by us, so >99% of all this traffic was a Retrieve Transaction failure with SC=404, Not Found. That was >99%...


A client doesn't know what transactions they sent to us, so they were sending us 10 calls to Retrieve Transaction with ReferenceID (not actual but just an example) of:

  • 000001-0
  • 000001-1
  • 000001-2
  • 000001-3
  • 000001-4
  • 000001-5
  • 000001-6
  • 000001-7
  • 000001-8
  • 000001-9
and looking for which one returned a 200 or 404. So >25% of all their traffic was this Retrieve Transaction call.

What was incorrect?

  • Doing a Retrieve by ReferenceID
  • But the biggest concern was them not knowing if they sent the transaction or not


A client was using us to determine if an account was already added or not, so they were sending us a Create Account and expecting:

  • 200 - new
  • 409 - duplicate
So >10% of all their traffic was this Create Account call that was returning 409.


Another client was using us to determine if an account was already added or not, so they were sending us a Retrieve Account with ReferenceID (not actual but just an example) of:

  • 123v1
  • 123v1
  • 123v2
  • 234v1
  • 234v1
  • 234v1
So >90% of all their traffic was this Retrieve Account call.

What was incorrect?

  • >90%
  • Doing a Retrieve by ReferenceID
  • Doing a Retrieve with the same ReferenceID multiple times


This same client was also doing this behavior:

  • Query Card
  • Create Account
  • Delete Account
Not once, but multiple times; and all of them were one right after the other one. It was some sort of bug.

So, what is the issue?
We are also holding a lot of inactive:
  • Accounts
  • Keys
and we are holding a lot of duplicate:
  • Accounts
and we are processing a lot of useless requests:
  • Retrieve Account
  • Retrieve Transaction
that the Clients should already be saving the data from the Response of the corresponding Create Call:
  • Create Account
  • Create Transaction

From a Real Life Example described above:

Just think if all the clients where sending us requests where >90% of all these requests were basically useless.

Duplicate Card Check FAQ

The Duplicate Card Check feature will check if a Card Number is already in use by another Account. It can be used on the following:You will need permissions to use the Duplicate Card Check feature as there will be an extra charge (fee) for using this feature.


How does Duplicate Card Check work?
You must always use the extra Query String Parameters on the following:

What if I want to add an Account that is using a Card Number that is already used by another AccountID?

Can I mix the usage of using the Query Parameters and not using the Query Parameters?

No

If you do, then the Duplicate Card Check feature might no longer be valid.

So, if you decide to do this (mixing), you might as well NOT use this feature, since using this feature will incur an extra charge (fee)...


Errors?
  • CreateAccount
    Status CodeAccount Created?Duplicate Card Check
    200✔ Yes✔ Yes, No Match
    207✔ Yes✘ Processing Error
    409✘ No✔ Yes, Match

  • UpdateAccount
    Status CodeAccount Updated?Duplicate Card Check
    200✔ Yes✔ Yes, No Match
    207✔ Yes✘ Processing Error
    409✘ No✔ Yes, Match

  • DeleteAccount
    Status CodeAccount Deleted?Duplicate Card Check
    200✔ Yes✔ Yes
    207✔ Yes✘ Processing Error

Future FAQ

What are our Future Feature Plans?
UAT Environment

Authorization Tokens
  • Authorization Tokens can Expire
  • You will be able to change your Authorization Token

TabaPay PayFac Platform
  • Future

List of Available Documentation

Copyright © 2017-2021   TabaPay, Inc.   All Rights Reserved...