Integraciones

API REST para código propio

Tres pasos: creas el cobro, mandas al comprador a la página de pago, y recibes un aviso firmado cuando el pago se confirma.

Base

https://pagosbi.com/api/v1

Autenticación

Cabecera X-API-Key: <tu clave>. La generas en Integraciones; se muestra una sola vez.

Formato

JSON en la petición y en la respuesta.

1. Crear un cobro

POST /checkouts

curl -X POST https://pagosbi.com/api/v1/checkouts \
  -H "X-API-Key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "4821",
    "priceAmount": "24.50",
    "priceCurrency": "USD",
    "webhookUrl": "https://tutienda.com/avisos/cobros",
    "verificationToken": "un-texto-tuyo-que-te-devolvemos",
    "successRedirectUrl": "https://tutienda.com/gracias"
  }'

orderId y priceAmount son obligatorios. El resto es opcional.

Respuesta 201:

{
  "id": "ch_9f3a12c7d4",
  "orderId": "4821",
  "priceCurrency": "USD",
  "priceAmount": "24.50",
  "uniqueAmount": "24.57",
  "status": "OPEN",
  "checkoutUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4",
  "expiresAt": "2026-09-06T04:12:00Z",
  "createdAt": "2026-09-06T02:12:00Z",
  "successRedirectUrl": "https://tutienda.com/gracias"
}

1.b Cobrar en bolívares por Pago Móvil

Además de Binance Pay puedes cobrar por Pago Móvil. El dinero entra en una cuenta nuestra y se te acredita en saldo, que retiras cuando quieras.

Es la misma llamada de arriba con "via": "pagomovil":

curl -X POST https://pagosbi.com/api/v1/cobros \
  -H "X-API-Key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "4821",
    "priceAmount": "24.50",
    "via": "pagomovil",
    "webhookUrl": "https://tutienda.com/avisos/cobros",
    "successRedirectUrl": "https://tutienda.com/gracias"
  }'

Respuesta 201 — trae además lo que necesita tu comprador:

{
  "id": "ch_9f3a12c7d4",
  "via": "pagomovil",
  "priceAmount": "24.50",
  "importeVes": "23590.05",
  "tasa": "962.9",
  "checkoutUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4",
  "pagoMovil": {
    "banco": "0102",
    "bancoNombre": "Banco de Venezuela",
    "telefono": "04121234567",
    "rif": "J-123456789",
    "titular": "NOMBRE DEL COMERCIO, C.A.",
    "qrUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4/qr"
  }
}

El importe en bolívares se congela

importeVes se calcula al crear el cobro con la tasa de ese momento y ya no cambia, aunque la tasa suba antes de que pague. Es el importe exacto que tiene que transferir: el banco confirma una cifra concreta.

Importe mínimo

El banco cobra un mínimo por operación, así que un cobro pequeño sale proporcionalmente carísimo. Por eso hay un mínimo, hoy Bs 1.000. Por debajo, la respuesta es 400:

{
  "error": "El importe mínimo para cobrar por Pago Móvil es de Bs 1000.00. Este cobro son Bs 200.00.",
  "codigo": "importe_minimo",
  "minimoVes": "1000.00",
  "importeVes": "200.00",
  "tasa": "962.9"
}

El mínimo va en bolívares, no en dólares: como la tasa se mueve, comprueba importeVes y no el precio en USD.

Cómo paga tu comprador

Mándalo a checkoutUrl y no tienes que hacer nada más: ahí ve a quién pagar, el QR del banco, y un formulario donde escribe la referencia de su Pago Móvil. Se lo preguntamos al banco al instante y, si cuadra, el cobro pasa a COMPLETED y te llega el mismo aviso que con Binance Pay. No hay nada distinto que programar.

Lo que hay que saber

• El banco sólo deja comprobar pagos de los últimos 3 días.
• Una referencia acreditada no se puede reutilizar en otro pedido.
• Si el banco confirma menos de lo esperado, no se acredita: se avisa para revisarlo a mano.
• El saldo se te abona en USDT, a la tasa congelada del cobro.

1.c Cobrar con tarjeta (Visa y Mastercard)

La tercera vía. Tu comprador paga con su tarjeta en una pasarela segura y el importe se te acredita en saldo, igual que en Pago Móvil, pero en dólares.

La misma llamada, con "via": "tarjeta":

curl -X POST https://pagosbi.com/api/v1/cobros \
  -H "X-API-Key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "4821",
    "priceAmount": "24.50",
    "via": "tarjeta",
    "webhookUrl": "https://tutienda.com/avisos/cobros",
    "successRedirectUrl": "https://tutienda.com/gracias"
  }'

Respuesta 201:

{
  "id": "ch_9f3a12c7d4",
  "via": "tarjeta",
  "priceAmount": "24.50",
  "importeTarjeta": "26.02",
  "recargoPct": "6.20",
  "checkoutUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4",
  "status": "OPEN",
  "expiresAt": "2026-09-06T04:12:00Z"
}

Lo que verá tu comprador en su extracto

Un concepto genérico de la pasarela, no el nombre de tu tienda. Es la condición del proveedor y no se puede cambiar por comercio. Conviene decirlo en tu tienda antes de cobrar: así nadie desconoce el cargo y lo reclama a su banco.

Lo que hay que saber

