Devolver una transferencia

Disponible en México y Chile

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

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

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

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

Solo puedes devolver una transferencia en estado succeeded. Si la transferencia tiene otro estado, Fintoc responde con el estado 409 Conflict y el código de error invalid_transfer_status.

Devoluciones en Chile

En Chile, puedes devolver una transferencia entrante apenas llega al estado succeeded si la cuenta del remitente también está en Fintoc. Si la transferencia viene de otro banco, espera 90 segundos después de que la transferencia llegue a succeeded antes de devolverla. Si llamas al endpoint antes, Fintoc responde con el mismo estado 409 Conflict y código de error invalid_transfer_status, y el message del error indica que Fintoc recibió la transferencia hace muy poco. Reintenta la solicitud después de que termine la ventana de 90 segundos.

Devolver una transferencia desde el Dashboard

También puedes devolver una transferencia entrante desde el Dashboard de Fintoc:

Ve a la lista de transferencias y busca la transferencia entrante con estado succeeded.
Abre el menú de opciones de la transferencia y selecciona Devolver.
Revisa el monto y la cuenta de destino. El Dashboard muestra la Clave Bancaria Estandarizada (CLABE) para transferencias mexicanas y el número de cuenta para transferencias chilenas.
Selecciona Confirmar devolución e ingresa los 6 dígitos de tu app de autenticación.

La opción Devolver solo aparece si tienes permiso para devolver transferencias y Fintoc permite la devolución de esa transferencia. Para transferencias chilenas desde otro banco, vuelve a cargar la transferencia después de la ventana de 90 segundos para ver la opción.

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. En México, 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

Business Accounts

Movimientos

Skeleton group medium 9

Devolver una transferencia

Disparar la devolución

Devoluciones en Chile

Devolver una transferencia desde el Dashboard

Manejar el resultado de la devolución

Probar la integración

Inicio

Recursos

Pagos

Business Accounts

Movimientos

Skeleton group medium 9

​Disparar la devolución

​Devoluciones en Chile

​Devolver una transferencia desde el Dashboard

​Manejar el resultado de la devolución

​Probar la integración

Disparar la devolución

Devoluciones en Chile

Devolver una transferencia desde el Dashboard

Manejar el resultado de la devolución

Probar la integración