En esta página

Referencia de API

Documentación completa de los endpoints disponibles en la API de iion pay.

¿Prefieres probar en vez de leer?
Esta página describe los endpoints; en la referencia interactiva puedes ejecutarlos en vivo desde el navegador con tus API keys.
Base URL
Todas las solicitudes deben hacerse a: https://api.prod.iionpay.com/api/v1

Autenticación

Todas las solicitudes requieren autenticación mediante headers:

Headers requeridos
X-Api-Key: tu_api_key
X-Api-Secret: tu_api_secret
Content-Type: application/json

Endpoints

POST /v1/collect

Crea una nueva orden de cobro y genera un link de pago donde tu cliente puede completar el pago.

Body Parameters

reference string opcional
Identificador de la orden en tu sistema (ej: número de factura). Máximo 100 caracteres. Si no la envías, la API genera una. Para no duplicar cobros al reintentar, usa Idempotency-Key.
amount number obligatorio salvo con priceCurrency/priceAmount
Monto a cobrar en la moneda del cobro: COP o bolívares (Bs). En COP, el mínimo es 5.000 COP: con un monto menor, la API responde 400 COLLECT_AMOUNT_BELOW_MINIMUM. En Bs, Pago Móvil exige un mínimo de 100 Bs. No lo envíes junto con priceCurrency y priceAmount.
currency string opcional
Código de moneda. Default: COP. Usa "VES" para cobrar en bolívares en Venezuela. Consulta Cobro en bolívares (Venezuela).
country string opcional
País del cobro: "CO" (Colombia) o "VE" (Venezuela). Si no viene, la API lo deriva de currency.
priceCurrency string opcional
Moneda del precio fijado. Único valor: "USD". Va junto con priceAmount y en lugar de amount. Con este par, currency debe ser "COP" o no venir, y expirationMinutes admite máximo 1440 (24 h).
priceAmount number opcional
Precio en dólares: mayor que 0, máximo 2 decimales. Va junto con priceCurrency. La API lo convierte a COP con la TRM spot del momento de crear el cobro y redondea al peso entero hacia arriba. La tasa queda congelada en el cobro.
description string opcional
Descripción del cobro visible para el cliente. Máximo 500 caracteres.
customerName string opcional
Nombre completo del cliente. Máximo 200 caracteres.
customerEmail string opcional
Email del cliente. Si lo envías, debe ser un email válido.
customerDocType string opcional
Tipo de documento: CC (Cédula), CE (Cédula Extranjería), NIT, PP (Pasaporte). Si envías el tipo y el número, la API valida el número según el tipo.
customerDocNumber string opcional
Número de documento del cliente.
expirationMinutes number opcional
Tiempo de expiración en minutos. Default: 60. Mínimo: 5.
callbackUrl string opcional
URL a la que redirigir al cliente después del pago. Debe ser una URL válida con HTTPS.
allowedMethods array opcional
Métodos de pago permitidos. Valores: PSE, BANK_TRANSFER, ACH, WIRE, CRYPTO, CARD, X402. Si no se especifica, usa los métodos habilitados para tu comercio (un comercio nuevo nace con ["PSE", "BANK_TRANSFER"]). iion pay quita los que tu comercio no tiene habilitados; si no queda ninguno, la API responde 400. La respuesta trae la lista final.
allowedMethodKeys array opcional
Llaves de los métodos que ofrece el cobro, por ejemplo ["pago_movil"]. Cada llave usa minúsculas, números y _. Si no viene, el cobro ofrece todos los métodos activos de tu comercio. Si ninguna llave está activa en tu comercio, la API responde 400.
metadata object opcional
Datos adicionales que quieras asociar a la orden. Se retornan en webhooks. Máximo 1KB.
feeMode string opcional
Quién asume la comisión en este cobro: "CUSTOMER_PAYS" (el pagador paga el monto más la comisión) o "MERCHANT_PAYS" (la comisión se descuenta de lo que recibes). Si no lo envías, se usa el modo por defecto de tu comercio. Si tu comercio tiene un contrato de tarifa con modo propio, el contrato manda sobre este campo. No hay un modo por defecto igual para todos los comercios: lee feeMode en la respuesta. Si MERCHANT_PAYS no está disponible, la API responde 400 FEE_MODE_UNAVAILABLE. Con CUSTOMER_PAYS, el total depende del método de pago que elige el pagador. Consulta Total según el método de pago.
branchId string opcional
Sede del cobro. Máximo 64 caracteres. Si tu llave API está atada a una sede, el cobro queda en la sede de la llave; si envías otra sede, la API responde 403 BRANCH_FORBIDDEN.
couponCode string opcional
Código de un cupón de tu comercio. Máximo 32 caracteres. El descuento se resta del monto base antes de la comisión. No se acepta con escrow. Si los cupones no están disponibles, la API responde 403 FEATURE_DISABLED. Si el cupón no existe, está inactivo, venció o se agotó, la API responde 422 con un código COUPON_*.
idempotencyKey string opcional
Alternativa al header Idempotency-Key. Máximo 255 caracteres: letras, números y los signos _ - : .. Si envías los dos, manda el header. Consulta Idempotencia.
deliveryMode boolean opcional
Cobro al entregar: el mensajero muestra un QR o una llave Bre-B al entregar el pedido. Solo admite Bre-B y COP, exige customerName y vence en 10080 minutos si no envías expirationMinutes. La respuesta trae deliveryUrl. Errores: 400 INVALID_COMBINATION con escrow, 400 METHOD_NOT_AVAILABLE sin Bre-B, 400 CURRENCY_NOT_SUPPORTED con una moneda distinta de COP, 400 PAYER_DATA_REQUIRED sin customerName, 403 FEATURE_DISABLED con la función apagada. 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. Consulta Cobrar al entregar (Bre-B).

