DashboardHome
Guides
GuidesAPI ReferenceChangelog

Sending transfers

Initiate real-time payments using our outbound Transfers API

Suggest Edits

To start using Fintoc's Transfers API to create outbound transfers, once you have completed the setup guide, you just need to follow these steps:

  1. Configure JWS Signing Keys and generate JWS Signature
  2. Add funds to the Account's root_account_number
  3. From your backend, create a Transfer using your Secret Key and a JWS Signature
  4. Monitor transfer status

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

Step 1: Configure JWS Signing Keys and generate JWS Signature

To make requests to our Transfers endpoints, a JSON Web Signature (JWS) is required. JWS is a standard mechanism used to digitally sign a piece of data to ensure its integrity and authenticity.

To learn how to sign an API call, follow the steps in the JWS Signature guide.

Step 2: Add funds to Fintoc

To create Transfers, fund your Account first. You can achieve this by adding funds to the root_account_number. This will appear as an Inbound Transfer.

Step 3: Create Transfer

You can start making real-time transfers once you add funds to your account. Using your test Secret Key and including your JWS Signature, create a Transfer from your backend with the origin account (where the funds should come out of), amount, currency, and counterparty that will receive the payment.

The examples below show successful Transfer responses. You can test out unsuccessful results with the predefined inputs in the Test your integration section.

Use an Idempotency Key

Fintoc supports idempotency to safely retry Transfers without accidentally performing the same operation twice. When creating a Transfer, use an idempotency key. Then, if a connection error occurs, you can safely repeat the Transfers request without risk of creating a second Transfer.

To perform an idempotent request, provide an Idempotency-Key header to the request. Learn more about idempotent request in this guide.

Create a Transfer for Mexico 🇲🇽

Here is an example of how to create a Transfer for $590.13 Mexican Pesos:

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": "012969123456789120"
  },
  "metadata": {
  	"customer_id": "12050123"
   }
}
'

🚧

Currencies are represented as integers

The Fintoc API represents currencies in its smallest possible units with no decimals (as an integer). That means that an amount of MXN $10.29 gets represented by Fintoc as 1029.

You can read more about currencies here.

Using our SDK

If you are using our Python SDK, you can create the transfer like this:

transfer = client.v2.transfers.create(
  idempotency_key="12345678910",
  amount=59013,
  currency="MXN",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  reference_id="150195",
  counterparty={"account_number": "012969123456789120"},
  metadata={"customer_id": "12050123"}
)

In Mexico, the Counterparty object is defined by a minimum of 1 attribute:

ParameterDescription
account_numberRecipient Account Number (🇲🇽 CLABE, mobile number or debit card number).

A successful request response looks like this:

{
  "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 gas",
  "reference_id": "150195",
  "tracking_key": "s2123423423324334",
  "receipt_url": "https://www.banxico.org.mx/cep/",
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "OODC911119JL3",
    "holder_name": "Carmen Marcela",
    "account_number": "012969123456789120",
    "account_type": "clabe",  
    "institution": {
      "id": "mx_bbva_mexico",
      "name": "BBVA Mexico",
      "country": "mx" 
     }
   },
  "account_number": {
    "id": "acno_Kasf91034gj1AD",
    "account_id": "acc_Jas92lf9adg94ka",
    "number": "738969123456789120",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "description": null,
    "metadata": {},
    "object": "account_number",
  },
  "metadata": {
    "order_id": 1234
  }
}

Create a Transfer for Chile 🇨🇱

Here is an example to create a transfer of $1869 Chilean Pesos:

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": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "metadata": {
  	"customer_id": "12050123"
  }
}
'

Using our SDK

If you are using our Python SDK, you can create the transfer like this:

transfer = client.v2.transfers.create(
  idempotency_key="12345678910",
  amount=1869,
  currency="CLP",
  account_id="acc_M8sKf230BgHjD4",
  comment="Pago de credito 10451",
  counterparty={
    "holder_id": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  metadata={"customer_id": "12050123"}
)

In Chile, the Counterparty object is defined by a minimum of 5 attributes:

ParameterDescription
holder_idAccount holder's RUT
holder_nameAccount holder's name
account_numberAccount number
account_typeType of account. Supported types are checking_account and sight_account.
institution_idFintoc institution id for the bank receiving the bank transfer. You can see the code for each institution here

A successful request response looks like this:

{
  "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 gas",
  "reference_id": null,
  "receipt_url": null,
  "tracking_key": null,
  "mode": "test",
  "return_reason": null,
  "counterparty": {
    "holder_id": "771433855",
    "holder_name": "Piped Piper SpA",
    "account_number": "502955923",
    "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": "738969123456789120",
    "created_at": "2024-03-01T20:09:42.949787176Z",
    "mode": "test",
    "object": "account_number",
    "description": null,
    "metadata": {}
  },
  "metadata": {
    "order_id": 1234
  }
}

Step 4: Monitor transfer status

Transfer status flow

Transfers' status can be either pending, succeeded, failed or returned. The status flow behaves as shown below:


Monitor status using webhooks

Fintoc sends a transfer.outbound.succeeded event when the transfer settles. Use the webhook guide to receive these events and run actions, such as sending a notification email to your customer or logging the transfer in your ERP.

We recommend handling the following events:

EventDescription
transfer.outbound.succeededSent when the transfer successfully settles.
transfer.outbound.returned🇲🇽 In Mexico: Sent when either Banco de Mexico or the counterparty institution has rejected the transfer. You can see the rejection causes here

🇨🇱 In Chile: Sent when the counterparty institution has rejected the transfer.
transfer.outbound.failedSent when the transfer has not been able to reach its destination account, due to an error during the process.

Updated 4 days ago