En esta página

Cobro directo por API

Cobra sin checkout: tu sistema pide los datos del pagador y muestra el link, la llave o el QR de pago en tu propia pantalla.

Cómo funciona
Crea la orden con POST /api/v1/collect → lista los métodos con /methods → crea el cargo con /pay → muestra lo que indica flow → confirma el pago con el webhook.

Antes de empezar

Con la API directa, tu sistema recibe el link, la llave o el QR de pago y lo muestra en tu propia pantalla. El pagador no ve el checkout. La API directa está activa para todos los comercios. Usa las mismas credenciales (x-api-key y x-api-secret) y la orden creada con POST /api/v1/collect.

Para crear la orden, consulta Endpoints en la referencia de API.

Paso 1: lista los métodos

Lista los métodos de la orden con GET /api/v1/collect/:id/methods. Cada método trae requiredFields: los datos del pagador que debes enviar. Los campos de selección traen sus options. Si creaste la orden con customerName, customerEmail, customerDocType o customerDocNumber, esos campos no se vuelven a pedir.

{
  "success": true,
  "data": [
    { "method": "breb", "label": "Bre-B", "currency": "COP", "minAmount": 5000,
      "requiredFields": [ { "key": "fullName", "type": "text", "label": "Nombre completo", "required": true } ] },
    { "method": "pse", "label": "PSE", "currency": "COP", "minAmount": 5000,
      "requiredFields": [
        { "key": "bank", "type": "bankSelect", "label": "Banco", "required": true,
          "options": [ { "value": "1007", "label": "Bancolombia" } ] },
        { "key": "fullName", "type": "text", "label": "Nombre completo", "required": true },
        { "key": "email", "type": "text", "label": "Correo electrónico", "required": true },
        { "key": "phone", "type": "phone", "label": "Teléfono", "required": true },
        { "key": "docType", "type": "docType", "label": "Tipo de documento", "required": true },
        { "key": "docNumber", "type": "docNumber", "label": "Número de documento", "required": true }
      ] }
  ]
}

Paso 2: crea el cargo

Crea el cargo con POST /api/v1/collect/:id/pay. fields lleva los requiredFields con la misma key. returnUrl (opcional, HTTPS) es la página adonde vuelve el pagador después de pagar en su banco.

POST /api/v1/collect/:id/pay

{
  "method": "pse",
  "fields": { "bank": "1007", "fullName": "Ana Pérez", "email": "ana@correo.com",
              "phone": "3001234567", "docType": "CC", "docNumber": "1234567890" },
  "returnUrl": "https://mitienda.com/pagos/retorno"
}

Bre-B con QR

Para recibir el QR de Bre-B, envía fields.brebMode "qr". Sin ese campo, la respuesta trae la llave Bre-B. El QR y la llave vencen en 10 minutos (expiresAt).

POST /api/v1/collect/:id/pay

{ "method": "breb", "fields": { "fullName": "Ana Pérez", "brebMode": "qr" } }

{ "success": true, "data": { "paymentUrl": null, "transactionId": "mm_...",
  "method": "breb", "flow": "qr", "keyValue": "00020101021126...6304ABCD",
  "qrImage": "data:image/png;base64,iVBORw0KG...",
  "expiresAt": "2026-11-03T15:21:21.209Z" } }

qrImage es el QR listo para mostrar: un PNG de 400 px en data URI. Solo llega con flow "qr". keyValue es la fuente de verdad. qrImage es una ayuda generada desde keyValue.

Los clientes de correo bloquean las imágenes data:. Para correo o WhatsApp, envía collectUrl (el checkout hospedado), no el QR.

Qué mostrar según flow

flow Métodos Qué muestras al pagador
redirectPSE, BancolombiaRedirige a paymentUrl.
pushNequiUn aviso para que apruebe el pago en su app. paymentUrl es null.
qrBre-B con brebMode "qr"Muestra qrImage en un <img src>, o dibuja keyValue (cadena EMVCo) con tu librería de QR.
keyBre-B sin brebModeLa llave de keyValue para copiar.

Reglas del cobro directo

  • El pago se confirma solo por el webhook firmado. La respuesta de /pay y el retorno a returnUrl no significan pagado.
  • Si repites /pay con el mismo método antes de expiresAt, la API devuelve el mismo cargo (mismo transactionId). Con otro método, o después de expiresAt, se crea un cargo nuevo. No la llames en bucle.
  • Usa flow para decidir qué mostrar. No uses uiType de /methods.
  • Si /pay responde 400 PAYER_DATA_REQUIRED, pide al pagador los campos de error.missingFields y vuelve a llamar /pay. Ante otro 400, ofrece otro método o usa collectUrl.

Si faltan datos del pagador (400 PAYER_DATA_REQUIRED)

Si a fields le falta un dato obligatorio, /pay responde 400 con el código PAYER_DATA_REQUIRED. error.missingFields lista los campos que faltan: fullName, email, phone, docType, docNumber y, en PSE, bank. No se crea ningún cargo. Pide esos datos al pagador y vuelve a llamar /pay con los campos completos.

En Bre-B, fullName es obligatorio. Si no lo envías (en fields.fullName o en customerName al crear el cobro), /pay responde 400 PAYER_DATA_REQUIRED con missingFields: ["fullName"] y no crea el cargo.

POST /api/v1/collect/:id/pay

{ "method": "pse", "fields": { "fullName": "Ana Pérez", "email": "ana@correo.com",
  "phone": "3001234567", "docType": "CC", "docNumber": "1234567890" } }

{
  "success": false,
  "statusCode": 400,
  "message": "Faltan datos del pagador: bank.",
  "error": {
    "code": "PAYER_DATA_REQUIRED",
    "message": "Faltan datos del pagador: bank.",
    "missingFields": ["bank"]
  },
  "path": "/api/v1/collect/clxyz123abc456def/pay"
}
POST /api/v1/collect/:id/pay

{ "method": "breb", "fields": { "brebMode": "qr" } }

{
  "success": false,
  "statusCode": 400,
  "message": "Faltan datos del pagador: fullName.",
  "error": {
    "code": "PAYER_DATA_REQUIRED",
    "message": "Faltan datos del pagador: fullName.",
    "missingFields": ["fullName"]
  },
  "path": "/api/v1/collect/clxyz123abc456def/pay"
}

Paso 3: confirma el pago con el webhook

El pago queda confirmado solo cuando llega el webhook firmado a tu webhookUrl. Verifica la firma antes de marcar la orden como pagada. Consulta Webhooks para los eventos y la verificación de la firma.