Cobra en tu web con validación bancaria al instante

Antes de empezar

1. 1

   Tu comercio tiene que estar ACTIVO

   El alta se hace una sola vez en armorpay.net/registro: subes tus documentos, registras la cuenta bancaria de tu empresa y nosotros la verificamos contra el banco. Mientras tu comercio no esté activo, la API responde 401 a todo — no pierdas tiempo depurando tu código si aún estás en revisión.
2. 2

   Crea tu llave de API

   En tu panel: API → Crear llave. Se muestra UNA sola vez — guárdala en la configuración de tu servidor. Empieza con ak_live_.
3. 3

   Registra tu webhook (recomendado)

   En API → Webhooks: pon la URL de tu servidor y guarda el secreto (whsec_...). Es la vía en la que tu tienda se entera de cada pago confirmado sin preguntar. Puedes integrar sin webhook usando GET /intents/{id}, pero el webhook es lo que hace la confirmación instantánea.

Las 3 vías de integración

De menos a más código. Las tres confirman con las mismas reglas — elige por comodidad, no por seguridad.

El flujo completo, de punta a punta

Sea cual sea la vía, por debajo siempre pasan estas cuatro cosas, en este orden:

1. 1

   Tu servidor crea el intent (el cobro que esperas)

   Con el monto que TU sistema calculó — nunca un monto que declare el navegador del cliente. El intent vence a los 30 minutos.
2. 2

   Tu cliente paga

   Por pago móvil a tu cuenta (y te da los últimos dígitos de la referencia del comprobante), o por Botón de Pago C2P (genera una clave en su banco y el débito es al instante).
3. 3

   ArmorPay valida contra el banco

   El pago existe, el monto alcanza y esa referencia no se usó antes — ni en tu web ni en tus cajas físicas. Es el mismo árbitro antifraude para todos tus canales.
4. 4

   Tu tienda se entera y entrega

   Por el webhook firmado (instantáneo) o consultando el intent. Cuando el status es CONFIRMED, entregas el pedido.

En curl, la integración mínima con checkout alojado son DOS pasos:

# 1. Crear el intent (server-to-server, desde tu backend)
curl -X POST https://armorpay.net/api/v1/intents \
  -H "Authorization: Bearer ak_live_TU_LLAVE" \
  -H "Idempotency-Key: pedido-8812" \
  -H "Content-Type: application/json" \
  -d '{ "externalRef": "8812", "amountVES": "1450.00", "concepto": "Pedido 8812" }'

# → 201 { "intent": { "id": "cmm...", "status": "PENDING", ... } }

# 2. Redirigir al cliente a la página de pago
https://armorpay.net/pay/cmm...

# 3. (automático) Al confirmarse te llega el webhook intent.confirmed
#    — o consultas tú mismo:
curl https://armorpay.net/api/v1/intents/cmm... \
  -H "Authorization: Bearer ak_live_TU_LLAVE"
# → 200 { "intent": { "status": "CONFIRMED", "method": "REFERENCIA", ... } }

Autenticación

Todas las llamadas llevan tu llave en el header Authorization. La llave es secreta y solo de servidor: nunca la pongas en el navegador de tus clientes, en el código fuente visible de tu tienda ni en una app instalable. Si se te filtra, revócala y crea otra desde el panel — al instante.

Base:          https://armorpay.net/api/v1
Autorización:  Authorization: Bearer ak_live_...

Límites: 60 peticiones/min por llave · 15 intentos/5 min por IP
en validación de referencia. Al superarlos: 429 con Retry-After.

# La API es server-to-server: no hay CORS abierto. Si intentas llamarla
# con fetch() desde el navegador, fallará — y así debe ser: proteger tu
# llave es proteger tu dinero.

Cobros (intents)

Un intent es un cobro que esperas recibir. Lo creas server-to-server con el monto que TÚ decides — la validación compara contra ese monto, nunca contra lo que declare el cliente final.

