Valida pagos desde tu propio sistema

1. Empieza en 5 minutos

1. Crea tu cuenta con el nombre y el RIF de tu comercio.
2. En API keys crea una key de pruebas y cópiala. Solo se muestra una vez.
3. Haz tu primera llamada. Esta referencia existe en la cuenta de pruebas del banco, así que verás un pago real encontrado:

curl https://checapagos.com/v1/payment_validations \
  -H "Authorization: Bearer cp_test_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"reference_lookup","reference":"59487"}'

Si la respuesta trae "status": "found", ya estás integrado. El resto de la guía explica qué más puedes pedir y cómo interpretar lo que vuelve.

2. API keys y entornos

Cada petición lleva tu key en la cabecera Authorization:

Authorization: Bearer cp_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

El prefijo de la key decide contra qué banco se consulta:

Guarda la key en el servidor, nunca en una app móvil ni en JavaScript del navegador. Si se filtra, revócala en el panel y crea otra: la antigua deja de funcionar al instante.

3. Validación rápida: solo la referencia

Tu cliente te manda «pagué, referencia 59487». Con eso basta. Buscamos en el historial de tu cuenta todos los movimientos cuya referencia termina en esos dígitos y te los devolvemos, pagos recibidos primero.

POST /v1/payment_validations
{
  "method": "reference_lookup",
  "reference": "59487",
  "days_back": 7,
  "payment_date": "2026-10-02",
  "metadata": { "order_id": "1042" }
}

• reference: la referencia completa o sus últimos 6 dígitos. Se comparan como número, así que 59487, 059487 y 0000059487 son lo mismo.
• days_back: cuántos días hacia atrás buscar, de 1 a 31. Por defecto 7.
• payment_date: fin de la ventana. Por defecto hoy.
• metadata: lo que quieras guardar junto a la validación (tu número de pedido, el cliente). Te lo devolvemos tal cual.

Seis dígitos no son únicos: la misma referencia puede aparecer en un pago y en su comisión, o en dos pagos de semanas distintas. Por eso la respuesta trae una lista (matches) y el mejor candidato en movement. Si solo coinciden movimientos salientes, el estado es not_found.

4. Validación estricta: el banco confirma monto y fecha

Cuando vas a liberar un pedido quieres que el banco confirme ese pago exacto. Le mandas referencia, monto y fecha (y, si fue Pago Móvil, el teléfono y el banco del pagador) y responde sí o no.

POST /v1/payment_validations
{
  "method": "pago_movil",
  "reference": "59487",
  "amount": "12.00",
  "payment_date": "2026-10-01",
  "payer_phone": "584142786580",
  "payer_bank_code": "0191",
  "metadata": { "order_id": "1042" }
}

• amount en bolívares con dos decimales y punto: "150.00". Tiene que coincidir exactamente.
• payer_phone en formato internacional sin signos: 584121234567.
• payer_bank_code: código de 4 dígitos del banco del pagador. La lista está en GET /v1/banks.

5. Leer la respuesta

Las dos validaciones devuelven el mismo objeto. La llamada es síncrona: cuando responde, ya tiene el resultado final.

{
  "id": "pv_qnjqTgTa2fqz8IBUtNOv",
  "object": "payment_validation",
  "status": "found",
  "mode": "test",
  "method": "reference_lookup",
  "reference": "59487",
  "matched_via": "bnc_api",
  "movement": {
    "date": "2026-10-01", "amount": 12.0, "incoming": true,
    "type": "Abono Pago Movil BNC", "control_number": "102652871",
    "reference": "59487", "bank_code": "0191",
    "payer_phone": "584142786580", "payer_id": "V16113363"
  },
  "matches": [ "…un elemento por cada movimiento que coincide…" ],
  "bank": { "status": "OK", "code": "000000", "message": "Consulta exitosa" },
  "metadata": { "order_id": "1042" },
  "validated_at": "2026-10-02T01:36:02-04:00",
  "created_at": "2026-10-02T01:36:00-04:00"
}

movement.incoming te dice si el dinero entró (true) o salió. payer_id es la cédula o RIF del pagador cuando el banco la informa (pagos entre cuentas BNC). Para auditoría, GET /v1/payment_validations/pv_… devuelve la validación cuando quieras.

6. Integrarlo en tu checkout

El flujo que recomendamos para una tienda:

1. Muestra al cliente tus datos de Pago Móvil y el monto exacto del pedido.
2. Pídele la referencia (y su teléfono, si vas a hacer validación estricta).
3. Llama a POST /v1/payment_validations con Idempotency-Key igual a tu número de pedido. Si tu servidor reintenta, recibes la misma validación sin volver a consultar al banco.
4. Si es found y movement.amount es igual o mayor al pedido, márcalo pagado.
5. Si es not_found, dile al cliente que revise los datos y permite reintentar. Los pagos interbancarios pueden tardar unos minutos en aparecer.

Ejemplo en Node.js:

const res = await fetch("https://checapagos.com/v1/payment_validations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CHECAPAGOS_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}`
  },
  body: JSON.stringify({
    method: "pago_movil",
    reference: order.reference,
    amount: order.total.toFixed(2),
    payment_date: order.paidOn,
    payer_phone: order.payerPhone,
    payer_bank_code: order.payerBank,
    metadata: { order_id: order.id }
  })
});
const validation = await res.json();
if (validation.status === "found") markAsPaid(order, validation.movement.control_number);

Y en PHP:

$ch = curl_init("https://checapagos.com/v1/payment_validations");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CHECAPAGOS_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: order-" . $orderId
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "method" => "reference_lookup",
    "reference" => $reference,
    "metadata" => ["order_id" => $orderId]
  ])
]);
$validation = json_decode(curl_exec($ch), true);
if ($validation["status"] === "found") { /* pedido pagado */ }

7. Errores y límites

Los errores siempre tienen la misma forma:

{ "error": { "type": "invalid_request_error", "code": "invalid_parameter", "param": "payer_phone", "message": "payer_phone: debe tener el formato 584121234567" } }

Una validación estricta tarda entre 1 y 3 segundos; una rápida, alrededor de 2. Pon un tiempo de espera de al menos 20 segundos en tu cliente HTTP.

8. Avisos del banco

En producción, BNC nos avisa en tiempo real de cada pago que entra a tu cuenta. Los guardamos y los usamos para responder validaciones sin esperar al banco. Puedes listarlos:

GET /v1/bank_notifications?tx_date=2026-10-02

Pronto podrás recibirlos también en tu propio servidor (webhooks salientes). Si te interesa, dínoslo.

9. Referencia de endpoints

La base es https://checapagos.com/v1. Todo es JSON. Las fechas van en AAAA-MM-DD y las horas en ISO 8601 con zona de Caracas. La versión va en la ruta: cambios que rompan compatibilidad saldrán como /v2; añadir campos no cuenta.

¿Algo no cuadra? Escríbenos desde el panel o a hola@checapagos.com.