A payout refers to a situation where the TPP needs to make a payment to an individual or a sub-TPP. The TPP’s account is debited and the individual or sub-TPP’s account is credited. A payout can also be initiated by a TPP when they want to make outbound payments. In this scenario, the Token.io settlement account is the debtor. The beneficiary or payee could be a sub-TPP or another TPP-owned corporate account.
See the Token.io API reference for details of the following payouts endpoints:
Details of the steps within the payouts flow are shown below.
sub-TPP -> TPP - The sub-TPP initiates the payout by passing the payment
idto the TPP.TPP -> Token.io - The TPP initiates the payout with Token.io using the POST /payouts endpoint.
If you're an unregulated TPP, you'll always need to pass the onBehalfOfId field in the POST /payouts request.
- Token.io -> TPP - Token.io returns the payout initiation status to the TPP.
If the payout initiation status is INITIATION_PROCESSING, the TPP must wait to receive the final payout initiation status from Token.io through a webhook.
If webhooks are not working, or have not been configured, Token.io also provides a polling option, GET /payouts/{id}, to retrieve the payout initiation status instead. This can be used by the TPP as a fallback mechanism to the webhook.
- TPP -> sub-TPP - The TPP returns the payout initiation status to the sub-TPP.
In situations where the TPP’s account is the settlement account, the remittance reference (refId) field in the payout request should include the merchant name. This is to ensure the user understands the origins of the transaction.
The refId field is limited to 18 characters. To meet this requirement, use a shortened form of the merchant name along with a unique identifier to make the reference unique.
The following table describes the possible statuses that can be returned in the status field of the POST /payouts, GET /payouts and GET /payouts/{id} responses.
| status | Description |
|---|---|
INITIATION_PENDING | Token.io has received the payout 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 (see Webhooks) with the status update, or a polling call. |
INITIATION_PROCESSING | The payout 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 (see Webhooks) 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 or INITIATION_FAILED (if the status polling period is exhausted). |
INITIATION_COMPLETED | The final status indicating that the payout initiation request has been successfully completed. This doesn't guarantee that the payout is settled. |
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. |
INITIATION_FAILED | The final status indicating that Token.io failed to proceed with the initiation due to problems with reaching the bank within the allowed time period. More details are shared in the corresponding statusReasonInformation field. |
If you have any feedback about the developer documentation, please contact devdocs@token.io