Receive transfers

Complete the Business Accounts setup guide first. Then follow these steps to receive inbound transfers in Chile or Mexico:

Use your secret key to create an Account Number.
Create a webhook endpoint to handle inbound transfer events.
Receive a transfer at the Account Number and handle the webhook notification.

The following diagram shows how Fintoc interacts with you and the counterparty that sends the inbound transfer.

Step 1: Create an Account Number

An Account Number is the string of digits a sender uses to pay you. Fintoc generates the digits for you in both countries:

In Mexico, an Account Number is a standardized Mexican bank account number (CLABE). Senders reach it over the Sistema de Pagos Electrónicos Interbancarios rail.
In Chile, an Account Number is a bank account number on your Cuenta con Provisión de Fondos (CPF). Senders reach it over the Centro de Compensación Automatizado rail and select Fintoc as the destination institution.

Assign the Account Number to a customer or order to reconcile your incoming payments. Assign one Account Number per customer. A transfer to that Account Number then identifies the customer who sent the transfer. To learn more, see the Account Number data model.

Attach arbitrary key-value data to your Account Number

When you create an Account Number, attach arbitrary key-value data to the metadata object. Use metadata to store a unique identifier, such as your internal customer ID. Fintoc includes the metadata object with each inbound transfer so you can reconcile the transfer against your internal records.

Example

Using your test secret key and your account ID, create an AccountNumber from your backend, attaching an internal customer ID 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"
  }
}

Inbound amount limits are available in Mexico onlyoptions.min_amount and options.max_amount reject transfers outside a range. Fintoc applies these limits to Mexican Account Numbers. See Add logic to Account Numbers.

Step 2: Create a webhook endpoint to handle inbound transfer events

Fintoc sends a transfer.inbound.succeeded event whenever you receive an inbound transfer. Follow the webhook guide to create an endpoint that receives these events and runs actions. The event carries the same structure in both countries. The counterparty block and the fields the local rail fills in differ:

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

In Mexico, the Sistema de Pagos Electrónicos Interbancarios fills in reference_id, tracking_key, and a receipt_url that points to the Comprobante Electrónico de Pago. In Chile, those three fields are null, and counterparty.holder_id carries the sender’s Chilean tax ID (RUT).

Step 3: Receive a transfer at the Account Number

After you create an Account Number and add a webhook endpoint, you can receive transfers and reconcile your payments.

Test the integration

In test mode, use the /v2/simulate/receive_transfer endpoint to simulate an inbound transfer. The simulated transfer behaves like a real transfer sent to the same Account Number. Pass your test secret key and the account_number_id you created. Also pass an amount in the smallest currency unit and an uppercase ISO 4217 currency code:

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

To simulate a Chilean inbound transfer, set currency to CLP and describe the sender with these optional parameters:

Parameter	Description
`counterparty_account_number`	Bank account number of the simulated sender. Defaults to a Fintoc test counterparty.
`counterparty_account_type`	Type of the simulated sender account. One of `checking_account` or `sight_account`.
`counterparty_holder_id`	Chilean tax ID (RUT) of the simulated sender.
`counterparty_holder_name`	Name of the simulated sender account holder.
`counterparty_institution_id`	Institution of the simulated sender, such as `cl_banco_santander`. See Chilean institution codes.

The endpoint settles the transfer and delivers a transfer.inbound.succeeded event to your webhook endpoint. The event contains the payload shown in Step 2. Receiving the transfer.inbound.succeeded event confirms your integration is working. For the full set of test values, see Test your integration.

​Step 1: Create an Account Number

​Attach arbitrary key-value data to your Account Number

​Example

​Step 2: Create a webhook endpoint to handle inbound transfer events

​Step 3: Receive a transfer at the Account Number

​Test the integration

Step 1: Create an Account Number

Attach arbitrary key-value data to your Account Number

Example

Step 2: Create a webhook endpoint to handle inbound transfer events

Step 3: Receive a transfer at the Account Number

Test the integration