Documentación

API para puntos de venta

Cinco endpoints REST para consultar, reservar, cobrar y reversar el saldo de una gift card desde tu POS. Todas las respuestas son JSON y los montos son pesos enteros (MXN).

Autenticación

Genera tu llave en el panel del restaurante y envíala en cada llamada. Cada llamada queda registrada en tu bitácora.

Authorization: Bearer rgl_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Generar o rotar mi llave en el panel →

Endpoints

GET/api/public/pos/v1/giftcards/{referencia}

Al escanear el QR: devuelve marca, saldo disponible, estado y vigencia. Sin datos personales. La referencia es el código de la gift card o el token del QR.

Respuesta

{
  "merchant": { "id": "...", "name": "Cantina Rosales" },
  "usable": true,
  "status": "active",
  "currency": "MXN",
  "initial_amount": 1000,
  "balance": 650,
  "held": 0,
  "available": 650,
  "expires_at": "2027-03-01T00:00:00Z"
}

POST/api/public/pos/v1/giftcards/{referencia}/authorize

En el checkout del POS: reserva un monto y devuelve un authorization_id que expira en minutos.

Cuerpo

{
  "amount": 350,
  "pos_reference": "ticket-4821",
  "ttl_minutes": 15
}

Respuesta

{
  "authorization": { "id": "...", "amount": 350, "expires_at": "...", "status": "pending" },
  "remaining_available": 300
}

POST/api/public/pos/v1/giftcards/{referencia}/redeem

Confirma el consumo. Idempotente por idempotency_key: reintentar la misma llave nunca descuenta doble. Puede capturar una autorización previa o descontar directo.

Cuerpo

{
  "amount": 350,
  "authorization_id": "opcional",
  "pos_reference": "ticket-4821",
  "idempotency_key": "ticket-4821-cierre"
}

Respuesta

{
  "transaction_id": "...",
  "replayed": false,
  "status": "active",
  "balance": 300,
  "available": 300
}

POST/api/public/pos/v1/giftcards/{referencia}/void

Reversa una redención (cancelación de ticket o devolución). El saldo regresa a la gift card.

Cuerpo

{
  "transaction_id": "...",
  "idempotency_key": "ticket-4821-cancelacion"
}

Respuesta

{ "ok": true, "balance": 650 }

POST/api/public/pos/v1/authorizations/{id}/cancel

Libera una autorización que no se va a cobrar.

Respuesta

{ "ok": true }

Errores

HTTP	code	Qué significa
401	`unauthorized`	Llave de API ausente, inválida o revocada.
403	`forbidden`	La gift card no pertenece a tu restaurante.
404	`not_found`	No existe una gift card con esa referencia.
400	`invalid_payload`	El cuerpo no cumple el esquema del endpoint.
409	`insufficient_funds / card_not_usable`	Saldo insuficiente, tarjeta vencida o cancelada.

Flujo recomendado

El cajero escanea el QR y el POS llama al GET para mostrar el saldo disponible.
Al cerrar el ticket, el POS llama a authorize con el monto a aplicar.
Al cobrar, llama a redeem con el authorization_id y una idempotency_key derivada del ticket.
Si el ticket se cancela, llama a void (o a cancel si nunca se cobró).