Saltar al contenido principal
API docs by Redocly

Binkio API (v1 (2026-09-09))

Download OpenAPI specification:Download

License: Uso sujeto a los Términos de Servicio de Binkio

La API de Binkio para mover dinero desde tu propio sistema: consultar saldos y movimientos, crear cobros y recibir avisos cuando se pagan.

Base: https://api.binkio.com/v1. Todo lo de esta referencia cuelga de ahí.

Webhooks salientes: verificación de firma

Autenticación

Cabecera Authorization, con el secreto de tu credencial:

Authorization: Bearer bk_live_sec_7f3a…

El prefijo declara el entorno: bk_test_… contra el entorno de pruebas, bk_live_… contra el real. Se distinguen a simple vista en un log, en una captura o en un ticket — es la defensa más barata contra configurar la credencial equivocada.

El secreto se muestra una sola vez, al crearlo. Si se pierde, se rota; no se recupera. Puedes tener dos credenciales activas a la vez: ése es el procedimiento de rotación sin cortar servicio (crea la nueva, despliégala, comprueba que la vieja dejó de usarse, revócala).

Todos los fallos de autenticación devuelven el mismo 401, con el mismo cuerpo: no distinguimos «revocada» de «IP no permitida» de «no existe». No es una carencia de la documentación; distinguirlos le diría a quien está probando credenciales que acertó una y sólo le falta cambiar de red.

Alcances

Cada credencial lleva los permisos que le diste, por recurso y acción (balances:read, links:write, logs:read…). Cada endpoint declara el suyo. Emite claves con lo mínimo: una terminal de mostrador necesita crear cobros, no leer el histórico de la empresa — si esa terminal se compromete, el daño queda acotado a lo que su clave podía hacer.

Si a la credencial le falta el alcance, la respuesta es 403 y sí dice cuál falta: quien pregunta ya demostró tener una credencial válida.

Idempotencia

Obligatoria en todo método que crea o modifica (POST, PUT, PATCH, DELETE). Sin la cabecera, 400.

Idempotency-Key: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Una clave por operación, no por reintento: los reintentos de la misma operación repiten la clave, y eso es justo lo que impide el cobro duplicado cuando una terminal con mala cobertura no llega a ver la respuesta.

Situación Respuesta
Clave nueva Se ejecuta y se guarda la respuesta.
Misma clave, mismo cuerpo, ya terminada La respuesta guardada, con Idempotent-Replay: true. No se vuelve a ejecutar.
Misma clave, mismo cuerpo, en curso 409 idempotency_request_in_progress. Reintenta en unos segundos con la misma clave.
Misma clave, cuerpo distinto 422 idempotency_key_reused. Es el caso peligroso: significa que reutilizaste la clave para otra operación. Ejecutarla sería cobrar dos veces con nuestra bendición.
Clave de hace más de 24 h Se trata como nueva.

Cómo comprobar que tu manejo es correcto sin mover un peso: llama dos veces a POST /v1/ping con la misma clave. Si el execution_id es el mismo y llega Idempotent-Replay: true, tu reintento no duplicó nada. Si cambia, ejecutaste dos veces — y más vale descubrirlo ahí que con un cobro.

Versiones

El contrato lleva fecha. La RUTA sigue siendo /v1 —eso identifica la API— pero lo que decide la forma de cada respuesta es una versión con fecha, y va en la cabecera Binkio-Version de toda respuesta, la hayas pedido o no.

Se resuelve en este orden:

Orden De dónde sale
1 La cabecera Binkio-Version de tu petición.
2 La versión FIJADA en tu credencial al emitirla. No cambia sola.
3 La actual — sólo en el checkout, que no lleva credencial.

Que el paso 2 no cambie solo es el punto entero: una integración escrita hoy sigue recibiendo la forma de hoy cuando publiquemos la siguiente. Subir de versión es una decisión tuya.

Manda la cabecera para probar una versión nueva en una llamada suelta, desde curl, antes de tocar nada. Una versión que no existe se rechaza con 400 unknown_api_version y el mensaje enumera las válidas: no se cae en silencio a la actual, porque un dedazo que cambia el comportamiento en silencio es peor que un error.

Versión Qué trae
2026-09-09 Línea de salida del contrato versionado. Incluye los eventos de enlace de pago con code y amount alineados con la API REST, y el neto del comercio en net_amount / net_currency.

Límites

Dos, y hacen falta los dos: peticiones por minuto (abuso técnico) y operaciones de dinero por día (abuso económico — una credencial robada que respete el límite por minuto puede crear cientos de miles de cobros al día).

Los límites son por credencial, no por IP: detrás de un comercio hay muchas terminales tras la misma salida a internet, y un cubo por IP dejaría a todas sin servicio por culpa de una.

Cada respuesta trae con qué autorregularte:

Cabecera Qué dice
RateLimit-Limit Peticiones por minuto de esta credencial.
RateLimit-Remaining Cuántas quedan en la ventana actual.
RateLimit-Reset Segundos hasta que la ventana se reinicia.
RateLimit-Money-* Lo mismo para la cuota diaria de operaciones de dinero (sólo en métodos que mutan).

Al pasarte: 429 y Retry-After con los segundos que faltan. Usa las cabeceras y no llegarás a verlo.

Errores

Mismo sobre en toda la API:

{
  "error": {
    "type": "invalid_request",
    "code": "insufficient_balance",
    "message": "No hay saldo suficiente para esta operación.",
    "param": "amount",
    "request_id": "req_9f2a4c8b7e1d3a5f"
  }
}
  • type — familia estable y corta. Es con lo que decides qué hacer (reintentar, arreglar la petición, avisar a una persona) sin conocer el catálogo completo.
  • code — el caso concreto. Es lo que debes comparar en tu código. No compares message: cambia, se traduce y se reescribe.
  • param — qué campo lo provocó, cuando se puede determinar.
  • request_id — identifica esta llamada exacta.

request_id

Va siempre: en la cabecera X-Request-Id y en el cuerpo, tanto en éxito como en error. Guárdalo. Es lo primero que pide soporte, y es la clave con la que encuentras tu propia llamada en GET /v1/request_logs.

Paginación

Por cursor, no por número de página: un histórico al que se le añaden filas por delante hace que la página 2 de un listado por desplazamiento contenga cosas que ya viste en la página 1.

GET /v1/transactions?limit=50
GET /v1/transactions?limit=50&cursor=eyJ2IjoxLCJ0Ijoi…

Repite mientras has_more sea true, pasando el next_cursor de la respuesta anterior. No te guíes por el número de elementos: una página puede venir con menos de limit y aún tener más detrás.

El cursor es opaco. No lo interpretes ni lo construyas: su contenido no forma parte del contrato y puede cambiar.

Importes

Siempre cadena decimal, nunca número:

{ "amount": "1500.00000000" }

