This section describes the API integration where the TPP owns the full user experience. We recommend that TPPs use webhooks to receive notification of the payment status.
See the Token.io API reference for details of the following endpoints:
GET /banksPOST /token-requestGET /token-requests/{request ID}/resultPOST /token-requests/{tokenRequestId}/authorizationGET /transfers/{transferId}
Use our Launchpad to test them.
The image below is a simplified swim lane diagram of the integration flow.
Details of the steps within the integration flow are shown below.
The TPP retrieves the list of available banks using the GET /banks call.
We recommend that this step is performed once daily, outside any payment initiation, e.g., at 11pm UTC, and that the result is cached.
In the GET /banks request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.
See Mandatory fields for information on which fields must be provided for a given bank to accept a payment initiation request.
a. TPP -> Token.io - The TPP requests the list of banks from Token.io.
b. Token.io -> TPP - Token.io supplies the list of banks to the TPP.
The user selects the bank.
a. TPP -> User - The TPP displays the bank selection screen.
b. User -> TPP - The user selects the bank.
The TPP collects consent from the user. For more information see User consent collection.
a. TPP -> User - The TPP initiates consent acceptance from the user.
b. User -> TPP - The user gives consent to the TPP.
The TPP initiates the token request with Token.io using the POST /token-requests call. Token.io responds by acknowledging the details of the request.
a. TPP -> Token.io - The TPP creates the token request using the POST /token-requests call.
If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the Settlement account id of the sub-TPP in the POST /token-requests request.
b. Token.io -> TPP - Token.io generates a response to the token request.
The TPP requests authorization using the POST /transfers call. Token.io responds with the authorization URL.
a. TPP -> Token.io - The TPP requests the bank authorization URL using the POST /token-requests/{tokenRequestId}/authorization call.
b. Token.io -> TPP - Token.io returns the redirectUrl provided by the bank.
The user completes authorization with the bank.
a. Bank -> User - The bank displays the authorization page to the user.
b. User -> Bank - The user authorizes the payment with the bank.
The user is redirected and the TPP consumes the Token.io callback.
a. Bank -> Token.io - The bank redirects the user to Token.io.
b. Token.io -> TPP - Token.io immediately redirects the user to the redirect URL provided by the TPP in the redirect URL parameter of the token-request call. The TPP then consumes the callback from Token.io.
See Redirect callback for more information on the Token.io callback.
If for some reason neither the callback nor the webhook have been received, you can use the GET /token-requests/{tokenRequestId}/result call to retrieve the current status of the request.
If you're initiating a payment and you're not using both auto redeem and webhooks, you must fetch the status of the token request result using the GET /token-requests/{tokenRequestId}/result call.
When no further activity is detected in the production environment related to an active token request, the request expires after 20 minutes have elapsed.
Token.io recommends that the TPP subscribes to webhooks to receive payment status updates. As a fallback, the TPP can also poll Token.io for the current status of an initiated payment request.
a. Token.io -> TPP - Token.io sends the payment status to the TPP in a webhook.
If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a transfer is created or updated.
See Webhooks for an example webhook notification.
If the webhook is not received within 30 minutes, the TPP should call GET /transfers/{transferId} to retrieve the payment status.
If you're not using webhooks, you'll need to use GET /token-requests/{tokenRequestId}/result to obtain the transferId to then call GET /transfers/{transferId}.
See Alternative to webhooks for more details.
b. TPP -> Token.io - The TPP checks the status with Token.io with the GET /transfers/{transferId} request.
c. Token.io -> TPP - Token.io confirms the payment status with the GET /transfers/{transferId} response.
If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be SETTLEMENT_COMPLETED. Depending on the payment rail used, this can take a while.
If you're not using Settlement accounts and the payment initiation request is successful, the status will be SUCCESS, but this does not guarantee that the payment has been settled.
If the status is non-final, e.g., PROCESSING, the TPP should wait for additional webhooks to be sent. If the webhook is not received, the TPP should use a polling call (GET /transfers/{transferId}) every 15 mins.
The recommended maximum polling time is 30 days. If the bank doesn't update the status, it will change to INITIATED after 30 days.
See HTTP errors for information on HTTP error status codes.
If you have any feedback about the developer documentation, please contact devdocs@token.io