Ejemplo de solicitud

{
  "reference": "ORDER-12345",
  "amount": 150000,
  "currency": "COP",
  "description": "Pago de factura #12345",
  "customerName": "Juan Pérez",
  "customerEmail": "juan@email.com",
  "customerDocType": "CC",
  "customerDocNumber": "1234567890",
  "expirationMinutes": 60,
  "callbackUrl": "https://mitienda.com/pago-exitoso",
  "allowedMethods": ["PSE", "BANK_TRANSFER"],
  "metadata": {
    "orderId": "12345",
    "userId": "user_abc"
  }
}

Respuesta exitosa

201 Created
{
  "success": true,
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-12345",
    "amount": 150000,
    "currency": "COP",
    "status": "PENDING",
    "collectUrl": "https://pay.iionpay.com/c/clxyz123abc456def",
    "expiresAt": "2024-01-15T13:00:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

La respuesta de crear trae también estos campos:

CampoSignificado
baseAmountMonto base: el valor del cobro, sin comisión.
feeAmountComisión de iion pay.
feeModeQuién asume la comisión en este cobro: CUSTOMER_PAYS o MERCHANT_PAYS.
taxAmountImpuesto sobre la comisión de iion pay. null en órdenes creadas sin el motor de tarifas.
netAmountLo que se acredita a tu comercio por el cobro. null en órdenes creadas sin el motor de tarifas: ahí se acredita baseAmount.
providerFeeAmountComisión del proveedor de pago que asume tu comercio (por ejemplo, en ventas de datáfono). Solo baja lo que recibes; no es parte de feeAmount. null si no hay.
withholdingAmountRetenciones de ley que aplicó el proveedor de pago. null si no hay.
providerNameProveedor de pago que registró esa comisión. null si no hay.
couponCodeCódigo del cupón aplicado al cobro. null sin cupón.
discountAmountDescuento del cupón. null sin cupón.
branchIdSede del cobro. null = sin sede.
deliveryUrlEnlace del mensajero. Solo viene en un cobro al entregar.

Total según el método de pago (CUSTOMER_PAYS)

Con feeMode CUSTOMER_PAYS, el total que paga el cliente depende del método que elige el pagador.

  • Al crear el cobro, amount usa la tarifa general.
  • Cuando el pagador elige el método, amount pasa a la tarifa de ese método.
  • baseAmount no cambia. Tú recibes siempre baseAmount.
  • Con MERCHANT_PAYS, amount es igual a baseAmount y no cambia.

La respuesta de crear y GET /v1/collect/:id traen dos campos:

CampoSignificado
pricingByMethodUna fila por método ofrecido: methodKey, feeAmount, taxAmount y totalAmount. Es null cuando amountIsFinal es true. Si el campo no viene en la respuesta, no se pudo calcular en ese momento: consulta de nuevo con GET /v1/collect/:id.
amountIsFinaltrue cuando amount ya no puede cambiar: con MERCHANT_PAYS, en un cobro al entregar, o cuando el cobro ya no está pendiente (pagado, vencido o cancelado). Mientras el cobro está pendiente con CUSTOMER_PAYS, es false aunque el pagador ya haya elegido un método, porque puede cambiar de método.

Ejemplo con CUSTOMER_PAYS y baseAmount 5000 (valores ilustrativos: la tarifa de cada método depende del plan del comercio):

{
  "amount": 5100,
  "baseAmount": 5000,
  "feeAmount": 100,
  "feeMode": "CUSTOMER_PAYS",
  "amountIsFinal": false,
  "pricingByMethod": [
    { "methodKey": "breb", "feeAmount": 525, "taxAmount": 0, "totalAmount": 5525 },
    { "methodKey": "nequi", "feeAmount": 600, "taxAmount": 0, "totalAmount": 5600 }
  ]
}

Si el pagador elige breb, amount pasa a 5525 y feeAmount pasa a 525.

methodKey es la llave del método en el checkout. La lista sale del ruteo de pagos de tu comercio: trae los métodos que el checkout ofrece en ese cobro, y cambia si cambia el ruteo. breb y nequi son solo ejemplos. Otros valores posibles son iion_app (pago con la app iion pay) y kushki_pse (PSE). No asumas una lista fija: lee la que trae cada respuesta.

El total final que pagó el cliente llega en el webhook payment.completed, en amount, baseAmount y feeAmount. Si una tarifa cambia entre crear y pagar, usa el valor del webhook. Un cupón aplicado en el checkout puede bajar amount. El total final siempre llega en el webhook payment.completed.

Precio en USD, pago en pesos

En lugar de amount, envía priceCurrency y priceAmount. El checkout muestra el precio en grande (por ejemplo «5 USD») y debajo «Pagas en pesos $ 15.859 COP». Ese total en pesos es el amount del cobro: con la comisión asumida por el comercio es igual a baseAmount, y con la comisión a cargo del pagador incluye la comisión. En la respuesta, amount y currency son los COP que se cobran, y price trae el precio en USD con la tasa congelada. En los cobros sin precio en USD, price es null.

{
  "reference": "ORDER-12346",
  "priceCurrency": "USD",
  "priceAmount": 5,
  "customerName": "Juan Pérez",
  "customerEmail": "juan@email.com",
  "customerDocType": "CC",
  "customerDocNumber": "1234567890",
  "expirationMinutes": 60
}
{
  "success": true,
  "data": {
    "id": "clxyz123abc789ghi",
    "reference": "ORDER-12346",
    "amount": 15859,
    "baseAmount": 15859,
    "feeAmount": 578,
    "currency": "COP",
    "price": {
      "amount": 5,
      "currency": "USD",
      "fxRate": 3171.7515,
      "fxRateKind": "trm",
      "fxRateAt": "2026-10-15T14:00:00.000Z"
    },
    "status": "PENDING",
    "collectUrl": "https://pay.iionpay.com/c/clxyz123abc789ghi",
    "expiresAt": "2026-10-15T15:00:00.000Z",
    "createdAt": "2026-10-15T14:00:00.000Z"
  }
}

Conversión del ejemplo: 5 × 3171.7515 = 15858.7575, que se redondea hacia arriba a amount 15859. Quién asume la comisión depende del comercio. Por defecto la asume el comercio: amount = baseAmount (15859) y feeAmount (578 en el ejemplo: Bre-B, plan START) se descuenta de lo que recibes. Si la paga el pagador, amount = baseAmount + feeAmount, y el total puede cambiar cuando el pagador elige el método (ver Total según el método de pago). El porcentaje depende del plan o del contrato del comercio. El desglose siempre viene en la respuesta. Los webhooks traen los montos en la moneda del cobro: en este caso, COP. En los cobros en VES, los montos van en Bs. Para conciliar en USD, guarda price de la respuesta de creación o léelo con GET /v1/collect/:id.

Errores 400: USD_PRICE_WITH_AMOUNT, USD_PRICE_INCOMPLETE, USD_PRICE_CURRENCY_INVALID, USD_PRICE_CURRENCY_NOT_COP, USD_PRICE_EXPIRATION_TOO_LONG. Si no hay tasa vigente, la API responde 503 RATE_UNAVAILABLE: reintenta más tarde o crea el cobro con amount en COP. Consulta Manejo de Errores.

Cobro directo por API (sin checkout)

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. Usa las mismas credenciales y la orden creada con POST /api/v1/collect. El flujo usa GET /api/v1/collect/:id/methods y POST /api/v1/collect/:id/pay. El pago se confirma por el webhook. Consulta la guía completa en Cobro directo por API.

Si /pay responde 400 PAYER_DATA_REQUIRED, consulta Si faltan datos del pagador.

Cobro en bolívares (Venezuela)

Para cobrar en Venezuela, envía currency "VES" y country "VE". El monto va en bolívares (Bs). Tu cliente paga con Pago Móvil.

Requisito: activa Pago Móvil en el portal, en la pantalla «Configuración del comercio». Sin Pago Móvil activo, el checkout no ofrece ese método.

POST /api/v1/collect

{
  "reference": "ORDER-VE-001",
  "amount": 500,
  "currency": "VES",
  "country": "VE",
  "allowedMethodKeys": ["pago_movil"],
  "customerName": "Juan Pérez",
  "customerEmail": "juan@email.com",
  "expirationMinutes": 60
}
201 Created
{
  "success": true,
  "data": {
    "id": "clxyz123abc999ve",
    "reference": "ORDER-VE-001",
    "amount": 500,
    "baseAmount": 500,
    "feeAmount": 0,
    "currency": "VES",
    "status": "PENDING",
    "collectUrl": "https://pay.iionpay.com/c/clxyz123abc999ve",
    "expiresAt": "2026-10-19T15:00:00.000Z",
    "createdAt": "2026-10-19T14:00:00.000Z"
  }
}

baseAmount es el monto que pediste, en Bs. amount es baseAmount más la comisión (feeAmount). En el ejemplo, la comisión es 0. Comparte collectUrl con tu cliente. La respuesta no trae las instrucciones de Pago Móvil: estas nacen cuando el cliente paga.

El cliente paga el monto del cobro más el cargo del proveedor de Pago Móvil. El total exacto en bolívares aparece en las instrucciones de pago.

  • Mínimo: 100 Bs. Con un monto menor, la orden se crea, pero el checkout no ofrece Pago Móvil.
  • Vencimiento de la orden: expirationMinutes, por defecto 60 minutos.
  • Vencimiento de las instrucciones: 30 minutos desde que el cliente las pide.
  • Liquidación: el saldo de tu comercio queda en pesos.
  • Webhooks: traen currency "VES" y los montos en Bs. No traen los pesos acreditados.

Cobro directo por API (/pay)

Con la API directa, tu sistema pide las instrucciones de Pago Móvil sin abrir el checkout. Llama a POST /api/v1/collect/:id/pay con method "pago_movil". Si la API directa está desactivada, la API responde 503. Para ver los métodos de una orden, llama a GET /api/v1/collect/:id/methods.

POST /api/v1/collect/clxyz123abc999ve/pay

{
  "method": "pago_movil",
  "payer": {
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "docType": "V",
    "docNumber": "12345678"
  }
}

La cédula del pagador va en payer.docType y payer.docNumber. docType es V (venezolano) o E (extranjero). docNumber tiene entre 6 y 9 dígitos, sin letras ni puntos.

La respuesta trae transactionId, method, flow ("push"), expiresAt y paymentInstructions. paymentUrl es null.

Campo de paymentInstructions Descripción
bankBanco que recibe el Pago Móvil
phoneTeléfono que recibe el Pago Móvil
identificationDocumento que recibe el Pago Móvil
amountLocalTotal exacto que paga el cliente, en Bs
localCurrencySiempre "VES"
timeLimitTextTexto con el plazo para pagar
legendTexto de ayuda para el cliente

Errores de los cobros en bolívares

HTTP Código Causa
400—Los cobros en VES no están disponibles en este momento.
400—Ninguna llave de allowedMethodKeys está activa en tu comercio.
400—Al pagar: el método no está disponible. Causas: Pago Móvil no está activo en tu comercio o el monto es menor que 100 Bs.
400INVALID_PAYER_DOCUMENTLa cédula no es tipo V o E, o no tiene entre 6 y 9 dígitos.
400—Al pagar: el monto supera el máximo por pago.
400—Al pagar: la orden venció.
409ACTIVE_PAYMENT_INSTRUCTIONSOtra cédula tiene instrucciones de pago vigentes para esta orden.
502—El proveedor de Pago Móvil falló al crear la orden de pago.
503—El proveedor de Pago Móvil rechazó la orden de pago.
503—La API directa está desactivada temporalmente.

POST /v1/collect/batch

Crea hasta 500 órdenes de cobro en una llamada. La API procesa 5 filas a la vez y devuelve un resultado por fila. Consulta la guía en Cobrar al entregar (Bre-B).

Body Parameters

orders array obligatorio
Entre 1 y 500 filas. Cada fila tiene la forma del cuerpo de POST /v1/collect. reference es obligatoria en cada fila.

Ejemplo de solicitud

POST /v1/collect/batch

{ "orders": [
  { "reference": "PEDIDO-1042", "amount": 45000, "currency": "COP",
    "customerName": "Ana Pérez", "deliveryMode": true }
] }

Respuesta exitosa

200 OK
{
  "success": true,
  "data": {
    "total": 1, "created": 1, "duplicates": 0, "failed": 0,
    "results": [
      { "index": 0, "reference": "PEDIDO-1042", "ok": true,
        "id": "clxyz123abc456def",
        "amount": 45000, "currency": "COP",
        "checkoutUrl": "https://pay.iionpay.com/c/clxyz123abc456def",
        "deliveryUrl": "https://pay.iionpay.com/c/clxyz123abc456def/entrega" }
    ]
  },
  "error": null
}

Si una reference ya existe en una orden viva o pagada de tu comercio, la fila devuelve esa orden con duplicate: true y no crea otra. Cada fila ok: true trae amount y currency de la orden guardada. En un duplicado son los de la orden existente, no los de la fila enviada. Una fila fallida trae ok: false y error con code y message. Una fila mal formada (un tipo incorrecto o un campo obligatorio ausente) rechaza el lote completo con HTTP 400.

Errores

Alcance Código Causa
LoteBATCH_TOO_LARGEHTTP 400. Más de 500 filas.
FilaREFERENCE_REQUIREDLa fila no trae reference.
FilaDUPLICATE_IN_BATCHLa reference ya aparece antes en el lote.
FilaAMOUNT_BELOW_MINMonto bajo el mínimo de un cobro. En un cobro individual, el mismo caso responde COLLECT_AMOUNT_BELOW_MINIMUM.
FilaREFERENCE_LOCKEDOtra llamada crea esa reference. Reintenta la fila.
FilaREFERENCE_ALREADY_EXISTSLa reference ya existe en una orden viva o pagada de otro modo (normal o contraentrega).

GET /v1/collect/:id

Obtiene los detalles y estado actual de una orden de cobro.

Path Parameters

id string requerido
ID de la orden de cobro retornado al crearla.

Ejemplo de solicitud

GET /v1/collect/clxyz123abc456def

Respuesta exitosa

200 OK
{
  "success": true,
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-12345",
    "amount": 150000,
    "currency": "COP",
    "description": "Pago de factura #12345",
    "status": "COMPLETED",
    "selectedMethod": "PSE",
    "allowedMethods": ["PSE", "BANK_TRANSFER"],
    "customer": {
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "documentType": "CC",
      "documentNumber": "1234567890"
    },
    "collectUrl": "https://pay.iionpay.com/c/clxyz123abc456def",
    "callbackUrl": "https://mitienda.com/pago-exitoso",
    "metadata": {
      "orderId": "12345",
      "userId": "user_abc"
    },
    "expiresAt": "2024-01-15T13:00:00.000Z",
    "paidAt": "2024-01-15T12:15:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:15:00.000Z"
  }
}

