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.
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 |
|---|---|---|
redirect | PSE, Bancolombia | Redirige a paymentUrl. |
push | Nequi | Un aviso para que apruebe el pago en su app. paymentUrl es null. |
qr | Bre-B con brebMode "qr" | Muestra qrImage en un <img src>, o dibuja keyValue (cadena EMVCo) con tu librería de QR. |
key | Bre-B sin brebMode | La llave de keyValue para copiar. |
Reglas del cobro directo
- El pago se confirma solo por el webhook firmado. La respuesta de
/payy el retorno areturnUrlno significan pagado. - Si repites
/paycon el mismo método antes deexpiresAt, la API devuelve el mismo cargo (mismotransactionId). Con otro método, o después deexpiresAt, se crea un cargo nuevo. No la llames en bucle. - Usa
flowpara decidir qué mostrar. No usesuiTypede/methods. - Si
/payresponde 400PAYER_DATA_REQUIRED, pide al pagador los campos deerror.missingFieldsy vuelve a llamar/pay. Ante otro 400, ofrece otro método o usacollectUrl.
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.