Un float de JSON no representa 0.1 exactamente. Un cliente que hace JSON.parse sobre {"amount": 1234567.89} ya perdió precisión antes de tocar el dato. La cadena es lo único que sobrevive intacto a cualquier lenguaje. Mándalos igual: un número en el cuerpo recibe 400.

Avisos (webhooks)

Para no tener que sondear, registra un destino en el panel y te enviamos un aviso firmado cuando algo pasa en tu cuenta. El contrato de firma —qué se firma exactamente, cómo se verifica y por qué no debes reserializar el cuerpo antes de comprobarlo— está en la guía de webhooks:

https://docs.binkio.com/api/webhooks

Esa guía es la única fuente del contrato de firma. No se reproduce aquí a propósito: dos copias de un contrato criptográfico acaban diciendo cosas distintas, y la que leas será la equivocada.

Tu tráfico

GET /v1/request_logs devuelve tus propias llamadas: qué pediste, qué respondimos, cuándo, desde qué IP y con qué credencial. Es el sitio donde mirar antes de abrir un ticket.

Cuenta

Comprobación de vida, verificación de la credencial y saldos por activo.

¿Está la API en pie?

Comprobación de vida, sin credencial. Responde 200 mientras el proceso atienda peticiones.

No comprueba dependencias: que responda no garantiza que un cobro vaya a liquidar. Si necesitas saber si TU credencial funciona, usa /v1/ping, que además te dice sus alcances.

Alcance requerido: ninguno. Basta una credencial válida — es una comprobación, y exigir un alcance para ella empujaría a emitir claves más permisivas de lo necesario.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "timestamp": "2026-09-06T14:32:07.482Z"
}

Comprueba la credencial y devuelve la identidad autenticada

La primera llamada que conviene hacer al integrar: confirma de punta a punta que tu credencial funciona, contra qué entorno estás pegando y qué alcances tiene — sin mover un peso.

Si environment no es el que esperabas, tienes la credencial del otro entorno configurada.

Alcance requerido: ninguno. Basta una credencial válida — es una comprobación, y exigir un alcance para ella empujaría a emitir claves más permisivas de lo necesario.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "environment": "live",
  • "api_key": {
    },
  • "account": {
    },
  • "server_time": "2026-08-04T15:04:05.000Z",
  • "request_id": "req_9f2a4c8b7e1d3a5f"
}

Comprueba la idempotencia de extremo a extremo (no mueve dinero)

Llama dos veces con la MISMA Idempotency-Key y el mismo cuerpo. Si el execution_id es idéntico y la segunda respuesta trae Idempotent-Replay: true, acabas de comprobar que tu reintento no duplicó nada. Si cambia, tu cliente ejecutó dos veces — y más vale descubrirlo aquí que con un cobro.

Pruébalo también con un cuerpo distinto y la misma clave: debe darte 422 idempotency_key_reused.

Alcance requerido: ninguno. Basta una credencial válida — es una comprobación, y exigir un alcance para ella empujaría a emitir claves más permisivas de lo necesario.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
optional

Cualquier objeto JSON. Se devuelve tal cual en echo, para que puedas comprobar que la MISMA clave con un cuerpo distinto da 422 idempotency_key_reused.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true,
  • "execution_id": "0f8c2b1a-7d6e-4c3b-9a58-1e2f3d4c5b6a",
  • "executed_at": "2026-08-04T15:04:05.000Z",
  • "idempotency_key": "9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c",
  • "echo": {
    },
  • "request_id": "req_9f2a4c8b7e1d3a5f"
}

Saldos de la cuenta, por activo

Devuelve el saldo de cada activo con fondos. available es lo que se puede operar, pending lo retenido y total la suma — publicada ya calculada para que nadie la sume mal.

Los importes son cadenas decimales de 8 decimales, la escala del libro. as_of dice cuándo se leyó: un saldo sin marca temporal es un dato del que no se puede decir si está viejo.

Alcance requerido: balances:read.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "balance_list",
  • "account_id": "b3d9c1a2-5e4f-4c8b-9a70-1f2e3d4c5b6a",
  • "as_of": "2026-08-04T15:04:05.000Z",
  • "data": [
    ]
}

Enlaces de pago

Crear, consultar y cancelar cobros. Es el motor: multimoneda, multirriel y con conversión cuando la moneda del pagador no es la tuya.

Con qué se puede pagar un importe, antes de crear el enlace

Crear un enlace con un accepted_methods que el importe no soporta devuelve 400. Los métodos de la OTRA familia de divisa exigen convertir, y la conversión tiene mínimos: un enlace de 500 MXNB no puede cobrarse en USDC.

Hasta ahora la única forma de saberlo por API era intentarlo y leer el error. Esto se pregunta ANTES, con el importe del carrito en la mano, y no crea ni consulta ningún enlace.

Alcance requerido: links:read.

Authorizations:
api-key
query Parameters
currency
required
string
Enum: "MXNB" "USDC" "COP"
Example: currency=MXNB

Divisa en la que recibiría la cuenta.

amount
required
string^\d{1,12}(\.\d{1,8})?$
Example: amount=50000.00

Importe que recibiría la cuenta, en esa divisa.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "payment_method_options",
  • "currency": "MXNB",
  • "amount": "80.00",
  • "available_methods": [
    ],
  • "conversion_enabled": false,
  • "methods": [
    ],
  • "amount_limits": {
    }
}

Cobro con QR

El QR fijo de mostrador y los cargos que se generan contra él.

Da de alta el QR maestro de la cuenta

Una cuenta tiene un QR maestro. Esta llamada lo crea; si ya hay uno, responde 409 — el que existe se consulta con GET /v1/qr.

Los dos campos son opcionales: sin cuerpo, la divisa se deduce de los activos que la cuenta tenga aprobados.

El id que devuelve es lo que se va a IMPRIMIR en el cartel, y no cambia. Por eso el alta es una llamada explícita y no un efecto secundario de la primera lectura.

Alcance requerido: qr:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
display_name
string <= 80 characters

Nombre comercial que ve el pagador. Si se omite, se usa el de la cuenta.

currency
string
Enum: "MXNB" "USDC" "COP"

Divisa en la que se generarán los cobros. Si se omite, se deduce de los activos que la cuenta tenga aprobados.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Cafeteria Central",
  • "currency": "MXNB"
}

Response samples

