Para comenzar a usar la API de Transfers de Fintoc para crear transferencias salientes, una vez que hayas completado la guía de configuración, solo necesitas seguir estos pasos:

Configurar las llaves de firma JWS y generar la JWS Signature.
Agregar fondos al root_account_number de la cuenta.
Desde tu backend, crear un Transfer usando tu Secret Key y una JWS Signature.
Monitorear el estado de la transferencia.

El siguiente diagrama muestra cómo interactuará Fintoc contigo y con la contraparte que recibe el payout.

Paso 1: Configurar las llaves de firma JWS y generar la JWS Signature

Para hacer solicitudes a nuestros endpoints de Transfers, se requiere una JSON Web Signature (JWS). JWS es un mecanismo estándar usado para firmar digitalmente un dato y garantizar su integridad y autenticidad. Para aprender a firmar una llamada a la API, sigue los pasos en la guía de JWS Signature.

Paso 2: Agregar fondos a Fintoc

Para crear Transfers, primero financia tu Account. Puedes hacerlo agregando fondos al root_account_number. Esto aparecerá como una transferencia entrante.

Paso 3: Crear Transfer

Puedes comenzar a realizar transferencias en tiempo real una vez que agregues fondos a tu cuenta. Usando tu Secret Key de prueba e incluyendo tu JWS Signature, crea un Transfer desde tu backend con la cuenta de origen (de donde deben salir los fondos), el monto, la moneda y la contraparte que recibirá el pago. Los ejemplos a continuación muestran respuestas exitosas de Transfer. Puedes probar resultados no exitosos con los inputs predefinidos en la sección Prueba tu integración.

Usa una Idempotency Key

Fintoc soporta idempotencia para reintentar Transfers de forma segura sin realizar accidentalmente la misma operación dos veces. Al crear un Transfer, usa una idempotency key. Así, si ocurre un error de conexión, puedes repetir la solicitud de Transfer de forma segura, sin riesgo de crear un segundo Transfer. Para hacer una solicitud idempotente, proporciona un header Idempotency-Key en la solicitud. Aprende más sobre solicitudes idempotentes en esta guía.

Crear un Transfer para México 🇲🇽

Aquí hay un ejemplo de cómo crear un Transfer de $590.13 pesos mexicanos:

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

Las monedas se representan como enterosLa API de Fintoc representa las monedas en su unidad mínima posible sin decimales (como entero). Eso significa que un monto de MXN $10.29 se representa en Fintoc como 1029.Puedes leer más sobre monedas aquí.

Recuerda agregar el ID de la institución

Al transferir a una CLABE, no se necesita el ID de la institución de la Counterparty ya que Fintoc puede deducirlo del número CLABE. Sin embargo, si tu Counterparty es un número de teléfono móvil o una tarjeta de débito, debes incluir el ID de la institución como un número de 5 dígitos según se muestra aquí. De lo contrario, obtendrás un error 400.

Usando nuestro SDK

Si estás usando nuestro SDK de Python o de Node, puedes crear la transferencia así:

transfer = client.v2.transfers.create(
  idempotency_key="12345678910",
  amount=59013,
  currency="MXN",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  reference_id="150195",
  counterparty={"account_number": "012969123456789120"},
  metadata={"customer_id": "12050123"}
)

Node

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '12345678910',
  amount: 59013,
  currency: 'mxn',
  account_id: 'acc_2tgq0oPCyMInAZWiZt5',
  counterparty: {
      account_number: '012969100000000026',
    },
  metadata: {
      customer_id: '19385014'
    }
});

En México, el objeto Counterparty se define con un mínimo de 1 atributo:

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

Una respuesta exitosa de la solicitud 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 gas",
  "reference_id": "150195",
  "tracking_key": "s2123423423324334",
  "receipt_url": "https://www.banxico.org.mx/cep/",
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "OODC911119JL3",
    "holder_name": "Carmen Marcela",
    "account_number": "012969123456789120",
    "account_type": "clabe",  
    "institution": {
      "id": "mx_bbva_mexico",
      "name": "BBVA Mexico",
      "country": "mx" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "738969123456789120",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "description": null,
    "metadata": {},
    "object": "account_number",
  },
  "metadata": {
    "order_id": 1234
  }
}

