README

El SDK de iPagos para PHP proporciona una interfaz orientada a objetos, robusta y fácil de usar para integrar los servicios de procesamiento de pagos de iPagos (basados en la infraestructura de CyberSource) en tu aplicación PHP. Diseñado aprovechando las características modernas de PHP 8.2 (como clases readonly y enums), garantiza un tipado estricto, una mayor seguridad en las transacciones y un rendimiento óptimo.

Instalación

Puedes instalar el SDK mediante Composer ejecutando el siguiente comando:

composer require ipagos/php-sdk

Nota: Si el repositorio donde se aloja el SDK es privado, asegúrate de añadir la configuración correspondiente en la sección repositories de tu archivo composer.json e incluir tus credenciales o token de acceso.

Configuración Inicial

Para comenzar a interactuar con la API, necesitas instanciar el cliente IpagosClient utilizando un objeto de configuración IpagosConfig y especificando el entorno (Sandbox o Producción).

<?php

require 'vendor/autoload.php';

use Ipagos\Sdk\Client\IpagosClient;
use Ipagos\Sdk\DTO\IpagosConfig;
use Ipagos\Sdk\Config\IpagosEnvironment;

$config = new IpagosConfig(
    merchantId: 'tu_merchant_id',
    merchantKeyId: 'tu_merchant_key_id',
    merchantSecretKey: 'tu_merchant_secret_key'
);

$client = new IpagosClient($config, IpagosEnvironment::SANDBOX->value);

Módulos Principales

Pagos

Permite realizar transacciones, como crear un pago o una autorización de forma sencilla.

<?php

use Ipagos\Sdk\Models\Payment\CreatePaymentRequest;

$request = new CreatePaymentRequest([
    'clientReferenceInformation' => [
        'code' => 'ORD-12345'
    ],
    // Otros campos necesarios para procesar el pago...
]);

try {
    $response = $client->createPayment($request);
    echo "ID del Pago: " . $response->getId();
} catch (\Exception $e) {
    echo "Error procesando el pago: " . $e->getMessage();
}

Tokenización

Genera un token seguro para los datos de pago, reduciendo el alcance de cumplimiento PCI DSS.

<?php

use Ipagos\Sdk\Models\Tms\TokenizeRequest;

$tokenizeRequest = new TokenizeRequest([
    // Detalles del instrumento a tokenizar...
]);

try {
    $response = $client->tokenize($tokenizeRequest);
    echo "Token generado con éxito: " . $response->getTokenId();
} catch (\Exception $e) {
    echo "Error al tokenizar: " . $e->getMessage();
}

Reportes

Consulta y extrae reportes transaccionales y notificaciones de cambios de estado.

<?php

try {
    // Especifica los parámetros para obtener las notificaciones de cambios
    $startTime = '2026-03-01T00:00:00Z';
    $endTime = '2026-03-24T23:59:59Z';
    
    $response = $client->getNotificationOfChanges($startTime, $endTime);
    print_r($response);
} catch (\Exception $e) {
    echo "Error obteniendo el reporte: " . $e->getMessage();
}

Manejo de Excepciones

El SDK lanza excepciones específicas para un mejor manejo y depuración de errores. Todas heredan de la clase base Ipagos\Sdk\Common\Exceptions\IpagosException.

Estructura de Carpetas

La arquitectura de este SDK está organizada de la siguiente manera:

src/
├── Client/         # Cliente principal de la API (IpagosClient)
├── Common/         # Componentes transversales
│   ├── Authentication/ # Firmas y seguridad de las peticiones
│   ├── Exceptions/     # Excepciones personalizadas para el SDK
│   └── Http/           # Middlewares y clientes HTTP
├── Config/         # Configuraciones generales (ej. IpagosEnvironment)
├── DTO/            # Objetos de transferencia de datos (ej. IpagosConfig)
├── Models/         # Clases de Dominio (Requests) agrupadas por módulo
│   ├── Auth/       # Modelos para autenticación
│   ├── Payment/    # Modelos para pagos y transacciones
│   ├── Reporting/  # Modelos para extracción de reportes
│   ├── Tms/        # Modelos de tokenización e instrumentos de pago
│   └── ...         # Otros submódulos de la API
└── Response/       # Estructura genérica para procesar las respuestas

Soporte

Si tienes dudas, problemas durante la integración o necesitas ayuda adicional, por favor contacta a nuestro equipo de soporte enviando un correo a: integraciones@ipagos.lat.