Referencia de API

Documentación completa de los endpoints disponibles en la API de NIIO Payments.

¿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.niiopay.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 requerido
Identificador único de la orden en tu sistema (ej: número de factura). Máximo 100 caracteres.
amount number requerido
Monto a cobrar en COP. Mínimo: 1,000 COP.
currency string opcional
Código de moneda. Default: COP. Actualmente solo se soporta COP.
description string opcional
Descripción del cobro visible para el cliente. Máximo 500 caracteres.
customerName string requerido
Nombre completo del cliente. Máximo 200 caracteres.
customerEmail string requerido
Email del cliente. Debe ser un email válido.
customerDocType string requerido
Tipo de documento: CC (Cédula), CE (Cédula Extranjería), NIT, PP (Pasaporte)
customerDocNumber string requerido
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: ["PSE", "BANK_TRANSFER"]. Si no se especifica, usa los métodos configurados en tu cuenta.
metadata object opcional
Datos adicionales que quieras asociar a la orden. Se retornan en webhooks. Máximo 1KB.

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.niiopay.com/c/clxyz123abc456def",
    "expiresAt": "2024-01-15T13:00:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}
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.niiopay.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"
  }
}

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
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í ✓

Webhooks

Cuando el estado de una orden cambia a COMPLETED o FAILED, NIIO envía una notificación POST a tu webhookUrl configurada:

Evento: payment.completed

{
  "event": "payment.completed",
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-12345",
    "amount": 150000,
    "currency": "COP",
    "status": "COMPLETED",
    "paidAt": "2024-01-15T12:15:00.000Z",
    "metadata": {
      "orderId": "12345"
    }
  },
  "timestamp": "2024-01-15T12:15:01.000Z"
}

Evento: payment.failed

{
  "event": "payment.failed",
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-12345",
    "amount": 150000,
    "currency": "COP",
    "status": "FAILED",
    "paidAt": null,
    "metadata": {
      "orderId": "12345"
    }
  },
  "timestamp": "2024-01-15T12:20:00.000Z"
}

Rate Limits

La API tiene límites de solicitudes para garantizar la estabilidad del servicio:

Endpoint Límite
POST /v1/collect 100 solicitudes/minuto
GET /v1/collect/:id 1000 solicitudes/minuto

Si excedes el límite, recibirás un error 429 Too Many Requests. Los headers de respuesta incluyen información sobre el límite: 

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705323600