Respuesta base

{
  "ok": true,
  "data": {}
}

{
  "ok": false,
  "error": "CODIGO_ERROR",
  "message": "Mensaje claro para el integrador",
  "trace_id": "abc123"
}

Variables criticas

idtrans

Para ventas en Multiproducto se recomienda un identificador unico de 16 digitos.

1778858151875649

• No reutilizar el mismo id entre ventas.
• Relacionarlo con la orden interna del integrador.
• Guardarlo junto con trace_id.

inputs y extraInputs

Cuando un servicio devuelve configuracion dinamica, el integrador debe construir el formulario y reenviar las llaves exactas.

{
  "productId": 101001,
  "catalogProductId": 101000,
  "extraInputs": {
    "productId": 101001,
    "customerEmail": "cliente@correo.com",
    "amount": 20000
  }
}

QR COP

POST /v2/nq/apicop

{
  "valor": 25000
}

La respuesta normalmente incluye image_b64, reference y provider_reference.

POST /v2/nq/verify_qr

{
  "sid": "7049126"
}

QR Bre-B

POST /v2/breb/generate/qr

{
  "valor": 25000
}

Es de un solo uso. Si vence o se paga, debe generarse uno nuevo.

POST /v2/breb/verify_qr

{
  "sid": "BREB-287372123456"
}

Generar QR Binance

POST /v2/bn/bnapi

{
  "valor": 5.3
}

Verificar Binance

POST /v2/bn/ver_pay

{
  "data": "PREPAY_ID_BINANCE"
}

Generar link

POST /v2/prix/generate/link

{
  "valor": 25000,
  "return_url": "https://tu-app.com/pagos/resultado"
}

Valor minimo recomendado: 20000 COP.

Consultar estado

POST /gen_hys/prix_status

{
  "reference": "1779040898962525"
}

Usar para revisar estado normalizado, pago esperado, pago recibido, costo y valor acreditable.

Cotizar y generar

POST /v2/spr/consulta/exchange

{
  "valor": 35000,
  "money": "COP"
}

POST /v2/spr/generate/link

{
  "valor": 35000,
  "money": "COP",
  "return_url": "https://tu-app.com/pagos/resultado"
}

Verificar directo

POST /v2/spr/verify/pay

{
  "idver": "ID_PAGO_SUPRA"
}

La respuesta minima esperada debe incluir status, reference, provider_reference, paid_amount, cost, credit y currency.

Cotizar y generar

POST /v2/rbill/consulta/exchange

{
  "valor": 35000
}

POST /v2/rbill/generate/link

{
  "valor": 35000,
  "return_url": "https://tu-app.com/pagos/resultado"
}

Verificar directo

POST /v2/rbill/verify/pay

{
  "idver": "ID_PAGO_EFIPAY"
}

La respuesta minima esperada debe incluir status, reference, provider_reference, paid_amount, cost, credit y currency.

Recarga Colombia

POST /gen_hys/recargas

{
  "flow": "recarga",
  "opc": 1,
  "operador": "cl",
  "celular": "3001234567",
  "valor": 10000,
  "idtrans": "1778858151875649",
  "originCash": 0
}

Recarga Mexico

POST /gen_hys/recargas-mx

{
  "flow": "recarga",
  "carrier": 1234,
  "telefono": "5512345678",
  "type": 1,
  "walletType": "SL",
  "idtrans": "1778858151875649"
}

Listar paquetes Colombia

POST /gen_hys/recargas

{
  "flow": "paquetes_list",
  "operador": "pc"
}

Compra habitual

• flow
• operador
• paquete
• celular
• valor
• idtrans
• originCash

Proveedor 1

POST /gen_hys/recargas listado

{
  "flow": "pines_list",
  "operador": "nx"
}

POST /gen_hys/recargas compra

{
  "flow": "pines",
  "celular": "3001234567",
  "email": "cliente@correo.com",
  "operador": "nx",
  "paquete": 101001,
  "idtrans": "1778858151875649",
  "originCash": 0
}

Proveedor 2

1. Catalogo: flow = pines_prove2_list
2. Detalle: flow = pines_prove2_producto
3. Renderizar inputs
4. Comprar: flow = pines_prove2_pago

{
  "flow": "pines_prove2_pago",
  "productId": 101001,
  "catalogProductId": 101000,
  "valor": 20000,
  "celular": "3001234567",
  "customerEmail": "cliente@correo.com",
  "extraInputs": {
    "productId": 101001,
    "customerCellphone": "3001234567",
    "customerEmail": "cliente@correo.com",
    "amount": 20000
  },
  "idtrans": "1778858151875649",
  "originCash": 0
}

Apuesta deportiva

POST /gen_hys/recargas

{
  "flow": "apuesta",
  "celular": "1012345678",
  "telefono": "3001234567",
  "operador": "lk",
  "valor": 20000,
  "name": "Cliente Demo",
  "idtrans": "1778858151875649",
  "originCash": 0
}

Recarga especial

POST /gen_hys/esp/req

{
  "celular": "1012345678",
  "operador": "Betplay",
  "idtrans": "1778858151875649",
  "descript": "BetPlay",
  "identidad": "1012345678",
  "valor": 30000
}

Catalogo

GET /gen_hys/pantalla/catalog

{
  "ok": true,
  "data": {
    "rows": [
      {
        "id": 12345,
        "nombre": "Netflix 1 pantalla",
        "precio": 18000,
        "descripcion": "Cuenta mensual"
      }
    ]
  }
}

Summary

GET /gen_hys/pantalla/summary

Util para mostrar cantidades, resumen rapido del catalogo o informacion de apoyo antes de vender.

Guardar siempre

• trace_id
• reference
• provider_reference
• idtrans cuando aplique

Evitar errores comunes

• No regenerar cobros en automatico si la verificacion responde pendiente.
• No asumir formularios fijos cuando el servicio devuelve inputs.
• Si existe preconsulta, pagar solo con los datos ya validados.