API basics

The following sections provide basic information about how Token.io's API is structured.

Base URLs

Correlated in the following table, the {{BASE_URL}} for calls and redirects depends on the environment in which you're operating.

Be sure to include the BASE_URL for the appropriate environment and purpose in each call.

Common request headers

In order to successfully send API requests, TPPs must send a set of HTTP headers that allow the bank to check the request's validity. This includes signing the request with a qualified certificate.

The Authorization header field is mandatory and must be included in all relevant requests.

The token-customer-ip-address header field is recommended and should be included in all relevant requests.

The table below describes the common request headers.

Response headers

Headers included in the response do not directly relate to the content of the message, and not all headers appearing in the response are categorised as response headers. In general, response-header fields allow the responding server to pass additional information about the response that cannot be placed in the Status-Line.

W3C standard and non-standard response header field definitions can be found in https://www.rfc-editor.org/rfc/rfc9110.html.

In Token.io responses to TPP requests, the most important non-standard field is tokenTraceId. This string value is unique to a single request-response flow, captured from the originating request and sent across to the bank to be stored with the request throughout its lifecycle. Serving primarily as an audit-trail aid, TTID is valuable for debugging the message exchange flow during sandbox testing, and for issue resolution in production.

When the bank reports a 5xx error, Token.io sets "token-external-error":= "true" as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of Token.io's internal services fails or when the bank reports a 4xx error, this header is not populated.

The absence of this response header should be interpreted as "token-external-error"= "false".

This field will be populated if the status is final and the payment is not successful, and there has been an error that caused payment rejection, or prevented us from reaching the bank and updating the status within allotted time.

The tokenExternalError field can be populated as a result of both 4xx and 5xx errors. We recommend that you only rely on it for 5xx errors.

Error codes

The Token.io platform supports the following error codes:

• gRPC

• HTTP

• JSON

gRPC errors

When a gRPC call completes successfully, the server returns an OK status to the client. If a call isn't successful, gRPC returns one of its error status codes instead, with an optional string error message that provides further details about what happened.

HTTP errors

The following table gives a general description of the possible HTTP status codes that could be returned in response to API requests to the Token.io platform. These statuses could be related to business logic or system errors.

JSON format

If you'd prefer to receive error responses in JSON format, add the following header to your request:

token-json-error: true

If the request throws an exception/error, the response body will take the following form:

{
    "error": {
        "code": 504,
        "message": "Deadline exceeded",
        "token_trace_id": "123456asdf",
        "error_origin": "bank"
    }
}

Backward compatibility

The following API changes are considered backward compatible, and should be handled by you:

• Adding new API endpoints

• Adding new properties to the responses from existing API endpoints

• Reordering properties returned from existing API endpoints

• Adding optional request parameters to existing API endpoints

• Altering the format or length of ids

• Altering the message attributes returned by validation failures / other errors

• Sending webhooks for new event types

To ensure these changes are handled correctly and do not cause failures on your system we recommend all clients utilise a lenient json parser.

If you have any feedback about the developer documentation, please contact devdocs@token.io