POST /api/v1/intents
Authorization: Bearer ak_live_...
Idempotency-Key: pedido-8812        # obligatorio: único por pedido
Content-Type: application/json

{
  "externalRef": "8812",            # el id del pedido en TU sistema
  "amountVES": "1450.00",           # máx. 2 decimales; string o número
  "concepto": "Tienda X pedido 8812"  # opcional, ≤40 tras sanear
}

# ¿Tus precios están en dólares? Manda amountUSD EN VEZ de amountVES:
# congelamos el monto en Bs con la tasa BCV del momento, y la validación
# acepta también USD × tasa vigente (el que paga con la tasa de hoy no falla).
# { "externalRef": "8812", "amountUSD": "25.00" }
# → el intent trae además amountUSD y exchangeRateUsed.

→ 201
{
  "intent": {
    "id": "cmm...",                 # úsalo para validar o redirigir a /pay
    "externalRef": "8812",
    "amountVES": "1450.00",
    "concepto": "Tienda X pedido 8812",
    "method": null,                 # REFERENCIA | C2P al confirmarse
    "status": "PENDING",            # ver ciclo de vida abajo
    "referencia": null,
    "overpaidVES": null,
    "expiresAt": "2026-08-06T21:30:00.000Z",
    "confirmedAt": null,
    "createdAt": "2026-08-06T21:00:00.000Z"
  }
}

# Reintentar con la MISMA Idempotency-Key devuelve el mismo intent (200):
# un timeout de red nunca duplica un cobro. Usa el id de TU pedido como
# key y el reintento sale gratis.

GET /api/v1/intents/{id}
→ 200 { "intent": { ...la misma forma... } }
# Consúltalo al volver el cliente a tu tienda o como respaldo del webhook.
# Es de lectura: consultarlo no cambia nada.

✗ Idempotency-Key: armorpay-${crypto.randomUUID()}   // nueva en cada render
✓ Idempotency-Key: pedido-8812                       // el id de TU pedido

PENDING ──(pago validado)──────────→ CONFIRMED   (final: entrega el pedido)
   │
   └──(30 min sin confirmarse)─────→ EXPIRED     (final: crea uno nuevo)

Validar una referencia

Tu cliente ya pagó por pago móvil a tu cuenta y te da los últimos dígitos de la referencia de su comprobante (pídele 6 o más). Nosotros confirmamos que el pago existe, alcanza y no se usó antes — el mismo árbitro antifraude que usan las cajas físicas.

Manda lo que te dé el cliente, tal cual: el banco nos notifica la referencia en su forma y cada banco pagador la muestra a su manera. Emparejamos por el final, así que da igual si viene con ceros de más, con espacios o con guiones. Lo único que exigimos son 6 dígitos de verdad.

POST/api/v1/intents/{id}/validate-reference

{
  "referencia": "789123"            # 6 a 20 dígitos, del comprobante
}                                   # sirve completa o solo el final: los
                                    # ceros de adelante y los separadores
                                    # se limpian de nuestro lado

→ 200 (confirmado)
{
  "intent": { ... "status": "CONFIRMED", "method": "REFERENCIA" ... },
  "pago": {
    "referencia": "000000789123",
    "banco": "BDT",                 # banco receptor
    "bancoPagador": "0134 · Banesco",
    "montoVES": "1450.00",
    "overpaidVES": null,            # sobrepago aceptado y registrado
    "fecha": "2026-08-06",
    "hora": "153000"
  }
}

Reglas de monto: se acepta un faltante de hasta max(1 Bs, 0.5%).
Subpago → 422 INSUFFICIENT_AMOUNT (con faltanteVES).
Sobrepago → se confirma y queda en overpaidVES.
Referencia ya cobrada (en caja o por otro intent) → 409 REFERENCE_ALREADY_USED.

✗ <input maxlength="9" pattern="\d{6,9}">   // el comprador no puede pegar la suya
✓ <input inputmode="numeric">              // manda lo pegado tal cual

