Cobro con QR

El QR de mostrador es un código fijo, pegado en tu caja, que no cambia. Cada vez que cobras algo generas un cargo contra él por el importe de ese ticket, y el cliente lo paga escaneando el mismo código de siempre.

Es lo que necesita un punto de venta: el cajero teclea el importe, el cliente escanea, y listo. Sin imprimir un QR nuevo por cada venta.

:::info El QR se crea desde el panel /v1 puede leerlo, configurarlo, cobrar contra él y consultarlo — pero no crearlo. La primera vez hay que entrar al panel del comercio. Si operas una plataforma que da de alta comercios de forma automática, tenlo en cuenta: ese paso todavía necesita una persona. :::

Consultar tu QR

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

{
  "object": "qr",
  "id": "34f4e409-…",
  "status": "active",
  "currency": "MXNB",
  "display_name": "Caja 1",
  "url": "https://app.binkio.com/pay/master/AShgI3mMYzIadVWN3maozr",
  "verification_code": "4F9C",
  "max_amount_per_charge": "5000.00",
  "max_amount_per_day": "50000.00",
  "amount_paid_today": "1250.00",
  "created_at": "2026-06-14T11:05:23.000Z"
}

verification_code es para el cajero: se enseña en el mostrador para que el cliente compruebe que el QR que escaneó es el del comercio y no una pegatina que alguien encimó. Píntalo junto al código.

status puede ser active, paused (lo apagaste tú) o revoked.

Configurarlo

curl -X PATCH https://api.binkio.com/v1/qr \
  -H "Authorization: Bearer bk_live_sec_…" \
  -H "Idempotency-Key: config-caja-1" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Caja 1",
    "max_amount_per_charge": "5000.00",
    "max_amount_per_day": "50000.00"
  }'

Los topes son tu red de seguridad. Un QR de mostrador está expuesto: cualquiera que lo vea puede generarle un cobro si tiene la credencial. Poner un máximo por cargo acota lo que puede salir mal, y amount_paid_today te deja vigilarlo.

Manda null en cualquiera de los dos para quitar el tope.

Cerrar y abrir la caja

curl -X POST https://api.binkio.com/v1/qr/pause  -H "Authorization: Bearer …" -H "Idempotency-Key: cierra-1"
curl -X POST https://api.binkio.com/v1/qr/resume -H "Authorization: Bearer …" -H "Idempotency-Key: abre-1"

Un QR pausado no admite cobros nuevos. Los que ya estaban generados siguen su curso.

Cobrar

curl -X POST https://api.binkio.com/v1/qr/charges \
  -H "Authorization: Bearer bk_live_sec_…" \
  -H "Idempotency-Key: ticket-77" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "350.50", "reference": "ticket-77" }'

La respuesta es un enlace de pago como cualquier otro, con su code, su checkout_url y su QR — atado al QR maestro por qr_id.

reference es tu número de ticket. Úsalo: es lo que te permite cuadrar cada cobro contra tu punto de venta sin llevar una tabla aparte.

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

Consultar los cobros

# Los cobros del QR, del más reciente al más antiguo
curl "https://api.binkio.com/v1/qr/charges?status=paid&limit=50" \
  -H "Authorization: Bearer bk_live_sec_…"

# El resumen
curl https://api.binkio.com/v1/qr/stats \
  -H "Authorization: Bearer bk_live_sec_…"

{
  "object": "qr_stats",
  "qr_id": "34f4e409-…",
  "currency": "MXNB",
  "charges_generated": 128,
  "charges_paid": 119
}

La diferencia entre generados y pagados es la que interesa mirar: cobros que se crearon y nadie pagó. Un salto ahí suele ser un problema de mostrador —el QR tapado, el cliente que se fue— no de la API.

Alcances

Para	Necesitas
Leer el QR, sus cobros y las estadísticas	`qr:read`
Configurar, pausar, reanudar y cobrar	`qr:write`

Una terminal de mostrador se lleva qr:write y nada más. No necesita leer el histórico de la empresa ni tocar los enlaces de pago; si esa terminal se compromete, el daño queda acotado a lo que esa credencial podía hacer. Emite una por caja y podrás revocar la de una sucursal sin tumbar las demás.

Consultar tu QR​

Configurarlo​

Cerrar y abrir la caja​

Cobrar​

Consultar los cobros​

Alcances​