Crear un Transfer para Chile 🇨🇱

Aquí hay un ejemplo para crear una transferencia de $1869 pesos chilenos:

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": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "metadata": {
  	"customer_id": "12050123"
  }
}
'

Usando nuestro SDK

Si estás usando nuestro SDK de Python o de Node, puedes crear la transferencia así:

transfer = client.v2.transfers.create(
  idempotency_key="12345678910",
  amount=1869,
  currency="CLP",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  counterparty={
    "holder_id": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  metadata={"customer_id": "12050123"}
)

Node

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '12345678910',
  amount: 59013,
  currency: 'CLP',
  account_id: 'acc_2tgq0oPCyMInAZWiZt5',
  comment: 'Pago de credito 12543',
  counterparty: {
    holder_id: '771433855',
    holder_name: 'Pied Piper SpA',
    account_number: '012969100000000026',
    account_type: 'checking_account',
    institution_id: 'cl_banco_de_chile'
  },
  metadata: {
      customer_id: '19385014'
  }
});

En Chile, el objeto Counterparty se define con un mínimo de 5 atributos:

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

Una respuesta exitosa de la solicitud 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 gas",
  "reference_id": null,
  "receipt_url": null,
  "tracking_key": null,
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "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": "738969123456789120",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "object": "account_number",
    "description": null,
    "metadata": {}
  },
  "metadata": {
    "order_id": 1234
  }
}

Paso 4: Monitorear el estado de la transferencia

Flujo de estado de la transferencia

El estado de las transferencias puede ser pending, succeeded, failed, returned, return_pending o rejected. Para más detalles sobre los estados de las transferencias, revisa el modelo de datos de Transfers.

Monitorear el estado usando webhooks

Fintoc envía un evento transfer.outbound.succeeded cuando la transferencia se concilia. Usa la guía de webhooks para recibir estos eventos y ejecutar acciones, como enviar una notificación por correo 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: se envía cuando Banco de México o la institución de la contraparte ha rechazado la transferencia. Puedes ver las causas de rechazo aquí. 🇨🇱 En Chile: se envía cuando la institución de la contraparte ha rechazado la transferencia. `rejected` es un estado final y no sufrirá más cambios.
`transfer.outbound.failed`	Se envía cuando la transferencia no ha podido alcanzar la cuenta destino, debido a un error durante el proceso.

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

Inicio

Recursos

Pagos

Transferencias

Domiciliación bancaria

Movimientos

Enviar transferencias

Paso 1: Configurar las llaves de firma JWS y generar la JWS Signature

Paso 2: Agregar fondos a Fintoc

Paso 3: Crear Transfer

Usa una Idempotency Key

Crear un Transfer para México 🇲🇽

Recuerda agregar el ID de la institución

Usando nuestro SDK

Crear un Transfer para Chile 🇨🇱

Usando nuestro SDK

Paso 4: Monitorear el estado de la transferencia

Flujo de estado de la transferencia

Monitorear el estado usando webhooks

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

​Paso 2: Agregar fondos a Fintoc

​Paso 3: Crear Transfer

​Usa una Idempotency Key

​Crear un Transfer para México 🇲🇽

​Recuerda agregar el ID de la institución

​Usando nuestro SDK

​Crear un Transfer para Chile 🇨🇱

​Usando nuestro SDK

​Paso 4: Monitorear el estado de la transferencia

​Flujo de estado de la transferencia

​Monitorear el estado usando webhooks

Paso 1: Configurar las llaves de firma JWS y generar la JWS Signature

Paso 2: Agregar fondos a Fintoc

Paso 3: Crear Transfer

Usa una Idempotency Key

Crear un Transfer para México 🇲🇽

Recuerda agregar el ID de la institución

Usando nuestro SDK

Crear un Transfer para Chile 🇨🇱

Usando nuestro SDK

Paso 4: Monitorear el estado de la transferencia

Flujo de estado de la transferencia

Monitorear el estado usando webhooks