Docs · Desde tu sistema Descargar .md

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

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

Referencia completa de la API: Referencia de la API y la colección Postman.