Data Format & Schema

How to structure your API request and what data formats to use.

Is there a JSON Schema?

Additional JSON name–value pairs (NVPs) are allowed to be added in requests, and may return in responses. However, adding extra fields in a request is not recommended.

Requests may contain NVPs in any order, and responses may return NVPs in any order including optional fields that your integration does not use but other clients might be using.

⚠️
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).

Format of the JSON Request and Response Data?

TabaPay requires that all whitespaces are removed from the JSON Request (pack your JSON Request). TabaPay will also return a JSON Response in a packed format where all whitespaces are removed.

Nice for human:

{
  "NameA": "Test",
  "NameB": 1
}

Nice for applications, and does not clutter system logs:

{"NameA":"Test","NameB":1}

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.2 --> 1Invalid, comma not needed $10.21 --> Invalid, dollar sign not needed

Character Sets and Rules

Size limits, allowed characters, null handling, and encoding rules for API fields.

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...?

⚠️
We recommend the use of only the Base64 URL-Safe Character Set*.
Because other, upstream or downstream, processes that may be using this data, we recommend the use of only the Base64 URL-Safe Character Set
*The space character is also allowed

The API can accept any UTF-8 character.

Restricted Characters

We will also explicitly restrict the use of these characters:

Forbidden Character	Character Description
`\`	Backslash
`^`	Caret
`,`	Comma
`"`	Double Quotes
`()`	Parentheses
`\|`	Pipe
`;`	Semi-Colon
`~`	Tilde

Note: For forbidden characters related to the soft descriptor, refer to Soft Descriptor Restricted Characters.

Text Patterns to Avoid

Consecutive . will be blocked
Any text fragments that resemble SQL Statements or code
Avoid using consecutive characters not part of the URL-Safe Base64 Character Set, as our WAF will block any suspicious text.
Parentheses ( ) will trigger the WAF and will result in a 406 Error.

Name Field Mistakes

Incomplete names (missing first name or last name)
Submitting invalid name formats (too short, too long, or disallowed characters)
Populating with a phone number, email address or alias (including usernames or nicknames)
Populating non-English language characters in the name field (including characters from non-Latin alphabets or characters with umlauts, accents, and other diacritical marks)
Populating with non-informative or placeholder data (e.g. 123456, TEST, ---)”

Note: Not all name field mistakes may result in a 400 Error, or be rejected by the TabaPay API, but may be recommended as best practice for card networks.

Name field character restrictions are recommended as best practice for card networks.

Restricted Name Field Character	Character Description
`&`	Ampersand
`\`	Backslash
`^`	Caret
`:`	Colon
`,`	Comma
`$`	Dollar Sign
`"`	Double Quotes
`=`	Equal Sign
`!`	Exclamation Mark
`/`	Forward Slash
`#`	Hash / Pound
`()`	Parentheses
`%`	Percent
`+`	Plus
`\|`	Pipe
`?`	Question Mark
`;`	Semi-Colon
`~`	Tilde
`_`	Underscore

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:

URL-Safe Character	Character Description
`[A-Z]`	Uppercase Alphabetic Characters
`[a-z]`	Lowercase Alphabetic Characters
`[0-9]`	Digits
`-`	Minus Sign (also referred to as hyphen)
`_`	Underscore

Unique IDs

It is best practice to never share, or expose any of these values publicly.

Most generated TabaPay unique IDs are case-sensitive (.e.g accountID, settlementAccountID, Bearer Token, ClientID, SubClientID)

However the referenceID is NOT case sensitive, and Uppercase and lowercase letters are treated as equivalent.

Reference ID

You will generate a unique referenceID for different requests for Create Account API, and Create Transaction API.

referenceID is NOT case-sensitive.

Uppercase and lowercase of the same letters are treated the same.

For example, ABC123 and abc123 are considered the same referenceID.