Send transfers

Complete the Business Accounts setup guide, then follow these steps to send outbound transfers:

Configure JSON Web Signature (JWS) signing keys and generate a JWS signature.
Add funds to the account’s root_account_number.
Create a transfer from your backend using your secret key and a JWS signature.
Monitor transfer status.

The following diagram shows how Fintoc interacts with you and the counterparty receiving the payout.

Step 1: Configure JWS signing keys and generate a JWS signature

Every request to a Fintoc Business Accounts API endpoint requires a JWS signature. JWS digitally signs data to verify its integrity and authenticity. To sign an API request, follow the JWS signature guide.

Step 2: Add funds to Fintoc

Before creating transfers, deposit funds into your Account through its root_account_number. The deposit appears as an inbound transfer.

Step 3: Create a transfer

After you add funds to your account, create a transfer from your backend. Include your test secret key, JWS signature, origin account, amount, currency, and counterparty. The following examples show successful transfer responses. To test other terminal outcomes, use the table in Test the integration.

Use an idempotency key

Fintoc supports idempotency so you can retry transfers without creating duplicates. Use an idempotency key when creating a transfer. If a connection error occurs, retry the request with the same key. To make an idempotent request, include the Idempotency-Key header. See Idempotent requests for details.

Create a transfer for Mexico 🇲🇽

Here is an example that creates a transfer of $590.13 MXN. The amount field is in the smallest currency unit, so $590.13 is the integer 59013. A successful request returns the created Transfer:

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'Fintoc-JWS-Signature: CNMaYaDGU3ZhFV1ve6p3sAdYXhEklej8DVIAMqIWCkpNmT6Jp7iigcndXwH5q3WQFHiswgIQU5-_-4rV3jKGptCROmEyWPW8_elhYH1apzAyjOjyZ55ygv37xKHzIFhixzAwmXlAv4pfD4lVelYWVNOSN7REA0QJeCy2vKdqZ5cjqCXQ1lkQUlzOE7dpuNoAkhAhAJJ8HaamFKy7Gl7uwmqbIr-dVYv21d_9O7mO26n0gy3zWXD2nJDxU5Mzl2pZd8-sFvUr9Kmp_YkeRMh4bSe0fr1Uc_YgkjpmYUyu7kaxRWTbAdJ3GwqWFMUDiyfhHdzvZPZyU4VkWreimoydMA' \
     --header 'Idempotency-Key: 1ebfd86c-a75b-4606-872f-9f1cdd9724ca' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 59013,
  "currency": "MXN",
  "account_id": "acc_M8sKf230BgHjD4",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "counterparty": {
    "account_number": "012000000000000001"
  },
  "metadata": {
  	"customer_id": "12050123"
   }
}
'

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca',
  amount: 59013,
  currency: 'MXN',
  account_id: 'acc_M8sKf230BgHjD4',
  comment: 'Pago de credito 10451',
  reference_id: '150195',
  counterparty: { account_number: '012000000000000001' },
  metadata: { customer_id: '12050123' }
});

transfer = client.v2.transfers.create(
  idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca",
  amount=59013,
  currency="MXN",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  reference_id="150195",
  counterparty={"account_number": "012000000000000001"},
  metadata={"customer_id": "12050123"}
)