La respuesta incluye deliveryMode (boolean) y deliveryUrl (string, o null si el cobro no es de entrega). Consulta Cobrar al entregar (Bre-B).

El GET trae también estos campos:

CampoSignificado
baseAmount, feeAmount, taxAmount, netAmount, feeModeEl mismo desglose que la respuesta de crear.
selectedMethodMétodo que eligió el pagador. null si aún no eligió.
confirmationStateFinalidad del pago, aparte de status: AUTHORIZED, luego CONFIRMED, luego SETTLED. null si el cobro no pasó por esa política.
resolutionStatusLo que pasó después del pago, aparte de status: NONE, DISPUTED, PARTIALLY_REFUNDED, REFUNDED o CHARGEBACK.
deliveryModetrue en un cobro al entregar.
deliveryUrlEnlace del mensajero. null si el cobro no es de entrega.

GET /v1/collect

Lista las órdenes de cobro de tu comercio, de la más reciente a la más antigua.

Query Parameters

status string opcional
Filtra por estado. Acepta uno o varios separados por coma, por ejemplo PENDING,WAITING_TRANSFER. Un estado desconocido responde 400.
limit number opcional
Cantidad de órdenes por página. Default: 20.
offset number opcional
Cantidad de órdenes que se saltan. Default: 0.

