Recibir transferencias

Transferencias entrantes en México

Completa primero la guía de configuración. Para recibir transferencias entrantes, sigue estos pasos:

Crea un account_number, una Clave Bancaria Estandarizada (CLABE) usada por el riel del Sistema de Pagos Electrónicos Interbancarios (SPEI), con tu clave secreta.
Crea un endpoint de webhook para manejar los eventos de transferencias entrantes.
Recibe una transferencia en el account number y recibe la notificación por webhook.

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

Paso 1: Crear un account number (CLABE)

Un AccountNumber representa una CLABE. Puedes pensar en el account number como una referencia que asignas a un cliente u orden para conciliar tus pagos entrantes. Asigna un account number por cliente, de modo que una transferencia a ese account number identifique al cliente del que proviene. Para conocer más sobre los account numbers, consulta el modelo de datos.

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 tu identificador único de ese account number, como tu ID interno de cliente. Cuando recibes una transferencia entrante, Fintoc adjunta el objeto metadata para que puedas conciliar la transferencia con tus registros internos.

Ejemplo

Usando tu clave secreta de prueba y tu ID de 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"
   }
}
'

Node

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

Python

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

La respuesta debería verse así:

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

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

Cada vez que recibes una transferencia entrante, Fintoc envía un evento transfer.inbound.succeeded. Sigue la guía de webhooks para aprender a crear un endpoint de webhook que reciba estos eventos y ejecute acciones. El evento transfer.inbound.succeeded se ve así:

{
  "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",
      "type": "clabe",
      "institution": {
        "id": "40012",
        "name": "BBVA Mexico",
        "country": "mx"
      }
    }
  },
  "created_at": "2020-04-22T21:10:19.254Z",
  "mode": "test"
}

Paso 3: Recibir una transferencia en el account number

Ahora que creaste un account number y agregaste un endpoint de webhook para manejar las notificaciones, puedes recibir transferencias a ese account number y empezar a conciliar tus pagos.

Probar la integración

En modo test, usa el endpoint /v2/simulate/receive-transfer para simular una transferencia entrante. El comportamiento es idéntico al de una transferencia real enviada al mismo account number. Pasa tu clave secreta de prueba, el account_number_id que creaste, un amount en la unidad mínima de la moneda y el código currency en ISO 4217 en minú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

Node

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

Python

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

Response

{
  "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",
    "type": "clabe",
    "institution": {
      "id": "40012",
      "name": "BBVA Mexico",
      "country": "mx"
    }
  }
}

El endpoint liquida la transferencia y entrega un evento transfer.inbound.succeeded a tu endpoint de webhook con el payload mostrado arriba. Recibir ese evento confirma que tu integración está funcionando. Para conocer el conjunto completo de valores de prueba, consulta Prueba tu integración.

Transferencias entrantes en Chile

Completa primero la guía de configuración. Para recibir transferencias entrantes, sigue estos pasos:

Identifica tu cuenta y su root_account_number, el account number que recibe la transferencia. Consulta el modelo de datos de cuenta para aprender cómo se provisiona.
Crea un endpoint de webhook para manejar los eventos de transferencias entrantes.
Recibe una transferencia en tu cuenta y recibe la notificación por webhook.

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

Paso 1: Identificar tu cuenta

Cada cuenta chilena tiene un root_account_number, el account number que recibe las transferencias entrantes. Este es el account_number que aparece en el payload transfer.inbound.succeeded que se muestra abajo. Consulta el modelo de datos de cuenta para aprender cómo se provisiona.

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

{
  "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": "111111111111111111",
      "created_at": "2024-03-01T20:09:42.949787176Z",
      "mode": "test",
      "metadata": {
        "id_cliente": "12343212"
      }
    },
    "counterparty": {
      "holder_id": "11111111-1",
      "holder_name": "Test Customer 1",
      "account_number": "000000000",
      "type": "checking_account",
      "code": "01",
      "institution": {
        "id": "cl_banco_santander",
        "name": "Banco Santander",
        "country": "cl"
      }
    }
  },
  "created_at": "2020-04-22T21:10:19.254Z",
  "mode": "test"
}

Paso 3: Recibir una transferencia en tu cuenta

Ahora que identificaste tu cuenta y su root_account_number y agregaste un endpoint de webhook para manejar las notificaciones, puedes recibir transferencias en ella y empezar a conciliar tus pagos.

Probar la integración

En modo test, usa el endpoint /v2/simulate/receive-transfer para simular una transferencia entrante. El comportamiento es idéntico al de una transferencia real enviada al mismo account number. Pasa tu clave secreta de prueba, el account_number_id de tu cuenta, un amount en la unidad mínima de la moneda y el código currency en ISO 4217 en minú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=clp

Node

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

Python

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

Response

{
  "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": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "metadata": {
      "id_cliente": "12343212"
    }
  },
  "counterparty": {
    "holder_id": "11111111-1",
    "holder_name": "Test Customer 1",
    "account_number": "000000000",
    "type": "checking_account",
    "code": "01",
    "institution": {
      "id": "cl_banco_santander",
      "name": "Banco Santander",
      "country": "cl"
    }
  }
}

Inicio

Recursos

Pagos

Transferencias

Movimientos

Recibir transferencias

Transferencias entrantes en México

Paso 1: Crear un account number (CLABE)

Adjunta datos arbitrarios de clave-valor a tu account number

Ejemplo

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

Paso 3: Recibir una transferencia en el account number

Probar la integración

Transferencias entrantes en Chile

Paso 1: Identificar tu cuenta

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

Paso 3: Recibir una transferencia en tu cuenta

Probar la integración

​Transferencias entrantes en México

​Paso 1: Crear un account number (CLABE)

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

​Ejemplo

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

​Paso 3: Recibir una transferencia en el account number

​Probar la integración

​Transferencias entrantes en Chile

​Paso 1: Identificar tu cuenta

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

​Paso 3: Recibir una transferencia en tu cuenta

​Probar la integración

Transferencias entrantes en México

Paso 1: Crear un account number (CLABE)

Adjunta datos arbitrarios de clave-valor a tu account number

Ejemplo

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

Paso 3: Recibir una transferencia en el account number

Probar la integración

Transferencias entrantes en Chile

Paso 1: Identificar tu cuenta

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

Paso 3: Recibir una transferencia en tu cuenta

Probar la integración