Recargas LATAM

Consultar ofertas de recarga y comprar recargas telefónicas para países de Latinoamérica.

`GET /store/topup-catalog`

Catálogo navegable de recargas telefónicas. Endpoint multimodo: el modo se determina por los query params presentes. Combina ofertas globales de LATAM con paquetes nacionales de Cuba.

Autenticación

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

Modos

Modo	Query	Devuelve
Destacados	`?featured`	Top 12 operadores globales por cantidad de ofertas
Países	`?countries` (o sin params)	Lista de países con recargas disponibles
Operadores	`?country=XX`	Operadores disponibles para un país
Ofertas	`?country=XX&brand=Nombre`	Ofertas de un operador (acepta `&subType=MOBILE\|DATA\|...`)

Modo países

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

{
  "countries": [
    { "code": "CU", "offer_count": 6, "name": "Cuba", "flag": "🇨🇺", "dial": "+53", "pattern": "^\\+535\\d{7}$" },
    { "code": "MX", "offer_count": 18, "name": "México", "flag": "🇲🇽", "dial": "+52", "pattern": "^\\+52\\d{10}$" }
  ]
}

Modo operadores (por país)

curl -X GET "https://api.qvapay.com/store/topup-catalog?country=MX"

{
  "country": { "name": "México", "flag": "🇲🇽", "dial": "+52", "pattern": "^\\+52\\d{10}$" },
  "brands": [
    {
      "brand": "Telcel",
      "slug": "telcel",
      "source": "global",
      "logo_url": "https://...",
      "bg_color": "#E60000",
      "offer_count": 12,
      "price_min": 5.00,
      "price_max": 50.00
    }
  ]
}

Para Cuba, el operador es Cubacel (source: "cuba") y los precios vienen de los paquetes nacionales.

Modo ofertas

curl -X GET "https://api.qvapay.com/store/topup-catalog?country=MX&brand=Telcel"

{
  "country": { "name": "México", "flag": "🇲🇽", "dial": "+52", "pattern": "^\\+52\\d{10}$" },
  "brand": "Telcel",
  "brand_logo_url": "https://...",
  "offers": [
    {
      "source": "global",
      "offer_id": "TOPUP_MX_001",
      "name": "Recarga $100 MXN",
      "notes": "Recarga $100 MXN",
      "sent_benefits": "100 MXN",
      "sub_type": "MOBILE",
      "price_type": "FIXED",
      "price": 5.25
    },
    {
      "source": "global",
      "offer_id": "TOPUP_MX_002",
      "name": "Recarga personalizada",
      "sub_type": "MOBILE",
      "price_type": "RANGE",
      "price_min": 1.00,
      "price_max": 50.00,
      "service_fee_pct": 5.0
    }
  ]
}

Notas

Para ofertas FIXED, price ya incluye comisión. No se exponen base_price ni tax_pct.
Para ofertas RANGE, service_fee_pct permite calcular el total: total = amount + (amount * service_fee_pct / 100).
sent_benefits describe lo que recibe el destinatario (ej: "4 GB datos", "100 MXN").
Cuba se sirve desde paquetes nacionales (source: "cuba"); su flujo de compra es POST /store/phone_package, no POST /store/topup.

`GET /store/topup`

Retorna las ofertas de recarga telefónica disponibles para un país de Latinoamérica. Los resultados se cachean para mejorar el rendimiento.

Autenticación

No requiere autenticación (endpoint público).

Request

curl -X GET "https://api.qvapay.com/store/topup?country=MX&brand=Telcel"

Parámetros (query)

Parámetro	Tipo	Requerido	Descripción
`country`	string	Sí	Código ISO-3166-1 alpha-2 del país (ver países soportados)
`brand`	string	No	Filtrar por marca/operador (ej: `Telcel`, `Claro`)

La lista de países es dinámica: cubre todo el catálogo de Zendit disponible (cientos de países a nivel global, no sólo LATAM) y cambia según la cobertura activa. No la consultes hardcodeada; obtén la lista vigente desde:

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

