Receive transfers

Inbound transfers in Mexico

Complete the transfers setup guide first. Then follow these steps to receive inbound transfers:

Use your secret key to create an account_number. This account number is a standardized Mexican bank account number (CLABE) used on the Sistema de Pagos Electrónicos Interbancarios (SPEI) rail.
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 (CLABE)

An AccountNumber represents a CLABE. 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"
   }
}
'

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

The API returns the following response:

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

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 transfer.inbound.succeeded event looks like this:

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

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 a lowercase 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

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

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.

Inbound transfers in Chile

Complete the transfers setup guide first. Then follow these steps to receive inbound transfers:

Identify your account and its root_account_number, which receives the transfer. See the account data model to learn how Fintoc provisions this account number.
Create a webhook endpoint to handle inbound transfer events.
Receive a transfer at your account and handle the webhook notification.

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

Step 1: Identify your account

Each Chilean account has a root_account_number that receives inbound transfers. This value appears as account_number in the transfer.inbound.succeeded payload below. See the account data model to learn how Fintoc provisions this account number.

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

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

Step 3: Receive a transfer at your account

After you identify your account and its root_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 your account’s account_number_id. Also pass an amount in the smallest currency unit and a lowercase 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=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"
    }
  }
}

Home

Resources

Payments

Transfers

Movements

Receive transfers

Inbound transfers in Mexico

Step 1: Create an account number (CLABE)

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

Inbound transfers in Chile

Step 1: Identify your account

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

Step 3: Receive a transfer at your account

Test the integration

​Inbound transfers in Mexico

​Step 1: Create an account number (CLABE)

​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

​Inbound transfers in Chile

​Step 1: Identify your account

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

​Step 3: Receive a transfer at your account

​Test the integration

Inbound transfers in Mexico

Step 1: Create an account number (CLABE)

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

Inbound transfers in Chile

Step 1: Identify your account

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

Step 3: Receive a transfer at your account

Test the integration