Content type
application/json
{
  • "object": "qr",
  • "id": "AShgI3mMYzIadVWN3maozr",
  • "status": "active",
  • "currency": "MXNB",
  • "display_name": "Caja 1",
  • "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  • "verification_code": "4F9C",
  • "max_amount_per_charge": "5000.00000000",
  • "max_amount_per_day": "50000.00000000",
  • "amount_paid_today": "1250.00000000",
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Configuración del QR maestro de la cuenta

Devuelve la URL que codifica el QR, su divisa, sus topes y cuánto se lleva cobrado hoy. No crea nada: si la cuenta todavía no tiene QR, responde 404.

verification_code es para el mostrador: se enseña para que el pagador compruebe que el QR que escaneó es el del comercio y no una pegatina que alguien encimó.

Alcance requerido: qr:read.

Authorizations:
api-key
query Parameters
qr_id
string <= 32 characters
Example: qr_id=qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "qr",
  • "id": "AShgI3mMYzIadVWN3maozr",
  • "status": "active",
  • "currency": "MXNB",
  • "display_name": "Caja 1",
  • "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  • "verification_code": "4F9C",
  • "max_amount_per_charge": "5000.00000000",
  • "max_amount_per_day": "50000.00000000",
  • "amount_paid_today": "1250.00000000",
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Actualiza la configuración del QR maestro

Parcial: lo que no se envía se queda como está. Enviar null en un campo opcional quita el tope.

Los topes son tu red de seguridad: un QR de mostrador está expuesto, y acotar el máximo por cargo acota lo que puede salir mal.

Alcance requerido: qr:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
qr_id
string <= 32 characters

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

display_name
string or null <= 80 characters

Nombre comercial que ve el pagador. null lo borra y vuelve al de la cuenta; omitirlo lo deja como está.

currency
string
Enum: "MXNB" "USDC" "COP"

Divisa en la que se generarán los cobros. Si se omite, se deduce de los activos que la cuenta tenga aprobados.

max_amount_per_charge
string or null^\d{1,12}(\.\d{1,8})?$

Tope por cobro. null lo quita.

max_amount_per_day
string or null^\d{1,12}(\.\d{1,8})?$

Tope diario agregado sobre lo COBRADO en el día. null lo quita.

Responses

Request samples

Content type
application/json
{
  • "qr_id": "qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb",
  • "display_name": "Cafeteria Central",
  • "currency": "MXNB",
  • "max_amount_per_charge": "50000.00",
  • "max_amount_per_day": "200000.00"
}

Response samples

Content type
application/json
{
  • "object": "qr",
  • "id": "AShgI3mMYzIadVWN3maozr",
  • "status": "active",
  • "currency": "MXNB",
  • "display_name": "Caja 1",
  • "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  • "verification_code": "4F9C",
  • "max_amount_per_charge": "5000.00000000",
  • "max_amount_per_day": "50000.00000000",
  • "amount_paid_today": "1250.00000000",
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Pausa el QR: deja de generar cobros

Los cobros ya generados siguen su curso y se pueden pagar. Pausar uno ya pausado devuelve el mismo estado, sin error.

Alcance requerido: qr:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
qr_id
string <= 32 characters

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

Responses

Request samples

Content type
application/json
{
  • "qr_id": "qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb"
}

Response samples

Content type
application/json
{
  • "object": "qr",
  • "id": "AShgI3mMYzIadVWN3maozr",
  • "status": "active",
  • "currency": "MXNB",
  • "display_name": "Caja 1",
  • "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  • "verification_code": "4F9C",
  • "max_amount_per_charge": "5000.00000000",
  • "max_amount_per_day": "50000.00000000",
  • "amount_paid_today": "1250.00000000",
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Reanuda un QR pausado

Reanudar uno que ya estaba activo devuelve el mismo estado, sin error.

Alcance requerido: qr:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
qr_id
string <= 32 characters

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

Responses

Request samples

Content type
application/json
{
  • "qr_id": "qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb"
}

Response samples

Content type
application/json
{
  • "object": "qr",
  • "id": "AShgI3mMYzIadVWN3maozr",
  • "status": "active",
  • "currency": "MXNB",
  • "display_name": "Caja 1",
  • "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  • "verification_code": "4F9C",
  • "max_amount_per_charge": "5000.00000000",
  • "max_amount_per_day": "50000.00000000",
  • "amount_paid_today": "1250.00000000",
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Genera un cobro desde el QR

Crea un enlace de pago por el importe indicado, en la divisa del QR. Devuelve el enlace con su url: eso es lo que la terminal convierte en el QR que ve el pagador.

Usa el número de ticket como Idempotency-Key. Si la terminal pierde la red justo al enviar y el cajero vuelve a pulsar, la misma clave devuelve el cobro original en vez de generar un segundo cargo — en un mostrador con prisa eso pasa más de lo que parece.

Alcance requerido: qr:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
qr_id
string <= 32 characters

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

amount
required
string^\d{1,12}(\.\d{1,8})?$

Importe a cobrar, en la divisa del QR.

reference
string <= 80 characters ^[\p{L}\p{N}\s.,#\-_/()'"&:]+$

Concepto libre del cobro («Mesa 5», «Pedido 12»). Admite letras, números, espacios y .,#-_/()'"&:

Responses

Request samples

Content type
application/json
{
  • "qr_id": "qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb",
  • "amount": "350.50",
  • "reference": "Mesa 5"
}

Response samples

Content type
application/json
{
  • "object": "payment_link",
  • "qr_id": "AShgI3mMYzIadVWN3maozr",
  • "code": "PL-7C3D-1A2B-9E4F",
  • "status": "active",
  • "amount": "350.50000000",
  • "currency": "MXNB",
  • "description": "ticket-77",
  • "metadata": {
    },
  • "fee_bearer": "merchant",
  • "accepted_methods": [
    ],
  • "url": "https://app.binkio.com/pay/PL-7C3D-1A2B-9E4F",
  • "checkout_url": "https://app.binkio.com/pay/PL-7C3D-1A2B-9E4F",
  • "created_at": "2026-09-07T18:22:41.000Z",
  • "expires_at": "2026-09-07T19:22:41.000Z",
  • "paid_at": null,
  • "paid_with_method": null,
  • "qr": {
    }
}

Cobros generados desde el QR, paginados por cursor

Del más reciente al más antiguo. Para recorrer el histórico completo, repite la llamada pasando next_cursor en cursor mientras has_more sea true.

Alcance requerido: qr:read.

Authorizations:
api-key
query Parameters
qr_id
string <= 32 characters
Example: qr_id=qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántos cobros por página.

cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

status
string
Enum: "active" "processing" "paid" "cancelled" "expired"
Example: status=paid

Devuelve sólo los cobros en este estado.

created_after
string <date-time>
Example: created_after=2026-09-01T00:00:00Z

Sólo cobros creados en o después de esta fecha.

created_before
string <date-time>
Example: created_before=2026-09-01T00:00:00Z

Sólo cobros creados en o antes de esta fecha.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJpZCI6IjdjM2QxYTJiIn0"
}

Cobros y montos acumulados del QR

Los importes de hoy y del mes se calculan sobre lo COBRADO (no sobre lo generado) y con días UTC.

La diferencia entre generados y pagados es la que interesa vigilar: un salto ahí suele ser un problema de mostrador —el QR tapado, el cliente que se fue— no de la API.

Alcance requerido: qr:read.

Authorizations:
api-key
query Parameters
qr_id
string <= 32 characters
Example: qr_id=qr_7Kd93Lm2Pq8Rt5Vw1Xy4Zb

El QR sobre el que operar. Hoy la cuenta tiene uno solo y se puede omitir; mandarlo desde el principio deja la terminal preparada para cuando haya varios.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "qr_stats",
  • "qr_id": "AShgI3mMYzIadVWN3maozr",
  • "currency": "MXNB",
  • "charges_generated": 128,
  • "charges_paid": 119,
  • "charges_pending": 9,
  • "amount_paid_today": "1250.00000000",
  • "amount_paid_this_month": "41830.75000000"
}

Movimientos

Histórico de la cuenta y detalle de cada movimiento.

Movimientos de la cuenta, paginados por cursor

Devuelve los movimientos del más reciente al más antiguo. Para recorrer el histórico completo, repite la llamada pasando next_cursor en cursor mientras has_more sea true. No te guíes por el número de elementos: una página puede venir con menos de limit y aun así tener más movimientos detrás.

Alcance requerido: transactions:read.

Authorizations:
api-key
query Parameters
limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántos movimientos por página.

cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

asset
string^[A-Za-z0-9]{2,10}$
Example: asset=USDC

Código del activo: MXNB, USDC, USDT, COP…

type
string
Enum: "deposit" "withdrawal" "conversion" "payment" "transfer" "p2p"
Example: type=withdrawal

Familia de movimiento.

status
string
Enum: "pending" "completed" "failed"
Example: status=completed

Estado del movimiento.

created_after
string <date-time>
Example: created_after=2026-09-01T00:00:00Z

Sólo movimientos creados en o después de esta fecha.

created_before
string <date-time>
Example: created_before=2026-09-01T00:00:00Z

Sólo movimientos creados en o antes de esta fecha.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJ2IjoxLCJ0IjoiMjAyNi0wOC0wNFQxNDozMjoxMC4xMjM0NTZaIn0"
}

Detalle de un movimiento

Añade al movimiento su comisión, su tasa y —cuando aplica— la red y el hash on-chain.

Los campos opcionales se omiten cuando no aplican, en lugar de venir a null: un "fee": null obliga a cada cliente a distinguir «no hubo comisión» de «no lo sabemos», y casi ninguno lo hace bien.

No se publican los datos del tercero (destino de un retiro, quién pagó un enlace): que la operación sea de tu cuenta no los convierte en tuyos.

Alcance requerido: transactions:read.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "transaction",
  • "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  • "type": "conversion",
  • "direction": "debit",
  • "status": "completed",
  • "amount": "1500.00000000",
  • "asset": "MXNB",
  • "reference": "BNK-4F2A9C",
  • "created_at": "2026-08-04T14:32:10.000Z",
  • "completed_at": "2026-08-04T14:32:44.000Z",
  • "fee": "12.50000000",
  • "net_amount": "1487.50000000",
  • "exchange_rate": "17.42000000",
  • "from_asset": "MXNB",
  • "to_asset": "USDC",
  • "from_amount": "1500.00000000",
  • "to_amount": "85.39000000",
  • "network": "ARBITRUM",
  • "tx_hash": "0x4f2a9c8b7e1d3a5f6c2b0a9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f",
  • "payment_link_code": "PL-4F2A-9C8B-7E1D",
  • "travel_rule_applied": false
}

Webhooks

Destinos a los que te avisamos cuando algo pasa en tu cuenta, y su secreto de firma.

Eventos a los que puedes suscribirte

El catálogo completo, con los campos que viajan en data de cada uno. Esa lista de campos es la lista blanca real: no llega nada más, ni aunque el evento interno tenga más datos.

Pídelo antes de crear un destino en vez de escribir los tipos a mano: un evento mal escrito se rechaza con 400, no en silencio.

Alcance requerido: webhooks:manage.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Tus destinos de webhooks

Del más reciente al más antiguo. Sin paginar: el tope por cuenta son 10 destinos, así que la lista cabe siempre en una respuesta.

Nunca incluye el secreto de firma, sólo sus últimos cuatro caracteres.

Alcance requerido: webhooks:manage.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Registra un destino

Única respuesta, junto con la rotación, que incluye signing_secret. Se muestra una sola vez: guárdalo al recibirlo, porque no se puede recuperar y perderlo obliga a rotar.

Con él verificas cada envío: la firma es un HMAC-SHA256 sobre el momento y el cuerpo tal cual llegó. El contrato completo está en la guía de webhooks enlazada en la portada.

El destino nace encendido.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
url
required
string [ 1 .. 2000 ] characters

URL a la que enviaremos los avisos. Tiene que ser https: y resolver a una dirección pública: se comprueba al darla de alta y antes de CADA envío, y no se sigue ninguna redirección.

description
string <= 200 characters

Etiqueta para distinguirlos cuando tienes varios.

enabled_events
required
Array of strings [ 1 .. 50 ] items unique

Eventos a los que se suscribe. Los válidos salen de GET /v1/webhook_endpoints/event_types.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "3e8b1d24-6f70-4c19-b2a5-0d9e7f4c6a13",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": true,
  • "disabled_at": null,
  • "disabled_reason": null,
  • "consecutive_failures": 0,
  • "last_success_at": null,
  • "last_failure_at": null,
  • "secret_rotated_at": null,
  • "created_at": "2026-09-01T10:00:00.000Z",
  • "signing_secret": "whsec_7f3a9c2e5b1d8a406c93e2f7b5a1d4c8"
}

