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.
Any status you encounter that's not listed in the table has been deprecated. It will be removed in the future. Please rely only on the statuses specified below.
| Payment Initiation Status | Status Description | Final/Intermediate |
|---|---|---|
PROCESSING | This status indicates that the transaction is in process and that the final status has not been received from the bank. | Intermediate |
SUCCESS | This status indicates that successful payment initiation has been received from the bank. Settlement might not be complete. | Final |
INITIATED | This status is set when the previous status has remained as PROCESSING for 30 days and cannot be updated. The transaction has been initiated but the result is unknown. This is the final status and will not get updated later because Token.io has stopped polling the bank.This status is also returned in a two-step flow in the event that a user’s request has been authorized at the bank but the payment confirmation has subsequently failed.” | Final |
PENDING | This status indicates that the user has successfully completed the authorization process with the bank and the transfer is pending redemption. This status is only relevant for two-step payment flows. | Intermediate |
PENDING_EXTERNAL_AUTHORIZATION | This status indicates that the user has been sent to the bank to complete the authorization process. If not completed within the allowed timeframe (usually around 15 mins, but there are variations between banks) the transaction will expire and transition to FAILURE_EXPIRED. This status is only relevant for one-step payment flows. | Intermediate |
FAILURE_GENERIC | This status usually indicates a technical failure. Possibly, a failure callback was received from the bank, with no transaction status and no further information. | Final |
FAILURE_PERMISSION_DENIED | This status indicates that the user has been denied authorization with the bank This status is only relevant for two-step payment flows. | Final |
FAILURE_CANCELED | This status indicates that the payment initiation has been canceled before execution. | Final |
FAILURE_EXPIRED | This status indicates that the user did not complete the authorization process within the allowed timeframe (usually around 15 mins, but there are variations between banks) and the payment has expired. Token.io will poll the bank for an authorization response for maximum of 30 minutes. If no response has been received in this time, the transaction will be updated to this status. | Final |
FAILURE_INSUFFICIENT_FUNDS | This status indicates that the payment initiation request has been rejected due to insufficient funds. | Final |
FAILURE_DECLINED | This status indicates that the payment initiation has been rejected by the bank. | 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 (GET /transfers/{transferId}). 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 {% $COMPANY %} Settlement account is used as the beneficiary for the payment, and replaces the payment initiation status. The payment has reached the payee bank and {% $COMPANY %} has matched the transaction in the {% $THIRDPARTY %}’s settlement account to the initiated payment. For instant payments, SETTLEMENT_COMPLETEDwill be achieved within 30-45 minutes from payment initiation, at the latest. For non-instant payments, the time to reachSETTLEMENT_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 SUCCESS status does not guarantee funds transfer. It merely indicates/confirms the success of a payment initiation. SUCCESS 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 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.
If you have any feedback about the developer documentation, please contact devdocs@token.io