• Se cobra en dólares, no en bolívares: no hay tasa que congelar ni importe mínimo del banco.
• Tu comprador paga un recargo de 6,2% sobre priceAmount, y lo ve antes de pagar: la respuesta trae importeTarjeta (lo que pagará) y recargoPct. El aviso de pago trae via: "tarjeta", importePagado y recargoPct; su priceAmount sigue siendo el de tu pedido.
• Se te acredita el importe entero. La comisión se descuenta cuando retiras, no cuando cobras.
• El saldo de tarjeta es aparte del de Pago Móvil, porque cada vía se retira a un precio distinto. En Mi saldo ves los dos y eliges de cuál sacas.
• Si el importe que confirma la pasarela no cuadra con el del cobro, no se acredita: preferimos pararlo a dejar un descuadre.
• Un pago rechazado por el banco deja el cobro abierto: tu comprador puede volver a intentarlo con otra tarjeta.

1.d Verificar el pago tú mismo

Si pintas tu propia pantalla en vez de mandar al comprador a la nuestra, necesitas dos cosas más: los bancos para el desplegable, y a dónde mandar la referencia que escriba.

Los bancos

GET /bancos — sin clave, porque son los bancos de Venezuela y no un dato de nadie:

curl https://pagosbi.com/api/v1/bancos

{
  "bancos": [
    {"codigo": "0102", "nombre": "Banco de Venezuela"},
    {"codigo": "0105", "nombre": "Banco Mercantil"},
    ...
  ]
}

Mandar la referencia

POST /pay/{id}/confirmar — sin clave de API: lo llama el navegador del comprador, que no tiene tus credenciales ni debe tenerlas. Se manda como formulario, no como JSON:

curl -X POST https://pagosbi.com/pay/ch_9f3a12c7d4/confirmar \
  -d "cedula=V12345678" \
  -d "telefono=04121234567" \
  -d "banco=0102" \
  -d "referencia=001070787744" \
  -d "fecha=2026-09-14"

La respuesta es siempre igual de simple:

{"ok": true,  "mensaje": "Pago confirmado.", "ya": false}
{"ok": false, "mensaje": "Todavía no vemos ese pago en el banco…", "ya": false}

ok: true significa que el banco confirmó el pago y el cobro ya está COMPLETED: te llegará el mismo aviso firmado que con Binance. ya: true es que ya estaba confirmado de antes — no es un error, y pasa cuando el comprador pulsa dos veces.

Lo que te va a contestar cuando NO cuadre

El mensaje está escrito para enseñárselo tal cual al comprador. Estos son los casos, y conviene tratarlos distinto:

Y si prefieres no pintar nada

Manda al comprador a checkoutUrl y ya está: esa página hace todo lo de arriba —le enseña a quién pagar, el QR, y el formulario de la referencia— y te llega el aviso cuando cuadre. Lo de esta sección es sólo para quien quiera su propia pantalla.

2. Consultar un cobro

GET /checkouts/{id} con tu X-API-Key:

{
  "id": "ch_9f3a12c7d4",
  "orderId": "4821",
  "priceCurrency": "USD",
  "priceAmount": "24.50",
  "uniqueAmount": "24.57",
  "status": "COMPLETED",
  "estado": "pagado",
  "checkoutUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4",
  "expiresAt": "2026-09-06T04:12:00Z",
  "createdAt": "2026-09-06T02:12:00Z",
  "successRedirectUrl": "https://tutienda.com/gracias"
}

status es el estado interno (OPEN, COMPLETED, EXPIRED, CANCELED) y estado es el que ve el comprador (esperando, detectado, pagado, caducado).

Existe también GET /cobros/{id}, con los mismos datos y los nombres en español: pedido, importe, importeAEnviar, urlDePago, transaccion, urlDeAviso.

Buscar entre tus cobros

GET /cobros con tu X-API-Key. Con ?pedido= resuelve de una llamada la pregunta de siempre: ¿me pagaron el pedido 4821?

curl "https://pagosbi.com/api/v1/cobros?pedido=4821" \
  -H "X-API-Key: TU_CLAVE"

3. El aviso a tu tienda

Cuando el pago se confirma, hacemos POST a tu webhookUrl con este cuerpo:

{
  "data": {
    "status": "COMPLETED",
    "orderId": "4821",
    "id": "ch_9f3a12c7d4",
    "priceAmount": "24.50",
    "priceCurrency": "USD",
    "verificationToken": "un-texto-tuyo-que-te-devolvemos",
    "checkoutUrl": "https://pagosbi.com/pay/ch_9f3a12c7d4",
    "createdAt": "2026-09-06T02:12:00Z"
  }
}

Y con dos cabeceras para que compruebes que viene de nosotros:

X-PagosBI-Fecha: 1788660000
X-PagosBI-Firma: sha256=<hmac>

La firma es HMAC-SHA256 sobre fecha + "." + cuerpo —el cuerpo tal cual llega, sin volver a serializarlo— con el secreto de avisos de tu cuenta. En PHP:

$cuerpo = file_get_contents('php://input');
$fecha  = $_SERVER['HTTP_X_PAGOSBI_FECHA'] ?? '';
$firma  = $_SERVER['HTTP_X_PAGOSBI_FIRMA'] ?? '';
$mio    = 'sha256=' . hash_hmac('sha256', $fecha . '.' . $cuerpo, TU_SECRETO);
if (!hash_equals($mio, $firma)) { http_response_code(401); exit; }

Responde 200 para que lo demos por entregado. Si no, reintentamos con esperas crecientes.

POST /cobros/{id}/reenviar-aviso vuelve a mandarlo si tu servidor estaba caído.

4. Estado de tu cuenta

GET /cuenta devuelve tu plan, cuánto llevas consumido este mes y si tu detección está viva. Útil para vigilar desde tu propio panel.

Errores