Un destino

Útil para releer el estado sin descargarte la lista entera: live te dice si ahora mismo estás recibiendo avisos, y disabled_reason por qué no, si lo hemos apagado nosotros.

Alcance requerido: webhooks:manage.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "9a1f7c3e-2b4d-4a68-9e05-7c1b3d5a8f24",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": false,
  • "disabled_at": "2026-08-30T09:12:44.000Z",
  • "disabled_reason": "5 entregas agotadas seguidas",
  • "consecutive_failures": 5,
  • "last_success_at": "2026-08-29T18:41:02.000Z",
  • "last_failure_at": "2026-08-30T09:12:44.000Z",
  • "secret_rotated_at": null,
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Cambia la URL, la descripción o los eventos

Parcial: lo que no mandes, no se toca. El secreto de firma no cambia — para eso está la rotación.

Una description vacía la borra; omitirla la deja como estaba.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
url
string [ 1 .. 2000 ] characters

URL a la que enviaremos los avisos. Tiene que ser https: y resolver a una dirección pública: se comprueba al darla de alta y antes de CADA envío, y no se sigue ninguna redirección.

description
string <= 200 characters

Etiqueta del destino. La cadena vacía la QUITA; omitir el campo la deja como está.

enabled_events
Array of strings [ 1 .. 50 ] items unique

Eventos a los que se suscribe. Los válidos salen de GET /v1/webhook_endpoints/event_types.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "9a1f7c3e-2b4d-4a68-9e05-7c1b3d5a8f24",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": false,
  • "disabled_at": "2026-08-30T09:12:44.000Z",
  • "disabled_reason": "5 entregas agotadas seguidas",
  • "consecutive_failures": 5,
  • "last_success_at": "2026-08-29T18:41:02.000Z",
  • "last_failure_at": "2026-08-30T09:12:44.000Z",
  • "secret_rotated_at": null,
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Da de baja el destino

