En esta página
Cobrar al entregar (Bre-B)
Cobra cada pedido en la puerta del cliente, sin efectivo: es el cobro contraentrega de iion pay. No es lo mismo que el pago en custodia (escrow), que retiene el dinero hasta que tú y el comprador confirman la entrega. El mensajero muestra un QR o una llave Bre-B por el total del cobro y tu sistema recibe el resultado por webhook.
POST /api/v1/collect y deliveryMode: true → entrega el deliveryUrl al mensajero → el cliente paga con su app bancaria → confirma con el webhook payment.completed.
En el panel, la opción se llama «Cobrar al entregar (QR Bre-B)».
Antes de empezar
- Usa las mismas credenciales que el resto de la API (
x-api-keyyx-api-secret). - Tu comercio debe tener Bre-B. Si la función no está disponible por ahora, la API responde 403.
- El modo entrega solo admite Bre-B y solo COP.
- Bre-B pide un monto mínimo de 5.000 COP por cobro.
- El cobro al entregar no se combina con custodia (
escrow).
El flujo en pasos
- Crea el cobro. Envía
deliveryMode: truey el nombre del cliente encustomerName. Guarda elidy eldeliveryUrl. - Entrega el enlace al mensajero. El
deliveryUrltiene la formahttps://pay.iionpay.com/c/:id/entrega. Ábrelo en el teléfono del mensajero. - El mensajero elige el modo. Muestra al cliente un QR Bre-B o una llave Bre-B por el total del cobro.
- El cliente paga. Escanea el QR o copia la llave en la app de su banco.
- Recibes el webhook.
payment.completedconfirma el pago.payment.attempt_failedindica que el banco rechazó un intento.
Cada solicitud de pago (QR o llave) vive 10 minutos. Si vence, el mensajero genera una nueva desde el mismo enlace.
La orden vive 10080 minutos (7 días) si no envías expirationMinutes.
Desde el panel, sin integrar la API
- En el panel de iion pay, entra a Crear cobro.
- Enciende el interruptor Cobrar al entregar (QR Bre-B).
- Escribe el Nombre del cliente. Es obligatorio. Al entregar, el mensajero ve solo las iniciales.
- Escribe el precio. El panel muestra el total que paga el cliente antes de crear el cobro.
- Pulsa Crear cobro.
- En la tarjeta Cobrar en la entrega, copia o comparte el enlace con el mensajero. El mensajero también puede escanear el código de la tarjeta para abrir el enlace en su celular.
Si el interruptor no aparece, la función no está disponible para tu cuenta por ahora. Si tu cuenta no tiene Bre-B, el panel no deja crear el cobro al entregar.
Paso 1: crea el cobro
curl -X POST https://api.prod.iionpay.com/api/v1/collect \
-H "X-Api-Key: $IION_API_KEY" \
-H "X-Api-Secret: $IION_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"currency": "COP",
"reference": "PEDIDO-1042",
"description": "Pedido 1042",
"customerName": "Ana Pérez",
"deliveryMode": true,
"feeMode": "CUSTOMER_PAYS"
}'
La respuesta trae el deliveryUrl y el desglose del precio.
Los números de este ejemplo son solo ilustrativos: la comisión depende del plan de tu comercio.
{
"success": true,
"data": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"reference": "PEDIDO-1042",
"amount": 5525,
"baseAmount": 5000,
"feeAmount": 525,
"netAmount": 5000,
"feeMode": "CUSTOMER_PAYS",
"currency": "COP",
"status": "PENDING",
"collectUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479",
"deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega",
"expiresAt": "2026-11-11T15:00:00.000Z"
}
}
El amount de la respuesta es el total que paga el cliente y no cambia al pagar. La sección Cuánto paga el cliente explica el desglose.
| Campo | Obligatorio | Notas |
|---|---|---|
deliveryMode | sí | true activa el modo entrega. |
customerName | sí | Nombre del cliente. Bre-B lo exige. |
amount | sí | Monto base en COP. Mínimo 5.000. Según feeMode, el cliente paga más que este valor. |
feeMode | no | CUSTOMER_PAYS o MERCHANT_PAYS. Sin valor, la API usa el modo por defecto de tu comercio. |
reference | recomendado | Tu identificador del pedido. En un lote es obligatorio. |
expirationMinutes | no | Por defecto 10080 (7 días). |
Cuánto paga el cliente
El campo amount que envías es el monto base: el valor de tu pedido.
El total que paga el cliente puede ser mayor, porque incluye la comisión de iion pay cuando la paga el cliente.
Los números de esta sección son un ejemplo. La comisión depende del plan de tu comercio.
Quién paga la comisión
El campo feeMode define quién asume la comisión de este cobro.
feeMode | El cliente paga | Tú recibes |
|---|---|---|
CUSTOMER_PAYS | baseAmount + feeAmount | baseAmount |
MERCHANT_PAYS | baseAmount | baseAmount − feeAmount |
Si no envías feeMode, la API usa el modo por defecto de tu comercio.
Si tu contrato de tarifa fija un modo, ese modo manda sobre el campo.
Ejemplo con CUSTOMER_PAYS: un cobro de amount 5.000 queda con comisión de 525 y total de 5.525.
El cliente paga 5.525 y tú recibes 5.000.
Qué campos muestran el precio
La respuesta de crear el cobro trae el desglose. GET /api/v1/collect/:id devuelve los mismos campos.
| Campo | Significado |
|---|---|
amount | Total que paga el cliente (base más comisión si la paga el cliente). |
baseAmount | Monto base: el valor de tu pedido. |
feeAmount | Comisión de iion pay. |
netAmount | Lo que recibes por el cobro. |
feeMode | Quién paga la comisión en este cobro. |
El total no cambia
- iion pay fija el total al crear el cobro. El total no cambia cuando el cliente paga.
- El QR y la llave Bre-B cobran ese mismo total.
- Si cambia la tarifa de tu comercio, el cambio aplica solo a los cobros nuevos. Los cobros ya creados conservan su total.
Cotizar antes de crear
La API pública con X-Api-Key no tiene un endpoint de cotización. Para conocer el total, crea el cobro y lee el campo amount de la respuesta.
El panel de iion pay sí muestra la cotización antes de crear el cobro, con el mismo total que fija la creación.
Paso 2: consulta el cobro
Consulta el estado con GET /api/v1/collect/:id. La respuesta incluye deliveryMode (boolean) y deliveryUrl (string, o null si el cobro no es de entrega).
curl https://api.prod.iionpay.com/api/v1/collect/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-H "X-Api-Key: $IION_API_KEY" \
-H "X-Api-Secret: $IION_API_SECRET"
{
"success": true,
"data": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"reference": "PEDIDO-1042",
"status": "PENDING",
"amount": 5525,
"baseAmount": 5000,
"feeAmount": 525,
"feeMode": "CUSTOMER_PAYS",
"deliveryMode": true,
"deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega"
}
}
La vista del mensajero
El deliveryUrl abre una pantalla pensada para el teléfono del mensajero. No pide usuario ni contraseña.
- Muestra un QR Bre-B o una llave Bre-B por el total del cobro, el mismo
amountde la orden. ConCUSTOMER_PAYSincluye la comisión. - Cada solicitud vive 10 minutos.
- Hay una sola solicitud a la vez. Si el mensajero pide el otro modo mientras la solicitud sigue vigente, la API responde 409
CHARGE_STILL_ACTIVEconactiveModeyexpiresAt. Puede cambiar de modo cuando la solicitud venza. - Si el cliente rechaza el pago, la orden vuelve a
PENDINGy el mensajero puede reintentar.
Cobros en lote
Crea hasta 500 cobros en una llamada con POST /api/v1/collect/batch. La API procesa 5 filas a la vez.
Cada fila tiene la misma forma que el cuerpo de POST /api/v1/collect. reference es obligatoria en cada fila.
curl -X POST https://api.prod.iionpay.com/api/v1/collect/batch \
-H "X-Api-Key: $IION_API_KEY" \
-H "X-Api-Secret: $IION_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"orders": [
{ "reference": "PEDIDO-1042", "amount": 5000, "currency": "COP",
"customerName": "Ana Pérez", "deliveryMode": true },
{ "reference": "PEDIDO-1043", "amount": 3000, "currency": "COP",
"customerName": "Luis Gómez", "deliveryMode": true }
]
}'
La respuesta trae un resultado por fila, en el mismo orden del envío:
{
"success": true,
"data": {
"total": 2,
"created": 1,
"duplicates": 0,
"failed": 1,
"results": [
{ "index": 0, "reference": "PEDIDO-1042", "ok": true,
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"amount": 5525, "baseAmount": 5000, "currency": "COP",
"checkoutUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479",
"deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega" },
{ "index": 1, "reference": "PEDIDO-1043", "ok": false,
"error": { "code": "AMOUNT_BELOW_MIN", "message": "El monto mínimo de un cobro es $5.000 COP" } }
]
},
"error": null
}
Cada fila ok: true trae amount, baseAmount y currency de la orden guardada.
El baseAmount es el monto base de la orden y el amount es el total que paga el cliente. baseAmount es null si la orden no tiene monto base. En el ejemplo, la fila 0 envía un monto base de 5.000 y recibe un total de 5.525 (valores ilustrativos).
Son los mismos valores que devuelve GET /api/v1/collect/:id.
Una fila que rompe una regla de negocio (monto mínimo, referencia repetida, etc.) falla sola. La API crea las filas válidas y reporta cada error en results.
El HTTP de la respuesta es 200.
Una fila mal formada (un tipo incorrecto o un campo obligatorio ausente) rechaza el lote completo con HTTP 400. La API no crea ninguna fila.
Reenviar un lote no duplica
Si una reference ya existe en una orden viva o pagada de tu comercio, la API no crea otra orden.
Devuelve la orden existente con duplicate: true. Puedes reenviar el mismo lote sin riesgo de cobrar dos veces el mismo pedido.
En un duplicado, amount, baseAmount y currency son los de la orden existente, no los de la fila enviada.
Compara baseAmount con el amount de tu fila para detectar un monto distinto.
Si la orden existente es de otro modo (normal en vez de contraentrega, o al revés), la fila falla con REFERENCE_ALREADY_EXISTS. Usa otra reference.
{ "index": 0, "reference": "PEDIDO-1042", "ok": true,
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"amount": 5525, "baseAmount": 5000, "currency": "COP",
"checkoutUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479",
"deliveryUrl": "https://pay.iionpay.com/c/f47ac10b-58cc-4372-a567-0e02b2c3d479/entrega",
"duplicate": true }
Errores
Al crear un cobro de entrega
| HTTP | Código | Causa |
|---|---|---|
| 400 | INVALID_COMBINATION | deliveryMode junto con custodia (escrow). |
| 400 | COLLECT_AMOUNT_BELOW_MINIMUM | El monto está bajo el mínimo de un cobro. |
| 400 | METHOD_NOT_AVAILABLE | Bre-B no está disponible para este cobro. También responde así un monto bajo el mínimo de Bre-B. |
| 400 | CURRENCY_NOT_SUPPORTED | La moneda no es COP. El cobro de entrega solo acepta COP. |
| 400 | PAYER_DATA_REQUIRED | Falta customerName. La respuesta trae missingFields. |
| 403 | FEATURE_DISABLED | La función no está disponible por ahora. |
Al iniciar el pago de la orden
| HTTP | Código | Causa |
|---|---|---|
| 400 | METHOD_NOT_ALLOWED | Un cobro de entrega solo acepta Bre-B. |
| 409 | CHARGE_STILL_ACTIVE | Hay una solicitud vigente de otro modo. La respuesta trae activeMode y expiresAt. |
| 403 | FEATURE_DISABLED | La función no está disponible por ahora. Si la función se apaga, tampoco se crean QR ni llaves nuevos para los cobros de entrega que ya existen. Un QR o una llave vigente se puede pagar hasta que vence. |
En un lote
| Alcance | Código | Causa |
|---|---|---|
| Lote | BATCH_TOO_LARGE | HTTP 400. El lote trae más de 500 filas. La API no crea ninguna. |
| Fila | REFERENCE_REQUIRED | La fila no trae reference. |
| Fila | DUPLICATE_IN_BATCH | La reference ya aparece antes en el mismo lote. |
| Fila | AMOUNT_BELOW_MIN | El monto está bajo el mínimo de un cobro. En un cobro individual, el mismo caso responde COLLECT_AMOUNT_BELOW_MINIMUM. |
| Fila | REFERENCE_LOCKED | Otra llamada está creando esa reference, o el candado no está disponible. Reintenta la fila. |
| Fila | REFERENCE_ALREADY_EXISTS | La reference ya existe en una orden viva o pagada de otro modo (normal o contraentrega). Usa otra reference. |
Las filas también pueden devolver los códigos del cobro individual, por ejemplo INVALID_COMBINATION o METHOD_NOT_AVAILABLE. AMOUNT_BELOW_MIN existe solo en las filas del lote: un cobro individual no lo devuelve.
Webhooks de este flujo
| Evento | Cuándo llega |
|---|---|
payment.completed | El cliente pagó. La orden pasa a COMPLETED. |
payment.attempt_failed | El banco rechazó un intento. La orden sigue en PENDING y el mensajero puede reintentar. |
payment.failed | El pago falló y la orden pasa a FAILED. Trae failureCode y failureReason. |
payment.expired | La orden venció sin pago. Solo llega con los webhooks V2 activos. |
payment.attempt_failed trae failureCode (código del proveedor), failureReason (motivo en español), attempt (número del intento) y status "PENDING".
La solicitud que vence a los 10 minutos no genera este evento.
Consulta el payload completo en Webhooks.
Buenas prácticas
- Escucha el webhook. El pago se confirma solo por el webhook firmado. Verifica la firma antes de actuar.
- No marques el pedido como entregado sin
payment.completed. Lo que ve el mensajero en pantalla no confirma el pago. - Un intento fallido no cierra el pedido. Con
payment.attempt_failedla orden sigue abierta. Decide en tu sistema si avisas al cliente o al mensajero. - Usa una
referenceestable por pedido. Así un reintento de tu sistema no duplica el cobro en un lote. - Responde 200 rápido y procesa después. Haz tu handler idempotente: el mismo evento puede llegar más de una vez.
- Revisa tu validación de webhooks.
payment.failedtrae ahora dos campos nuevos. Si validas el cuerpo de forma estricta, acepta campos adicionales. - Trata el
deliveryUrlcomo un enlace de cobro. Quien lo abre puede generar un QR que paga a tu comercio. Compártelo solo con el mensajero del pedido.
Para el detalle de la verificación de firma y los reintentos, consulta Webhooks. Para los campos de la orden, consulta la Referencia de API.