Tu primer cobro

Cinco pasos. Al final tendrás un enlace que puedes mandarle a un cliente y un aviso en tu servidor cuando lo pague.

:::info Antes de empezar Necesitas una cuenta de empresa (persona moral) con la verificación KYB aprobada. Es el único requisito: las credenciales de API no están disponibles para cuentas de persona física. :::

1 · Emite tu credencial

En el panel: Configuración → Credenciales de API → Crear credencial.

Ponle un nombre que te diga qué sistema la usa (Tienda en línea, TPV sucursal Centro) y marca sólo los alcances que ese sistema necesita. Para una tienda que cobra y quiere enterarse:

links:write y links:read — crear y consultar cobros
webhooks:manage — decirnos dónde avisarte
balances:read y transactions:read — si vas a conciliar

El secreto (bk_live_sec_…) se muestra una sola vez. Cópialo en ese momento: no lo podemos recuperar, y perderlo obliga a rotar la credencial.

:::tip Una credencial por integración Entre menos permisos, menos daño si se filtra. Una clave de mostrador con qr:write y nada más no puede leer el histórico de tu empresa — y si esa terminal se compromete, la revocas sin tumbar el resto. :::

:::danger No hay entorno de pruebas separado Tu credencial pertenece al entorno donde se emitió, y hoy no ofrecemos un sandbox público: lo que crees con una credencial de producción es real.

Para ensayar sin arriesgar, usa importes pequeños —por encima del mínimo del riel, que el 400 amount_too_low te dice cuál es— y cancela el enlace con POST /v1/payment_links/{code}/cancel al terminar. Crear y cancelar un enlace no mueve dinero; sólo lo mueve un pago.

Y POST /v1/ping existe justamente para ensayar la idempotencia de punta a punta sin tocar dinero: llámalo dos veces con la misma Idempotency-Key y compara el execution_id. :::

2 · Comprueba que funciona

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

{
  "ok": true,
  "environment": "live",
  "api_key": {
    "id": "5b9941bf-…",
    "name": "Tienda en línea",
    "last_four": "9f2a",
    "scopes": ["links:read", "links:write", "webhooks:manage"]
  },
  "request_id": "req_9f2a4c8b7e1d3a5f"
}

Esta llamada no mueve un peso y te dice tres cosas: que la credencial es válida, contra qué entorno estás pegando y qué puede hacer. Es el primer sitio donde mirar cuando algo no responde como esperas.

3 · Crea el cobro

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

{
  "object": "payment_link",
  "code": "PL-9C2X-4T7B-1KD8",
  "status": "active",
  "amount": "1500.25000000",
  "currency": "MXNB",
  "fee_bearer": "payer",
  "accepted_methods": ["SPEI", "MXNB", "USDC"],
  "checkout_url": "https://app.binkio.com/pay/PL-9C2X-4T7B-1KD8",
  "created_at": "2026-09-07T10:14:22.481Z",
  "request_id": "req_5c4b3a2f1e0d4c9b"
}

Tres cosas que conviene entender de esta llamada:

amount va como cadena, no como número. Un float de JSON no representa 0.1 exactamente: si mandas 1500.25 como número, la precisión ya se perdió antes de que lo leamos. Con cadena llega exactamente lo que escribiste.

Idempotency-Key es obligatoria, no opcional. Una petición que se corta por un tiempo de espera agotado pudo haberse ejecutado igual; sin la clave, tu reintento le cobra dos veces a tu cliente. Usa tu propio identificador de pedido.

accepted_methods es lo que hace multi-riel a esta liga. Ahí decides si tu cliente puede pagarte por transferencia bancaria, en cripto, o eligiendo entre varias. Cada método se cotiza por separado. → Enlaces de pago

4 · Mándale el enlace a tu cliente

checkout_url es la página de cobro alojada: tu cliente la abre, elige cómo pagar, ve exactamente cuánto y a dónde, y paga. No tienes que construir nada.

Si prefieres tu propia pantalla, GET /v1/checkout/{code} te da los mismos datos —métodos, importes, instrucciones— sin credencial, porque el código del enlace es la credencial del pagador. → El checkout

Y si necesitas el código QR para imprimirlo o pintarlo:

curl https://api.binkio.com/v1/payment_links/PL-9C2X-4T7B-1KD8/qr \
  -H "Authorization: Bearer bk_live_sec_…"

Te devuelve el SVG dentro del JSON, listo para incrustar.

5 · Entérate cuando te paguen

Consultar el enlace en bucle funciona, pero es caro y lento. Dinos a dónde avisarte:

curl -X POST https://api.binkio.com/v1/webhook_endpoints \
  -H "Authorization: Bearer bk_live_sec_…" \
  -H "Idempotency-Key: destino-produccion" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.mitienda.mx/binkio/webhooks",
    "description": "Producción",
    "enabled_events": ["payment_link.paid"]
  }'

La respuesta trae el signing_secret, y es la única vez que lo verás. Con él verificas que cada aviso viene de nosotros.

Cuando el cobro se complete recibirás:

{
  "id": "evt_9f2a4c8b7e1d3a5f",
  "type": "payment_link.paid",
  "created": 1757241262,
  "livemode": true,
  "data": {
    "code": "PL-9C2X-4T7B-1KD8",
    "link_code": "PL-9C2X-4T7B-1KD8",
    "amount": "1500.25000000",
    "currency": "MXNB",
    "net_amount": "1500.25000000",
    "net_currency": "MXNB",
    "payment_method": "SPEI"
  }
}

code y amount son los mismos que te devolvió la API al crear el enlace: por ahí se concilia. net_amount es lo que se abonó al comercio; aquí coincide con el total porque la comisión la puso el pagador (fee_bearer: "payer"). → El cuerpo, campo a campo

No proceses ese aviso sin verificar la firma primero. Es un POST a una URL pública: cualquiera que la adivine puede inventarte un cobro. → Cómo verificar la firma

Para probar tu verificación sin esperar a un cobro real:

curl -X POST https://api.binkio.com/v1/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer bk_live_sec_…" \
  -H "Idempotency-Key: prueba-1"

Te devuelve el desenlace real: si tu servidor contestó 500, lo verás con su código y su error.

Ya está

Con esos cinco pasos tienes una integración funcionando. Lo que sigue depende de lo que necesites:

Si quieres…	Ve a
Entender monedas, métodos y comisiones	Enlaces de pago
Cobrar en pesos algo que recibes en dólares digitales	Pagos cruzados
Cobrar en mostrador con un QR fijo	Cobro con QR
Saber qué hacer ante cada error	Errores
Salir a producción con todo cubierto	Lista de verificación

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

1 · Emite tu credencial​

2 · Comprueba que funciona​

3 · Crea el cobro​

4 · Mándale el enlace a tu cliente​

5 · Entérate cuando te paguen​

Ya está​