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:
- OpenAPI Generator - Genera clientes en 50+ lenguajes
- Swagger Codegen - Generador de código oficial de Swagger
- openapi-typescript-codegen - Para TypeScript
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.