{
  "object": "transfer", 
  "id": "tr_jKaHD105H",
  "amount": 59013,  
  "currency": "MXN", 
  "direction": "outbound",
  "status": "succeeded",
  "transaction_date": "2020-04-17T05:12:41.462Z",
  "post_date": "2020-04-17T00:00:00.000Z",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "tracking_key": "s2123423423324334",
  "receipt_url": "https://www.banxico.org.mx/cep/",
  "mode": "test",
  "return_reason": null,
  "settled_amount": 59013,
  "counterparty": {
    "holder_id": "AAA010101AAA",
    "holder_name": "Test Customer 1",
    "account_number": "012000000000000001",
    "account_type": "clabe",  
    "institution": {
      "id": "mx_bbva_mexico",
      "name": "BBVA Mexico",
      "country": "mx" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "description": null,
    "metadata": {},
    "object": "account_number"
  },
  "metadata": {
    "customer_id": "12050123"
  }
}

Currencies are represented as integersFor example, Fintoc represents MXN $10.29 as 1029.See Currencies for details.

Add institution_id for mobile numbers and debit cardsWhen transferring to a standardized Mexican bank account number (CLABE), you do not need institution_id. Fintoc determines the institution from the CLABE. For a mobile phone number or debit card, include the five-digit institution_id from the Banco de México institution list. Otherwise, the API returns a 400 Bad Request error.

In Mexico, the Counterparty object requires one attribute:

Parameter	Description
`account_number`	The recipient’s CLABE, mobile number, or debit card number.

Create a transfer for Chile 🇨🇱

Here is an example that creates a transfer of $1,869 CLP. Because CLP has no minor unit, the amount field is the same integer, 1869. A successful request returns the created Transfer:

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'Fintoc-JWS-Signature: CNMaYaDGU3ZhFV1ve6p3sAdYXhEklej8DVIAMqIWCkpNmT6Jp7iigcndXwH5q3WQFHiswgIQU5-_-4rV3jKGptCROmEyWPW8_elhYH1apzAyjOjyZ55ygv37xKHzIFhixzAwmXlAv4pfD4lVelYWVNOSN7REA0QJeCy2vKdqZ5cjqCXQ1lkQUlzOE7dpuNoAkhAhAJJ8HaamFKy7Gl7uwmqbIr-dVYv21d_9O7mO26n0gy3zWXD2nJDxU5Mzl2pZd8-sFvUr9Kmp_YkeRMh4bSe0fr1Uc_YgkjpmYUyu7kaxRWTbAdJ3GwqWFMUDiyfhHdzvZPZyU4VkWreimoydMA' \
     --header 'Idempotency-Key: 1ebfd86c-a75b-4606-872f-9f1cdd9724ca' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 1869,
  "currency": "CLP",
  "account_id": "acc_M8sKf230BgHjD4",
  "comment": "Pago de credito 10451",
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "metadata": {
  	"customer_id": "12050123"
  }
}
'

const transfer = await fintoc.v2.transfers.create({
  idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca',
  amount: 1869,
  currency: 'CLP',
  account_id: 'acc_M8sKf230BgHjD4',
  comment: 'Pago de credito 10451',
  counterparty: {
    holder_id: '11.111.111-1',
    holder_name: 'Test Customer 1',
    account_number: '11111111',
    account_type: 'checking_account',
    institution_id: 'cl_banco_de_chile'
  },
  metadata: { customer_id: '12050123' }
});