Ejemplo de solicitud

GET /v1/collect?status=COMPLETED&limit=20&offset=0

Respuesta exitosa

200 OK

data es una lista. Cada elemento tiene la misma forma que la respuesta de GET /v1/collect/:id. La respuesta no trae el total de órdenes: pide la página siguiente hasta recibir menos de limit elementos.

{
  "success": true,
  "data": [
    {
      "id": "clxyz123abc456def",
      "reference": "ORDER-12345",
      "amount": 150000,
      "currency": "COP",
      "status": "COMPLETED",
      "createdAt": "2024-01-15T12:00:00.000Z"
    }
  ]
}

GET /v1/collect/stats

Devuelve el resumen de todas las órdenes de cobro de tu comercio: conteos por estado, montos cobrados y montos por método.

Respuesta exitosa

200 OK
{
  "success": true,
  "data": {
    "from": null,
    "to": null,
    "total": 42,
    "pending": 3,
    "completed": 35,
    "failed": 2,
    "totalCollected": 5250000,
    "totalNet": 5040000,
    "totalFees": 210000,
    "totalTax": 0,
    "approvalRate": 0.9459,
    "refunded": { "count": 1, "amount": 150000 },
    "byStatus": {
      "PENDING": 3,
      "WAITING_TRANSFER": 0,
      "PROCESSING": 0,
      "CREDITING": 0,
      "HELD": 0,
      "COMPLETED": 35,
      "FAILED": 2,
      "EXPIRED": 1,
      "CANCELLED": 1,
      "NEEDS_REVIEW": 0
    },
    "byMethod": [
      { "method": "pse", "count": 20, "amount": 3000000 },
      { "method": "nequi", "count": 15, "amount": 2250000 }
    ]
  }
}
Campo Descripción
totalCollectedSuma de amount de las órdenes COMPLETED: lo que pagaron los pagadores.
totalNetLo que recibe tu comercio por las órdenes COMPLETED.
totalFeesSuma de comisiones de las órdenes COMPLETED.
approvalRateCOMPLETED sobre COMPLETED + FAILED, de 0 a 1. null si no hay órdenes en esos dos estados.
refundedÓrdenes pagadas que después se devolvieron o se disputaron, y el monto devuelto.
byStatusCantidad de órdenes en cada estado.
byMethodÓrdenes COMPLETED por método de pago, de mayor a menor monto.