Dejamos de avisar a esa URL y su secreto se pierde. No se deshace.

Si sólo quieres dejar de recibir un rato, usa /disable: conserva el destino, su secreto y sus eventos.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Enciende el destino

Además del interruptor, limpia la desactivación automática y su contador de fallos. Por eso encender y apagar son dos operaciones y no un campo booleano: no son la misma al revés.

Si lo apagamos nosotros porque tu servidor rechazaba los envíos, arréglalo antes de encenderlo: si sigue rechazando, se vuelve a apagar.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Responses

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "9a1f7c3e-2b4d-4a68-9e05-7c1b3d5a8f24",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": false,
  • "disabled_at": "2026-08-30T09:12:44.000Z",
  • "disabled_reason": "5 entregas agotadas seguidas",
  • "consecutive_failures": 5,
  • "last_success_at": "2026-08-29T18:41:02.000Z",
  • "last_failure_at": "2026-08-30T09:12:44.000Z",
  • "secret_rotated_at": null,
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Apaga el destino sin darlo de baja

Deja de recibir avisos conservando el destino, su secreto y sus eventos. Es lo que quieres durante un mantenimiento: dar de baja y volver a crear cambiaría el secreto.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Responses

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "9a1f7c3e-2b4d-4a68-9e05-7c1b3d5a8f24",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": false,
  • "disabled_at": "2026-08-30T09:12:44.000Z",
  • "disabled_reason": "5 entregas agotadas seguidas",
  • "consecutive_failures": 5,
  • "last_success_at": "2026-08-29T18:41:02.000Z",
  • "last_failure_at": "2026-08-30T09:12:44.000Z",
  • "secret_rotated_at": null,
  • "created_at": "2026-06-14T11:05:23.000Z"
}

Rota el secreto de firma

El secreto anterior deja de valer de inmediato. Despliega el nuevo ANTES de rotar, o firmarás con uno que tu servidor todavía no conoce: los envíos que rechace se reintentan durante horas, pero no para siempre, y cinco entregas agotadas seguidas apagan el destino.

Como en el alta, el secreto se devuelve una sola vez.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Responses

Response samples

Content type
application/json
{
  • "object": "webhook_endpoint",
  • "id": "3e8b1d24-6f70-4c19-b2a5-0d9e7f4c6a13",
  • "url": "https://api.mitienda.mx/binkio/webhooks",
  • "description": "Producción",
  • "enabled_events": [
    ],
  • "secret_last_four": "4f9c",
  • "enabled": true,
  • "live": true,
  • "disabled_at": null,
  • "disabled_reason": null,
  • "consecutive_failures": 0,
  • "last_success_at": null,
  • "last_failure_at": null,
  • "secret_rotated_at": null,
  • "created_at": "2026-09-01T10:00:00.000Z",
  • "signing_secret": "whsec_7f3a9c2e5b1d8a406c93e2f7b5a1d4c8"
}

Manda un `webhook.test` firmado y te cuenta qué pasó

Devuelve el desenlace real, no un acuse de que lo intentamos: si tu servidor contestó 500, aquí lo ves con su last_status_code y su last_error.

Es la forma de comprobar tu verificación de firma sin esperar a que ocurra un cobro de verdad. webhook.test no es suscribible: se manda a este destino aunque no lo tengas en enabled_events.

Alcance requerido: webhooks:manage.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Responses

Response samples

Content type
application/json
{
  • "object": "webhook_delivery",
  • "id": "c7d2e491-3a58-4b6f-8102-9e4d7a3c5b60",
  • "endpoint_id": "3e8b1d24-6f70-4c19-b2a5-0d9e7f4c6a13",
  • "event_id": "evt_5b1d8a406c93e2f7",
  • "event_type": "webhook.test",
  • "status": "failed",
  • "attempt_count": 1,
  • "attempts": [
    ],
  • "next_retry_at": "2026-09-06T12:31:11.482Z",
  • "delivered_at": null,
  • "last_status_code": 500,
  • "last_error": "El destino respondió 500",
  • "created_at": "2026-09-06T12:30:11.201Z"
}

Qué te hemos intentado entregar, y cómo fue

Del intento más reciente al más antiguo. Es lo PRIMERO que hay que mirar cuando un aviso no llega: dice si salió, cuántas veces se intentó, qué respondió tu servidor en cada intento y cuándo toca el siguiente.

status distingue los cuatro estados reales: pending (en cola), delivering (ahora mismo), succeeded y failed. Una entrega agotada se queda en failed con next_retry_at en null.

Para recorrer el histórico completo, repite la llamada pasando next_cursor en cursor mientras has_more sea true.

Alcance requerido: webhooks:manage.

Authorizations:
api-key
path Parameters
id
required
string
query Parameters
limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántas entregas por página.

cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

status
string
Enum: "pending" "delivering" "succeeded" "failed"
Example: status=failed

Devuelve sólo las entregas con este desenlace. Lo normal es venir a buscar failed.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wN1QxNzowNToxMS4wMDBaIn0"
}

Registro de llamadas

Tus propias llamadas a la API: qué pediste, qué respondimos y cuándo. Es lo primero que hay que mirar cuando algo no cuadra.

Tus llamadas a la API, paginadas por cursor

Devuelve las llamadas de la más reciente a la más antigua, de todas las credenciales de la cuenta. Para recorrer el histórico, repite la llamada pasando next_cursor en cursor mientras has_more sea true.

Es el primer sitio donde mirar antes de abrir un ticket: si tu llamada no aparece aquí, no nos llegó.

Ojo con dos campos que se parecen: call_request_id es el req_… de la llamada REGISTRADA (el que abres en un ticket) y request_id, al nivel de la respuesta, es el de esta consulta.

Alcance requerido: logs:read.

Authorizations:
api-key
query Parameters
limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántas llamadas por página.

cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

api_key_id
string <uuid>
Example: api_key_id=d41f8a2c-9b73-4e15-a6c8-3f0e7b2d1a94

Sólo las llamadas hechas con ESTA credencial.

method
string
Enum: "GET" "POST" "PUT" "PATCH" "DELETE"
Example: method=POST

Sólo las llamadas con este método HTTP.

status
number <int32> [ 100 .. 599 ]
Example: status=429

Código HTTP exacto.

failed
boolean
Example: failed=true

true devuelve sólo las llamadas que fallaron (400 o más); false, sólo las correctas.

created_after
string <date-time>
Example: created_after=2026-09-01T00:00:00Z

Sólo llamadas hechas en o después de esta fecha.

created_before
string <date-time>
Example: created_before=2026-09-01T00:00:00Z

Sólo llamadas hechas en o antes de esta fecha.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Detalle de una llamada, con lo que mandaste

