Quickstart

Step 1 — Get your test API keys

In the Dashboard, go to Developers → API Keys. You'll see two key pairs: test (sk_test_...) and live (sk_live_...). Copy the test Secret Key.

Step 2 — Register JWS keys

Money-moving endpoints (create transfer, return transfer, verify CLABE) require each request to be signed. Follow Generate JWS keys to create a keypair and upload the public key. Come back here when you're done.

Step 3 — List your Accounts

Every organization starts with a Root Account. Let's fetch it.

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": "ent_4324qwkalsds",
          "holder_name": "ACME Inc.",
          "holder_id": "ND"
      }
	}
]

Using our SDK

If you’re using Python or Node, you can install our Python SDK or Node SDK to make it easier to interact with our API. The SDK automatically generates the JWS signature, handles pagination, and offers many other helpful features.

First install our SDK:

pip install fintoc

npm install fintoc

Now list your accounts:

from fintoc import Fintoc

# You can provide a path to your PEM file or pass the PEM key directly as a string.
# jws_private_key = os.environ.get('JWS_PRIVATE_KEY')
jws_private_key = "./private_key.pem"

client = Fintoc("your_api_key", jws_private_key=jws_private_key)

for account in client.v2.accounts.list():
  print(account.id, account.description, account.root_account_number, account.available_balance)

const { Fintoc } = require('fintoc');

// You can provide a path to your PEM file or pass the PEM key directly as a string.
// const privateKey = process.env.JWS_PRIVATE_KEY;
const privateKey = './private_key.pem';

const fintoc = new Fintoc('your_api_key', privateKey);

const accounts = await fintoc.v2.accounts.list();
for await (const account of accounts) {
  console.log(account.id, account.description, account.root_account_number);
}

Keep the id (acc_...) and root_account_number from the response — you'll use them next.

Step 4 — Fund your test Account

Your test Account starts empty. Simulate an inbound transfer so you have money to send:

curl --request POST \
     --url https://api.fintoc.com/v2/simulate/receive_transfer \
     --header 'Authorization: sk_test_9c8d8CeyBT1ajVcJzuDgpm4H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_number_id": "acno_Kasf91034gj1AD",
  "amount": 59013,
  "currency": "MXN"
}
'

🚧
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 $590.13 gets represented by Fintoc as 59013.
If you are making a transfer in Chilean peso, because there are no decimals, if you want to transfer $59013 you just represent that amount as 59013.
You can read more about currencies here..

More simulation recipes (failures, returns, rejected payouts) live in Test your integration.

Step 5 — Send your first Transfer

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'Fintoc-JWS-Signature: YOUR_JWS_SIGNATURE' \
     --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"
  },
}

Step 6 — Create a webhook endpoint

Most real-world flows are webhook-driven. Go to Developers → Webhooks in the Dashboard, add your URL, and subscribe to transfer.inbound.succeeded and transfer.outbound.succeeded.