Send your first transfer

By the end, you will have signed your requests with a JSON Web Signature (JWS), funded a test Account, and sent your first Transfer.

Step 1: Get your test API keys

In the Dashboard, go to Developers → API Keys. You’ll see keys for test (sk_test_...) and live (sk_live_...) modes. Copy the test secret key.

Step 2: Register JWS keys

Money-moving endpoints require signed requests. These endpoints create transfers, return transfers, or verify a standardized Mexican bank account number. Follow Generate JWS keys to create a key pair and upload the public key. Return to this page when you’re done.

Step 3: List your accounts

Every organization starts with a root Account. Fetch it with a GET request to /v2/accounts:

cURL

curl --request GET \
     --url https://api.fintoc.com/v2/accounts \
     --header 'Authorization: YOUR_TEST_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

The response looks like this:

JSON

[
  {
    "id": "acc_23JlasHas241",
    "object": "account",
    "mode": "test",
    "description": "My root account",
    "root_account_number": "000000000000000000",
    "root_account_number_id": "acno_Kasf91034gj1AD",
    "available_balance": 0,
    "currency": "mxn",
    "entity": {
      "id": "ent_4324qwkalsds",
      "holder_name": "Test Entity 1",
      "holder_id": "ND"
    }
  }
]

Use an SDK

If you’re using Node or Python, install the Node SDK or Python SDK to call the API. The SDK signs each request with JWS and handles pagination. Install an SDK:

npm install fintoc

pip install fintoc

List your accounts:

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_TEST_SECRET_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, account.available_balance);
}

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_TEST_SECRET_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)

Keep the id (acc_...) and root_account_number_id (acno_...) from the response. Use root_account_number_id to fund the test Account. Use id to create the outbound Transfer.

Step 4: Fund your test account

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

cURL

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

The response is the simulated inbound Transfer that funds your Account:

JSON

{
  "id": "tr_7HbN2kPq9wZ4xR1s",
  "object": "transfer",
  "amount": 59013,
  "currency": "mxn",
  "status": "succeeded",
  "direction": "inbound",
  "account_number_id": "acno_Kasf91034gj1AD",
  "comment": "Simulated inbound transfer"
}

Currencies are represented as integersThe Fintoc API represents money in the smallest currency unit as an integer with no decimals. An amount of

590.13 MXN is `59013`. CLP has no minor unit, so an amount of

59,013 CLP is also 59013.See Currencies.

See Test your integration for simulations of failures, returns, and rejected payouts.

Step 5: Send your first transfer

Create an outbound Transfer from the test Account you funded.

cURL

curl --request POST \
     --url https://api.fintoc.com/v2/transfers \
     --header 'Authorization: YOUR_TEST_SECRET_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_23JlasHas241",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "counterparty": {
    "account_number": "000000000000000000"
  }
}'

The response is the outbound Transfer you created:

JSON

{
  "id": "tr_5pQ8rXcViBnM3kL2",
  "object": "transfer",
  "amount": 59013,
  "currency": "mxn",
  "status": "succeeded",
  "direction": "outbound",
  "comment": "Pago de credito 10451",
  "reference_id": "150195",
  "counterparty": {
    "account_number": "000000000000000000"
  }
}

Step 6: Create a webhook endpoint

Webhooks notify your server when a transfer settles, so you don’t need to poll for status. Go to Developers → Webhooks in the Dashboard. Add your URL, then subscribe to transfer.inbound.succeeded and transfer.outbound.succeeded.

Test the integration

Confirm the full flow worked end to end:

After Step 4, list your accounts again and confirm available_balance increased by 59013.
Confirm the Step 5 transfer returns "status": "succeeded".
After Step 6, repeat Steps 4 and 5. Confirm your endpoint receives a transfer.outbound.succeeded webhook for the new outbound transfer.

Home

Resources

Payments

Transfers

Movements

Send your first transfer

Step 1: Get your test API keys

Step 2: Register JWS keys

Step 3: List your accounts

Use an SDK

Step 4: Fund your test account

Step 5: Send your first transfer

Step 6: Create a webhook endpoint

Test the integration

​Step 1: Get your test API keys

​Step 2: Register JWS keys

​Step 3: List your accounts

​Use an SDK

​Step 4: Fund your test account

​Step 5: Send your first transfer

​Step 6: Create a webhook endpoint

​Test the integration

Step 1: Get your test API keys

Step 2: Register JWS keys

Step 3: List your accounts

Use an SDK

Step 4: Fund your test account

Step 5: Send your first transfer

Step 6: Create a webhook endpoint

Test the integration