Guía de integración

Esta guía recorre la integración completa de un banco participante: registrar un cliente, reservar su @alias, enviar su primer pago instantáneo y leer el historial de transacciones. Son cinco llamadas — todo lo demás (liquidación CBDC, compensación interbancaria, disponibilidad 24/7) lo hace la red por ti.

Los ejemplos de esta guía usan datos de demostración: el banco emisor Banco Demo y los @alias externos @juanp, @sofiar y @pedroh, que puedes usar tal cual en tus pruebas de integración.

1. Credenciales y URL base

Al darse de alta como banco participante recibes una clave de API por entorno. Todas las peticiones la envían como bearer token:

BASE_URL=https://bch-instant.vercel.app
API_KEY=<tu_clave_de_api>

curl -H "Authorization: Bearer $API_KEY" $BASE_URL/api/v1/users

2. Registra a tu cliente

Cada cliente de tu banco que activa pagos instantáneos se registra una única vez en la red. Puedes registrar el @alias en el mismo alta o dejarlo para después:

curl -X POST $BASE_URL/api/v1/users \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Laura",
    "lastName": "Castillo"
  }'
{
  "id": "usr_5f3a9c1e8b2d4706",
  "organizationId": "org_2f7c1d8a9b3e4f50",
  "organizationName": "Banco Demo",
  "firstName": "Laura",
  "lastName": "Castillo",
  "displayName": "Laura Castillo",
  "alias": null,
  "status": "ACTIVE",
  "createdAt": "2026-07-29T15:04:11.000Z"
}

3. Comprueba y registra el @alias

El @alias es la dirección de pago del cliente en toda la red: único, en minúsculas y portable entre bancos. Comprueba disponibilidad mientras el cliente teclea y regístralo cuando confirme:

curl -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api/v1/aliases/laurac/availability
# → { "alias": "laurac", "available": true }

curl -X POST $BASE_URL/api/v1/users/usr_5f3a9c1e8b2d4706/alias \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "laurac" }'

4. Envía un pago instantáneo

Para pagar solo hace falta el @alias del destinatario — da igual en qué banco esté. Resuélvelo primero para mostrar al usuario a quién está pagando, y envía el pago con una clave de idempotencia:

curl -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api/v1/aliases/juanp/resolve
# → { "alias": "juanp", "displayName": "Juan Pérez",
#     "organizationName": "Banco Atlántida", ... }

curl -X POST $BASE_URL/api/v1/payments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderUserId": "usr_5f3a9c1e8b2d4706",
    "recipientAlias": "juanp",
    "amount": "150.00",
    "reference": "Almuerzo",
    "idempotencyKey": "9c2e6a4f-1b3d-4e8a-9f70-2c5d8b1a3e47"
  }'

La respuesta llega ya finalizada, con el detalle de liquidación. Un pago entre bancos (CROSS_ORGANIZATION) incluye el hash de la transacción de liquidación on-chain; uno dentro de tu banco (INTERNAL) liquida internamente al instante:

{
  "publicId": "ip_4e8a9f702c5d8b1a",
  "status": "FINALIZED",
  "kind": "CROSS_ORGANIZATION",
  "amount": { "denom": "ehnl", "amount": "150.00" },
  "settlement": {
    "type": "ON_CHAIN",
    "fromBank": "Banco Demo",
    "toBank": "Banco Atlántida",
    "chainTxHash": "8F4A…C21D",
    "chainHeight": "1851204"
  },
  "timings": { "totalMs": 3120, "settlementMs": 2720 },
  ...
}

5. Lee las transacciones

El historial que muestras en tu app sale del mismo API. Filtra por dirección o por @alias para la vista de un cliente concreto:

curl -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/payments?alias=laurac&pageSize=20"

Siguientes pasos