gift2you
Crear cuenta

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 del comprador. La referencia es el código de la gift card o el token del QR.

Respuesta

{
  "merchant": { "id": "...", "name": "Cantina Rosales" },
  "usable": true,
  "gift_card": {
    "id": "...",
    "code_prefix": "RGL-7F3K",
    "status": "active",
    "currency": "MXN",
    "holder_name": "María López",
    "initial_amount": 1000,
    "balance": 650,
    "available": 650,
    "held_amount": 0,
    "expires_at": "2027-03-01T00:00:00.000Z",
    "issued_at": "2026-03-01T18:42:11.000Z"
  }
}
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": "suc01-ticket-4821-cierre"
}

Respuesta

{
  "transaction_id": "...",
  "replayed": false,
  "gift_card": { "status": "active", "balance": 300, "available": 300, "held_amount": 0 }
}
POST/api/public/pos/v1/giftcards/{referencia}/void

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

Cuerpo

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

Respuesta

{
  "transaction_id": "...",
  "gift_card": { "status": "active", "balance": 650, "available": 650, "held_amount": 0 }
}
POST/api/public/pos/v1/authorizations/{id}/cancel

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

Respuesta

{ "cancelled": true }

Errores

HTTPcodeQué significa
401unauthorizedLlave de API ausente, inválida o revocada.
403forbiddenLa gift card no pertenece a tu restaurante.
404not_foundNo existe una gift card o autorización con esa referencia.
400invalid_payloadEl cuerpo no cumple el esquema del endpoint.
409card_not_usableTarjeta vencida, cancelada o sin saldo.
409insufficient_fundsEl monto excede el disponible (se incluye available).
409authorization_not_foundEl authorization_id no corresponde a esa tarjeta.
409authorization_expiredLa reserva venció o ya fue capturada/cancelada.
409amount_exceeds_authorizationEl monto es mayor al reservado.
404transaction_not_foundVoid sobre una transacción inválida.

Flujo recomendado

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