POST /v1/collect/:id/cancel

Cancela una orden de cobro que nadie empezó a pagar. Solo se cancela una orden en estado PENDING. La orden pasa a CANCELLED y iion pay envía el webhook payment.cancelled.

Body Parameters

reason string opcional
Motivo de la cancelación. Queda en el historial de la orden. Máximo 500 caracteres.

Ejemplo de solicitud

POST /v1/collect/clxyz123abc456def/cancel

{
  "reason": "El cliente pagó por otro medio"
}

Respuesta exitosa

200 OK
{
  "success": true,
  "data": {
    "id": "clxyz123abc456def",
    "status": "CANCELLED",
    "cancelledAt": "2024-01-15T12:10:00.000Z"
  }
}

Errores

HTTP Causa
404La orden no existe o no es de tu comercio.
409La orden ya no está en PENDING: tiene un pago en curso (WAITING_TRANSFER, PROCESSING, CREDITING, HELD) o ya terminó. Una segunda cancelación de la misma orden también responde 409.
503La cancelación de cobros no está disponible en este momento.

GET /v1/collect/:id/events

Devuelve el historial de cambios de la orden, en orden de seq. Cada evento dice qué cambió, cuándo y quién lo originó.

Respuesta exitosa

200 OK
{
  "success": true,
  "data": [
    {
      "seq": 1,
      "eventType": "status.changed",
      "fromStatus": "PENDING",
      "toStatus": "CANCELLED",
      "source": "merchant_api",
      "createdAt": "2024-01-15T12:10:00.000Z",
      "chainHash": "9f2c4e…"
    }
  ]
}
Campo Descripción
seqNúmero del evento dentro de la orden, desde 1.
eventTypestatus.changed, confirmation.changed o resolution.changed.
fromStatus / toStatusEstado antes y después del cambio.
sourceOrigen del cambio, por ejemplo merchant_api o provider_webhook.
chainHashSHA-256 en hexadecimal que encadena el evento con el anterior.

