Developer Documentation

Recovery flow

Sometimes the bank might not send the callback to Token.io.

In most cases, this means that the user was not able to login to the bank authorization page and the status remains as INITIATION_PENDING_REDIRECT_AUTH, changing to INITIATION_EXPIRED after 40 minutes.

Additionally, the callback may not be sent if, for example, the user successfully logs in, approves the payment and then closes the browser page too early, or there are some other connection issues. The transaction may have completed and funds may have been transferred, but the user hasn't been redirected from the bank page and the TPP didn't receive the callback. In these cases, we recommend continuing to watch the payment status updates via webhook, or by polling the payment, until the status is finalised.

The following recovery flow describes what happens 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. In this type of scenario, the recovery flow should be implemented.

Token.io will continue to send webhooks as the payment status changes, and until a final status is set.

If you don't receive a webhook from Token.io for any reason we recommend using the GET /v2/payments/{paymentId} call.

See the API reference for details of the following call to retrieve details of a specific payment:

GET /v2/payments/{paymentId}

Payment status

The following table describes the possible statuses that can be returned in the status field of the POST /v2/payments, GET /v2/payments/{paymentId} and POST v2/payments/{paymentId}/embedded-auth endpoints.

status	Description	Final/Intermediate
`INITIATION_PENDING`	Token.io has received the payment initiation and the initiation has passed Token.io's validation. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PENDING_REDIRECT_AUTH`	The payment request has been acknowledged by the bank and Token.io is awaiting user confirmation on the bank's page. If you're not using Token.io's Hosted Pages, you'll need to redirect the user to the URL found in the authentication field and await a callback from the bank (if you're handling callbacks) or from Token.io (if Token.io handles the callbacks for you).	Intermediate
`INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION`	Token.io has received the callback information from the bank and is currently verifying it with the bank. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PENDING_REDIRECT_HP`	This status can only be observed if you're using Token.io's Hosted Pages and `flowType` is set to `FULL_HOSTED_PAGES` in the POST /v2/payments request. You'll need to redirect the user to the url found in the authentication field and await a callback from Token.io's Hosted Pages after Token.io handles the entire flow for you.	Intermediate
`INITIATION_PENDING_EMBEDDED_AUTH`	Token.io is waiting for the requested input from the user. If you're not using Token.io's Hosted Pages, you must provide the requested information to process the payment. Required information can be found in the authentication object of the payment.	Intermediate
`INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION`	Token.io is waiting for the bank to process the provided information. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PENDING_DECOUPLED_AUTH`	Token.io is polling the status from the bank while the user authenticates in a decoupled way. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PENDING_REDEMPTION`	The payment is ready for redemption. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PENDING_REDEMPTION_VERIFICATION`	Token.io is waiting for the bank to redeem the payment. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call.	Intermediate
`INITIATION_PROCESSING`	The payment initiation request has been acknowledged by the bank and is now being processed. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call. If necessary, wait for additional webhooks to be sent. If a webhook is not received, then use a polling call every 120 mins. The status can be updated to one of `INITIATION_COMPLETED`, `INITIATION_REJECTED`, `INITIATION_NO_FINAL_STATUS_AVAILABLE` or `INITIATION_EXPIRED` (if the status polling period is exhausted).	Intermediate
`INITIATION_COMPLETED`	The final status, indicating that the payment initiation request has been successfully completed. This doesn't guarantee that the payment is settled.	Final
`INITIATION_REJECTED`	The final status, indicating that the payment initiation request has been rejected by the bank. More details are shared in the corresponding `statusReasonInformation` field.	Final
`INITIATION_REJECTED_INSUFFICIENT_FUNDS`	The final status, indicating that the payment initiation request has been rejected due to insufficient funds.	Final
`INITIATION_FAILED`	The final status, indicating that Token.io failed to proceed with the initiation due to problems with reaching the bank, or because payment authentication has not been completed within the allowed time period. More details are shared in the corresponding `statusReasonInformation` field. For two-step banks, if the payment has been authorized, but Token.io is unable to reach the bank to redeem the payment, the request is retried for 35 mins. After this time the status is updated to `INITIATION_FAILED`. For all banks, if the payment status is still `INITIATION_PENDING*` after 40 mins, it will be updated to `INITIATION_FAILED`. Payments can transition to `INITIATION_FAILED` after less than 40 mins if Token.io is unable to reach the bank.	Final
`INITIATION_DECLINED`	The final status, indicating that the payment initiation request has been declined, in most cases actively by the user.	Final
`INITIATION_EXPIRED`	The final status, indicating that the bank has not responded to the payment initiation request. The payment status is polled while waiting for a callback (redirect authentication) or during the decoupled step. If the status is not successfully updated within 30 mins, it will be updated to `INITIATION_EXPIRED`. This status is only relevant for one-step payment flows.	Final
`INITIATION_NO_FINAL_STATUS_AVAILABLE`	The payment status has not been updated for some time and Token.io has stopped polling it. This is a final status, but it does not indicate success or failure. Please contact the bank to check the actual status of the payment.	Final
`SETTLEMENT_IN_PROGRESS`	This status is provided when a Token.io Settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. Token.io is waiting for the payment to reach the payee bank. No action is required; await the next step, e.g., Token.io sends a webhook with the status update, or a polling call. The status will change to `SETTLEMENT_IN_PROGRESS` soon after Token.io receives the final status from the debtor bank.	Intermediate
`SETTLEMENT_COMPLETED`	This status is provided when a Token.io Settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. The payment has reached the payee bank and Token.io has matched the transaction in the TPP’s settlement account to the initiated payment. For instant payments, `SETTLEMENT_COMPLETED` will be achieved within 30–45 minutes from payment initiation, at the latest. For non-instant payments, the time to reach `SETTLEMENT_COMPLETED` will depend on the clearing period for the payment.	Final
`SETTLEMENT_INCOMPLETE`	This status is provided when a Token.io Settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. Reconciliation has failed. This happens when Token.io doesn't find the corresponding transaction in the TPP's settlement account automatically. See Settlement status for SEPA and SEPA Instant payments for more information.	Final

Please be aware that Token.io’s INITIATION_COMPLETED status does not guarantee funds transfer. It merely indicates/confirms the success of a payment initiation. INITIATION_COMPLETED means the final status on the bank’s side has been reached, regardless of whether or not this status is shared with Token.io, and there will be no further updates from the bank. For non-instant transfers, TPPs are strongly advised to look at the combination of statuses — Token.io’s status, as well as the final status from the bank — for a risk-based approach; otherwise, TPPs are advised to rely on end-to-end reconciliation for final status confirmation.

The following diagram show the flow between payment statuses.

GET /v2/payments

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

Token.io recommends 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 paymentIds
all paymentIds except a specific set of paymentIds
one or more payment status values
all payments that don't have one or more payment status values
date range
refId list
sub-TPP reference id (onBehalfOfId)
PaymentRefundStatus

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