Envía tu primera transferencia

Al final, habrás firmado tus solicitudes con un JSON Web Signature (JWS), fondeado una Account de prueba y enviado tu primera Transfer. Los ejemplos cubren México y Chile. Elige la pestaña del país en el que opera tu organización.

Paso 1 — Obtén tus API keys de prueba

En el Dashboard, ve a Developers → API Keys. Verás llaves para el modo test (sk_test_...) y el modo live (sk_live_...). Copia la llave secreta de test.

Paso 2 — Registra las llaves JWS

Los endpoints que mueven dinero requieren solicitudes firmadas. Estos endpoints crean transferencias, devuelven transferencias o verifican un número de cuenta bancaria mexicano estandarizado. Sigue Genera llaves JWS para crear un par de llaves y subir la llave pública. Regresa a esta página cuando termines.

Paso 3 — Lista tus cuentas

Toda organización comienza con una Account raíz. En México, una Account raíz también se conoce como Centro de Costos. Obtén la cuenta raíz con una solicitud GET a /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'

La respuesta se ve así. La currency y la forma del root_account_number dependen del país de tu organización:

[
  {
    "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"
    }
  }
]

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

Usa un SDK

Si usas Node o Python, instala el SDK de Node o el SDK de Python para llamar a la API. El SDK firma cada solicitud con JWS y maneja la paginación. Instala un SDK:

npm install fintoc

pip install fintoc

Lista tus cuentas:

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

// Puedes proporcionar una ruta a tu archivo PEM o pasar la llave PEM directamente como 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

# Puedes proporcionar una ruta a tu archivo PEM o pasar la llave PEM directamente como 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)

Guarda el id (acc_...) y el root_account_number_id (acno_...) de la respuesta. Usa root_account_number_id para fondear la Account de prueba. Usa id para crear la Transfer saliente.

Paso 4 — Fondea tu cuenta de prueba

Tu Account de prueba comienza vacía. Simula una transferencia entrante para tener dinero que enviar:

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"
}
'

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": "CLP"
}
'

La respuesta es la Transfer entrante simulada que fondea tu Account:

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

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

Las monedas se representan como enterosLa API de Fintoc representa el dinero en la unidad mínima de la moneda como un entero sin decimales. Un monto de $590.13 MXN es 59013. El CLP no tiene unidad menor, así que un monto de $59.013 CLP también es 59013.Consulta Monedas.

Consulta Prueba tu integración para ver simulaciones de fallos, devoluciones y payouts rechazados.

Paso 5 — Envía tu primera transferencia

Crea una Transfer saliente desde la Account de prueba que fondeaste. En México, la counterparty solo necesita la CLABE del destinatario. En Chile, la counterparty también necesita el Rol Único Tributario (RUT), el nombre, el tipo de cuenta y la institución del destinatario:

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": "012000000000000001"
  }
}'

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": "CLP",
  "account_id": "acc_23JlasHas241",
  "comment": "Pago de credito 10451",
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "account_type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  }
}'

La respuesta es la Transfer saliente que creaste:

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

{
  "id": "tr_5pQ8rXcViBnM3kL2",
  "object": "transfer",
  "amount": 59013,
  "currency": "CLP",
  "status": "succeeded",
  "direction": "outbound",
  "comment": "Pago de credito 10451",
  "reference_id": null,
  "counterparty": {
    "holder_id": "11.111.111-1",
    "holder_name": "Test Customer 1",
    "account_number": "11111111",
    "account_type": "checking_account",
    "institution": {
      "id": "cl_banco_de_chile",
      "name": "Banco de Chile",
      "country": "cl"
    }
  }
}

Paso 6 — Crea un endpoint de webhook

Los webhooks notifican a tu servidor cuando una transferencia se liquida, así no necesitas hacer polling del estado. Ve a Developers → Webhooks en el Dashboard. Agrega tu URL y luego suscríbete a transfer.inbound.succeeded y transfer.outbound.succeeded.

Prueba la integración

Confirma que todo el flujo funcionó de principio a fin:

Después del Paso 4, vuelve a listar tus cuentas y confirma que available_balance aumentó en 59013.
Confirma que la transferencia del Paso 5 retorna "status": "succeeded".
Después del Paso 6, repite los Pasos 4 y 5. Confirma que tu endpoint recibe un webhook transfer.outbound.succeeded para la nueva transferencia saliente.

​Paso 1 — Obtén tus API keys de prueba

​Paso 2 — Registra las llaves JWS

​Paso 3 — Lista tus cuentas

​Usa un SDK

​Paso 4 — Fondea tu cuenta de prueba

​Paso 5 — Envía tu primera transferencia

​Paso 6 — Crea un endpoint de webhook

​Prueba la integración

Paso 1 — Obtén tus API keys de prueba

Paso 2 — Registra las llaves JWS

Paso 3 — Lista tus cuentas

Usa un SDK

Paso 4 — Fondea tu cuenta de prueba

Paso 5 — Envía tu primera transferencia

Paso 6 — Crea un endpoint de webhook

Prueba la integración