Cobro C2P (Botón de Pago)

Cobro activo: tu cliente genera una clave de pago (OTP) desde la app o banca en línea de su banco, te la da junto a su celular y cédula, y el débito ocurre al instante — sin comprobantes ni referencias que copiar. Requiere que tu comercio tenga C2P habilitado (se tramita con nosotros; en tu panel se ve si ya lo tienes).

POST/api/v1/intents/{id}/c2p

{
  "celular": "04121234567",         # 04 + 9 dígitos (0412, 0422, …)
  "bancoPagador": "0102",           # del catálogo C2P (ver Bancos)
  "cedula": "V12345678",
  "otp": "12345678"                 # clave dinámica que generó tu cliente
}

→ 200 confirmado: { "intent": {...CONFIRMED...}, "cobro": { "referencia", "montoComision", ... } }
→ 422 C2P_REJECTED: rechazo del banco, con "hint" en español y
  "retriable": true — puedes reintentar con una clave nueva
  mientras el intent no venza.
→ 502 BANK_UNAVAILABLE: el banco no respondió. NO asumas rechazo:
  verifica con tu cliente antes de reintentar.

El monto y el concepto salen del intent — el body nunca los lleva.
Pobla el select de bancos con GET /banks?service=c2p (los códigos del
catálogo C2P no siempre coinciden con los del BCV).

→ 422
{
  "code": "C2P_REJECTED",
  "message": "Clave de pago incorrecta",     # titular, ya en español
  "hint": "La clave dinámica está mal escrita, venció o ya se usó.
           Genera una nueva desde tu banco e intenta otra vez.",
  "codres": "C2P0104",                       # el código crudo del banco
  "retriable": true                          # el intent sigue vivo
}

Tasa BCV

Fija tus precios con la misma tasa con la que nosotros congelamos y validamos: cero discrepancias entre tu carrito y el cobro.

GET/api/v1/exchange-rate

→ 200
{ "currency": "USD/VES", "rate": "168.4200", "source": "BCV",
  "fetchedAt": "2026-08-06T14:00:00.000Z" }

# Sin tasa utilizable: 503 RATE_UNAVAILABLE — nunca inventamos una.

Bancos

GET/api/v1/banks

GET /api/v1/banks              # lista BCV — para mostrar el banco pagador
GET /api/v1/banks?service=c2p  # catálogo PROPIO del C2P — para poblar el
                               # select de un cobro C2P (sus códigos no
                               # siempre coinciden con los del BCV)

→ 200 { "service": "...", "banks": [{ "code": "0102", "name": "..." }] }

Checkout alojado (la vía rápida)

Si no quieres construir el formulario: crea el intent y redirige (o abre en iframe) nuestra página de pago. Muestra tu razón social y tu logo, guía al cliente por referencia o C2P según lo que tu comercio tenga habilitado, reintenta sola mientras llega la notificación del banco, y confirma con las mismas reglas de la API.

Redirección:   https://armorpay.net/pay/{intentId}

# No lleva parámetros de retorno: la página no redirige de vuelta sola.
# Pon tú un enlace/botón «volver a la tienda» en tu página de gracias, o
# usa el iframe para quedarte en tu dominio:

En iframe, te avisamos por postMessage:
window.addEventListener("message", (e) => {
  const a = e.data?.armorpay;
  if (a?.event === "confirmed") { /* pagado: a.intentId, a.externalRef */ }
  if (a?.event === "expired")   { /* venció sin pagar */ }
});

# El postMessage es UX (cerrar el modal, mostrar el check): la señal de
# VERDAD para entregar el pedido es el webhook o GET /intents/{id}.
# Un navegador puede fabricar un postMessage; tu servidor no debe creerle.

Plugin WooCommerce

Todo lo de arriba, sin escribir código: el plugin crea el intent al hacer el pedido, manda al cliente a la página de pago, recibe el webhook firmado y marca el pedido como pagado — con un respaldo por consulta cuando el cliente vuelve a la tienda.