Si la orden no existe o no es de tu comercio, la API responde 404.

Idempotencia

Envía el header Idempotency-Key en POST /v1/collect para reintentar sin duplicar cobros. Usa una clave única por cobro, por ejemplo pedido-42-intento-1. Máximo 255 caracteres: letras, números y los signos _ - : ..

  • Misma clave y mismo cuerpo: la API devuelve la orden ya creada, con el mismo id. No crea un cobro nuevo.
  • Misma clave y otro cuerpo: la API responde 409 IDEMPOTENCY_KEY_REUSED.
  • Misma clave en otra sede (branchId): la API responde 409 IDEMPOTENCY_BRANCH_MISMATCH.
  • Sin clave: cada solicitud crea un cobro nuevo, aunque repitas la misma reference.
POST /v1/collect
Idempotency-Key: pedido-42-intento-1
Content-Type: application/json

{ "reference": "ORDER-12345", "amount": 150000 }

Estados de una Orden

Una orden de cobro puede tener los siguientes estados:

Estado Descripción Final
PENDING Orden creada, esperando que el cliente seleccione método de pago No
PROCESSING Pago PSE en proceso de autorización No
WAITING_TRANSFER Cliente seleccionó transferencia bancaria, esperando el depósito No
CREDITING El pago está confirmado y iion pay acredita los fondos a tu comercio No
HELD Pago en custodia: el pago está confirmado y los fondos quedan retenidos hasta que se confirma la entrega No
NEEDS_REVIEW El pago está confirmado, pero la acreditación necesita una revisión manual de nuestro equipo No
COMPLETED Pago completado exitosamente Sí ✓
FAILED El pago falló (rechazado por el banco, fondos insuficientes, etc.) Sí ✓
EXPIRED La orden expiró sin recibir pago Sí ✓
CANCELLED Tu comercio canceló la orden con POST /v1/collect/:id/cancel antes de que alguien empezara a pagar Sí ✓

