API v1.0 & Webhooks

Guía de Integración para Comercios y Desarrolladores

Aprende a integrar 1pay con tus puntos de venta (POS), sistemas de facturación (ERP) y cajas de mostrador para conciliar Pago Móvil en tiempo real con tasa oficial BCV.

1. Modelo de Operación & Denominación Dual

1pay unifica el flujo de cobranza venezolana permitiendo a los comercios fijar precios estables y recibir pagos en Bolívares con tasa oficial:

💵

Precios en $REF & Tasa Oficial BCV

Los productos se denominan en dólares estadounidenses referenciales ($REF). La conversión a Bolívares se realiza en vivo según la tasa oficial del Banco Central de Venezuela (BCV), cumpliendo la normativa tributaria y comercial.

⚡

Verificación Inmediata en Mostrador

Al recibirse un Pago Móvil, el sistema asocia automáticamente la referencia bancaria al ticket de caja, calcula discrepancias o vueltos en Bolívares y anuncia la confirmación con locución por voz clara.

🔊

Soundbox Hablante & Cierre Z

Tu teléfono o tablet anuncia en voz alta cada Pago Móvil verificado en menos de 2 segundos y consolida automáticamente el Cierre Z diario por caja y banco.

2. Webhooks en Tiempo Real (Eventos Push)

Configura tu URL de Webhook en los Ajustes del Comercio en la consola para recibir notificaciones HTTP POST instantáneas cada vez que un pago sea acreditado en tu cuenta bancaria:

Payload JSON (POST /tu-endpoint)
{
  "event": "PAYMENT_RECEIVED",
  "storeId": "tu_tienda_id",
  "bank": "Banco de Venezuela",
  "reference": "007373140250",
  "referenceSuffix4": "0250",
  "referenceSuffix6": "140250",
  "amount": "150.00",
  "currency": "VES",
  "timestamp": "2026-10-07T20:30:00.000Z",
  "status": "CONFIRMED"
}

3. API de Verificación de Pagos (Consulta Pull)

Para sistemas POS locales o checkouts que necesitan comprobar si una referencia bancaria ya ingresó en el estado de cuenta:

const response = await fetch('https://api.1pay.market/api/cashier/payments?store=merch_a1b2c3d4', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ' + process.env.ONEPAY_API_KEY
  }
});

const data = await response.json();
const match = (data.payments || []).find(p => p.reference.endsWith('0250'));
if (match) {
  console.log(`✅ Pago aprobado en ${match.bankName}: Bs. ${match.amountBs}`);
}

4. Entornos: Sandbox vs Producción

5. Esquema de Tarifas & Licencias

Precios predecibles y transparentes en dólares estadounidenses (USD), sin comisiones porcentuales sobre tus ventas:

Multi-Caja & Sucursales

$10 USD / mes

Múltiples sucursales y terminales de cobro ($10 USD / mes por terminal adicional), webhooks dedicados para ERP y soporte prioritario.