API pública

La API de Binkio convierte tu sistema en el que cobra: creas enlaces de pago desde tu tienda, tu ERP o tu punto de venta, y te avisamos cuando se pagan. Sin que nadie tenga que entrar al panel.

Lo que la separa de un botón de pago corriente son tres cosas:

Multi-moneda — cobras en pesos digitales, dólares digitales o pesos colombianos.
Multi-riel — tu cliente paga por transferencia bancaria (SPEI, wire) o en cadena (MXNB, USDC, USDT). Tú eliges qué le ofreces.
Pagos cruzados — él manda una cosa y tú recibes otra. Transfiere pesos por SPEI y tu cuenta se abona en dólares digitales, sin que ninguno de los dos toque un exchange. → Pagos cruzados

https://api.binkio.com/v1

:::tip ¿Primera vez? Tu primer cobro en cinco pasos — de la credencial al webhook, con curl copiable. :::

La referencia completa, con cada endpoint, sus parámetros y sus errores, está publicada y se genera del propio código:

Referencia navegable
Documento OpenAPI — para generar un cliente en tu lenguaje

Esta página cubre lo transversal: lo que aplica a todas las llamadas y que no cabe en la ficha de ningún endpoint concreto.

:::info Sólo para cuentas de empresa Las credenciales de API están disponibles para personas morales con la verificación de empresa (KYB) aprobada. Si tu cuenta es de persona física, la sección de credenciales no aparece en el panel. :::

Autenticación

Cada llamada lleva el secreto de tu credencial en la cabecera Authorization:

Authorization: Bearer bk_live_sec_7f3a…

El secreto se muestra una sola vez, al crear la credencial o al rotarla. No lo podemos recuperar: si lo pierdes, rota la credencial y despliega el nuevo.

curl https://api.binkio.com/v1/ping \
  -H "Authorization: Bearer bk_live_sec_7f3a…"

GET /v1/ping es la forma de comprobar de punta a punta que tu credencial funciona, contra qué entorno estás pegando y qué alcances tiene — sin mover un peso. Es el primer sitio donde mirar cuando algo no responde como esperas.

Alcances

Una credencial sólo puede hacer aquello para lo que la emitiste. Los alcances se eligen al crearla y no cambian solos:

Alcance	Qué habilita
`balances:read`	Leer los saldos de la cuenta por activo
`transactions:read`	Leer el histórico de movimientos y su detalle
`links:read`	Consultar enlaces de pago y su estado
`links:write`	Crear, modificar y cancelar enlaces de pago
`qr:read`	Consultar los QR de mostrador y sus cobros
`qr:write`	Crear y administrar QR de mostrador
`logs:read`	Leer el registro de tus llamadas a la API
`webhooks:manage`	Registrar y administrar los destinos de tus avisos

Emite una credencial por integración, con lo mínimo que necesite. Una terminal de mostrador se lleva qr:write y nada más: si esa terminal se compromete, el daño queda acotado a lo que esa credencial podía hacer. Una sola credencial con todos los alcances repartida por tres sistemas es una credencial que no puedes revocar sin tumbar los tres.

También puedes restringir una credencial a un conjunto de direcciones IP.

Idempotencia

Toda llamada que crea o modifica algo exige la cabecera Idempotency-Key. No es opcional: sin ella recibes un 400.

curl -X POST https://api.binkio.com/v1/payment_links \
  -H "Authorization: Bearer bk_live_sec_7f3a…" \
  -H "Idempotency-Key: pedido-4821" \
  -H "Content-Type: application/json" \
  -d '{"amount":"1500.25","currency":"MXNB","description":"Pedido 4821"}'

Si repites la llamada con la misma clave, te devolvemos la respuesta original en lugar de crear un segundo cobro, y la marcamos con Idempotent-Replay: true.

Úsala siempre que crees algo. Una petición que se corta por un tiempo de espera agotado pudo haberse ejecutado igualmente: sin clave de idempotencia, tu reintento crea un cobro duplicado.

La clave vive 24 horas y va atada al cuerpo de la petición: reutilizarla con un cuerpo distinto es un error, no un reemplazo silencioso.

Límites

Cada credencial tiene su propio límite. Las respuestas correctas traen tres cabeceras para que puedas autorregularte en vez de descubrir el tope a golpes:

Cabecera	Qué dice
`RateLimit-Limit`	Tu tope por minuto
`RateLimit-Remaining`	Lo que te queda en la ventana actual
`RateLimit-Reset`	Segundos hasta que se reinicie

Pasado el tope recibes un 429 con la cabecera Retry-After: los segundos exactos que faltan. Espera eso, no un valor inventado — reintentar antes vuelve a dar 429 y consume otro hueco de la ventana.

Compresión

Mándanos Accept-Encoding: gzip y te devolvemos la respuesta comprimida. Compensa: el contrato completo pasa de 527 KB a 40, y una página de cien registros de 37 KB a 6. Por debajo de 1 KB no comprimimos — el trabajo cuesta más que los bytes que ahorra.

Casi todos los clientes HTTP lo mandan solos. Si el tuyo no, ponlo.

Dónde quedó lo que acabas de crear

Toda respuesta 201 trae la cabecera Location con la URL del recurso recién creado. Se puede seguir tal cual:

HTTP/1.1 201 Created
Location: /v1/payment_links/PL-4F2A-9C8B-7E1D
Idempotency-Key: pedido-4821

No hace falta que construyas la URL: un retiro se consulta por id y un enlace por code, y la cabecera te ahorra saberlo. La repetición idempotente trae la misma Location que el primer intento — el recurso existe igual, lo creó esa primera llamada.

Errores

Todos los errores tienen la misma forma:

{
  "error": {
    "type": "invalid_request",
    "code": "insufficient_balance",
    "message": "No hay saldo suficiente para esta operación.",
    "param": "amount",
    "request_id": "req_9f2a4c8b7e1d3a5f"
  }
}

Ramifica sobre code, nunca sobre message. El code es parte del contrato; el message está escrito para que una persona lo entienda y puede cambiar de redacción.

El request_id viaja en toda respuesta, correcta o no, y también en la cabecera X-Request-Id. Es el identificador con el que se abre un ticket: guárdalo en tus registros.

Paginación

Los listados devuelven un objeto list y se recorren por cursor:

{
  "object": "list",
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJ…"
}

Repite la llamada pasando next_cursor en el parámetro cursor mientras has_more sea true. El cursor es opaco: no lo interpretes ni lo fabriques, pásalo tal cual.

Registro de llamadas

GET /v1/request_logs te devuelve tus propias llamadas: qué pediste, qué respondimos, cuándo, desde qué IP y con qué credencial.

Es el primer sitio donde mirar antes de abrir un ticket. Si tu llamada no aparece ahí, no nos llegó — y el problema está entre tu servidor y nosotros, no en la API.

Por dónde seguir


Inicio rápido	De cero a tu primer cobro, con `curl`
Enlaces de pago	Monedas, métodos, comisiones, ciclo de vida, checkout
Pagos cruzados	Cobrar en una moneda y recibir en otra
Cobro con QR	El QR fijo de mostrador
Webhooks	Recibir y verificar los avisos
Errores	Todos los códigos y qué hacer con cada uno
Salir a producción	Lista de verificación antes de cobrar de verdad

Y la referencia endpoint por endpoint, generada del propio código: api.binkio.com/v1/docs.

Autenticación​

Alcances​

Idempotencia​

Límites​

Compresión​

Dónde quedó lo que acabas de crear​

Errores​

Paginación​

Registro de llamadas​

Por dónde seguir​