Cada país se devuelve con su code (ISO-2), name, flag, dial (prefijo) y pattern. Cuba (CU) se sirve aparte vía POST /store/phone_package.

Response

{
  "offers": [
    {
      "offerId": "TOPUP_MX_001",
      "brand": "Telcel",
      "country": "MX",
      "priceType": "FIXED",
      "price": 5.00,
      "notes": "Recarga Telcel $100 MXN",
      "subType": "MOBILE"
    },
    {
      "offerId": "TOPUP_MX_002",
      "brand": "Telcel",
      "country": "MX",
      "priceType": "RANGE",
      "price": {
        "min": 1.00,
        "max": 50.00
      },
      "notes": "Recarga Telcel personalizada",
      "subType": "MOBILE"
    }
  ],
  "country": "MX"
}

Campos de oferta

Campo	Tipo	Descripción
`offerId`	string	Identificador único de la oferta
`brand`	string	Marca/operador telefónico
`country`	string	Código del país
`priceType`	string	Tipo de precio: `FIXED` o `RANGE`
`price`	number \| object	Precio fijo (number) o rango con `min` y `max` (object)
`notes`	string \| null	Notas adicionales de la oferta
`subType`	string \| null	Subtipo de recarga (ej: `MOBILE`)

Rate Limiting

10 requests por minuto por IP.

Errores

Código	Descripción
`400`	País inválido o no soportado
`429`	Demasiadas solicitudes
`500`	Error al obtener las ofertas

`POST /store/topup`

Compra una recarga telefónica para un número de Latinoamérica. El monto más la comisión se descuentan del balance del usuario.

Autenticación

Bearer Token (header Authorization: Bearer <token>).

Request

curl -X POST https://api.qvapay.com/store/topup \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "TOPUP_MX_001",
    "phone_number": "+525512345678",
    "country": "MX",
    "amount": 10.00
  }'

Parámetros (body)

Parámetro	Tipo	Requerido	Descripción
`offer_id`	string	Sí	ID de la oferta (obtenido del campo `offerId` en la lista)
`phone_number`	string	Sí	Número de teléfono con código de país (ej: `+525512345678`)
`country`	string	Sí	Código ISO del país (debe coincidir con la oferta)
`amount`	number	Condicional	Monto deseado. Requerido solo para ofertas con `priceType: "RANGE"`

Formato de teléfono

Envía el número en formato E.164 (prefijo internacional + seguido del código de país y el número nacional, sin espacios ni guiones). Ejemplo: +525512345678.

El número se valida en el servidor con libphonenumber según el country indicado, así que debe ser un número válido y consistente con ese país. El prefijo (dial) de cada país está disponible en el campo correspondiente de GET /store/topup-catalog?countries.

Response

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

Recuperar el detalle de la recarga

La recarga queda en pending hasta que se procesa la entrega. Para consultar su estado y los datos de entrega, usa GET /store/my/{buyedService_id} con el buyedService_id devuelto aquí. Ver Mis Compras.

Comisión

Se aplica una comisión porcentual sobre el monto base de la recarga:

Usuarios regulares: se usa el campo tax del servicio.
Usuarios GOLD: se usa el campo tax_gold (comisión reducida).

Rate Limiting

1 request cada 10 segundos por usuario.

Errores

Código	Descripción
`400`	Datos de solicitud inválidos
`400`	Número de teléfono inválido para el país seleccionado
`400`	El país de la oferta no coincide
`400`	Se requiere `amount` para ofertas de precio variable
`400`	El monto está fuera del rango permitido
`400`	Saldo insuficiente
`401`	No autorizado
`404`	Oferta no disponible
`429`	Demasiadas solicitudes
`500`	Error al procesar la recarga

`GET /store/topup-catalog`

Autenticación

Modos

Modo países

Modo operadores (por país)

Modo ofertas

Notas

`GET /store/topup`

Autenticación

Request

Parámetros (query)

Países soportados

Response

Campos de oferta

Rate Limiting

Errores

`POST /store/topup`

Autenticación

Request

Parámetros (body)

Formato de teléfono

Response

Recuperar el detalle de la recarga

Comisión

Rate Limiting

Errores

On this page