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:

Payment initiation starts from the POST /token-requests/{tokenRequestId}/authorization endpoint with bank authorization, using a given token request ID. If you've redirected the user to the redirect URL provided in the response for the POST /token-requests/{tokenRequestId}/authorization call, the bank will call back to Token.io. Token.io will process the callback and call back to you. The callback parameters normally include the token request ID, but if this is followed by an embedded or decoupled step, additional credential-fields are returned.

In the callback response you may receive:

• request-id AND request_id ONLY - these are mandatory fields; you'll then need to call GET /token-requests/{tokenRequestId}/result to get the payment authorization result.

• request-id AND request_id AND credential-fields - you'll then follow the process for receiving additional credentials in the POST /token-requests/{tokenRequestId}/authorization response.

• error response - this means an error occurred; check the gRPC code.

Callback for redirect authentication flow

The callback for redirect authorisation flow contains the request-id and the request_id. You won't receive any additional credentials.

After this, you should call GET /token-requests/{tokenRequestId}/result to get the payment authorization result.

If the callback is unsuccessful, a gRPC code is displayed:

Callback for embedded authentication flow

If more credentials are required, for example if you're using an embedded authentication flow, additional credentials will be returned in the callback URL in the credential-fields query parameter:

In this example, once you base64-decode the value of credential-fields, you'll see:

The decoded credentials have the same structure as credentials returned in the payment initiation response.

Callback for decoupled authentication flow

If a decoupled authentication step is required after the initial redirect callback, additional credentials will be returned in the callback URL in the credential-fields query parameter:

In this example, once you base64-decode the value of credential-fields, you'll see:

Fetching the status of a token request result

To check on whether the final result of a token request is available, call GET /token-requests/{tokenRequestId}/result using the tokenRequestId returned in the response to your original request. This call will return a PENDING status if the result is not available. The status is PROCESSED once the result becomes available. If the request is rejected by the bank, status becomes REJECTED. The status will be EXPIRED if the token request expires before a PROCESSED or REJECTED status is issued by the bank.

Recovery flow

The recovery flow should be implemented when the user doesn't return to the redirectUrl specified in the Token.io request after a given amount of time.

For example, due to connectivity issues the user may have completed the transaction and funds may have been transferred, but the user has not been redirected.

Token.io will send webhooks as the payment status changes, regardless of whether or where the user has been redirected, until a final status has been received from the bank.

The end point used in the recovery flow depends on the stage reached in the payment flow.

Recovery using GET a token request result

The GET /token-requests/{tokenRequestId}/result endpoint should be used when the TPP does not receive a callback from Token.io.

1. TPP -> Token.io - Using the GET /token-requests/{tokenRequestId}/result endpoint, the TPP checks the status of the payment initiation from Token.io.

2. Token.io -> TPP - If the payment initiation has been successful, Token.io returns a 200 response. The response may contain:

• status = PENDING - The result is not yet available and the TPP should wait.

• status = PROCESSED - The TPP should continue as if the user has returned to the redirect URL specified in the Token.io request.

Recovery using GET a transfer

The GET /transfers/{transferId} endpoint is used if GET /token-requests/{tokenRequestId}/result has been called, and/or no webhook was received in the expected timeframe.

1. TPP -> Token.io - Using the GET /transfers/{transferId} endpoint, the TPP checks the status of the payment initiation from Token.io.

2. Token.io -> TPP - If the payment initiation has been successfully processed by the bank, Token.io returns a 200 response. The response may contain:

• status = PROCESSING - The payment initiation request has been acknowledged by the bank and is now being processed.

• status = SUCCESS - The payment initiation request has been successfully completed. This does not guarantee that the payment has been settled.

Payment initiation status

The following table describes the possible statuses that can be returned in the status field of the POST /transfers, GET /transfers and GET /transfers/{transferId} endpoints.

The following diagram shows the flow between payment initiation statuses for one-step banks.

The following diagram shows the flow between payment initiation statuses for two-step banks.

GET payment information for all transfers

To retrieve payment information for multiple payments in one request, TPPs can use the GET /transfers call.

We recommend that this API is used when webhooks are not working as expected. The date range should be restricted to less than one day.

Filtering capabilities allow for retrieving payment details by:

• a specific set of tokenIds

• all tokenIds except a specific set of tokenIds

• boundaries for start and end times of transfers

• one or more transactionStatus values

• all transfers that don't have one or more transactionStatus values

• refId list

• role, e.g., payer or payee.

• sub-TPP reference id (actingAsRefId)

• refund status (transferRefundStatus)