README

Bienvenido/a a Dpago! Esta librería fue creada para facilitar los pagos a través de la plataforma Dpago, ofreciendo una interfaz sencilla y conveniente para interactuar con sus servicios de pago.

Descripción

Dpago es una plataforma de pagos en línea que permite a los comercios procesar transacciones de manera segura y confiable. Esta librería proporciona una serie de funciones y métodos para interactuar con la API de Dpago y realizar operaciones como crear transacciones, links de pago y más.

Documentación

Para obtener información detallada sobre cómo utilizar la Dpago, consulta nuestra documentación oficial en https://docs.dpago.com. La documentación proporciona ejemplos, guías y detalles sobre cada función disponible en la librería, lo que te permitirá integrar fácilmente la plataforma Dpago en tus proyectos.

Instalación

Para utilizar esta librería en tu proyecto, simplemente ejecuta el siguiente comando:

composer require tecnolab-sa/dpago-php

Como usar

Para comenzar a utilizar es necesario estar registrado en Dpago y tener uno o mas comercios habilitados y verificados.

Primero inicializá la librería con el ID y el token del comercio:

<?php

require __DIR__ . '/vendor/autoload.php';

use Dpago\Dpago;

$commerceId = 123;
$commerceToken = 'tu-token-del-comercio';

$dpago = new Dpago($commerceId, $commerceToken);

Todos los métodos devuelven un arreglo con la respuesta de Dpago. Si ocurre un error de conexión, una respuesta inválida o un error de la API, la librería devuelve un arreglo con la clave error.

if (!empty($response['error'])) {
    echo $response['error'];
}

Obtener plataformas habilitadas

Usá platforms->get() o listPlatforms() para consultar los medios de pago disponibles para el comercio.

$platforms = $dpago->platforms->get();
// También:
$platforms = $dpago->listPlatforms();

foreach ($platforms as $platform) {
    echo $platform['id'] . ' - ' . $platform['name'] . PHP_EOL;
}

El id de la plataforma es el valor que se usa como platformId al crear una transacción.

Crear un link de pago

Usá link->create() cuando quieras generar un link de pago para cobrar un monto.

$link = $dpago->link->create(
    150000,
    'Compra #1234',
    'PYG'
);

if (!empty($link['redirectUrl'])) {
    echo $link['redirectUrl'];
}

También podés usar el alias por arreglo createPaymentLink():

$link = $dpago->createPaymentLink([
    'amount' => 150000,
    'description' => 'Compra #1234',
    'currency' => 'PYG',
]);

Parámetros:

• amount: monto a cobrar.
• description: descripción que verá el cliente.
• currency: moneda. Por defecto es PYG.

Respuesta esperada:

[
    'redirectUrl' => 'https://pago.dpago.com/link/...',
    'reference' => '...',
]

Crear una transacción común

Usá transactions->create() cuando ya conocés la plataforma de pago que querés usar. Antes podés llamar a platforms->get() para obtener el platformId correcto.

$payment = $dpago->transactions->create(
    150000,
    'Compra #1234',
    'ORD-1234',
    18,
    false,
    'PYG',
    [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ]
);

if (!empty($payment['redirectUrl'])) {
    header('Location: ' . $payment['redirectUrl']);
    exit;
}

echo $payment['error'] ?? 'No se pudo crear el pago.';

También podés usar el alias por arreglo createTransaction():

$payment = $dpago->createTransaction([
    'amount' => 150000,
    'description' => 'Compra #1234',
    'reference' => 'ORD-1234',
    'platformId' => 18,
    'withInvoice' => false,
    'customer' => [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ],
]);

Parámetros:

• amount: monto a cobrar.
• description: descripción del pago.
• reference: referencia única creada por tu comercio, por ejemplo el ID de orden.
• platformId: ID del medio de pago.
• withInvoice: true si se solicitará factura, false si no.
• customer: datos del cliente con name, email, phone e identification.

Crear una transacción QR Upay

El helper createUpayQr permite enviar el monto y los datos del cliente para obtener una URL directa a la pantalla del QR de Upay. Así el cliente no tiene que rellenar nombre, correo, teléfono ni identificación.

$payment = $dpago->transactions->createUpayQr(
    150000,
    'Compra #1234',
    'ORD-1234',
    [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ]
);

if (!empty($payment['redirectUrl'])) {
    header('Location: ' . $payment['redirectUrl']);
    exit;
}

echo $payment['error'] ?? 'No se pudo crear el pago.';

Parámetros:

• amount: monto a cobrar.
• description: descripción del pago.
• reference: referencia única creada por tu comercio.
• customer: datos del cliente con name, email, phone e identification.
• options: arreglo opcional con platformId y withInvoice.

Si querés que la librería haga la redirección automáticamente, podés usar:

$dpago->transactions->redirectToUpayQr(
    150000,
    'Compra #1234',
    'ORD-1234',
    [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ]
);

redirectToUpayQr() envía el header Location y termina la ejecución con exit. Si necesitás que devuelva la respuesta sin cortar el script, pasá ['exit' => false] en las opciones.

$payment = $dpago->transactions->redirectToUpayQr(
    150000,
    'Compra #1234',
    'ORD-1234',
    [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ],
    ['exit' => false]
);

También podés enviar todos los datos en un solo arreglo:

$payment = $dpago->transactions->createUpayQrFromArray([
    'amount' => 150000,
    'description' => 'Compra #1234',
    'reference' => 'ORD-1234',
    'customer' => [
        'name' => 'Juan Perez',
        'email' => 'juan@example.com',
        'phone' => '0981123456',
        'identification' => '1234567',
    ],
    'withInvoice' => false,
]);

Este formato es cómodo cuando armás el pago desde un formulario o desde un checkout externo.

Por defecto se usa la plataforma qr ueno/Upay QR (platformId 18) y withInvoice en false. Si necesitás cambiarlo:

$payment = $dpago->transactions->createUpayQr(
    150000,
    'Compra #1234',
    'ORD-1234',
    $customer,
    [
        'platformId' => 18,
        'withInvoice' => false,
    ]
);

Desarrollo y pruebas

La librería incluye un entorno Docker para correr las verificaciones sin instalar PHP ni Composer en tu máquina:

docker compose run --rm test

Ese comando instala dependencias, valida Composer, ejecuta lint de PHP, corre PHPUnit y revisa auditoría de dependencias.

También podés correr los comandos dentro del contenedor:

docker compose run --rm test composer test
docker compose run --rm test composer test:coverage
docker compose run --rm test composer lint
docker compose run --rm test composer check

Antes de publicar una versión en Packagist, corré composer check, actualizá CHANGELOG.md y creá un tag SemVer como v1.1.0.

Contribuciones

Si encuentras algún problema o tienes alguna sugerencia de mejora, ¡estamos abiertos a recibir contribuciones! Siéntete libre de abrir un "issue" o enviar un "merge request" en nuestro repositorio en GitLab.

License

MIT