Añade al listado los parámetros y el cuerpo de la petición, redactados: los campos con nombre sensible (contraseñas, secretos, firmas, tarjetas) salen como [REDACTED] y los valores muy largos, truncados.

El cuerpo de la RESPUESTA no se guarda: lo que se conserva es status y error_code, que es lo que necesitas para decidir qué hacer.

Alcance requerido: logs:read.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "request_log",
  • "id": "5c4b3a2f-1e0d-4c9b-8a76-5f4e3d2c1b0a",
  • "call_request_id": "req_9f2a4c8b7e1d3a5f",
  • "api_key_id": "7c1f0a4e-3d2b-4f9a-8b11-2e6c9d4a5f30",
  • "method": "POST",
  • "path": "/v1/payment_links",
  • "status": 422,
  • "error_code": "idempotency_key_reused",
  • "duration_ms": 41,
  • "ip": "187.190.12.44",
  • "idempotency_key": "9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c",
  • "idempotent_replay": false,
  • "created_at": "2026-08-04T14:30:00.000Z",
  • "query": { },
  • "request_body": {
    },
  • "user_agent": "binkio-node/1.4.2"
}

Depósitos

Dónde te pueden mandar dinero —CLABE, llave Bre-B, direcciones on-chain— y qué ha entrado. Sólo lectura: un depósito lo inicia quien envía.

Dónde te pueden mandar dinero

Todos los sitios a los que tu cuenta puede recibir: la CLABE para SPEI, la llave Bre-B para Colombia y las direcciones on-chain, cada una con su red.\n\nMira usable. Una vía recién aprovisionada puede estar todavía en trámite con el proveedor; enseñársela a un pagador antes de tiempo es perder el dinero que mande.\n\n:::danger La red importa más que la dirección\nEn las instrucciones de cripto, network es la red EXACTA. Mandar el mismo activo por otra red pierde el dinero y no se recupera. Enséñala junto a la dirección, siempre.\n:::\n\nEstos datos son estables: la CLABE de una cuenta no cambia. Se pueden guardar, pero conviene refrescarlos cuando aparezca un activo nuevo.

Alcance requerido: deposits:read.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Lo que ha entrado en tu cuenta

Del más reciente al más antiguo, con el riel por el que llegó y de dónde vino cuando el proveedor lo informa.\n\nPara enterarte de un depósito EN CUANTO llega, suscríbete a deposit.completed en vez de sondear aquí. → /v1/webhook_endpoints

Alcance requerido: deposits:read.

Authorizations:
api-key
query Parameters
cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántos depósitos por página.

status
string
Enum: "processing" "completed" "failed"
Example: status=completed

Devuelve sólo los depósitos en este estado. El filtro se aplica en la consulta, así que la página viene llena y se puede paginar.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

El detalle de un depósito

Tres estados: processing (llegó y se está confirmando), completed (acreditado en tu saldo) y failed.\n\n**processing no es un fallo**: un depósito en cadena espera confirmaciones y uno por transferencia espera al banco.

Alcance requerido: deposits:read.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "deposit",
  • "id": "e2f8a1c4-6b09-4d73-8e5a-1c7f3b90d426",
  • "status": "completed",
  • "rail": "spei",
  • "amount": "25000.00000000",
  • "asset": "MXNB",
  • "source": "012180001234567890",
  • "provider_reference": "JUNO-ISS-7C3D1A2B",
  • "created_at": "2026-09-08T10:14:02.000Z",
  • "completed_at": "2026-09-08T10:14:37.000Z"
}

Conversiones

Cambiar el saldo de un activo a otro. Dos pasos: pedir precio y ejecutarlo, porque el precio caduca.

Pide precio para una conversión

Devuelve cuánto recibirías, a qué tasa y hasta cuándo vale ese precio. No mueve dinero y no consume nada: cotizar dos veces devuelve dos precios distintos si el mercado se movió, que es lo correcto.\n\nExige Idempotency-Key, como todo POST de la API. Ojo a la consecuencia: repetir la misma clave devuelve la cotización GUARDADA, no una nueva. Para pedir precio otra vez, clave nueva.\n\nGuarda el quote_id: es lo único que POST /v1/conversions acepta para ejecutar ESTE precio.\n\nto_amount ya trae la comisión descontada — es lo que de verdad entra en tu cuenta, no el bruto.\n\nSi off_market viene en true, el mercado del par está cerrado (fin de semana, festivo) y la tasa es peor de lo habitual. Es la única explicación de por qué el precio de un domingo no es el del martes.

Alcance requerido: conversions:read.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
from_asset
required
string
Enum: "MXNB" "USDC" "USDT" "COP"

Activo de origen.

to_asset
required
string
Enum: "MXNB" "USDC" "USDT" "COP"

Activo de destino.

amount
required
string^\d{1,12}(\.\d{1,8})?$

Cuánto convertir, expresado en from_asset.

Responses

Request samples

Content type
application/json
{
  • "from_asset": "USDC",
  • "to_asset": "MXNB",
  • "amount": "1500.00"
}

Response samples

Content type
application/json
{
  • "object": "conversion_quote",
  • "quote_id": "cq_7f3a2b9c1d4e8a6f",
  • "from_asset": "MXNB",
  • "to_asset": "USDC",
  • "from_amount": "30000.00000000",
  • "to_amount": "1738.52000000",
  • "exchange_rate": "17.25000000",
  • "fee": "17.39000000",
  • "fee_percentage": "1.00",
  • "expires_at": "2026-09-08T14:32:10.000Z",
  • "off_market": false
}

Ejecuta una cotización

Convierte al precio que devolvió POST /v1/conversions/quote. El quote_id es obligatorio: no se puede ejecutar «lo último que cotizaste», porque entonces no habría forma de saber qué precio aceptaste.\n\nfrom_asset, to_asset y amount van ADEMÁS del quote_id y se contrastan con lo que guardamos al cotizar. Si no cuadran, se rechaza — es lo que impide que reusar por error un quote_id de otro par convierta algo distinto de lo que aceptaste.\n\nmax_slippage_bps acota cuánto puede empeorar la tasa entre las dos llamadas. Entre cotizar y ejecutar pasa tiempo real y el mercado se mueve: sin tope, una ejecución tardía se liquida a un precio que nadie aceptó.\n\nLa respuesta puede llegar en processing: las rutas de dos patas —vender y emitir— no terminan en la misma llamada. processing no es un fallo.

Alcance requerido: conversions:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
quote_id
required
string

El id que devolvió POST /v1/conversions/quote.

from_asset
required
string
Enum: "MXNB" "USDC" "USDT" "COP"

Activo de origen. Debe coincidir con el de la cotización: si no, se rechaza sin convertir nada.

to_asset
required
string
Enum: "MXNB" "USDC" "USDT" "COP"

Activo de destino. Debe coincidir con el de la cotización.

amount
required
string^\d{1,12}(\.\d{1,8})?$

Importe a convertir. Debe coincidir con el de la cotización.

