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.

Cómo funciona
Crea el cobro con 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-key y x-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

  1. Crea el cobro. Envía deliveryMode: true y el nombre del cliente en customerName. Guarda el id y el deliveryUrl.
  2. Entrega el enlace al mensajero. El deliveryUrl tiene la forma https://pay.iionpay.com/c/:id/entrega. Ábrelo en el teléfono del mensajero.
  3. El mensajero elige el modo. Muestra al cliente un QR Bre-B o una llave Bre-B por el total del cobro.
  4. El cliente paga. Escanea el QR o copia la llave en la app de su banco.
  5. Recibes el webhook. payment.completed confirma el pago. payment.attempt_failed indica 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

  1. En el panel de iion pay, entra a Crear cobro.
  2. Enciende el interruptor Cobrar al entregar (QR Bre-B).
  3. Escribe el Nombre del cliente. Es obligatorio. Al entregar, el mensajero ve solo las iniciales.
  4. Escribe el precio. El panel muestra el total que paga el cliente antes de crear el cobro.
  5. Pulsa Crear cobro.
  6. 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.

CampoObligatorioNotas
deliveryModesítrue activa el modo entrega.
customerNamesíNombre del cliente. Bre-B lo exige.
amountsíMonto base en COP. Mínimo 5.000. Según feeMode, el cliente paga más que este valor.
feeModenoCUSTOMER_PAYS o MERCHANT_PAYS. Sin valor, la API usa el modo por defecto de tu comercio.
referencerecomendadoTu identificador del pedido. En un lote es obligatorio.
expirationMinutesnoPor 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.

feeModeEl cliente pagaTú recibes
CUSTOMER_PAYSbaseAmount + feeAmountbaseAmount
MERCHANT_PAYSbaseAmountbaseAmount − 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.

CampoSignificado
amountTotal que paga el cliente (base más comisión si la paga el cliente).
baseAmountMonto base: el valor de tu pedido.
feeAmountComisión de iion pay.
netAmountLo que recibes por el cobro.
feeModeQuié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 amount de la orden. Con CUSTOMER_PAYS incluye 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_ACTIVE con activeMode y expiresAt. Puede cambiar de modo cuando la solicitud venza.
  • Si el cliente rechaza el pago, la orden vuelve a PENDING y 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

HTTPCódigoCausa
400INVALID_COMBINATIONdeliveryMode junto con custodia (escrow).
400COLLECT_AMOUNT_BELOW_MINIMUMEl monto está bajo el mínimo de un cobro.
400METHOD_NOT_AVAILABLEBre-B no está disponible para este cobro. También responde así un monto bajo el mínimo de Bre-B.
400CURRENCY_NOT_SUPPORTEDLa moneda no es COP. El cobro de entrega solo acepta COP.
400PAYER_DATA_REQUIREDFalta customerName. La respuesta trae missingFields.
403FEATURE_DISABLEDLa función no está disponible por ahora.

Al iniciar el pago de la orden

HTTPCódigoCausa
400METHOD_NOT_ALLOWEDUn cobro de entrega solo acepta Bre-B.
409CHARGE_STILL_ACTIVEHay una solicitud vigente de otro modo. La respuesta trae activeMode y expiresAt.
403FEATURE_DISABLEDLa 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

AlcanceCódigoCausa
LoteBATCH_TOO_LARGEHTTP 400. El lote trae más de 500 filas. La API no crea ninguna.
FilaREFERENCE_REQUIREDLa fila no trae reference.
FilaDUPLICATE_IN_BATCHLa reference ya aparece antes en el mismo lote.
FilaAMOUNT_BELOW_MINEl monto está bajo el mínimo de un cobro. En un cobro individual, el mismo caso responde COLLECT_AMOUNT_BELOW_MINIMUM.
FilaREFERENCE_LOCKEDOtra llamada está creando esa reference, o el candado no está disponible. Reintenta la fila.
FilaREFERENCE_ALREADY_EXISTSLa 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

EventoCuándo llega
payment.completedEl cliente pagó. La orden pasa a COMPLETED.
payment.attempt_failedEl banco rechazó un intento. La orden sigue en PENDING y el mensajero puede reintentar.
payment.failedEl pago falló y la orden pasa a FAILED. Trae failureCode y failureReason.
payment.expiredLa 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_failed la orden sigue abierta. Decide en tu sistema si avisas al cliente o al mensajero.
  • Usa una reference estable 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.failed trae ahora dos campos nuevos. Si validas el cuerpo de forma estricta, acepta campos adicionales.
  • Trata el deliveryUrl como 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.