Enviar transferencias

Completa primero la guía de configuración de Business Accounts. Luego, sigue estos pasos para crear transferencias salientes:

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 la API de Business Accounts 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. Una solicitud exitosa devuelve la Transfer creada:

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": "012000000000000001"
  },
  "metadata": {
  	"customer_id": "12050123"
   }
}
'

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: '012000000000000001' },
  metadata: { customer_id: '12050123' }
});

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": "012000000000000001"},
  metadata={"customer_id": "12050123"}
)

{
  "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,
  "settled_amount": 59013,
  "counterparty": {
    "holder_id": "AAA010101AAA",
    "holder_name": "Test Customer 1",
    "account_number": "012000000000000001",
    "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. Una solicitud exitosa devuelve la Transfer creada:

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": "11111111",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "metadata": {
  	"customer_id": "12050123"
  }
}
'

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: '11111111',
    account_type: 'checking_account',
    institution_id: 'cl_banco_de_chile'
  },
  metadata: { customer_id: '12050123' }
});

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": "11111111",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  metadata={"customer_id": "12050123"}
)

{
  "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,
  "settled_amount": 1869,
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "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í.

Transferencias grandes en Chile

Algunos bancos chilenos limitan las transferencias entrantes a $7.000.000 CLP. Para enviar más, crea una sola transferencia por el monto total. Fintoc divide toda transferencia saliente sobre $7.000.000 CLP en partes de hasta $7.000.000 CLP, sin importar el banco de la contraparte, y envía cada parte a la contraparte.

Las transferencias entre cuentas de Fintoc no se dividenUna transferencia a otra cuenta de Fintoc se liquida de inmediato por el monto total, sin el límite de $7.000.000 CLP. La contraparte recibe una sola transferencia y no tiene partes que conciliar. Cuando tus proveedores, clientes o socios también tienen cuentas de Fintoc, todos los pagos entre ustedes llegan así.

Trabajas con una sola transferencia. La API devuelve un único Transfer con el amount total. Los webhooks, el comprobante y el movimiento de la cuenta pertenecen a esa transferencia. Las partes no aparecen en la API.
La contraparte recibe una transferencia por cada parte. Cada parte es de $7.000.000 CLP, salvo la última, que puede ser menor. Por ejemplo, $15.000.000 CLP llegan como $7.000.000, $7.000.000 y $1.000.000 CLP.
El comentario de cada parte indica su posición. Fintoc agrega X de N a tu comment para que la contraparte pueda conciliar las partes. Por ejemplo, Factura 1042 se convierte en Factura 1042 2 de 3 en la segunda de tres partes. Sin comment, el comentario de la parte es solo 2 de 3. Para que el comentario de cada parte no supere los 40 caracteres, Fintoc trunca tu comment y deja espacio para el sufijo. Una transferencia dividida en 2 a 9 partes conserva los primeros 33 caracteres. El comment del Transfer queda tal como lo enviaste.
Tu saldo debe cubrir el monto total. Fintoc retiene el amount total al crear la transferencia. Si tu saldo es menor, la solicitud falla y Fintoc no envía ninguna parte.
Las partes salen una tras otra. Una transferencia dividida queda en pending más tiempo que una transferencia simple.

La transferencia queda en pending hasta que todas las partes terminan. Una parte puede fallar si, por ejemplo, el banco de la contraparte se cae mientras Fintoc todavía está enviando las partes. Cuando todas las partes terminan, la transferencia llega a uno de estos estados:

Partes que se liquidan	`status` de la transferencia	`settled_amount`	Evento de webhook
Todas	`succeeded`	Igual a `amount`	`transfer.outbound.succeeded`
Algunas	`partially_succeeded`	Suma de las partes liquidadas	`transfer.outbound.partially_succeeded`
Ninguna	`failed`	`0`	`transfer.outbound.failed`

Fintoc devuelve a tu saldo disponible el monto de cada parte que no se liquida, y no reintenta esas partes. Para enviar el resto de una transferencia partially_succeeded, crea una nueva transferencia por amount menos settled_amount.

Para recibir una notificación cuando una transferencia dividida llega a partially_succeeded, suscribe tu webhook endpoint a transfer.outbound.partially_succeeded.

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, rejected o reject_failed. Las transferencias chilenas suman partially_succeeded, reverse_pending y reversed. Para más detalles sobre los estados de transferencia, consulta el modelo de datos de Transfer.

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. Suscribe tu webhook endpoint a estos eventos y maneja cada uno, incluido transfer.outbound.partially_succeeded si envías transferencias chilenas sobre $7.000.000 CLP:

Evento	Descripción
`transfer.outbound.succeeded`	Se envía cuando la transferencia se liquida exitosamente.
`transfer.outbound.partially_succeeded`	🇨🇱 Se envía cuando solo algunas partes de una transferencia dividida se liquidan.
`transfer.outbound.rejected`	Se envía cuando el Banco de México o la institución de la contraparte rechaza una transferencia en México, o cuando la institución de la contraparte rechaza la transferencia en Chile. Consulta las causas de rechazo; `rejected` es un estado final.
`transfer.outbound.failed`	Se envía cuando la transferencia no ha podido llegar a su cuenta destino debido a un error durante el proceso.
`transfer.outbound.reversed`	🇨🇱 Se envía cuando una transferencia liquidada se reversa.

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 estos estados terminales para confirmar tu manejo de webhooks:

Resultado	Estado resultante	Evento del webhook
Exitoso	`succeeded`	`transfer.outbound.succeeded`
🇨🇱 Parcialmente exitoso	`partially_succeeded`	`transfer.outbound.partially_succeeded`
Rechazado	`rejected`	`transfer.outbound.rejected`
Fallido	`failed`	`transfer.outbound.failed`
🇨🇱 Reversado	`reversed`	`transfer.outbound.reversed`

​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 🇨🇱

​Transferencias grandes en 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 🇨🇱

Transferencias grandes en Chile

Paso 4: Monitorear el estado de la transferencia

Flujo de estados de la transferencia

Monitorear el estado usando webhooks

Probar la integración