En esta página

SDKs y Librerías

Integra iion pay rápidamente usando nuestras librerías oficiales o la API REST directamente.

Librerías oficiales

SDKs en desarrollo
Estamos trabajando en SDKs oficiales para los lenguajes más populares. Por ahora, puedes usar la API REST directamente con los ejemplos que proporcionamos.

Roadmap de SDKs

Lenguaje Estado
Node.js / TypeScript En preparación
Python En preparación
PHP En preparación
Ruby En preparación
Go En preparación

Integración directa con la API

Mientras tanto, puedes integrar directamente con nuestra API REST. Aquí tienes ejemplos completos para los lenguajes más comunes.

Node.js

Crea un cliente simple para interactuar con la API:

// iion-pay-client.js
class IionPayClient {
  constructor(apiKey, apiSecret) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.baseUrl = 'https://api.prod.iionpay.com/api/v1';
  }

  async request(method, path, body = null) {
    const options = {
      method,
      headers: {
        'X-Api-Key': this.apiKey,
        'X-Api-Secret': this.apiSecret,
        'Content-Type': 'application/json',
      },
    };

    if (body) {
      options.body = JSON.stringify(body);
    }

    const response = await fetch(`${this.baseUrl}${path}`, options);
    const data = await response.json();

    if (!data.success) {
      // El 429 trae el detalle un nivel más adentro; un 500 trae error: null.
      const inner = data.error && typeof data.error.error === 'object' ? data.error.error : data.error;
      const message = Array.isArray(inner?.message) ? inner.message.join('; ') : inner?.message ?? data.message;
      const error = new Error(message);
      error.statusCode = data.statusCode;
      error.code = inner?.code ?? null; // solo algunos errores traen código
      error.details = inner?.details ?? null;
      throw error;
    }

    return data.data;
  }

  // Órdenes de cobro
  async createOrder(orderData) {
    return this.request('POST', '/collect', orderData);
  }

  async getOrder(orderId) {
    return this.request('GET', `/collect/${orderId}`);
  }
}

module.exports = { IionPayClient };

Uso:

const { IionPayClient } = require('./iion-pay-client');

const iionpay = new IionPayClient(
  process.env.IION_API_KEY,
  process.env.IION_API_SECRET
);

// Crear orden de cobro
const order = await iionpay.createOrder({
  reference: 'ORDER-123',
  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://tutienda.com/pago-completado',
});

console.log('URL de pago:', order.collectUrl);
console.log('ID de orden:', order.id);

// Consultar estado de la orden
const status = await iionpay.getOrder(order.id);
console.log('Estado:', status.status); // PENDING, PROCESSING, COMPLETED, FAILED, EXPIRED

Python

import requests
import os

class IionPayClient:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = 'https://api.prod.iionpay.com/api/v1'

    def _request(self, method, path, body=None):
        headers = {
            'X-Api-Key': self.api_key,
            'X-Api-Secret': self.api_secret,
            'Content-Type': 'application/json',
        }

        response = requests.request(
            method,
            f'{self.base_url}{path}',
            headers=headers,
            json=body,
            timeout=30
        )

        data = response.json()

        if not data.get('success'):
            # El 429 trae el detalle un nivel más adentro; un 500 trae error: None.
            error = data.get('error') or {}
            inner = error['error'] if isinstance(error.get('error'), dict) else error
            message = inner.get('message') or data.get('message')
            if isinstance(message, list):
                message = '; '.join(message)
            raise IionPayError(
                message,
                data.get('statusCode'),
                inner.get('code'),  # solo algunos errores traen código
                inner.get('details')
            )

        return data.get('data')

    def create_order(self, order_data):
        return self._request('POST', '/collect', order_data)

    def get_order(self, order_id):
        return self._request('GET', f'/collect/{order_id}')


class IionPayError(Exception):
    def __init__(self, message, status_code=None, code=None, details=None):
        super().__init__(message)
        self.status_code = status_code
        self.code = code
        self.details = details

Uso:

import os
from iion_pay_client import IionPayClient

iionpay = IionPayClient(
    api_key=os.environ['IION_API_KEY'],
    api_secret=os.environ['IION_API_SECRET']
)

# Crear orden de cobro
order = iionpay.create_order({
    'reference': 'ORDER-123',
    '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://tutienda.com/pago-completado',
})

print(f"URL de pago: {order['collectUrl']}")
print(f"ID de orden: {order['id']}")

# Consultar estado de la orden
status = iionpay.get_order(order['id'])
print(f"Estado: {status['status']}")  # PENDING, PROCESSING, COMPLETED, FAILED, EXPIRED

PHP

class IionPayClient {
    private $apiKey;
    private $apiSecret;
    private $baseUrl;

    public function __construct($apiKey, $apiSecret) {
        $this->apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
        $this->baseUrl = 'https://api.prod.iionpay.com/api/v1';
    }

    private function request($method, $path, $body = null) {
        $ch = curl_init();

        $options = [
            CURLOPT_URL => $this->baseUrl . $path,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => [
                'X-Api-Key: ' . $this->apiKey,
                'X-Api-Secret: ' . $this->apiSecret,
                'Content-Type: application/json',
            ],
        ];

        if ($method === 'POST') {
            $options[CURLOPT_POST] = true;
            if ($body) {
                $options[CURLOPT_POSTFIELDS] = json_encode($body);
            }
        }

        curl_setopt_array($ch, $options);
        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);

        if (empty($data['success'])) {
            // El 429 trae el detalle un nivel más adentro; un 500 trae error: null.
            $error = is_array($data['error'] ?? null) ? $data['error'] : [];
            $inner = is_array($error['error'] ?? null) ? $error['error'] : $error;
            $message = $inner['message'] ?? $data['message'] ?? 'Error desconocido';
            if (is_array($message)) {
                $message = implode('; ', $message);
            }
            throw new IionPayException(
                $message,
                $data['statusCode'] ?? null,
                $inner['code'] ?? null, // solo algunos errores traen código
                $inner['details'] ?? null
            );
        }

        return $data['data'];
    }

    public function createOrder($orderData) {
        return $this->request('POST', '/collect', $orderData);
    }

    public function getOrder($orderId) {
        return $this->request('GET', '/collect/' . $orderId);
    }
}

class IionPayException extends Exception {
    public $statusCode;
    public $errorCode;
    public $details;

    public function __construct($message, $statusCode = null, $errorCode = null, $details = null) {
        parent::__construct($message, (int) $statusCode);
        $this->statusCode = $statusCode;
        $this->errorCode = $errorCode;
        $this->details = $details;
    }
}

Uso:

$iionpay = new IionPayClient(
    getenv('IION_API_KEY'),
    getenv('IION_API_SECRET')
);

// Crear orden de cobro
$order = $iionpay->createOrder([
    'reference' => 'ORDER-123',
    '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://tutienda.com/pago-completado',
]);

echo "URL de pago: " . $order['collectUrl'];
echo "ID de orden: " . $order['id'];

// Consultar estado de la orden
$status = $iionpay->getOrder($order['id']);
echo "Estado: " . $status['status']; // PENDING, PROCESSING, COMPLETED, FAILED, EXPIRED

Colección Postman

Importa nuestra especificación OpenAPI en Postman para probar la API rápidamente (Postman → Import → Link, pega la URL del spec):

Importar en Postman
https://pay.iionpay.com/api/openapi.json

Al importar el spec obtienes:

  • Todos los endpoints documentados
  • Ejemplos de request y response
  • Esquemas de request listos para completar

Especificación OpenAPI

La especificación OpenAPI 3.0 de nuestra API está disponible para generar clientes automáticamente:

OpenAPI Spec
https://pay.iionpay.com/api/openapi.json

Puedes usarla con herramientas como:

Contribuir

¿Quieres contribuir con un SDK en tu lenguaje favorito? Contacta a tu representante en iion pay y te ayudaremos a crear una librería oficial.