En esta página
Referencia de API
Documentación completa de los endpoints disponibles en la API de iion pay.
https://api.prod.iionpay.com/api/v1
Autenticación
Todas las solicitudes requieren autenticación mediante headers:
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
Idempotency-Key.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.COP. Usa "VES" para cobrar en bolívares en Venezuela. Consulta Cobro en bolívares (Venezuela)."CO" (Colombia) o "VE" (Venezuela). Si no viene, la API lo deriva de currency."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).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.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.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.["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."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.BRANCH_FORBIDDEN.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_*.Idempotency-Key. Máximo 255 caracteres: letras, números y los signos _ - : .. Si envías los dos, manda el header. Consulta Idempotencia.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
{
"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:
| Campo | Significado |
|---|---|
baseAmount | Monto base: el valor del cobro, sin comisión. |
feeAmount | Comisión de iion pay. |
feeMode | Quién asume la comisión en este cobro: CUSTOMER_PAYS o MERCHANT_PAYS. |
taxAmount | Impuesto sobre la comisión de iion pay. null en órdenes creadas sin el motor de tarifas. |
netAmount | Lo que se acredita a tu comercio por el cobro. null en órdenes creadas sin el motor de tarifas: ahí se acredita baseAmount. |
providerFeeAmount | Comisió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. |
withholdingAmount | Retenciones de ley que aplicó el proveedor de pago. null si no hay. |
providerName | Proveedor de pago que registró esa comisión. null si no hay. |
couponCode | Código del cupón aplicado al cobro. null sin cupón. |
discountAmount | Descuento del cupón. null sin cupón. |
branchId | Sede del cobro. null = sin sede. |
deliveryUrl | Enlace 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,
amountusa la tarifa general. - Cuando el pagador elige el método,
amountpasa a la tarifa de ese método. baseAmountno cambia. Tú recibes siemprebaseAmount.- Con
MERCHANT_PAYS,amountes igual abaseAmounty no cambia.
La respuesta de crear y GET /v1/collect/:id traen dos campos:
| Campo | Significado |
|---|---|
pricingByMethod | Una 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. |
amountIsFinal | true 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
}
{
"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 |
|---|---|
bank | Banco que recibe el Pago Móvil |
phone | Teléfono que recibe el Pago Móvil |
identification | Documento que recibe el Pago Móvil |
amountLocal | Total exacto que paga el cliente, en Bs |
localCurrency | Siempre "VES" |
timeLimitText | Texto con el plazo para pagar |
legend | Texto 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. |
| 400 | INVALID_PAYER_DOCUMENT | La 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ó. |
| 409 | ACTIVE_PAYMENT_INSTRUCTIONS | Otra 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
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
{
"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 |
|---|---|---|
| Lote | BATCH_TOO_LARGE | HTTP 400. Más de 500 filas. |
| Fila | REFERENCE_REQUIRED | La fila no trae reference. |
| Fila | DUPLICATE_IN_BATCH | La reference ya aparece antes en el lote. |
| Fila | AMOUNT_BELOW_MIN | Monto bajo el mínimo de un cobro. En un cobro individual, el mismo caso responde COLLECT_AMOUNT_BELOW_MINIMUM. |
| Fila | REFERENCE_LOCKED | Otra llamada crea esa reference. Reintenta la fila. |
| Fila | REFERENCE_ALREADY_EXISTS | La 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
Ejemplo de solicitud
GET /v1/collect/clxyz123abc456def
Respuesta exitosa
{
"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:
| Campo | Significado |
|---|---|
baseAmount, feeAmount, taxAmount, netAmount, feeMode | El mismo desglose que la respuesta de crear. |
selectedMethod | Método que eligió el pagador. null si aún no eligió. |
confirmationState | Finalidad del pago, aparte de status: AUTHORIZED, luego CONFIRMED, luego SETTLED. null si el cobro no pasó por esa política. |
resolutionStatus | Lo que pasó después del pago, aparte de status: NONE, DISPUTED, PARTIALLY_REFUNDED, REFUNDED o CHARGEBACK. |
deliveryMode | true en un cobro al entregar. |
deliveryUrl | Enlace 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
PENDING,WAITING_TRANSFER. Un estado desconocido responde 400.Ejemplo de solicitud
GET /v1/collect?status=COMPLETED&limit=20&offset=0
Respuesta exitosa
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
{
"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 |
|---|---|
totalCollected | Suma de amount de las órdenes COMPLETED: lo que pagaron los pagadores. |
totalNet | Lo que recibe tu comercio por las órdenes COMPLETED. |
totalFees | Suma de comisiones de las órdenes COMPLETED. |
approvalRate | COMPLETED 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. |
byStatus | Cantidad 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
Ejemplo de solicitud
POST /v1/collect/clxyz123abc456def/cancel
{
"reason": "El cliente pagó por otro medio"
}
Respuesta exitosa
{
"success": true,
"data": {
"id": "clxyz123abc456def",
"status": "CANCELLED",
"cancelledAt": "2024-01-15T12:10:00.000Z"
}
}
Errores
| HTTP | Causa |
|---|---|
| 404 | La orden no existe o no es de tu comercio. |
| 409 | La 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. |
| 503 | La 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
{
"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 |
|---|---|
seq | Número del evento dentro de la orden, desde 1. |
eventType | status.changed, confirmation.changed o resolution.changed. |
fromStatus / toStatus | Estado antes y después del cambio. |
source | Origen del cambio, por ejemplo merchant_api o provider_webhook. |
chainHash | SHA-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 409IDEMPOTENCY_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-Limit | Solicitudes permitidas por minuto para la llave |
X-RateLimit-Merchant-Remaining | Solicitudes que quedan en la ventana actual |
X-RateLimit-Merchant-Reset | Fecha 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.