To start creating payouts using Fintoc's Transfers API, you just need to create an account on our Dashboard and follow these four steps:

1. Get your test API Keys
2. Add funds to the account indicated by Fintoc.
3. From your backend, create a Transfer using your Secret Key
4. 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.

🚧

Transfer safely

Before start creating outbound transfers from your backend we strongly recommend to implement idempotent requests to avoid any undesired behaviour.

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 1 attribute:

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:

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: