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

Usando el transfer_id y el header Fintoc-JWS-Signature para la solicitud, llama al endpoint de devolución de transferencia:

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 un objeto de transferencia con estado return_pending. Después de que Fintoc procesa la devolución, el estado 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, por lo que la transferencia vuelve a su estado original `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 estado returned.
Para una devolución fallida, espera el evento transfer.inbound.return_failed y una transferencia que regresa al estado 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