Refunds

When a service or goods is purchased from a sub-TPP by a consumer, the consumer might decide to return the goods or service. In this case, the sub-TPP will need to return the money paid by the consumer as a refund.

Token.io’s Refunds support account-to-account payments initiated by the TPP through Token.io.

The sub-TPP initiates a refund request to the TPP. The TPP then initiates a refund request to Token.io and references the original payment id along with the amount to be refunded and a description. The payer details (the settlement account from which the money is debited) can also be passed in optionally.

Full and partial refunds are supported. If a payment has been partially refunded, Token.io ensures that the TPP cannot initiate a refund where the total refunded amount will exceed the original payment amount.

See the Token.io API reference for details of the following payouts endpoints:

POST /refunds
GET /refunds
GET /refunds/{id}
GET /transfers/{id}/refunds (this endpoint is payments v1 specific)

To test the Refunds endpoints, use our Launchpad.

The diagram below explains the refunds flow:

sub-TPP -> TPP - The sub-TPP initiates the refund by passing the payment id to the TPP.
TPP -> Token.io - The TPP initiates the refund with Token.io using the POST /refunds endpoint, passing in payment id, amount, description and accountId details.

if: the payer details are not passed in:

Token.io -> Token.io - The payment details including the payer details and payee details are retrieved.

else:

Token.io -> Token.io - The payer details are retrieved from the original payment.

If you're an unregulated TPP, you'll always need to pass the onBehalfOfId field in the POST /refunds request.

Token.io -> Token.io - Token.io initiates the refund.
Token.io -> TPP - Token.io returns the Refund Initiation status to the TPP.

If the refund initiation status is INITIATION_PROCESSING, the TPP must wait to receive the final refund 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 /refunds/{id} to retrieve the refund initiation status instead. This can be used by the TPP as a fallback mechanism to the webhook.

TPP -> Merchant - The TPP returns the refund initiation status to the merchant.

In situations where the TPP’s account is the settlement account, the remittance reference (refId) field in the refund request should include the merchant name. This is to ensure the user understands the origins of the transaction.

Refund status

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

status	Description
`INITIATION_PENDING`	Token.io has received the refund 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 refund 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 refund initiation request has been successfully completed. This doesn't guarantee that the refund is settled.
`INITIATION_REJECTED`	The final status, indicating that the refund 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, or because refund authentication hasn't been completed within the allowed time period. More details are shared in the corresponding `statusReasonInformation` field.
`INITIATION_NO_FINAL_STATUS_AVAILABLE`	The payment status has not been updated for some time and Token.io has stopped polling it. The recommended maximum polling time is 30 days. The status `INITIATION_PROCESSING` will change to `INITIATION_NO_FINAL_STATUS_AVAILABLE` after 30 days if the bank does not update the status. 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.

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