Outbound transfers
Initiate real-time payments using our outbound Transfers API
To start creating payouts using Fintoc's Transfers API, you just need to create an account on our Dashboard and follow these four steps:
- Get your test API Keys
- Add funds to the account indicated by Fintoc.
- From your backend, create a
Transfer
using your Secret Key - Monitor transfer status
The following diagram shows how Fintoc will interact with you and the counterparty receiving the payout.
Step 1: Get your test Secret API Key
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.
Keep your keys safe
Anyone can use your live mode secret API Key to make transfers on behalf of your account.
Step 2: Add funds to Fintoc
To create Transfers, you need to add funds to your account first. You should see the account to which you need to add funds in your Dashboard.
Step 3: Create Transfer
You can start making real-time transfers once you add funds to your account. Using your test Secret Key, create a Transfer from your backend with the amount, currency, and counterparty that will receive the payment.
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/v1/transfers \
--header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"amount": 59013,
"currency": "mxn",
"comment": "Pago de credito 10451",
"reference_id": "150195",
"counterparty": {
"holder_id": "LFHU290523OG0",
"holder_name": "Jon Snow",
"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.
In Mexico, the Counterparty object is defined by a minimum of 2 attributes:
Parameter | Description |
---|---|
holder_id | Account holder's RFC |
holder_name | Account holder's name |
account_number | Account number |
A successful request response looks like this:
{
"id": "tr_jKaHD105H",
"object": "transfer",
"amount": 59013,
"post_date": null,
"transaction_date": null,
"created_at": "2020-04-17T00:00:00.000Z",
"currency": "mxn",
"comment": "Pago de credito 10451",
"reference_id": "150195",
"receipt_url": null,
"type": "outbound",
"tracking_key": null,
"status": "pending",
"mode": "test",
"account_number": null,
"counterparty": {
"holder_id": "LFHU290523OG0",
"holder_name": "Jon Snow",
"account_number": "012969123456789120",
"type": "clabe",
"type_code": "40",
"institution": {
"id": "40012",
"name": "BBVA MEXICO",
"country": "mx"
}
}
}
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/v1/transfers \
--header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"amount": 1869,
"currency": "clp",
"comment": "Pago de credito 10451",
"counterparty": {
"holder_id": "771433855",
"holder_name": "Piped Piper SpA",
"account_number": "502955923",
"type": "checking_account",
"institution_id": "cl_banco_de_chile"
},
"metadata": {
"customer_id": "12050123"
}
}
'
In Chile, the Counterparty object is defined by 5 attributes:
Parameter | Description |
---|---|
holder_id | Account holder's RUT |
holder_name | Account holder's name |
account_number | Account number |
type | Type of account. Supported types are checking_account and sight_account . |
institution_id | Fintoc 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:
{
"id": "tr_jKaHD105H",
"object": "transfer",
"amount": 1869,
"post_date": null,
"transaction_date": null,
"currency": "clp",
"comment": "Pago de credito 10451",
"reference_id": null,
"receipt_url": null,
"type": "outbound",
"tracking_key": null,
"status": "pending",
"mode": "test",
"account_number": null,
"counterparty": {
"holder_id": "771433855",
"holder_name": "Piped Piper SpA",
"account_number": "502955923",
"type": "checking_account",
"type_code": null,
"institution": {
"id": "cl_banco_de_chile",
"name": "Banco de Chile",
"country": "cl"
}
}
}
Transfer status
After you create the Transfer, it will have a pending
status. As soon as the transfer is settled, it will change its status to succeeded
.
In case there is a problem with the Transfer, such as the counterparty account doesn't exist or is blocked, the Transfer will change its status to rejected
. You can see all the reasons why a transfer can be rejected here.
Step 4: Monitor transfers status
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:
Event | Description |
---|---|
transfer.outbound_succeeded | Sent when the transfer successfully settles. |
transfer.outbound_rejected | 🇲🇽 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. |
Updated 4 days ago