max_slippage_bps
number <int32> [ 0 .. 1000 ]

Cuánto puede empeorar la tasa entre cotizar y ejecutar, en puntos básicos (100 bps = 1 %). Si se supera, la conversión falla en vez de liquidarse a un precio que nadie aceptó.

Responses

Request samples

Content type
application/json
{
  • "quote_id": "qt_9f2a4c8b7e1d3a5f",
  • "from_asset": "USDC",
  • "to_asset": "MXNB",
  • "amount": "1500.00",
  • "max_slippage_bps": 50
}

Response samples

Content type
application/json
{
  • "object": "conversion",
  • "id": "a7c2e910-4b6d-4f83-9e21-c5b8a0d3f742",
  • "status": "completed",
  • "from_asset": "MXNB",
  • "to_asset": "USDC",
  • "from_amount": "30000.00000000",
  • "to_amount": "1738.52000000",
  • "exchange_rate": "17.25000000",
  • "fee": "17.39000000",
  • "failure_reason": null,
  • "created_at": "2026-09-08T14:30:04.000Z",
  • "completed_at": "2026-09-08T14:30:21.000Z"
}

Tus conversiones, de la más reciente a la más antigua

Para conciliar: from_amount es lo que salió del activo de origen y to_amount lo que entró en el de destino. La diferencia contra la tasa es la comisión.

Alcance requerido: conversions:read.

Authorizations:
api-key
query Parameters
cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántas conversiones por página.

status
string
Enum: "processing" "completed" "failed"
Example: status=completed

Devuelve sólo las conversiones en este estado.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

El detalle de una conversión

Tres estados: processing (en marcha), completed (el saldo ya está en el activo de destino) y failed.\n\nCuando falla, failure_reason dice QUÉ paso falló. Importa: una conversión por la vía de mercado tiene dos patas —vender y emitir— y saber cuál se cayó es lo que decide si tiene sentido reintentar.

Alcance requerido: conversions:read.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "conversion",
  • "id": "a7c2e910-4b6d-4f83-9e21-c5b8a0d3f742",
  • "status": "completed",
  • "from_asset": "MXNB",
  • "to_asset": "USDC",
  • "from_amount": "30000.00000000",
  • "to_amount": "1738.52000000",
  • "exchange_rate": "17.25000000",
  • "fee": "17.39000000",
  • "failure_reason": null,
  • "created_at": "2026-09-08T14:30:04.000Z",
  • "completed_at": "2026-09-08T14:30:21.000Z"
}

Retiros

Sacar el dinero cobrado hacia tus cuentas bancarias. Sólo a destinos ya dados de alta: la API no puede añadir uno nuevo.

Las cuentas a las que puedes retirar

Las cuentas bancarias dadas de alta en el panel, que son las únicas a las que la API puede enviar dinero. El id de una de ellas es lo que lleva POST /v1/withdrawals.\n\nMira usable antes de ordenar un retiro. Una cuenta recién dada de alta está esperando al proveedor y no admite envíos todavía; ordenar contra ella falla más adelante, con el saldo ya apartado.\n\nDel número de cuenta se publican sólo los últimos cuatro dígitos: sirven para reconocerla en una pantalla, y para ordenar el retiro se usa el id.

Alcance requerido: withdrawals:read.

Authorizations:
api-key
query Parameters
rail
string
Enum: "spei" "wire"
Example: rail=spei

Devuelve sólo los destinos de este riel.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

Ordena un retiro a una cuenta dada de alta

Saca dinero de tu saldo hacia una de tus cuentas. El riel —SPEI o transferencia internacional— lo decide el destino, no tú.\n\nEsta llamada no se deshace. Usa como Idempotency-Key un identificador tuyo y estable (el número de la orden de pago, el del lote), nunca un aleatorio: un aleatorio hace que cada reintento sea un retiro nuevo.\n\nfee_mode decide quién pone la comisión. Con net_out (por defecto) pides 1.000 y llegan 1.000 menos comisión; con gross_up llegan 1.000 exactos y de tu saldo sale algo más.\n\nLa respuesta llega en processing: el dinero está en camino, no entregado. El desenlace llega por el webhook withdrawal.completed o withdrawal.failed, y también se puede consultar aquí.

Alcance requerido: withdrawals:write.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
destination_id
required
string <uuid>

El destino al que enviar, tomado de GET /v1/payout_destinations. El riel (SPEI o WIRE) lo determina el destino, no el cuerpo.

amount
required
string^\d{1,12}(\.\d{1,8})?$

Importe a retirar, en la divisa del destino.

concept
required
string [ 1 .. 40 ] characters

Lo que verá el beneficiario en su estado de cuenta. El tope de 40 caracteres lo impone SPEI.

fee_mode
string
Default: "net_out"
Enum: "net_out" "gross_up"

Quién asume la comisión. net_out (por defecto) la descuenta del importe: pides 1000 y llegan 1000 menos comisión. gross_up la suma: llegan 1000 exactos y de tu saldo sale algo más.

Responses

Request samples

Content type
application/json
{
  • "destination_id": "d41f8a2c-9b73-4e15-a6c8-3f0e7b2d1a94",
  • "amount": "1500.00",
  • "concept": "Liquidacion septiembre",
  • "fee_mode": "net_out"
}

Response samples

Content type
application/json
{
  • "object": "withdrawal",
  • "id": "9f3b1c7e-2a4d-4e8f-b0c6-1d5a2e9f4b83",
  • "status": "processing",
  • "rail": "spei",
  • "destination_last_four": "3456",
  • "amount": "5015.50000000",
  • "net_amount": "5000.00000000",
  • "fee": "15.50000000",
  • "asset": "MXNB",
  • "concept": "Liquidacion semana 36",
  • "provider_reference": null,
  • "receipt_url": null,
  • "failure_reason": null,
  • "created_at": "2026-09-07T19:02:11.000Z",
  • "completed_at": null
}

Tus retiros, del más reciente al más antiguo

Para conciliar: amount es lo que salió de tu saldo y net_amount lo que recibió el destino. La diferencia es la comisión.\n\nreceipt_url trae el CEP —el comprobante oficial de Banxico— en cuanto el proveedor lo publica. Es lo que vale como prueba ante quien cobró.

Alcance requerido: withdrawals:read.

Authorizations:
api-key
query Parameters
limit
number <int32> [ 1 .. 100 ]
Default: 25
Example: limit=25

Cuántos retiros por página.

cursor
string <= 512 characters
Example: cursor=eyJ2IjoxLCJ0IjoiMjAyNi0wOS0wOFQxNzo1ODo0Mi40MzgyMzRaIn0

El next_cursor de la respuesta anterior, tal cual. Es opaco: no lo interpretes ni lo construyas.

status
string
Enum: "processing" "completed" "failed" "cancelled"
Example: status=completed

Devuelve sólo los retiros en este estado.

header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false,
  • "next_cursor": null
}

El detalle de un retiro

