TabaPay
Developers
APIReferenceSamplesFAQLogin
API
Notices and Versions
Overview
Resources
Client
● Retrieve
Key
● Create
● Retrieve
● Delete
Card
● Query
Bank
● Query
OFAC
● Query
Account
● Create
● Retrieve
● Update
● Delete
Transaction
● Create
● Retrieve
● Delete
Reference
Networks
Network Response Codes
AVS Response Codes
Internal Error Codes
Status Codes
Currency Numbers
Country Codes
State Codes
Resource Statuses
Samples
Test Cards
Sample Flows
Code Samples
● curl
● wget
● openssl s_client
● Java
● JavaScript
● Go
● Python
● Ruby
PCI Helpers
● PCI Helper - SSO
● PCI Helper - RSA
FAQ
General
Data
Errors
Coding
Sandbox Environment
UAT Environment
Production Environment
PCI / SOC
PCI Helper - SSO
PCI Helper - RSA
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 02/28/2020 at 15:20 PST.

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.022402/24/2021
Production USE2v21.022402/24/2021
UATv21.022402/24/2021
Sandboxv21.022202/22/2021

View details of the major changes for all Versions

VersionEnvironment
Dev / QASandboxUATProduction
21.0224
21.0222
02/22/202102/24/202102/24/2021
21.020502/18/202102/23/202102/23/2021
21.0211
21.0209
02/11/2021
02/09/2021
21.0208
21.0205
21.0204


02/04/2021
02/08/2021
02/05/2021
02/04/2021
02/08/2021
02/05/2021
02/04/2021
21.0130
21.0127
21.0125
21.0122
21.0121
21.0116
01/30/2021
01/27/2021
01/25/2021
01/24/2021
01/21/2021
01/17/2021
01/30/2021
01/27/2021
01/25/2021
01/24/2021
01/21/2021
01/17/2021
20.121812/21/202001/06/202101/11/2021
20.1218
20.1211
20.1122
20.1113
20.1106

12/16/2020
12/02/2020
11/15/2020
11/12/2020
12/18/2020
12/16/2020
12/05/2020
11/22/2020
11/22/2020
12/18/2020
12/16/2020
12/05/2020
11/22/2020
11/22/2020
20.1106
20.1101
20.1027
20.1023
20.1007
20.1005
20.1001
20.0930
11/07/2020

10/27/2020


10/05/2020
10/04/2020
11/08/2020
11/01/2020
10/27/2020
10/27/2020

10/05/2020
10/04/2020
09/30/2020
11/08/2020
11/01/2020
10/27/2020
10/27/2020

10/05/2020
10/04/2020
09/30/2020
20.0911
20.0828
20.0807
20.0727
09/20/2020
08/29/2020
08/18/2020
07/29/2020
09/20/2020
09/08/2020
08/23/2020
07/29/2020
09/20/2020
09/08/2020
08/23/2020
07/29/2020
20.0727
20.0726
20.0722
20.0716
N/AN/A07/28/2020
07/26/2020
07/23/2020
07/16/2020
20.0525
20.0524
20.0508
20.0505
20.0411
06/21/2020
05/25/2020
06/01/2020
05/06/2020
05/06/2020
07/09/2020
06/03/2020
06/03/2020
05/06/2020
05/06/2020
07/09/2020
06/04/2020
06/04/2020
05/06/2020
05/06/2020
20.0410
20.0406
20.0311
20.0305
20.0303
04/10/2020
04/10/2020
03/12/2020
03/15/2020
03/05/2020
04/15/2020
04/15/2020
04/15/2020
04/15/2020
03/07/2020
04/15/2020
04/15/2020
04/15/2020
04/15/2020
03/07/2020
20.0205
20.0115
02/20/202002/20/202002/22/2020
20.0106
19.1216
19.1213
01/07/2020
12/18/2019
12/13/2019
01/07/2020
12/18/2019
12/14/2019
01/07/2020
12/18/2019
12/14/2019
19.110811/15/201911/23/201911/24/2019
19.1028
19.1026
19.1005
10/28/2019
10/26/2019
10/05/2019
10/28/2019
10/26/2019
10/05/2019
10/29/2019
10/26/2019
10/12/2019
19.092309/24/201909/24/201909/25/2019
19.091909/20/201909/20/201909/21/2019
19.0823C
19.0823B
19.0823A
19.0823
19.0830
09/20/2019
09/16/2019
09/12/2019
09/02/2019
09/02/2019
09/20/2019
09/16/2019
09/12/2019
09/02/2019
09/02/2019
09/21/2019
09/21/2019
09/12/2019
09/08/2019
08/30/2019
19.072808/10/201908/10/201908/11/2019
19.0714
19.0629
07/15/2019
06/29/2019
07/15/2019
06/29/2019
07/21/2019
XX/XX/2019
19.061807/08/201907/08/201907/21/2019
19.0705
19.0701
19.0623
19.0617
07/15/2019
07/03/2019
07/XX/2019
06/18/2019
07/15/2019
07/03/2019
07/XX/2019
06/18/2019
07/21/2019
07/03/2019
07/XX/2019
06/24/2019
19.0531
19.0527
06/01/201906/01/2019
19.050205/25/201905/26/2019
19.0430
19.0426
19.0425
05/04/201905/05/2019
19.041205/20/201906/07/201906/02/2019
19.041104/15/201904/21/2019
19.040504/06/201904/07/2019
19.032603/26/201903/26/2019
19.031803/20/201903/24/2019
19.031003/10/201903/12/2019
0.18v0.18.20190303
0.17v0.17.20190111
0.16v0.16.20181205
0.15v0.15.20180920
0.14v0.14.20180628
0.13
0.09
v0.13.20180416
v0.09.20180416
0.12
0.08
v0.12.20180212
v0.08.20180212
0.11
0.07
v0.11.20180125
v0.07.20180125
0.10
0.06
v0.10.20171215
v0.06.20171215
0.05v0.05.20171015
0.04v0.04.20170920
0.03v0.03.20170823
0.02v0.02.20170805
0.01v0.01.20170711


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.

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:

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
OWatachDog Request Identifier
This is Required 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 TypeSA 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
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 TypeDA 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
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 OptionsACH
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).

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