transfer = client.v2.transfers.create(
  idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca",
  amount=1869,
  currency="CLP",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  counterparty={
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  metadata={"customer_id": "12050123"}
)

{
  "object": "transfer",
  "id": "tr_jKaHD105H",
  "amount": 1869,   
  "currency": "CLP", 
  "direction": "outbound",
  "status": "succeeded",
  "transaction_date": "2020-04-17T05:12:41.462Z",
  "post_date": "2020-04-17T00:00:00.000Z", 
  "comment": "Pago de credito 10451",
  "reference_id": null,
  "receipt_url": null,
  "tracking_key": null,
  "mode": "test",
  "return_reason": null,
  "settled_amount": 1869,
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "account_type": "checking_account", 
    "institution": {
      "id": "cl_banco_de_chile",
      "name": "Banco de Chile",
      "country": "cl" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "111111111111111111",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "object": "account_number",
    "description": null,
    "metadata": {}
  },
  "metadata": {
    "customer_id": "12050123"
  }
}

In Chile, the Counterparty object requires five attributes:

Parameter	Description
`holder_id`	The account holder’s Chilean tax ID (RUT).
`holder_name`	The account holder’s full name.
`account_number`	The recipient’s bank account number at the counterparty institution.
`account_type`	Type of account. Supported types are `checking_account` and `sight_account`.
`institution_id`	Fintoc institution ID for the bank receiving the transfer. See Chilean institution codes.

Large transfers in Chile

Some Chilean banks cap incoming transfers at $7,000,000 CLP. To send more, create one transfer for the full amount. Fintoc splits every outbound transfer over $7,000,000 CLP into parts of up to $7,000,000 CLP, whatever the counterparty’s bank, and sends each part to the counterparty.

Transfers between Fintoc accounts are not splitA transfer to another Fintoc account settles immediately for the full amount, with no $7,000,000 CLP limit. The counterparty receives one transfer and has no parts to reconcile. When your suppliers, customers, or partners also hold Fintoc accounts, every payment between you arrives this way.

You work with one transfer. The API returns a single Transfer with the full amount. Webhooks, the receipt, and the account movement all belong to that transfer. The parts do not appear in the API.
The counterparty receives one transfer per part. Every part is $7,000,000 CLP except the last, which can be smaller. For example, $15,000,000 CLP arrives as $7,000,000, $7,000,000, and $1,000,000 CLP.
Each part’s comment names its position. Fintoc appends X de N to your comment so the counterparty can reconcile the parts. For example, Factura 1042 becomes Factura 1042 2 de 3 on the second of three parts. Without a comment, the part’s comment is only 2 de 3. To keep each part’s comment within 40 characters, Fintoc truncates your comment to leave room for the suffix. A transfer split into 2 to 9 parts keeps the first 33 characters. The comment on the Transfer stays as you sent it.
Your balance must cover the full amount. Fintoc holds the full amount when you create the transfer. If your balance is lower, the request fails and Fintoc sends no parts.
Parts go out one after another. A split transfer stays pending longer than a single transfer.

The transfer stays pending until every part finishes. A part can fail if, for example, the counterparty’s bank goes down while Fintoc is still sending the parts. When every part finishes, the transfer reaches one of these statuses:

Parts that settle	Transfer `status`	`settled_amount`	Webhook event
All	`succeeded`	Equal to `amount`	`transfer.outbound.succeeded`
Some	`partially_succeeded`	Sum of the parts that settled	`transfer.outbound.partially_succeeded`
None	`failed`	`0`	`transfer.outbound.failed`

Fintoc returns the amount of every part that does not settle to your available balance, and does not retry those parts. To send the rest of a partially_succeeded transfer, create a new transfer for amount minus settled_amount.

To receive a notification when a split transfer reaches partially_succeeded, subscribe your webhook endpoint to transfer.outbound.partially_succeeded.

Step 4: Monitor transfer status

Transfer status flow

A transfer’s status is one of pending, succeeded, failed, returned, return_pending, rejected, or reject_failed. Chilean transfers add partially_succeeded, reverse_pending, and reversed. For more details on transfer statuses, see the Transfer data model.

Monitor status using webhooks

Fintoc sends a transfer.outbound.succeeded event when the transfer settles. Use the webhook guide to receive these events. You can then notify your customer or log the transfer in your ERP. Subscribe your webhook endpoint to these events and handle each one, including transfer.outbound.partially_succeeded if you send Chilean transfers over $7,000,000 CLP:

Event	Description
`transfer.outbound.succeeded`	Sent when the transfer settles successfully.
`transfer.outbound.partially_succeeded`	🇨🇱 Sent when only some parts of a split transfer settle.
`transfer.outbound.rejected`	Sent when Banco de México or the recipient institution rejects a transfer in Mexico, or when the recipient institution rejects the transfer in Chile. See the rejection causes; `rejected` is a final status.
`transfer.outbound.failed`	Sent when the transfer cannot reach the destination account because an error occurs during processing.
`transfer.outbound.reversed`	🇨🇱 Sent when a settled transfer is reversed.

Webhooks may arrive out of orderFor example, a transfer.outbound.rejected event can arrive before the same transfer’s transfer.outbound.succeeded event. The transfer still succeeded before it was rejected.

Test the integration

Use your test secret key (sk_test_...) to run transfers in test mode without moving real money. Every response sets mode to test. In test mode, a transfer reaches the same terminal statuses as in production. Predefined inputs do not force an outcome. The outcome depends on how the receiving party resolves the transfer. Use these terminal statuses to confirm your webhook handling:

Outcome	Resulting status	Webhook event
Succeeded	`succeeded`	`transfer.outbound.succeeded`
🇨🇱 Partially succeeded	`partially_succeeded`	`transfer.outbound.partially_succeeded`
Rejected	`rejected`	`transfer.outbound.rejected`
Failed	`failed`	`transfer.outbound.failed`
🇨🇱 Reversed	`reversed`	`transfer.outbound.reversed`

​Step 1: Configure JWS signing keys and generate a JWS signature

​Step 2: Add funds to Fintoc

​Step 3: Create a transfer

​Use an idempotency key

​Create a transfer for Mexico 🇲🇽

​Create a transfer for Chile 🇨🇱

​Large transfers in Chile

​Step 4: Monitor transfer status

​Transfer status flow

​Monitor status using webhooks

​Test the integration

Step 1: Configure JWS signing keys and generate a JWS signature

Step 2: Add funds to Fintoc

Step 3: Create a transfer

Use an idempotency key

Create a transfer for Mexico 🇲🇽

Create a transfer for Chile 🇨🇱

Large transfers in Chile

Step 4: Monitor transfer status

Transfer status flow

Monitor status using webhooks

Test the integration