TabaPay
Developers
APIReferenceSamplesFAQLogin
API
Notices and Versions
Overview
Resources / Services
Client
● Retrieve
Key
● Create
● Retrieve
● Delete
Card
● Query
Bank
● Query
OFAC
● Query
Account
● Create
● Retrieve
● Update
● Delete
Transaction
● Create
● Retrieve
● Delete
TransactionRequest
● Create
3D Secure
● Initialize
● Lookup
● Authenticate
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
ACH / RTP
Clients WebSite
Anti-Pattern
Duplicate Card Check
Future

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 09/13/2021 at 12:30 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 USE1v21.060606/06/2021
Production USE2v21.060606/06/2021
UATv21.051105/16/2021
Sandboxv21.061306/13/2021


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 TextOAVS
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
●   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.

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
OACH Options:
  • N: Next Day Settlement
  • S: Same Day Settlement
  • 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
3dsECIStringO3D Secure ECI (Electronic Commerce Indicator)3D Secure
3dsUCAFStringO3D Secure UCAF (Universal Cardholder Authentication Field)
  • Visa uses CAVV (Cardholder Authentication Verification Value)
  • MasterCard uses AAV (Accountholder Authentication Value)
3D Secure
3dsXIDStringO3D Secure XID (Transaction ID)3D Secure
level2TaxExemptbooleanOLevel 2: Tax ExemptLevel 2
level2TaxAmountString
Amount
OLevel 2: Tax Amount
(Currency is the same as the Transaction Amount)
Level 2
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®
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>/v1/clients/<ClientIDISO>/transactionrequests
HTTP Method
POST
Request
Request Data
JSON NameValueRequiredDefaultDescriptionChoice
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
firstStringR nFirst Name
lastStringR nLast 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
View
Hide
  Samples
Pack your Request, the following Samples shown here are unpacked only for human readability:

{
  "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",
    },
  }
}
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
ottpIDString
22 characters
OTTPID
linkString
URL
URL
View
Hide
  Samples
{
  "SC": 200,
  "EC": "0",
  "otppid": "TabaPay_OTPPID_22Chars",
  "link": "https://link/otppid"
}
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.

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
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",
  "status": "Y",
  "ECI": "05",
  "UCAF": "1111111111111111111111111111"
}
Challenge:
{
  "SC": 200,
  "EC": "0",
  "3dsVersion": "2.1.0",
  "enrolled": "Y",
  "processorTransactionID":"11111111111111111111",
  "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.

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

Response Code for AVSDescription
APartial matchStreet address matches, but five-digit and nine-digit postal codes do not match.
BPartial matchStreet address matches, but postal code is not verified.
CNo matchStreet address and postal code do not match.
D & MMatchStreet address and postal code match.
EInvalidAVS data is invalid or AVS is not allowed for this card type.
FPartial matchCard member’s name does not match, but billing postal code matches. Returned only for the American Express card type.
HPartial matchCard member’s name does not match, but street address and postal code match. Returned only for the American Express card type.
INo matchAddress not verified.
JMatchCard member’s name, billing address, and postal code match. Shipping information verified and chargeback protection guaranteed through the Fraud Protection Program. Returned only if you are signed up to use AAV+ with the American Express Phoenix processor.
KPartial matchCard member’s name matches, but billing address and billing postal code do not match. Returned only for the American Express card type.
LPartial matchCard member’s name and billing postal code match, but billing address does not match. Returned only for the American Express card type.
MMatchStreet address and postal code match.
NNo matchOne of the following:
  • Street address and postal code do not match.
  • Card member’s name, street address, and postal code do not match. Returned only for the American Express card type.
OPartial matchCard member’s name and billing address match, but billing postal code does not match. Returned only for the American Express card type.
PPartial matchPostal code matches, but street address not verified.
QMatchCard member’s name, billing address, and postal code match. Shipping information verified but chargeback protection not guaranteed (Standard program). Returned only if you are signed to use AAV+ with the American Express Phoenix processor.
RSystem unavailableSystem unavailable.
SNot supportedU.S.-issuing bank does not support AVS.
TPartial matchCard member’s name does not match, but street address matches. Returned only for the American Express card type.
USystem unavailableAddress information unavailable for one of these reasons:
  • The U.S. bank does not support non-U.S. AVS.
  • The AVS in a U.S. bank is not functioning properly.
  • VMatchCard member’s name, billing address, and billing postal code match. Returned only for the American Express card type.
    WPartial matchStreet address does not match, but nine-digit postal code matches.
    XMatchStreet address and nine-digit postal code match.
    YMatchStreet address and five-digit postal code match.
    ZPartial matchStreet address does not match, but five-digit postal code matches.
    1Not supportedAVS is not supported for this processor or card type.
    2UnrecognizedThe processor returned an unrecognized value for the AVS response.
    International
    BPartial matchStreet address matches, but postal code is not verified.
    CNo matchStreet address and postal code do not match.
    D & MMatchStreet address and postal code match.
    INo matchAddress not verified.
    PPartial matchPostal code matches, but street address not verified.

    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.01200ZZ (or 999)ERRORZZ (or 999)ERRORTransaction Error
    0.02207UNKNOWNUNKNOWNTransaction Processing Failed
    0.0320000 (or 000)COMPLETED00 (or 000)COMPLETEDTransaction Successful, but upstream processing was delayed for 30 seconds
    0.04207UNKNOWN00 (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>
    

    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
    Copyright © 2017-2021   TabaPay, Inc.   All Rights Reserved...