Callback for API-only integration

For the API-only integration callback, the bank calls back to Token.io and Token.io calls back to the TPP - as shown here:

You should not rely on the parameters in the callback url to determine the payment status and potential next steps.

We recommend that you use webhooks or polling instead.

In this callback, the query parameters always contain payment-id, member-id and state.

Example callback for Payments v2

https://tpp.callback.url?member-id=m:33V1ykzKwHbkWqt7fDz2WPPdH2Zt:5zKtXEAq&payment-id=pm2:24YYrAZ34sTo4A6C47rYandHke2L:2gFUX1NDgoi&state=CallbackState1725556043
or in JSON format:
{
    "member-id": "m:33V1ykzKwHbkWqt7fDz2WPPdH2Zt:5zKtXEAq",
    "payment-id": "pm2:24YYrAZ34sTo4A6C47rYandHke2L:2gFUX1NDgoi",
    "state": "CallbackState1725556043"
}

In rare cases the status may be returned.
This only applies to multi-redirect banks where the callback is executed synchronously.

Token.io processes callback asynchronously in order to return control of the browser to the TPP as soon as possible. The TPP should either wait for a webhook or poll the payment in order to determine the payment status and potential next steps.

request-timeout header

Banks may take some time to respond when a request is made. Therefore, Token.io recommends that you set a request-timeout header in your API-only POST /v2/payments requests to match the timeout of your client and avoid DEADLINE_EXCEEDED errors.

If this is set, Token.io sends a response when this timeout period has passed and will update payment status as soon as the bank has responded.

The following example demonstrates what happens when you set a request-timeout of 10 seconds and the call to the bank takes 15 seconds:

The TPP makes a POST /v2/payments call.
Token.io creates a resource with the status INITIATION_PENDING.
Token.io starts the call to the bank.
After 10 seconds from (1): Token.io returns the payment status INITIATION_PENDING.
After 15 seconds from (3): Token.io receives a response from the bank and changes the status to, for example, INITIATION_PENDING_REDIRECT_AUTH. The update will be sent in a webhook, if the TPP is subscribed for webhooks.
The TPP makes the GET /v2/payments/{id} call and receives the payment with INITIATION_PENDING_REDIRECT_AUTH.

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