# Cobro por lote — botón de pago para tu bot de WhatsApp

Sirve para cobrarle a una lista de personas (una mensualidad, una cuota, una factura por cliente) desde el
bot que **ya tienes**, sin construir integración bancaria. Tú mandas la lista, QuickPay te devuelve un link
de pago por persona, tu bot envía cada link con un botón, y tú te enteras de cada pago por webhook o
consultando el lote.

Funciona con cualquier plataforma que pueda hacer una petición HTTP y mandar un mensaje con botón de URL
(software propio, n8n, Make, ManyChat, Wati, Landbot, Builderbot, Take Blip).

## 1. Crea el lote

```http
POST https://pay.pagaconquickpay.com/switch/v1/lotes
x-switch-key: <tu API key>
Content-Type: application/json

{
  "nombre": "Mensualidad septiembre",
  "idempotency_key": "mensualidad-2026-09",
  "expira_horas": 72,
  "items": [
    { "monto": 450.00, "concepto": "Mensualidad septiembre", "referencia_externa": "CLI-001",
      "cliente": { "nombre": "Cliente Uno", "telefono": "04141234567" } },
    { "monto": 450.00, "concepto": "Mensualidad septiembre", "referencia_externa": "CLI-002",
      "cliente": { "nombre": "Cliente Dos", "telefono": "04241234567" } }
  ]
}
```

Respuesta `201`: el lote con un item por persona. Lo que necesitas de cada item es `url` (para el botón) y
`link_id` (para reconciliar):

```json
{
  "id": "…", "total": 2, "mode": "test",
  "resumen": { "total": 2, "pagados": 0, "abiertos": 2, "monto_total": 900, "monto_pagado": 0, "completo": false },
  "items": [
    { "n": 1, "link_id": "…", "url": "https://pay.pagaconquickpay.com/l/…", "wa_deeplink": null,
      "referencia_externa": "CLI-001", "monto": 450, "estado": "pendiente" }
  ]
}
```

Reglas:
- **Hasta 500 items** por lote. Si un item no valida, no se crea ninguno.
- **`idempotency_key` del lote**: si repites la petición con la misma llave, recibes el mismo lote. Nunca se
  duplica un cobro por reintentar. Vale dentro del modo: la misma llave con `sk_test…` y con `sk_live…` son dos
  lotes distintos (lo mismo la `idempotency_key` de cada item).
- **Cada llave ve sólo los lotes de su modo**: con `sk_test…` no se listan, consultan ni cancelan los lotes
  creados con `sk_live…` (responde `404`), y al revés.
- **`referencia_externa`** es tu identificador (número de factura, fila del Excel). Vuelve en cada consulta.
- Con una API key de prueba (`sk_test…`) el lote nace en modo `test`: el checkout simula y **no cobra**.
  Con una `sk_live…` cobra de verdad.
- Si tienes la lista en Excel o CSV, conviértela a JSON en tu herramienta (n8n y Make lo hacen con un nodo).

## 2. Manda el botón desde tu bot

Envía a cada persona un mensaje con **botón de URL** (`cta_url` en la API de WhatsApp Cloud, o el bloque
"botón con enlace" de tu plataforma) apuntando a la `url` del item. El botón abre el checkout **dentro de
WhatsApp**; un enlace pegado como texto no siempre lo hace.

El checkout le pide a la persona su banco, teléfono o cuenta, cédula y el código OTP que le manda su banco.
QuickPay cobra por débito inmediato. Cada link se paga **exactamente una vez**.

El mensaje sale desde **tu** número, así que su costo en Meta es tuyo.

Si tu bot manda el cobro **fuera** de las 24 horas desde el último mensaje del cliente, WhatsApp exige una
**plantilla aprobada** (categoría *utility*). Ejemplo de plantilla que puedes registrar en tu WABA y ajustar
a tu tono (el botón es de tipo URL con sufijo dinámico, que rellenas con el `link_id` del item):

```
Hola {{1}}, tienes un pago pendiente de {{2}} por {{3}}.
Puedes pagarlo con débito inmediato desde tu banco, en un minuto.
[Botón URL]  Pagar ahora  →  https://pay.pagaconquickpay.com/l/{{1}}
```

Variables del cuerpo: `{{1}}` nombre del cliente, `{{2}}` concepto, `{{3}}` monto con "Bs". Variable del
botón: el `link_id`. Dentro de las 24 horas puedes mandar un mensaje interactivo `cta_url` sin plantilla.

## 3. Entérate de los pagos

Dos formas, y puedes usar las dos:

- **Webhook** (recomendado): registra tu URL en `/switch/v1/webhooks` y recibirás el evento `link.pagado`
  con el `link_id` en cuanto se confirme el pago.
- **Consulta del lote**: `GET /switch/v1/lotes/{id}` devuelve cada item con su `estado`
  (`pendiente`, `cobrando`, `procesando`, `revision`, `pagado`, `expirado`, `cancelado`) y el resumen
  (`pagados`, `abiertos`, `monto_pagado`, `completo`).

Un `pagado` es un pago confirmado por el banco. `procesando` y `revision` son estados intermedios: no los
trates como pagados ni como fallidos; espera el webhook o vuelve a consultar.

## 4. Cancela lo que no se cobró

`POST /switch/v1/lotes/{id}/cancelar` cancela **sólo** los items que siguen `pendiente`. Un item que está en
`cobrando`, `procesando` o `revision` no se cancela porque puede haber un OTP o un débito en curso; espera a
que termine.

## Prueba sin dinero real

1. En tu portal, **Integraciones › Llaves de API**, crea una llave de prueba.
2. Crea un lote con 2 items y manda los links a tu propio teléfono.
3. Abre uno, completa el checkout: en modo `test` el banco se simula y el item pasa a `pagado`.
4. Consulta el lote y verifica que el webhook llegó.

Referencia completa de la API: [Referencia de la API](/docs) y la [colección Postman](/developers/postman).