Devolver una transferencia

Solo disponible en México

Al terminar esta guía, podrás devolver una transferencia entrante y manejar los eventos de webhook que reportan el resultado. Fintoc te permite devolver una transferencia entrante hasta 90 días después de la transferencia original usando el endpoint de devolución de transferencia. Devuelve una transferencia según tu propia lógica de negocio, por ejemplo, cuando esperas un monto específico pero recibes otro distinto.

Disparar la devolución

Llama al endpoint de devolución de transferencia con el transfer_id y el header Fintoc-JWS-Signature. El header contiene una JSON Web Signature (JWS) para la solicitud:

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"
    }
  }
}

Si la solicitud es exitosa, la API devuelve una transferencia con status en return_pending. Después de que Fintoc procesa la devolución, status cambia a returned.

Manejar el resultado de la devolución

Maneja los siguientes eventos de webhook para rastrear el resultado de una devolución:

Evento	Descripción
`transfer.inbound.returned`	Fintoc devolvió la transferencia. El `receipt_url` muestra el Comprobante Electrónico de Pago original con el estado `Devuelta`.
`transfer.inbound.return_failed`	Fintoc no pudo devolver la transferencia. El `status` de la transferencia vuelve a `succeeded`.

Probar la integración

Confirma tu integración en modo test antes de salir a producción. Dispara una devolución contra una transferencia entrante simulada y verifica que tu manejador de webhooks reciba el evento esperado:

Para una devolución exitosa, espera el evento transfer.inbound.returned y una transferencia con status en returned.
Para una devolución fallida, espera el evento transfer.inbound.return_failed y una transferencia con status de vuelta en succeeded.

Consulta Prueba tu integración para conocer los pasos para simular ambos escenarios.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Devolver una transferencia

Disparar la devolución

Manejar el resultado de la devolución

Probar la integración

​Disparar la devolución

​Manejar el resultado de la devolución

​Probar la integración

Disparar la devolución

Manejar el resultado de la devolución

Probar la integración