Reference Materials

Format and protocol

Our APIs adhere to the following standard around format and protocol.

• Other items
  • kebab-case is used throughout in the URL
  • URLs generally use nouns, not verbs
  • Actions are determined by HTTP method used and request body of the post request (if required)
  • Depending on client needs, call-backs using WebHooks or similar approaches will also be considered

Environments available

TxB makes two environments available for our API users

• Test – api.test.txb.com
  • E.g., https://api.test.txb.gs.com/v1/accounts/reserved
  • Used to test initial integrations and new features
  • Our test environment is a replica of our production environment (with mocked payment rail and external settlement services) that allows you to experience production-like performance, errors, etc. before you hit the ground running in production
• Production - api.txb.gs.com
  • E.g., https://api.txb.gs.com/v1/accounts/reserved

Error behavior

TXB APIs respond with a small set of client actionable and universally well understood HTTP response codes. More granular level of information for error-scenarios is provided inside error objects

In case of non-successful processing of the request the TXB APIs respond with a non-200 HTTP response code.

• These lie in 2 broad categories:
  • 4XX response: - Some issue with the request
  • 5XX response: - Some issue on the server side

In all non-success scenarios, the response body contains a list of error objects containing detailed information about what caused this error and how can it be resolved.

Field naming

The following naming conventions are used throughout for TXB APIs:

• Field Names:
  • All field names are camelCased ASCII strings starting with a small cap alphabet or underscore
  • Examples: firstName, paymentAmount, dailyLimit, dailyLimit2, \_ext
• Dates:
  • All date fields end with “Date” suffix
  • Examples: startDate, submissionDate, validityDate
• Date-times:
  • All date-time fields end with “Time” suffix
  • Examples: paymentTime, acceptanceTime, completionTime
• Identifiers:
  • All identifier fields end with “Id” suffix
  • Examples: paymentId, clientId, agentId

Field formats

• Date and Date-time:
  • Only ISO8601 format is used to specify Date and Date-time Fields
  • Date Examples:
    • 2019-05-23, 1995-11-01, 2019-01-31
    • 2019-05-23T05:53:17Z, 1996-11-01T23:00:01Z
• Boolean:
  • Only true/false values are used
  • Following formats are not used
    • true/false
    • 1/0
    • “Yes”/”No”
    • “Y”/”N”
• JSON fields:
  • Only standard JSON field notations are used
  • Type casting like below examples are not used
    • “78” (Using strings in place of numbers)
    • “128.20” (Using strings in place of float)

Request headers

We support the below Request Headers

• Authorization header is non-mandatory as it holds additional information if required for additional authorization
• If a non-mandatory header is not passed in the request, then its value is set to the default header value
• Some additional security headers can also be required to be passed
• Any additional headers passed with the request (besides the supported ones) are ignored by TXB APIs

Response headers

Response headers are included in the https response to provide additional information about the response sent. API users are expected to parse these responses headers to correctly interpret the response.

• Default String encoding: - UTF-8 (Unicode Normalization Form C (NFC))
• Responses use their own encoding for content compression
• Response encoding format is captured in “Content-Encoding” response header