AVS Response Codes

Response Code
for AVS
Description
YZip Code and Address were matched
ZZip Code was matched
NZip Code and Address were not matched
AZip Code was not matched but Address was matched
UAVS Information not available
RAVS unavailable, can retry later

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
400000124000000✔ 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 NumberInternationalCard TypePullPush  (Availability)
CurrencyCountryDebitCreditPrePaidImmediateNextFew
IntlVisa8400124124999993124124
8400840124999994840124
8400704704999990704704
8400840704999992840704
8400764764999991764764
8400840764999999840764
8400458458999991458458
8400360360999996360360
8400946946999995946946
8400978946999998978946
8400144144999997144144
8401124124999992124124
8401840124999993840124
8401704704999999704704
8401840704999991840704
8401764764999990764764
8401840764999998840764
8401458458999990458458
8401360360999995360360
8401946946999994946946
8401978946999997978946
8401144144999996144144
8402124124999991124124
8402840124999992840124
8402704704999998704704
8402840704999990840704
8402764764999999764764
8402840764999997840764
8402458458999999458458
8402360360999994360360
8402946946999993946946
8402978946999996978946
8402144144999995144144
8403124124999990124124
8403840124999991840124
8403704704999997704704
8403840704999999840704
8403764764999998764764
8403840764999996840764
8403458458999998458458
8403360360999993360360
8403946946999992946946
8403978946999995978946
8403144144999994144144
8404124124999999124124
8404840124999990840124
8404704704999996704704
8404840704999998840704
8404764764999997764764
8404840764999995840764
8404458458999997458458
8404360360999992360360
8404946946999991946946
8404978946999994978946
8404144144999993144144
8405124124999998124124
8405840124999999840124
8405704704999995704704
8405840704999997840704
8405764764999996764764
8405840764999994840764
8405458458999996458458
8405360360999991360360
8405946946999990946946
8405978946999993978946
8405144144999992144144
8406124124999997124124
8406840124999998840124
8406704704999994704704
8406840704999996840704
8406764764999995764764
8406840764999993840764
8406458458999995458458
8406360360999990360360
8406946946999999946946
8406978946999992978946
8406144144999991144144
8407124124999996124124
8407840124999997840124
8407704704999993704704
8407840704999995840704
8407764764999994764764
8407840764999992840764
8407458458999994458458
8407360360999999360360
8407946946999998946946
8407978946999991978946
8407144144999990144144
8408124124999995124124
8408840124999996840124
8408704704999992704704
8408840704999994840704
8408764764999993764764
8408840764999991840764
8408458458999993458458
8408360360999998360360
8408946946999997946946
8408978946999990978946
8408144144999999144144
8409124124999994124124
8409840124999995840124
8409704704999991704704
8409840704999993840704
8409764764999992764764
8409840764999990840764
8409458458999992458458
8409360360999997360360
8409946946999996946946
8409978946999999978946
8409144144999998144144
8410124124999991124124
8410840124999992840124
8410704704999998704704
8410840704999990840704
8410764764999999764764
8410840764999997840764
8410458458999999458458
8410360360999994360360
8410946946999993946946
8410978946999996978946
8410144144999995144144
8411124124999990124124
8411840124999991840124
8411704704999997704704
8411840704999999840704
8411764764999998764764
8411840764999996840764
8411458458999998458458
8411360360999993360360
8411946946999992946946
8411978946999995978946
8411144144999994144144
8412124124999999124124
8412840124999990840124
8412704704999996704704
8412840704999998840704
8412764764999997764764
8412840764999995840764
8412458458999997458458
8412360360999992360360
8412946946999991946946
8412978946999994978946
8412144144999993144144
8413124124999998124124
8413840124999999840124
8413704704999995704704
8413840704999997840704
8413764764999996764764
8413840764999994840764
8413458458999996458458
8413360360999991360360
8413946946999990946946
8413978946999993978946
8413144144999992144144
8414124124999997124124
8414840124999998840124
8414704704999994704704
8414840704999996840704
8414764764999995764764
8414840764999993840764
8414458458999995458458
8414360360999990360360
8414946946999999946946
8414978946999992978946
8414144144999991144144
8415124124999996124124
8415840124999997840124
8415704704999993704704
8415840704999995840704
8415764764999994764764
8415840764999992840764
8415458458999994458458
8415360360999999360360
8415946946999998946946
8415978946999991978946
8415144144999990144144
8416124124999995124124
8416840124999996840124
8416704704999992704704
8416840704999994840704
8416764764999993764764
8416840764999991840764
8416458458999993458458
8416360360999998360360
8416946946999997946946
8416978946999990978946
8416144144999999144144
8417124124999994124124
8417840124999995840124
8417704704999991704704
8417840704999993840704
8417764764999992764764
8417840764999990840764
8417458458999992458458
8417360360999997360360
8417946946999996946946
8417978946999999978946
8417144144999998144144
8418124124999993124124
8418840124999994840124
8418704704999990704704
8418840704999992840704
8418764764999991764764
8418840764999999840764
8418458458999991458458
8418360360999996360360
8418946946999995946946
8418978946999998978946
8418144144999997144144
8419124124999992124124
8419840124999993840124
8419704704999999704704
8419840704999991840704
8419764764999990764764
8419840764999998840764
8419458458999990458458
8419360360999995360360
8419946946999994946946
8419978946999997978946
8419144144999996144144
8420124124999999124124
8420840124999990840124
8420704704999996704704
8420840704999998840704
8420764764999997764764
8420840764999995840764
8420458458999997458458
8420360360999992360360
8420946946999991946946
8420978946999994978946
8420144144999993144144
8421124124999998124124
8421840124999999840124
8421704704999995704704
8421840704999997840704
8421764764999996764764
8421840764999994840764
8421458458999996458458
8421360360999991360360
8421946946999990946946
8421978946999993978946
8421144144999992144144
8422124124999997124124
8422840124999998840124
8422704704999994704704
8422840704999996840704
8422764764999995764764
8422840764999993840764
8422458458999995458458
8422360360999990360360
8422946946999999946946
8422978946999992978946
8422144144999991144144
8423124124999996124124
8423840124999997840124
8423704704999993704704
8423840704999995840704
8423764764999994764764
8423840764999992840764
8423458458999994458458
8423360360999999360360
8423946946999998946946
8423978946999991978946
8423144144999990144144
NetworkCard NumberInternationalCard TypePullPush  (Availability)
CurrencyCountryDebitCreditPrePaidImmediateNextFew
IntlMasterCard8500124124999992124124
8500840124999993840124
8500704704999999704704
8500840704999991840704
8500764764999990764764
8500840764999998840764
8500458458999990458458
8500360360999995360360
8500946946999994946946
8500978946999997978946
8500144144999996144144
8501124124999991124124
8501840124999992840124
8501704704999998704704
8501840704999990840704
8501764764999999764764
8501840764999997840764
8501458458999999458458
8501360360999994360360
8501946946999993946946
8501978946999996978946
8501144144999995144144
8502124124999990124124
8502840124999991840124
8502704704999997704704
8502840704999999840704
8502764764999998764764
8502840764999996840764
8502458458999998458458
8502360360999993360360
8502946946999992946946
8502978946999995978946
8502144144999994144144
8503124124999999124124
8503840124999990840124
8503704704999996704704
8503840704999998840704
8503764764999997764764
8503840764999995840764
8503458458999997458458
8503360360999992360360
8503946946999991946946
8503978946999994978946
8503144144999993144144
8504124124999998124124
8504840124999999840124
8504704704999995704704
8504840704999997840704
8504764764999996764764
8504840764999994840764
8504458458999996458458
8504360360999991360360
8504946946999990946946
8504978946999993978946
8504144144999992144144
8505124124999997124124
8505840124999998840124
8505704704999994704704
8505840704999996840704
8505764764999995764764
8505840764999993840764
8505458458999995458458
8505360360999990360360
8505946946999999946946
8505978946999992978946
8505144144999991144144
8506124124999996124124
8506840124999997840124
8506704704999993704704
8506840704999995840704
8506764764999994764764
8506840764999992840764
8506458458999994458458
8506360360999999360360
8506946946999998946946
8506978946999991978946
8506144144999990144144
8507124124999995124124
8507840124999996840124
8507704704999992704704
8507840704999994840704
8507764764999993764764
8507840764999991840764
8507458458999993458458
8507360360999998360360
8507946946999997946946
8507978946999990978946
8507144144999999144144
8508124124999994124124
8508840124999995840124
8508704704999991704704
8508840704999993840704
8508764764999992764764
8508840764999990840764
8508458458999992458458
8508360360999997360360
8508946946999996946946
8508978946999999978946
8508144144999998144144
8509124124999993124124
8509840124999994840124
8509704704999990704704
8509840704999992840704
8509764764999991764764
8509840764999999840764
8509458458999991458458
8509360360999996360360
8509946946999995946946
8509978946999998978946
8509144144999997144144
8510124124999990124124
8510840124999991840124
8510704704999997704704
8510840704999999840704
8510764764999998764764
8510840764999996840764
8510458458999998458458
8510360360999993360360
8510946946999992946946
8510978946999995978946
8510144144999994144144
8511124124999999124124
8511840124999990840124
8511704704999996704704
8511840704999998840704
8511764764999997764764
8511840764999995840764
8511458458999997458458
8511360360999992360360
8511946946999991946946
8511978946999994978946
8511144144999993144144
8512124124999998124124
8512840124999999840124
8512704704999995704704
8512840704999997840704
8512764764999996764764
8512840764999994840764
8512458458999996458458
8512360360999991360360
8512946946999990946946
8512978946999993978946
8512144144999992144144
8513124124999997124124
8513840124999998840124
8513704704999994704704
8513840704999996840704
8513764764999995764764
8513840764999993840764
8513458458999995458458
8513360360999990360360
8513946946999999946946
8513978946999992978946
8513144144999991144144
8514124124999996124124
8514840124999997840124
8514704704999993704704
8514840704999995840704
8514764764999994764764
8514840764999992840764
8514458458999994458458
8514360360999999360360
8514946946999998946946
8514978946999991978946
8514144144999990144144
8515124124999995124124
8515840124999996840124
8515704704999992704704
8515840704999994840704
8515764764999993764764
8515840764999991840764
8515458458999993458458
8515360360999998360360
8515946946999997946946
8515978946999990978946
8515144144999999144144
8516124124999994124124
8516840124999995840124
8516704704999991704704
8516840704999993840704
8516764764999992764764
8516840764999990840764
8516458458999992458458
8516360360999997360360
8516946946999996946946
8516978946999999978946
8516144144999998144144
8517124124999993124124
8517840124999994840124
8517704704999990704704
8517840704999992840704
8517764764999991764764
8517840764999999840764
8517458458999991458458
8517360360999996360360
8517946946999995946946
8517978946999998978946
8517144144999997144144
8518124124999992124124
8518840124999993840124
8518704704999999704704
8518840704999991840704
8518764764999990764764
8518840764999998840764
8518458458999990458458
8518360360999995360360
8518946946999994946946
8518978946999997978946
8518144144999996144144
8519124124999991124124
8519840124999992840124
8519704704999998704704
8519840704999990840704
8519764764999999764764
8519840764999997840764
8519458458999999458458
8519360360999994360360
8519946946999993946946
8519978946999996978946
8519144144999995144144
8520124124999998124124
8520840124999999840124
8520704704999995704704
8520840704999997840704
8520764764999996764764
8520840764999994840764
8520458458999996458458
8520360360999991360360
8520946946999990946946
8520978946999993978946
8520144144999992144144
8521124124999997124124
8521840124999998840124
8521704704999994704704
8521840704999996840704
8521764764999995764764
8521840764999993840764
8521458458999995458458
8521360360999990360360
8521946946999999946946
8521978946999992978946
8521144144999991144144
8522124124999996124124
8522840124999997840124
8522704704999993704704
8522840704999995840704
8522764764999994764764
8522840764999992840764
8522458458999994458458
8522360360999999360360
8522946946999998946946
8522978946999991978946
8522144144999990144144
8523124124999995124124
8523840124999996840124
8523704704999992704704
8523840704999994840704
8523764764999993764764
8523840764999991840764
8523458458999993458458
8523360360999998360360
8523946946999997946946
8523978946999990978946
8523144144999999144144

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)

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.

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-2020   TabaPay, Inc.   All Rights Reserved...