Recibir transferencias

Completa primero la guía de configuración de Business Accounts. Luego sigue estos pasos para recibir transferencias entrantes en Chile o México:

Usa tu llave secreta para crear un Account Number.
Crea un endpoint de webhook para manejar los eventos de transferencias entrantes.
Recibe una transferencia en el Account Number y maneja la notificación del webhook.

El siguiente diagrama muestra cómo Fintoc interactúa contigo y con la contraparte que envía la transferencia entrante.

Paso 1: Crear un Account Number

Un Account Number es la cadena de dígitos que un remitente usa para pagarte. Fintoc genera los dígitos por ti en ambos países:

En México, un Account Number es un número de cuenta bancaria mexicano estandarizado (CLABE). Los remitentes lo alcanzan por el riel del Sistema de Pagos Electrónicos Interbancarios.
En Chile, un Account Number es un número de cuenta bancaria sobre tu Cuenta con Provisión de Fondos (CPF). Los remitentes lo alcanzan por el riel del Centro de Compensación Automatizado y eligen Fintoc como institución de destino.

Asigna el Account Number a un cliente u orden para conciliar tus pagos entrantes. Asigna un account number por cliente. Una transferencia a ese account number identifica entonces al cliente que la envió. Para saber más, revisa el modelo de datos del account number.

Adjunta datos arbitrarios de clave-valor a tu account number

Cuando creas un account number, adjunta datos arbitrarios de clave-valor al objeto metadata. Usa metadata para guardar un identificador único, como el ID interno de tu cliente. Fintoc incluye el objeto metadata en cada transferencia entrante para que puedas conciliar la transferencia contra tus registros internos.

Ejemplo

Con tu llave secreta de prueba y el ID de tu cuenta, crea un AccountNumber desde tu backend, adjuntando un ID interno de cliente id_cliente:

curl --request POST \
     --url https://api.fintoc.com/v2/account_numbers \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_id": "acc_Lq7dP901xZgA2B",
  "metadata": {
   "id_cliente": "12343212"
   }
}
'

const accountNumber = await fintoc.v2.accountNumbers.create({
  account_id: 'acc_Lq7dP901xZgA2B',
  metadata: {
    id_cliente: '12343212',
  },
});

account_number = client.v2.account_numbers.create(
    account_id="acc_Lq7dP901xZgA2B",
    metadata={"id_cliente": "12343212"}
)

{
  "id": "acno_Kasf91034gj1AD",
  "object": "account_number",
  "description": "My payins",
  "number": "111111111111111111",
  "account_id": "acc_Lq7dP901xZgA2B",
  "created_at": "2024-03-01T20:09:42.949787176Z",
  "mode": "test",
  "metadata": {
    "id_cliente": "12343212"
  }
}

Los límites de monto entrante están disponibles solo en Méxicooptions.min_amount y options.max_amount rechazan las transferencias fuera de un rango. Fintoc aplica estos límites a los account numbers mexicanos. Revisa Agregar lógica a los Account Numbers.

Paso 2: Crear un endpoint de webhook para manejar los eventos de transferencias entrantes

Fintoc envía un evento transfer.inbound.succeeded cada vez que recibes una transferencia entrante. Sigue la guía de webhooks para crear un endpoint que reciba estos eventos y ejecute acciones. El evento tiene la misma estructura en ambos países. Lo que difiere es el bloque counterparty y los campos que completa el riel local:

{
  "id": "evt_a4xK32BanKWYn",
  "type": "transfer.inbound.succeeded",
  "object": "event",
  "data": {
    "id": "tr_jKaHD105H",
    "object": "transfer",
    "direction": "inbound",
    "status": "succeeded",
    "amount": 2864,
    "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://www.banxico.org.mx/cep/",
    "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",
      "account_type": "clabe",
      "institution": {
        "id": "40012",
        "name": "BBVA Mexico",
        "country": "mx"
      }
    }
  },
  "created_at": "2020-04-22T21:10:19.254Z",
  "mode": "test"
}