1. 1

   Instala el plugin

   Descarga el .zip y súbelo en Plugins → Añadir nuevo → Subir plugin. Se actualiza solo cuando publicamos versiones nuevas.
2. 2

   Pega tus 2 valores

   En WooCommerce → Ajustes → Pagos → ArmorPay: tu Llave de API (ak_live_...) y el Secreto del webhook (whsec_...). El título y la descripción que ve tu cliente en el checkout también se editan ahí.
3. 3

   Registra el webhook apuntando a tu tienda

   En tu panel de ArmorPay (API → Webhooks), la URL es tu tienda más /?wc-api=armorpay — por ejemplo https://mitienda.com/?wc-api=armorpay. El secreto que te dé el panel es el que pegas en el paso 2.
4. 4

   Prueba con un pedido real de 1 Bs

   Crea un producto de prueba, cómpralo tú mismo pagando 1 Bs a tu cuenta, y verifica que el pedido pase a «Procesando». Luego borra el producto.

Webhooks firmados

Registra tu URL en tu panel (API → Webhooks) y te avisamos a tu servidor cada confirmación o vencimiento — con firma, para que verifiques que fuimos nosotros.

POST a tu URL
x-armorpay-timestamp: 1754516096        # epoch en segundos
x-armorpay-signature: hex(HMAC-SHA256(secreto, timestamp + "." + body))

{ "event": "intent.confirmed",          # o "intent.expired"
  "intent": { ...la misma forma de la API... } }

— Verificación en Node.js —
const crypto = require("node:crypto");
function verificar(secreto, timestamp, firma, bodyCrudo) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const esperada = crypto.createHmac("sha256", secreto)
    .update(timestamp + "." + bodyCrudo).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(firma));
}

— Verificación en PHP —
function verificar($secreto, $timestamp, $firma, $bodyCrudo) {
  if (abs(time() - (int)$timestamp) > 300) return false;
  $esperada = hash_hmac("sha256", $timestamp . "." . $bodyCrudo, $secreto);
  return hash_equals($esperada, $firma);
}

# Usa el body CRUDO (antes de parsear el JSON): re-serializarlo
# cambia bytes y la firma deja de coincidir.

Errores

Toda respuesta de error trae un code estable (programa contra él) y un message en español (muéstralo si te sirve).

Checklist antes de salir a producción

• ✓El monto lo calcula tu servidor — y va en el intent. Nada del navegador del cliente decide cuánto se cobra.
• ✓La llave vive solo en tu servidor — no en JavaScript del navegador, no en el repositorio público, no en una app.
• ✓Verificas la firma de cada webhook — con el body crudo, y descartas timestamps de más de 5 minutos.
• ✓Entregas pedidos solo con CONFIRMED — del webhook o de GET /intents/{id} — nunca por el postMessage ni porque el cliente 'volvió' a tu tienda.
• ✓Manejas PAYMENT_NOT_FOUND con reintentos — la notificación del banco tarda segundos; no lo trates como fallo definitivo.
• ✓Tu campo de referencia acepta 6 a 20 dígitos — sin maxlength de 9 y sin recortar lo que el comprador pega: cada banco se la muestra distinto.
• ✓La Idempotency-Key sale del pedido — no de un id nuevo por render — si no, un F5 abre un cobro nuevo.
• ✓Le muestras al comprador el motivo del rechazo — message y hint del 422, sobre todo en C2P: casi siempre es solo la clave dinámica.
• ✓Procesas cada evento una sola vez — mismo intent.id + event repetido = responder 200 sin repetir la entrega.
• ✓Hiciste una compra real de 1 Bs — de punta a punta, webhook incluido, antes de anunciar el botón de pago.

Tus ventas en línea, sus estados y cada webhook entregado o fallido los ves en tu panel (Ventas y API → Webhooks) — la misma fuente que usa esta API.