Enviar transferencias

Para crear transferencias salientes con la API de Transferencias de Fintoc, completa la guía de configuración y luego sigue estos pasos:

Configura las llaves de firma JSON Web Signature (JWS) y genera una firma JWS.
Agrega fondos al root_account_number de la cuenta.
Desde tu backend, crea una transferencia usando tu Secret Key y una firma JWS.
Monitorea el estado de la transferencia.

El siguiente diagrama muestra cómo Fintoc interactúa contigo y con la contraparte que recibe el payout.

Paso 1: Configurar las llaves de firma JWS y generar una firma JWS

Cada solicitud a los endpoints de Transferencias de Fintoc requiere una firma JWS. JWS es un mecanismo estándar utilizado para firmar digitalmente una pieza de datos con el fin de garantizar su integridad y autenticidad. Para aprender a firmar una llamada a la API, sigue los pasos de la guía de firma JWS.

Paso 2: Agregar fondos a Fintoc

Para crear transferencias, primero fondea tu Account agregando fondos al root_account_number. El depósito aparece como una transferencia entrante.

Paso 3: Crear una transferencia

Después de agregar fondos a tu cuenta, crea una transferencia desde tu backend. Incluye tu Secret Key de prueba, firma JWS, cuenta de origen, monto, moneda y contraparte. Los ejemplos siguientes muestran respuestas exitosas de transferencia. Para probar resultados fallidos, usa la tabla de estados terminales en la sección Probar la integración más abajo.

Usa una clave de idempotencia

Fintoc admite idempotencia para reintentar transferencias de manera segura sin crear una transferencia duplicada. Al crear una transferencia, usa una clave de idempotencia. Si ocurre un error de conexión, repite la solicitud de manera segura. Para realizar una solicitud idempotente, proporciona un header Idempotency-Key en la solicitud. Aprende más sobre solicitudes idempotentes en esta guía.

Crear una transferencia para México 🇲🇽

A continuación se muestra un ejemplo que crea una transferencia de

590.13 MXN. El campo `amount` está en la unidad mínima de la moneda, por lo que

590.13 es el entero 59013.

curl

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --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 '
{
  "amount": 59013,
  "currency": "mxn",
  "account_id": "acc_M8sKf230BgHjD4",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "counterparty": {
    "account_number": "000000000000000000"
  },
  "metadata": {
  	"customer_id": "12050123"
   }
}
'

Node

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca',
  amount: 59013,
  currency: 'mxn',
  account_id: 'acc_M8sKf230BgHjD4',
  comment: 'Pago de credito 10451',
  reference_id: '150195',
  counterparty: { account_number: '000000000000000000' },
  metadata: { customer_id: '12050123' }
});

Python

transfer = client.v2.transfers.create(
  idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca",
  amount=59013,
  currency="mxn",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  reference_id="150195",
  counterparty={"account_number": "000000000000000000"},
  metadata={"customer_id": "12050123"}
)

Una respuesta exitosa se ve así:

{
  "object": "transfer", 
  "id": "tr_jKaHD105H",
  "amount": 59013,  
  "currency": "mxn", 
  "direction": "outbound",
  "status": "succeeded",
  "transaction_date": "2020-04-17T05:12:41.462Z",
  "post_date": "2020-04-17T00:00:00.000Z",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "tracking_key": "s2123423423324334",
  "receipt_url": "https://www.banxico.org.mx/cep/",
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "AAA010101AAA",
    "holder_name": "Test Customer 1",
    "account_number": "000000000000000000",
    "account_type": "clabe",  
    "institution": {
      "id": "mx_bbva_mexico",
      "name": "BBVA Mexico",
      "country": "mx" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "description": null,
    "metadata": {},
    "object": "account_number"
  },
  "metadata": {
    "customer_id": "12050123"
  }
}

Las monedas se representan como enterosPor ejemplo, Fintoc representa MXN $10.29 como 1029.Puedes leer más sobre monedas aquí.

Recuerda agregar el institution IDAl transferir a una CLABE, no es necesario un institution ID de contraparte. Fintoc deduce la institución a partir del número de CLABE. Si tu contraparte es un número de teléfono móvil o una tarjeta de débito, incluye el institution ID como un número de 5 dígitos, como se muestra aquí. De lo contrario, obtendrás un error 400 Bad Request.

En México, el objeto Counterparty requiere un atributo:

Parámetro	Descripción
`account_number`	Número de cuenta bancaria del destinatario (🇲🇽 CLABE, número de móvil o número de tarjeta de débito).

Crear una transferencia para Chile 🇨🇱

A continuación se muestra un ejemplo que crea una transferencia de $1,869 CLP. Como CLP no tiene unidad menor, el campo amount es el mismo entero, 1869.

curl

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --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 '
{
  "amount": 1869,
  "currency": "clp",
  "account_id": "acc_M8sKf230BgHjD4",
  "comment": "Pago de credito 10451",
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "000000000",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "metadata": {
  	"customer_id": "12050123"
  }
}
'

Node

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca',
  amount: 1869,
  currency: 'clp',
  account_id: 'acc_M8sKf230BgHjD4',
  comment: 'Pago de credito 10451',
  counterparty: {
    holder_id: '11.111.111-1',
    holder_name: 'Test Customer 1',
    account_number: '000000000',
    account_type: 'checking_account',
    institution_id: 'cl_banco_de_chile'
  },
  metadata: { customer_id: '12050123' }
});