{
  "id": "evt_a4xK32BanKWYn",
  "type": "transfer.inbound.succeeded",
  "object": "event",
  "data": {
    "id": "tr_jKaHD105H",
    "object": "transfer",
    "direction": "inbound",
    "status": "succeeded",
    "amount": 2864,
    "currency": "CLP",
    "mode": "test",
    "post_date": "2020-04-17T00:00:00.000Z",
    "transaction_date": "2020-04-17T05:12:41.462Z",
    "comment": "Electricity bill",
    "reference_id": null,
    "receipt_url": null,
    "tracking_key": null,
    "return_reason": null,
    "account_number": {
      "id": "acno_Kasf91034gj1AD",
      "object": "account_number",
      "account_id": "acc_Lq7dP901xZgA2B",
      "description": "My payins",
      "number": "000000001",
      "created_at": "2024-03-01T20:09:42.949787176Z",
      "mode": "test",
      "metadata": {
        "id_cliente": "12343212"
      }
    },
    "counterparty": {
      "holder_id": "11.111.111-1",
      "holder_name": "Test Customer 1",
      "account_number": "000000000",
      "account_type": "checking_account",
      "institution": {
        "id": "cl_banco_santander",
        "name": "Banco Santander",
        "country": "cl"
      }
    }
  },
  "created_at": "2020-04-22T21:10:19.254Z",
  "mode": "test"
}

En México, el Sistema de Pagos Electrónicos Interbancarios completa reference_id, tracking_key y una receipt_url que apunta al Comprobante Electrónico de Pago. En Chile, esos tres campos vienen en null, y counterparty.holder_id trae el Rol Único Tributario (RUT) del remitente.

Paso 3: Recibir una transferencia en el account number

Después de crear un account number y agregar un endpoint de webhook, ya puedes recibir transferencias y conciliar tus pagos.

Prueba la integración

En modo test, usa el endpoint /v2/simulate/receive_transfer para simular una transferencia entrante. La transferencia simulada se comporta como una transferencia real enviada al mismo account number. Envía tu llave secreta de prueba y el account_number_id que creaste. Envía también un amount en la unidad monetaria más pequeña y un código currency ISO 4217 en mayúsculas:

curl --request POST \
     --url https://api.fintoc.com/v2/simulate/receive_transfer \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     -d account_number_id=acno_Kasf91034gj1AD \
     -d amount=2864 \
     -d currency=MXN

const transfer = await fintoc.v2.simulate.receiveTransfer({
  account_number_id: 'acno_Kasf91034gj1AD',
  amount: 2864,
  currency: 'MXN',
});

transfer = client.v2.simulate.receive_transfer(
    account_number_id="acno_Kasf91034gj1AD",
    amount=2864,
    currency="MXN",
)

{
  "id": "tr_jKaHD105H",
  "object": "transfer",
  "direction": "inbound",
  "status": "succeeded",
  "amount": 2864,
  "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://www.banxico.org.mx/cep/",
  "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",
    "account_type": "clabe",
    "institution": {
      "id": "40012",
      "name": "BBVA Mexico",
      "country": "mx"
    }
  }
}

Para simular una transferencia entrante chilena, envía currency en CLP y describe al remitente con estos parámetros opcionales:

Parámetro	Descripción
`counterparty_account_number`	Número de cuenta bancaria del remitente simulado. Por defecto, una contraparte de prueba de Fintoc.
`counterparty_account_type`	Tipo de cuenta del remitente simulado. Uno de `checking_account` o `sight_account`.
`counterparty_holder_id`	Rol Único Tributario (RUT) del remitente simulado.
`counterparty_holder_name`	Nombre del titular de la cuenta del remitente simulado.
`counterparty_institution_id`	Institución del remitente simulado, como `cl_banco_santander`. Revisa los códigos de institución de Chile.

El endpoint liquida la transferencia y entrega un evento transfer.inbound.succeeded a tu endpoint de webhook. El evento contiene el payload que se muestra en el Paso 2. Recibir el evento transfer.inbound.succeeded confirma que tu integración funciona. Para el conjunto completo de valores de prueba, revisa Prueba tu integración.

​Paso 1: Crear un Account Number

​Adjunta datos arbitrarios de clave-valor a tu account number

​Ejemplo

​Paso 2: Crear un endpoint de webhook para manejar los eventos de transferencias entrantes

​Paso 3: Recibir una transferencia en el account number

​Prueba la integración

Paso 1: Crear un Account Number

Adjunta datos arbitrarios de clave-valor a tu account number

Ejemplo

Paso 2: Crear un endpoint de webhook para manejar los eventos de transferencias entrantes

Paso 3: Recibir una transferencia en el account number

Prueba la integración