Vouchers / Gift Cards

Catálogo de vouchers y gift cards distribuido por país y marca. Es el flujo único para tarjetas de regalo (Amazon, Apple, Spotify, Steam, etc.) — los productos se descubren navegando por país y marca.

GET /store/voucher-catalogCopy Anchor Link

Endpoint multimodo. El modo se determina por los query params presentes.

AutenticaciónCopy Anchor Link

No requiere autenticación (endpoint público). Rate limit: 30 req/min por IP.

ModosCopy Anchor Link

Modo destacadosCopy Anchor Link

curl -X GET "https://api.qvapay.com/store/voucher-catalog?featured"

{
  "featured": [
    {
      "brand": "Amazon",
      "slug": "amazon",
      "country": "US",
      "logo_url": "https://...",
      "offer_count": 12,
      "country_meta": { "name": "Estados Unidos", "flag": "🇺🇸" }
    }
  ]
}

Modo paísesCopy Anchor Link

curl -X GET "https://api.qvapay.com/store/voucher-catalog?countries"

{
  "countries": [
    { "code": "US", "offer_count": 230, "name": "Estados Unidos", "flag": "🇺🇸" },
    { "code": "ES", "offer_count": 45, "name": "España", "flag": "🇪🇸" }
  ]
}

Modo marcas (por país)Copy Anchor Link

curl -X GET "https://api.qvapay.com/store/voucher-catalog?country=US&q=amazon"

{
  "country": { "name": "Estados Unidos", "flag": "🇺🇸" },
  "brands": [
    {
      "brand": "Amazon",
      "slug": "amazon",
      "country": "US",
      "logo_url": "https://...",
      "bg_color": "#FF9900",
      "offer_count": 5,
      "sample_price": 10.00
    }
  ]
}

Modo ofertasCopy Anchor Link

curl -X GET "https://api.qvapay.com/store/voucher-catalog?country=US&brand=Amazon"

{
  "country": { "name": "Estados Unidos", "flag": "🇺🇸" },
  "brand": "Amazon",
  "brand_logo_url": "https://...",
  "offers": [
    {
      "source": "global",
      "offer_id": "OFFER_ABC123",
      "name": "Amazon Gift Card $10",
      "notes": "Amazon Gift Card $10",
      "sent_benefits": "Código digital",
      "send": { "currency": "USD", "value": 10.00 },
      "sub_type": "DIGITAL",
      "price_type": "FIXED",
      "price": 10.50
    },
    {
      "source": "global",
      "offer_id": "OFFER_XYZ789",
      "name": "Amazon Gift Card (variable)",
      "notes": null,
      "sent_benefits": "Código digital",
      "sub_type": "DIGITAL",
      "price_type": "RANGE",
      "price_min": 5.00,
      "price_max": 500.00,
      "service_fee_pct": 5.0
    }
  ]
}

NotasCopy Anchor Link

• Para ofertas FIXED, el campo price ya incluye impuestos. No se expone base_price ni tax_pct.
• Para ofertas RANGE, se expone service_fee_pct para que el cliente pueda calcular el total: total = amount + (amount * service_fee_pct / 100).
• El offer_id es el identificador requerido por el endpoint de compra.
• sent_benefits describe lo que el destinatario recibe (ej: "60 UC", "12,000 UC + 4,200 Free"). Puede ser null si la oferta no provee descripción específica.
• send contiene el valor monetario que se entrega al destinatario ({ currency, value }). Útil cuando sent_benefits viene vacío y el voucher representa un monto fijo en USD/etc. — el cliente puede mostrar ese valor al usuario para transparencia.

POST /store/voucher/purchaseCopy Anchor Link

Compra un voucher. El monto total (base + impuesto) se descuenta del balance del usuario autenticado.

AutenticaciónCopy Anchor Link

Bearer Token (header Authorization: Bearer <token>). Rate limit: 1 req/10s por usuario.

RequestCopy Anchor Link

curl -X POST https://api.qvapay.com/store/voucher/purchase \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "OFFER_ABC123",
    "country": "US",
    "brand": "Amazon",
    "amount": 25
  }'

Parámetros (body)Copy Anchor Link

ResponseCopy Anchor Link

{
  "message": "Tarjeta solicitada",
  "transaction_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "buyedService_id": "123"
}

Recuperar el código del voucherCopy Anchor Link

La compra queda en pending hasta que se procesa la entrega. Para obtener el código/PIN/URL de canje una vez procesada, consulta GET /store/my/{buyedService_id} usando el buyedService_id devuelto aquí — el código vive en data.service_data.receipt. Ver Mis Compras.

NotasCopy Anchor Link

• La compra valida la oferta contra el catálogo en vivo (el precio puede haber cambiado entre la consulta del catálogo y la compra).
• El impuesto se aplica según el override de la oferta o el tax/tax_gold (si el usuario es golden) del service GIFT_CARD configurado para la marca.
• La compra queda en estado pending hasta que se procesa la entrega.
• Para ofertas RANGE, amount debe ser un entero (sin decimales) dentro del rango [price_min, price_max] retornado por el catálogo.

ErroresCopy Anchor Link

Los límites no se publican: la respuesta solo indica que se alcanzaron. Un 403/503 con estos códigos no cobra nada.