Guía de la API

Inicio rápido

En unos minutos tu sistema puede confirmar pagos. El panel te guía en cada paso.

1. Crea tu cuenta en el panel de PagoFino Developers.
2. Vincula tu teléfono: en Vincular app, escanea el QR con la app oficial de PagoFino en el teléfono donde llegan las notificaciones del banco.
3. Crea tu API Key en Tu API. Se muestra completa una sola vez: guárdala en una variable de entorno de tu servidor.
4. Haz tu primera consulta con el botón Probar mi API del panel, o con este comando:

Autenticación

Cada solicitud a /v1 debe llevar tu API Key en el header X-API-Key. También se acepta Authorization: Bearer.

X-API-Key: pfd_live_••••••••••••••••••••••••••••••••••••••••••••••••

Tu llave identifica tu cuenta: la API solo te mostrará y dejará modificar tus propios pagos. No existe forma de consultar pagos de otra cuenta.

Comprobar tu llave

{
  "ok": true,
  "cuenta": { "username": "mitienda", "nombre_comercio": "Mi Tienda C.A.", "plan": "developer", "estado": "activo", "creditos": 2996 }
}

Créditos y saldo

PagoFino Developers funciona con saldo prepagado, sin mensualidades:

• 1 crédito = 1 pago registrado por la app en tu cuenta. Si la app reenvía el mismo pago, no se cobra dos veces.
• Verificar, listar, conciliar y los webhooks son ilimitados. Puedes consultar el mismo pago todas las veces que necesites.
• Al crear tu cuenta recibes 100 créditos de bienvenida (válidos 60 días). Los créditos que compras vencen a los 12 meses; siempre se usan primero los que vencen antes.
• Recargas desde el panel (pestaña Créditos) con Pago Móvil, transferencia BDV o Binance Pay.

Si te quedas sin saldo

Tus pagos se siguen registrando: nunca pierdes un pago. Mientras el saldo sea 0, los endpoints de /v1/pagos responden 402 SALDO_AGOTADO y los webhooks esperan en la cola. Al recargar, se descuentan los pagos registrados sin saldo y todo vuelve a funcionar, incluidos los avisos pendientes.

HTTP/1.1 402 Payment Required

{ "ok": false, "error": "SALDO_AGOTADO", "creditos": 0,
  "mensaje": "Tu saldo de créditos está agotado. Tus pagos se siguen registrando; recarga en el panel…" }

Consultar tu saldo

Cada respuesta autenticada incluye el header X-PagoFino-Creditos con tu saldo actual, y GET /v1/cuenta lo devuelve en el campo creditos. Úsalo para avisarte antes de quedarte sin saldo.

Verificar un pago Recomendado

Busca el pago por referencia (completa o sus últimos 4 a 6 dígitos) y, con consumir: true, lo marca como usado en la misma llamada. Es atómico: aunque dos cajas pregunten por el mismo pago en el mismo instante, solo una recibe verificado: true.

Ejemplo de solicitud

POST /v1/pagos/verificar
X-API-Key: pfd_live_…
Content-Type: application/json

{ "referencia": "004512", "monto": 1250.50, "consumir": true }

Respuesta

{
  "ok": true,
  "verificado": true,
  "resultado": "conciliado",
  "mensaje": "Pago verificado y conciliado. Ya no podrá usarse de nuevo.",
  "pago": {
    "id": 1842, "referencia": "004512", "monto": 1250.5, "moneda": "Bs",
    "estado": "confirmed", "verificado_por": "API · Mi Tienda", "fecha": "2026-10-28T15:04:00Z"
  }
}

Solo consultar, sin conciliar

Con GET /v1/pagos/verificar?referencia=4512&monto=1250.50 obtienes el mismo resultado pero el pago no se marca como usado: responde disponible. Úsalo para mostrar estados; para aprobar ventas usa el POST con consumir.

Resultados posibles

Tu sistema solo tiene que revisar verificado. El campo resultado explica el motivo:

Listar pagos

Devuelve tus pagos del más reciente al más antiguo. Ideal para el cierre de caja y la conciliación contable.

GET /v1/pagos?estado=confirmed&desde=2026-10-01&limit=100

Detalle de un pago

Devuelve un pago de tu cuenta. Si el ID no existe o pertenece a otra cuenta, responde 404.

Conciliar un pago

Marca un pago pendiente como usado, por id o por referencia completa. Útil si verificaste con GET y apruebas la venta más tarde.

{ "id": 1842 }

Si ya estaba conciliado responde 409 YA_CONCILIADO; si estaba rechazado, 409 PAGO_RECHAZADO.

Tu cuenta

Devuelve el usuario, plan y estado de la cuenta dueña de la API Key. Si la cuenta está suspendida o la licencia vencida, todas las llamadas responden 403.

Webhooks

En lugar de preguntar, deja que PagoFino le avise a tu servidor. Registra una URL (https y pública) en el panel, sección Webhooks, y elige los eventos:

Tu servidor debe responder con un código 2xx en menos de 8 segundos. Cada aviso queda guardado en una cola, así que no se pierde aunque tu servidor esté caído: PagoFino lo reintenta durante unas 24 horas con espera creciente.

Si los 9 intentos fallan, el aviso queda como Fallido y puedes reenviarlo desde el panel o la API cuando tu servidor esté listo.

POST https://mi-erp.com/webhooks/pagofino
Content-Type: application/json
X-PagoFino-Event: pago.recibido
X-PagoFino-Signature: sha256=5f1c…
X-PagoFino-Timestamp: 1793160000
X-PagoFino-Delivery: evt_8d2e…

{
  "event": "pago.recibido",
  "id": "evt_8d2e…",
  "timestamp": 1793160000,
  "cuenta": "mitienda",
  "prueba": false,
  "data": {
    "id": 1842, "referencia": "004512", "monto": 1250.5, "moneda": "Bs",
    "estado": "pending", "origen": "APP PAGOFINO", "fecha": "2026-10-28T15:04:00Z"
  }
}

Validar la firma

Cada webhook trae X-PagoFino-Signature: sha256=<hex>: un HMAC-SHA256 del cuerpo crudo calculado con el secreto de tu webhook (lo ves en el panel). Compruébalo siempre antes de confiar en el contenido.

Administrar webhooks por API

Todo lo que haces en el panel también está disponible por API:

{ "url": "https://mi-erp.com/webhooks/pagofino", "eventos": ["pago.recibido", "pago.confirmado"] }

Errores y límites

Los errores responden con ok: false, un código en error y una explicación en mensaje.

Límites por API Key

• 120 solicitudes por minuto en total.
• 60 verificaciones por minuto.
• Hasta 5 API Keys activas y 5 webhooks por cuenta.

OpenAPI y Postman

La especificación completa está en formato OpenAPI 3. Ábrela en la referencia interactiva o descárgala para importarla en Postman, Insomnia o un generador de SDK.