DashboardHome
Guides
GuidesAPI ReferenceChangelog

Inbound transfers

Automatically track and reconcile your incoming payments in real time.

Suggest Edits

🇲🇽 Inbound Transfers in Mexico

To start using Fintoc's inbound Transfer API, you just need to create an account on our Dashboard and follow these five steps:

  1. Get your test API Keys
  2. Find or create an Account to relate your Account Number to. When you log into the dashboard will start out with one Default Account.
  3. Find or create an AccountNumber—or a SPEI CLABE— using your Secret key. When you log into the dashboard will start out with one Default Account Number.
  4. Create a WebhookEndpoint to handle incoming transfer events
  5. Receive a transfer at the created AccountNumber and get notified in real-time

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



Step 1: Get your test API Keys

Every interaction with the Fintoc API must be authenticated with the API Keys of your Fintoc account. If an interaction does not include your API Key or includes an incorrect API Key, Fintoc will return an error.

Every Fintoc account has two key pairs: one corresponds to the test mode and the other to the live API environment. Every resource is stored either in test mode or in live mode, and resources from one environment cannot be manipulated by resources from the other environment.

Your API Keys will be available in the Dashboard. First, you need to create an account on the Fintoc Dashboard. Once your Fintoc account has been created, you will be able to get your API Keys. In this case, you must use the Secret Key from test mode. We added the prefix sk_test_to quickly identify it.

Step 2: Find your Account ID

An Account is the object that keeps track of the balance you have available in Fintoc to use for Outbound Transfers. To receive an Inbound Transfer, you will need to find your Account ID to use as a parameter for creating an Account Number to receive Inbound Transfers at.

Example

Get your Accounts via API like this:

curl --request GET \
     --url https://api.fintoc.com/v2/accounts \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \

The response should look like this:

[
  {
    "id": "acc_23JlasHas241",
    "object": "account",
    "mode": "test",
    "description": "My root account",
    "root_account_number": "738969123456789120",
    "root_account_number_id": "acno_Kasf91034gj1AD",
    "available_balance": 0
    "currency": "MXN",
    "entity": {
          "id": "en_4324qwkalsds",
          "holder_name": "ACME Inc.",
          "holder_id": "ND"
      }
	}
]

As you can see, your Account has a root_account_number. You can use this Account Number to receive Inbound Transfers.

If you want to receive them at a different one, and attach specific metadata, go on to Step 2 to create one 👇

Step 3: Create an Account Number (SPEI CLABE)

An AccountNumber represents a SPEI CLABE. You can think of an account number as a reference that you can assign to a customer—or order— to easily reconcile your incoming payments. Companies usually assign one Account Number per customer so that when they receive a transfer to that Account Number, they automatically know that it comes from that specific customer.

💡

Account number limit

By default, you can create up to 100,000 Account Numbers per organization. If you need to create more than 100,000 Account Numbers, contact your sales rep.

Attach arbitrary key-value data to your account number

When you create an account number, you can attach arbitrary key-value data to it using the Metadata object. You can use metadata to store your unique identifier for that account number, such as your internal customer ID. When you receive an inbound transfer, the metadata object will be attached so you can easily 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"
   }
}
'

The response should look like this:

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

Step 4: Create a Webhook Endpoint to handle inbound transfer events

Whenever you receive an inbound transfer, Fintoc will send you 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_Jas92lf9adg94ka",
      "description": "My payins",
      "number": "738969123456789120",
      "created_at": "2024-03-01T20:09:42.949787176Z",
      "mode": "test",
      "metadata": {
        "client_id": "12343212"
      }
    },
    "counterparty": {
      "holder_id": "OODC911119JL3",
      "holder_name": "Carmen Marcela",
      "account_number": "012969123456789120",
      "type": "clabe", 
      "type": "40", 
      "institution": {
        "id": "40012",
        "name": "BBVA Mexico",
        "country": "mx" 
       }
     }
  },
  "created_at": "2020-04-22T21:10:19.254Z",
  "mode": "test"
}

Step 5: 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.

If you want to try everything in test mode, you can use our /simulate/receive-transfer endpoint to simulate an inbound transfer. The behavior is identical to what would happen if you send a real transfer to the specified account number. See our test guide to learn how you can simulate a transfer.

🇨🇱 Inbound Transfers in Chile

To start using Fintoc's inbound Transfer API, you just need to create an account on our Dashboard and follow these five steps:

  1. Get your test API Keys
  2. Find or create an Account. When you log into the dashboard will start out with one Default Account. You will find yout AccountNumber referenced in the root_account_number and root_account_number_id attributes in your Account
  3. Create a WebhookEndpoint to handle incoming transfer events
  4. Receive a transfer at your Account and get notified in real-time

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


Step 1: Get your test API Keys

Every interaction with the Fintoc API must be authenticated with the API Keys of your Fintoc account. If an interaction does not include your API Key or includes an incorrect API Key, Fintoc will return an error.

Every Fintoc account has two key pairs: one corresponds to the test mode and the other to the live API environment. Every resource is stored either in test mode or in live mode, and resources from one environment cannot be manipulated by resources from the other environment.

Your API Keys will be available in the Dashboard. First, you need to create an account on the Fintoc Dashboard. Once your Fintoc account has been created, you will be able to get your API Keys. In this case, you must use the Secret Key from test mode. We added the prefix sk_test_to quickly identify it.

Step 2: Find your Account ID

An Account is the object that keeps track of the balance you have available in Fintoc to use for Outbound Transfers. To receive an Inbound Transfer, you will need to find your Account's root Account Number information where you will receive Inbound Transfers at.

Example

Get your Accounts via API like this:

curl --request GET \
     --url https://api.fintoc.com/v2/accounts \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \

The response should look like this:

[
  {
    "id": "acc_23JlasHas241",
    "object": "account",
    "mode": "test",
    "description": "My root account",
    "root_account_number": "738969123456789120",
    "root_account_number_id": "acno_Kasf91034gj1AD",
    "available_balance": 0
    "currency": "CLP",
    "entity": {
          "id": "en_4324qwkalsds",
          "holder_name": "ACME Inc.",
          "holder_id": "ND"
      }
	}
]

As you can see, your Account has a root_account_number. You can use this number to receive Inbound Transfers.

Step 3: Create a Webhook Endpoint to handle inbound transfer events

Whenever you receive an inbound transfer, Fintoc will send you 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": "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_Jas92lf9adg94ka",
      "description": "My payins",
      "number": "738969123456789120",
      "created_at": "2024-03-01T20:09:42.949787176Z",
      "mode": "test",
      "metadata": {
        "client_id": "12343212"
      }
    },
    "counterparty": {
      "holder_id": "24354783K",
      "holder_name": "Carmen Marcela",
      "account_number": "012969123456789120",
      "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 4: Receive a transfer at your 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.

If you want to try everything in test mode, you can use our /simulate/receive_transfer endpoint to simulate an inbound transfer. The behavior is identical to what would happen if you send a real transfer to the specified account number. See our test guide to learn how you can simulate a transfer.

Updated about 8 hours ago

What’s Next