TEST no es un estado de una orden: solo aparece en el aviso de prueba test.ping. Consulta Registrar tu webhook por API.

Webhooks

iion pay envía notificaciones sobre tus órdenes a la URL de tu webhook: la de la API key que creó el cobro (campo url de PUT /v1/collect/webhook) o, si la llave no tiene, la del webhook general del panel. Consulta los eventos, el formato del payload y la verificación de la firma en Webhooks.

Rate Limits

Cada llave API tiene un límite de 120 solicitudes por minuto en los endpoints de /v1/collect. El límite es por llave, no por comercio: dos llaves del mismo comercio tienen cupos separados.

Cada respuesta incluye estos headers:

X-RateLimit-Merchant-Limit: 120
X-RateLimit-Merchant-Remaining: 87
X-RateLimit-Merchant-Reset: 2024-01-15T12:01:00.000Z
Header Descripción
X-RateLimit-Merchant-LimitSolicitudes permitidas por minuto para la llave
X-RateLimit-Merchant-RemainingSolicitudes que quedan en la ventana actual
X-RateLimit-Merchant-ResetFecha y hora (ISO 8601, UTC) en que se libera el cupo

Si excedes el límite, la API responde 429 Too Many Requests con el código MERCHANT_RATE_LIMIT_EXCEEDED y bloquea la llave durante 60 segundos. La respuesta incluye el header Retry-After con los segundos que debes esperar antes de reintentar. Consulta el cuerpo completo en Errores de Rate Limit.