El estado real, sin depender de que el webhook haya llegado.\n\nCuatro estados: processing (en camino), completed (llegó), failed (no salió, el saldo volvió a tu cuenta) y cancelled. processing no es un fallo: un SPEI tarda minutos y una transferencia internacional, días.

Alcance requerido: withdrawals:read.

Authorizations:
api-key
path Parameters
id
required
string
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "withdrawal",
  • "id": "9f3b1c7e-2a4d-4e8f-b0c6-1d5a2e9f4b83",
  • "status": "processing",
  • "rail": "spei",
  • "destination_last_four": "3456",
  • "amount": "5015.50000000",
  • "net_amount": "5000.00000000",
  • "fee": "15.50000000",
  • "asset": "MXNB",
  • "concept": "Liquidacion semana 36",
  • "provider_reference": null,
  • "receipt_url": null,
  • "failure_reason": null,
  • "created_at": "2026-09-07T19:02:11.000Z",
  • "completed_at": null
}

Envía activos a una dirección de blockchain

El destino va en el cuerpo y no se valida contra ninguna lista: no hay direcciones dadas de alta que comprobar. Es lo que separa esta llamada de POST /v1/withdrawals, y por eso lleva su propio alcance.

:::danger Esto no se deshace, y no hay a quién reclamar Una dirección equivocada, o la red equivocada, pierde el dinero para siempre. No lo recupera soporte, ni el proveedor, ni nosotros. Valida la dirección en tu lado antes de llamar, y no la construyas concatenando cadenas. :::

network es obligatorio y no tiene valor por defecto. El mismo activo vive en varias redes y la dirección no dice en cuál: deducirla por ti sería acertar casi siempre y perder el dinero el resto de las veces.

A partir de cierto importe hace falta beneficiary (Regla de Viaje, FATF R.16). Se pide ANTES de mover nada: sin esos datos el proveedor rechaza el envío, y para entonces el saldo ya está apartado.

Alcance requerido: withdrawals:crypto.

Exige la cabecera Idempotency-Key.

Authorizations:
api-key
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Idempotency-Key
required
string
Example: 9f2a4c8b-7e1d-4a5f-8c3b-2d1e0f9a8b7c

Clave única de la operación (uuid o cadena de ≤255). Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con Idempotent-Replay: true, sin volver a ejecutar.

Request Body schema: application/json
required
asset
required
string
Enum: "MXNB" "USDC" "USDT"

Activo a enviar.

amount
required
string^\d{1,12}(\.\d{1,8})?$

Importe a enviar, en el activo indicado.

address
required
string [ 20 .. 128 ] characters

Dirección de destino. No se valida contra ninguna lista: sólo se comprueba la forma. Que sea la dirección correcta es cosa tuya, y el envío no tiene vuelta atrás.

network
required
string [ 2 .. 32 ] characters

Red por la que enviar. Obligatorio y sin valor por defecto: el mismo activo vive en varias redes, la dirección se parece, y enviarlo por la equivocada lo pierde. Las redes disponibles para cada activo salen de lo que el proveedor admita en ese momento.

fee_mode
string
Default: "net_out"
Enum: "net_out" "gross_up"

Quién asume la comisión. net_out (por defecto) la descuenta del importe: pides 1000 y llegan 1000 menos comisión. gross_up la suma: llegan 1000 exactos y de tu saldo sale algo más.

object

Datos del beneficiario, exigidos por la Regla de Viaje a partir de cierto importe (FATF R.16). Por debajo del umbral se ignoran.

Responses

Request samples

Content type
application/json
{
  • "asset": "USDC",
  • "amount": "500.00",
  • "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  • "network": "arbitrum",
  • "fee_mode": "net_out",
  • "beneficiary": {
    }
}

Response samples

Content type
application/json
{
  • "object": "withdrawal",
  • "id": "9f3b1c7e-2a4d-4e8f-b0c6-1d5a2e9f4b83",
  • "status": "processing",
  • "rail": "spei",
  • "destination_last_four": "3456",
  • "amount": "5015.50000000",
  • "net_amount": "5000.00000000",
  • "fee": "15.50000000",
  • "asset": "MXNB",
  • "concept": "Liquidacion semana 36",
  • "provider_reference": null,
  • "receipt_url": null,
  • "failure_reason": null,
  • "created_at": "2026-09-07T19:02:11.000Z",
  • "completed_at": null
}

Checkout

La pantalla que ve el PAGADOR. Sin credencial, a propósito: quien paga no tiene cuenta con nosotros.

El cobro tal como lo ve quien va a pagar

Público: la credencial es el propio código del enlace. Devuelve el importe, quién cobra, las instrucciones de cada método y hasta cuándo vale cada importe. Un método con la cotización vencida no trae ni importe ni instrucciones: enviar dinero contra un importe caducado no acredita.

Alcance requerido: ninguno. Basta una credencial válida — es una comprobación, y exigir un alcance para ella empujaría a emitir claves más permisivas de lo necesario.

path Parameters
code
required
string
Example: PL-A1B2-C3D4-E5F6
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "checkout",
  • "return_url": "https://tutienda.com/pedido/4821/gracias",
  • "code": "PL-A1B2-C3D4-E5F6",
  • "status": "active",
  • "payable": true,
  • "unpayable_reason": null,
  • "amount": "1500.00000000",
  • "currency": "MXNB",
  • "description": "Pedido #10432",
  • "merchant": {
    },
  • "server_time": "2026-09-07T18:30:00.000Z",
  • "expires_at": "2026-09-08T18:30:00.000Z",
  • "expires_in": 86400,
  • "paid_at": null,
  • "checkout_url": "https://app.binkio.com/pay/PL-A1B2-C3D4-E5F6",
  • "qr": {
    },
  • "methods": [
    ],
  • "realtime": {}
}

Estado del cobro, para sondear mientras se espera el pago

Respuesta mínima y sin QR. Pensado para llamarse tras un aviso del canal en tiempo real, o cada poll_interval_seconds si no se puede usar. Es la FUENTE DE VERDAD del estado: la carga útil de los eventos del socket no forma parte de este contrato.

Alcance requerido: ninguno. Basta una credencial válida — es una comprobación, y exigir un alcance para ella empujaría a emitir claves más permisivas de lo necesario.

path Parameters
code
required
string
Example: PL-A1B2-C3D4-E5F6
header Parameters
Binkio-Version
string
Example: 2026-09-09

Versión del contrato para esta llamada. Sin ella se aplica la que tiene fijada tu credencial, que no cambia sola. Sirve para probar una versión nueva en una llamada suelta antes de adoptarla. Una versión que no existe se rechaza con 400 unknown_api_version: no se cae en silencio a la actual.

Responses

Response samples

Content type
application/json
{
  • "object": "checkout_status",
  • "code": "PL-A1B2-C3D4-E5F6",
  • "status": "active",
  • "payable": true,
  • "unpayable_reason": null,
  • "paid_at": null,
  • "server_time": "2026-09-07T18:30:00.000Z"
}