Python

transfer = client.v2.transfers.create(
  idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca",
  amount=1869,
  currency="clp",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  counterparty={
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "000000000",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  metadata={"customer_id": "12050123"}
)

Una respuesta exitosa se ve así:

{
  "object": "transfer",
  "id": "tr_jKaHD105H",
  "amount": 1869,   
  "currency": "clp", 
  "direction": "outbound",
  "status": "succeeded",
  "transaction_date": "2020-04-17T05:12:41.462Z",
  "post_date": "2020-04-17T00:00:00.000Z", 
  "comment": "Pago de credito 10451",
  "reference_id": null,
  "receipt_url": null,
  "tracking_key": null,
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "000000000",
    "account_type": "checking_account", 
    "institution": {
      "id": "cl_banco_de_chile",
      "name": "Banco de Chile",
      "country": "cl" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "object": "account_number",
    "description": null,
    "metadata": {}
  },
  "metadata": {
    "customer_id": "12050123"
  }
}

En Chile, el objeto Counterparty requiere cinco atributos:

Parámetro	Descripción
`holder_id`	El RUT chileno del titular de la cuenta.
`holder_name`	Nombre completo del titular de la cuenta.
`account_number`	Número de cuenta bancaria del destinatario en la institución de la contraparte.
`account_type`	Tipo de cuenta. Los tipos admitidos son `checking_account` y `sight_account`.
`institution_id`	El institution ID de Fintoc para el banco que recibe la transferencia. Puedes ver el código de cada institución aquí.

Paso 4: Monitorear el estado de la transferencia

Flujo de estados de la transferencia

El estado de una transferencia es uno de pending, succeeded, failed, returned, return_pending o rejected. Para más detalles sobre los estados de transferencia, consulta el modelo de datos de Transferencias.

Monitorear el estado usando webhooks

Fintoc envía un evento transfer.outbound.succeeded cuando la transferencia se liquida. Usa la guía de webhooks para recibir estos eventos y ejecutar acciones, como enviar un correo de notificación a tu cliente o registrar la transferencia en tu ERP. Recomendamos manejar los siguientes eventos:

Evento	Descripción
`transfer.outbound.succeeded`	Se envía cuando la transferencia se envía exitosamente.
`transfer.outbound.rejected`	🇲🇽 En México, Fintoc envía este evento cuando Banco de México o la institución de la contraparte rechaza la transferencia. Consulta las causas de rechazo. 🇨🇱 En Chile: Se envía cuando la institución de la contraparte ha rechazado la transferencia. `rejected` es un estado final y no sufre cambios posteriores.
`transfer.outbound.failed`	Se envía cuando la transferencia no ha podido llegar a su cuenta destino debido a un error durante el proceso.

Los webhooks pueden llegar en desordenPor ejemplo: un evento de webhook transfer.outbound.rejected podría llegar antes que el webhook transfer.outbound.succeeded de la misma transferencia, aunque la transferencia primero haya tenido éxito y luego haya sido rechazada.

Probar la integración

Usa tu Secret Key de prueba (sk_test_...) para ejecutar transferencias en modo test sin mover dinero real. Cada respuesta incluye "mode": "test". En modo test, una transferencia alcanza los mismos estados terminales que en producción. El resultado no se fuerza mediante una entrada predefinida. Depende de cómo la parte receptora resuelva la transferencia. Usa los tres estados terminales para confirmar tu manejo de webhooks:

Resultado	Estado resultante	Evento del webhook
Exitoso	`succeeded`	`transfer.outbound.succeeded`
Rechazado	`rejected`	`transfer.outbound.rejected`
Fallido	`failed`	`transfer.outbound.failed`

Inicio

Recursos

Pagos

Transferencias

Movimientos

Enviar transferencias

Paso 1: Configurar las llaves de firma JWS y generar una firma JWS

Paso 2: Agregar fondos a Fintoc

Paso 3: Crear una transferencia

Usa una clave de idempotencia

Crear una transferencia para México 🇲🇽

Crear una transferencia para Chile 🇨🇱

Paso 4: Monitorear el estado de la transferencia

Flujo de estados de la transferencia

Monitorear el estado usando webhooks

Probar la integración

​Paso 1: Configurar las llaves de firma JWS y generar una firma JWS

​Paso 2: Agregar fondos a Fintoc

​Paso 3: Crear una transferencia

​Usa una clave de idempotencia

​Crear una transferencia para México 🇲🇽

​Crear una transferencia para Chile 🇨🇱

​Paso 4: Monitorear el estado de la transferencia

​Flujo de estados de la transferencia

​Monitorear el estado usando webhooks

​Probar la integración

Paso 1: Configurar las llaves de firma JWS y generar una firma JWS

Paso 2: Agregar fondos a Fintoc

Paso 3: Crear una transferencia

Usa una clave de idempotencia

Crear una transferencia para México 🇲🇽

Crear una transferencia para Chile 🇨🇱

Paso 4: Monitorear el estado de la transferencia

Flujo de estados de la transferencia

Monitorear el estado usando webhooks

Probar la integración