Return a transfer

Only available in Mexico

By the end of this guide, you can return an inbound transfer and handle the webhook events that report the result. Use the return transfer endpoint up to 90 days after the original inbound transfer. Base the return on your business logic. For example, return a transfer when you expect a specific amount but receive a different one.

Trigger the return

Call the return transfer endpoint with the transfer_id and Fintoc-JWS-Signature header. The header contains a JSON Web Signature (JWS) for the request:

curl

curl --request POST \
     --url https://api.fintoc.com/v2/transfers/return \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H-bywJCeSx' \
     --header 'Fintoc-JWS-Signature: CNMaYaDGU3ZhFV1ve6p3sAdYXhEklej8DVIAMqIWCkpNmT6Jp7iigcndXwH5q3WQFHiswgIQU5-_-4rV3jKGptCROmEyWPW8_elhYH1apzAyjOjyZ55ygv37xKHzIFhixzAwmXlAv4pfD4lVelYWVNOSN7REA0QJeCy2vKdqZ5cjqCXQ1lkQUlzOE7dpuNoAkhAhAJJ8HaamFKy7Gl7uwmqbIr-dVYv21d_9O7mO26n0gy3zWXD2nJDxU5Mzl2pZd8-sFvUr9Kmp_YkeRMh4bSe0fr1Uc_YgkjpmYUyu7kaxRWTbAdJ3GwqWFMUDiyfhHdzvZPZyU4VkWreimoydMA' \
     --header 'Idempotency-Key: 1ebfd86c-a75b-4606-872f-9f1cdd9724ca' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "transfer_id": "tr_2wlt3xRBaEstTGPezqIGXy6JUU8"
}
'

Node

const transfer = await fintoc.v2.transfers.returnTransfer({
  transfer_id: "tr_2wlt3xRBaEstTGPezqIGXy6JUU8",
});

Python

transfer = client.v2.transfers.return_transfer(
  transfer_id="tr_2wlt3xRBaEstTGPezqIGXy6JUU8"
)

Response

{
  "id": "tr_2wlt3xRBaEstTGPezqIGXy6JUU8",
  "object": "transfer",
  "direction": "inbound",
  "status": "return_pending",
  "amount": 100000,
  "currency": "mxn",
  "mode": "test",
  "post_date": "2020-04-17T00:00:00.000Z",
  "transaction_date": "2020-04-17T05:12:41.462Z",
  "comment": "Electricity bill",
  "reference_id": "130824",
  "receipt_url": "https://api.fintoc.com/v2/transfers/tr_2wlt3xRBaEstTGPezqIGXy6JUU8/receipt",
  "tracking_key": "s2123423423324334",
  "return_reason": null,
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "object": "account_number",
    "account_id": "acc_Lq7dP901xZgA2B",
    "description": "My payins",
    "number": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "metadata": {
      "id_cliente": "12343212"
    }
  },
  "counterparty": {
    "holder_id": "AAA010101AAA",
    "holder_name": "Test Customer 1",
    "account_number": "000000000000000000",
    "type": "clabe",
    "institution": {
      "id": "40012",
      "name": "BBVA Mexico",
      "country": "mx"
    }
  }
}

After a successful request, the API returns a transfer with status set to return_pending. After Fintoc processes the return, status changes to returned.

Handle the return result

Handle the following webhook events to track the outcome of a return:

Event	Description
`transfer.inbound.returned`	Fintoc returned the transfer. The `receipt_url` shows the original Comprobante Electrónico de Pago with the status `Devuelta`.
`transfer.inbound.return_failed`	Fintoc could not return the transfer. The transfer’s `status` changes back to `succeeded`.

Test the integration

Confirm your integration in test mode before going live. Trigger a return for a simulated inbound transfer and check that your webhook handler receives the expected event:

For a successful return, expect the transfer.inbound.returned event and a transfer with status set to returned.
For a failed return, expect the transfer.inbound.return_failed event and a transfer with status set to succeeded.

See Test your integration for the steps to simulate both scenarios.

Home

Resources

Payments

Transfers

Movements

Return a transfer

Trigger the return

Handle the return result

Test the integration

​Trigger the return

​Handle the return result

​Test the integration

Trigger the return

Handle the return result

Test the integration