Inicio Rápido

Crea tu primer link de pago en menos de 5 minutos. Esta guía te llevará paso a paso desde obtener tus credenciales hasta generar tu primer cobro.

Prerequisitos

Antes de comenzar, necesitas:

• Una cuenta de negocio en NIIO (solicítala a tu contacto en NIIO)
• Tu perfil de merchant configurado y aprobado
• Tus credenciales de API (API Key y API Secret), entregadas por NIIO

Paso 1: Configura tus credenciales

Tus solicitudes a la API deben incluir dos headers de autenticación:

X-Api-Key: tu_api_key_aqui
X-Api-Secret: tu_api_secret_aqui
Content-Type: application/json

Paso 2: Crea tu primer link de pago

Envía una solicitud POST al endpoint /v1/collect con los datos del cobro:

curl -X POST https://api.prod.niiopay.com/api/v1/collect \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-001",
    "amount": 50000,
    "currency": "COP",
    "description": "Compra en Mi Tienda",
    "customerName": "Juan Pérez",
    "customerEmail": "juan@email.com",
    "customerDocType": "CC",
    "customerDocNumber": "1234567890",
    "expirationMinutes": 60,
    "callbackUrl": "https://mitienda.com/gracias"
  }'

const response = await fetch('https://api.prod.niiopay.com/api/v1/collect', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.NIIO_API_KEY,
    'X-Api-Secret': process.env.NIIO_API_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reference: 'ORDER-001',
    amount: 50000,
    currency: 'COP',
    description: 'Compra en Mi Tienda',
    customerName: 'Juan Pérez',
    customerEmail: 'juan@email.com',
    customerDocType: 'CC',
    customerDocNumber: '1234567890',
    expirationMinutes: 60,
    callbackUrl: 'https://mitienda.com/gracias',
  }),
});

const order = await response.json();
console.log(order.data.collectUrl);
// Redirige al cliente a esta URL

import requests
import os

response = requests.post(
    'https://api.prod.niiopay.com/api/v1/collect',
    headers={
        'X-Api-Key': os.environ['NIIO_API_KEY'],
        'X-Api-Secret': os.environ['NIIO_API_SECRET'],
        'Content-Type': 'application/json',
    },
    json={
        'reference': 'ORDER-001',
        'amount': 50000,
        'currency': 'COP',
        'description': 'Compra en Mi Tienda',
        'customerName': 'Juan Pérez',
        'customerEmail': 'juan@email.com',
        'customerDocType': 'CC',
        'customerDocNumber': '1234567890',
        'expirationMinutes': 60,
        'callbackUrl': 'https://mitienda.com/gracias',
    }
)

order = response.json()
print(order['data']['collectUrl'])
# Redirige al cliente a esta URL

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.prod.niiopay.com/api/v1/collect',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('NIIO_API_KEY'),
        'X-Api-Secret: ' . getenv('NIIO_API_SECRET'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'reference' => 'ORDER-001',
        'amount' => 50000,
        'currency' => 'COP',
        'description' => 'Compra en Mi Tienda',
        'customerName' => 'Juan Pérez',
        'customerEmail' => 'juan@email.com',
        'customerDocType' => 'CC',
        'customerDocNumber' => '1234567890',
        'expirationMinutes' => 60,
        'callbackUrl' => 'https://mitienda.com/gracias',
    ]),
]);

$response = curl_exec($ch);
$order = json_decode($response, true);

echo $order['data']['collectUrl'];
// Redirige al cliente a esta URL

Respuesta exitosa

{
  "success": true,
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-001",
    "amount": 50000,
    "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"
  }
}

Paso 3: Redirige al cliente

Usa la URL collectUrl de la respuesta para redirigir a tu cliente a la página de pago:

// Opción 1: Redirección completa
window.location.href = order.data.collectUrl;

// Opción 2: Abrir en nueva ventana
window.open(order.data.collectUrl, '_blank');

El cliente verá una página de pago donde puede seleccionar su método preferido (PSE o transferencia bancaria) y completar el pago.

Paso 4: Verifica el estado

Consulta el estado de la orden en cualquier momento usando el endpoint GET:

curl -X GET https://api.prod.niiopay.com/api/v1/collect/clxyz123abc456def \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret"

Respuesta

{
  "success": true,
  "data": {
    "id": "clxyz123abc456def",
    "reference": "ORDER-001",
    "amount": 50000,
    "currency": "COP",
    "status": "COMPLETED",
    "selectedMethod": "PSE",
    "customer": {
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "documentType": "CC",
      "documentNumber": "1234567890"
    },
    "paidAt": "2024-01-15T12:15:00.000Z",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

Paso 5: Recibe el webhook (opcional)

Si configuraste un webhookUrl en tu cuenta de merchant, NIIO enviará una notificación POST cuando el pago se complete o falle:

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

Siguientes pasos