Receive transfers

Inbound transfers in Mexico

Complete the setup guide first. To receive inbound transfers, follow these steps:

Create an account_number, a standardized Mexican bank account number (CLABE) used by the Sistema de Pagos Electrónicos Interbancarios (SPEI) rail, with your secret key.
Create a webhook endpoint to handle inbound transfer events.
Receive a transfer at the account number and get notified by webhook.

The following diagram shows how Fintoc interacts with you and the counterparty creating the payin.

Step 1: Create an account number (CLABE)

An AccountNumber represents a CLABE. You can think of the account number as a reference that you assign to a customer or order to reconcile your incoming payments. Assign one account number per customer, so a transfer to that account number identifies the customer it came from. To learn more about account numbers, see the 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 your unique identifier for that account number, such as your internal customer ID. When you receive an inbound transfer, Fintoc attaches the metadata object 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"}
)

The response should look like this:

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

Whenever you receive an inbound transfer, Fintoc sends a transfer.inbound.succeeded event. Follow the webhook guide to learn how to create a webhook endpoint to receive these events and run 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

Now that you have created an account number and added a webhook endpoint to handle notifications, you can transfer to it and start reconciling your payments.

Test the integration

In test mode, use the /v2/simulate/receive-transfer endpoint to simulate an inbound transfer. The behavior is identical to a real transfer sent to the same account number. Pass your test secret key, the account_number_id you created, an amount in the smallest currency unit, and the 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

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",
    "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 with the payload shown above. Receiving that event confirms your integration is working. For the full set of test values, see Test your integration.

Inbound transfers in Chile

Complete the setup guide first. To receive inbound transfers, follow these steps:

Identify your account and its root_account_number, the account number that receives the transfer. See the account data model to learn how it is provisioned.
Create a webhook endpoint to handle inbound transfer events.
Receive a transfer at your account and get notified by webhook.

The following diagram shows how Fintoc interacts with you and the counterparty creating the payin.

Step 1: Identify your account

Each Chilean account has a root_account_number, the account number that receives inbound transfers. This is the account_number that appears in the transfer.inbound.succeeded payload below. See the account data model to learn how it is provisioned.

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

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

Now that you have identified your account and its root_account_number and added a webhook endpoint to handle notifications, you can transfer to it and start reconciling your payments.

Test the integration

In test mode, use the /v2/simulate/receive-transfer endpoint to simulate an inbound transfer. The behavior is identical to a real transfer sent to the same account number. Pass your test secret key, the account_number_id for your account, an amount in the smallest currency unit, and the 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

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

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

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