Saltar al contenido
    Pabilo Docs

    Para validar webhooks salientes de enlaces de pago, consulta la firma HMAC-SHA256. La captura de notificaciones desde dispositivos utiliza autenticación de API; es un flujo distinto.

    Pasarela de Pago & Checkout
    Verificación Automática

    API de Links de Pago (Checkout)

    Genera URLs de cobro dinámicas desde tu backend para cobrar a tus clientes por Pago Móvil o transferencia, con validación bancaria en tiempo real, webhooks y redirección automática.

    ¿Qué hace este endpoint?

    Pasarela de Pago Completa para Venezuela sin Desarrollar Interfaces

    Tradicionalmente, cobrar por Pago Móvil o transferencia en Venezuela requiere compartir datos bancarios por WhatsApp, esperar capturas de pantalla falsificables y revisar manualmente la cuenta bancaria.

    1. Creas la Orden

    Tu servidor llama a POST /v1/paymentlink indicando el monto o productos, moneda y webhooks.

    2. El Cliente Paga

    El cliente abre la URL de Pabilo, ve tus datos bancarios oficiales y coloca su referencia bancaria.

    3. Validación & Webhook

    Pabilo confirma los fondos con el banco, notifica a tu servidor vía Webhook y redirige al comprador.

    Soporta cobros en Bolívares (VEF), Dólares (USD), Euros (EUR) y USDT.✓ Conversión automática a tasa oficial en tiempo real

    1. Crear un Link de Pago (POST /v1/paymentlink)

    Genera una URL única de cobro asociada a un carrito, factura u orden de compra.

    POST
    https://api.pabilo.app/v1/paymentlink

    Ejemplo de Petición cURL

    POST /v1/paymentlink
    curl -X POST https://api.pabilo.app/v1/paymentlink \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -d '{
    "currency": "USD",
    "description": "Orden #1234 - Suscripción Premium",
    "notification_by_whastapp": false,
    "webhook_url": "https://tu-tienda.com/api/webhooks/pabilo",
    "user_bank_id": "685725c59e6febc736848bf5",
    "client_id": "685725869e6febc736848bc9",
    "items": [
      { "product_id": "68b1a2c3d4e5f6a7b8c9d0e1", "quantity": 1 },
      { "name": "Costo de Envío", "unit_price": 10, "quantity": 1 }
    ],
    "redirect_url": "https://tu-tienda.com/checkout/gracias?order_id=1234",
    "expiration_time": 1440,
    "rate_expiration_time": 120
  }'

    Parámetros del Body (JSON)

    CampoTipoRequeridoDescripción
    user_bank_idstringSíID de la cuenta bancaria donde deseas recibir los fondos (ver Cuentas Bancarias).
    amountnumberCondicionalMonto total a cobrar. Con items, omite amount o envía exactamente la suma de las líneas; si difieren, la API responde 400.
    itemsarrayOpcionalDesglose de productos o conceptos de cobro. Permite referenciar productos registrados (con product_id) o líneas ad-hoc (con name, unit_price, quantity).
    currencystringOpcionalMoneda del cobro: "VEF" (por defecto), "USD", "EUR" o "USDT". Si es distinta de VEF, Pabilo muestra la conversión exacta en Bolívares al comprador.
    descriptionstringOpcionalTítulo o descripción visible en la pantalla de cobro para el cliente.
    webhook_urlstringOpcionalURL de tu servidor donde Pabilo enviará una petición HTTP POST al confirmarse el pago.
    redirect_urlstringOpcionalURL a la que el navegador del cliente será redirigido automáticamente tras completar exitosamente el pago.
    expiration_timenumberOpcionalMinutos de vigencia del enlace desde su creación. Por defecto 1440 (24 horas). Envía -1 para enlaces permanentes sin expiración.
    rate_expiration_timenumberOpcionalAplica para cobros en USD/EUR/USDT. Número de minutos durante los cuales la tasa de cambio en Bs queda congelada (por defecto 60 min).
    client_idstringOpcionalID del subcliente/comercio en entornos multi-tenant (ver Clientes API).

    Respuesta Exitosa (200 OK)

    Respuesta JSON
    {
  "id": "68b1a2c3d4e5f6a7b8c9d0e1",
  "url": "https://pabilo.app/pay/68b1a2c3d4e5f6a7b8c9d0e1",
  "amount": 50,
  "currency": "USD",
  "status": "pending",
  "rate_exchange": 62.45,
  "rate_expiration_time": 120,
  "client_id": "685725869e6febc736848bc9",
  "items": [
    {
      "product_id": "68b1a2c3d4e5f6a7b8c9d0e1",
      "name": "Suscripción Premium",
      "quantity": 1,
      "unit_price": 40,
      "currency": "USD"
    },
    {
      "name": "Costo de Envío",
      "quantity": 1,
      "unit_price": 10,
      "currency": "USD"
    }
  ]
}

    La respuesta se envuelve en { message, paymentlink }. Entrega la propiedad paymentlink.url a tu cliente (por WhatsApp, correo, botón de pago o redirección de tu carrito de compras).

    2. Consultar Estado del Link (GET /paymentlink/:id/info)

    Consulta en cualquier momento el estado actual de un link de pago por su ID.

    GET
    https://api.pabilo.app/paymentlink/{id}/info
    GET /paymentlink/{id}/info
    curl -X GET https://api.pabilo.app/paymentlink/68b1a2c3d4e5f6a7b8c9d0e1/info \
  -H "Authorization: Bearer TU_API_KEY"

    3. Webhooks de Notificación Automática

    Tan pronto como el comprador ingresa su referencia y el banco confirma los fondos, Pabilo envía una petición POST a tu webhook_url con el resultado.

    Webhook: Pago Confirmado (status: "paid")

    Payload POST recibido en tu servidor
    {
  "payment_link_id": "68b1a2c3d4e5f6a7b8c9d0e1",
  "status": "paid",
  "credit_balance": 150.5,
  "payment_link": {
    "id": "68b1a2c3d4e5f6a7b8c9d0e1",
    "created_at": "2026-08-03T14:50:00Z",
    "updated_at": "2026-08-03T14:52:30Z",
    "amount": 100,
    "currency": "VEF",
    "description": "Orden #1234",
    "user_bank_id": "685725c59e6febc736848bf5",
    "status": "paid",
    "url": "https://pabilo.app/pay/68b1a2c3d4e5f6a7b8c9d0e1",
    "redirect_url": "https://tu-tienda.com/gracias"
  },
  "user_bank_payment": {
    "id": "ubp_68b1a2c3d4e5f6a7b8c9d0e2",
    "bank_reference_id": "0025513902095",
    "amount": 100,
    "user_bank_id": "685725c59e6febc736848bf5",
    "status": "paid",
    "credit_cost": 1
  }
}

    Webhook: Pago Rechazado o Fallido (status: "failed")

    Payload POST con fallo bancario
    {
  "payment_link_id": "68b1a2c3d4e5f6a7b8c9d0e1",
  "status": "failed",
  "credit_balance": 149.5,
  "payment_link": {
    "id": "68b1a2c3d4e5f6a7b8c9d0e1",
    "status": "failed",
    "status_detail": "payment not found: movement not found with bank reference 123456"
  },
  "user_bank_payment": null
}

    Mejores Prácticas para tu Receptor de Webhook

    • Idempotencia: Guarda el payment_link_id y user_bank_payment.bank_reference_id en tu base de datos para ignorar eventos duplicados si la red reintenta la entrega.
    • Responde 200 OK: Tu servidor debe responder con un código HTTP 200 OK rápidamente antes de iniciar tareas pesadas en segundo plano.
    • Verifica el Monto: Asegúrate de que user_bank_payment.amount coincida con el total de tu orden de compra en tu sistema contable.

    Cobros, clientes y productos

    Usa el mismo client_id para identificar al comprador, tenga o no credenciales B2B2B. Asócialo en Betaserio, enlaces y suscripciones para consultar lo cobrado por cliente y descargar reportes.

    Ver parámetros, ejemplos y API de reportes JSON / CSV