README

Xoldy Payment Gateway integration for Laravel applications.

The package provides a small, fluent API for authenticating with Xoldy/LisaPay, creating payment checkouts, checking or cancelling carts, downloading receipts, and receiving webhooks.

Requirements

PHP 8.2 or newer
Laravel 12 or newer
A Xoldy/LisaPay account and API credentials

Installation

Install the package with Composer:

composer require antworks/xoldy

The service provider and Xoldy facade are registered automatically by Laravel's package discovery.

Publish the configuration file when you need to customize the defaults:

php artisan vendor:publish --tag=xoldy

Configuration

Add the following values to your application's .env file. The exact values are supplied by Xoldy/LisaPay for your environment.

XOLDY_CLIENT_ID=your-client-id
XOLDY_CLIENT_SECRET=your-client-secret
XOLDY_GRANT_TYPE=password
XOLDY_USERNAME=your-username
XOLDY_PASSWORD=your-password

XOLDY_BASE_URL=https://dev.lisapay.it
XOLDY_LOGIN_PATH=https://login-dev.lisapay.it
XOLDY_REALM=your-realm
XOLDY_CODE=LIC
XOLDY_PREFIX=your-prefix
XOLDY_XOLDY_CODE=your-xoldy-code

Keep credentials in environment variables and do not commit them to source control. The complete list of options is available in config/xoldy.php, including HTTP timeout/retry settings, payment method codes, receipt filenames, and webhook settings.

Creating a checkout

Build a checkout with the Xoldy facade. reference, email, and a payment method are required before calling create() (or its alias, charge()).

use AntWorks\Xoldy\Facades\Xoldy;

$item = Xoldy::item(
    code: 'PRODUCT-001',
    amount: 29.90,
    description: 'Example product',
    externalId: 'order-line-1',
);

$response = Xoldy::checkout($item)
    ->reference('order-123')
    ->email('customer@example.com')
    ->creditCard()
    ->description('Order 123')
    ->returnUrls(
        successUrl: route('checkout.success'),
        failureUrl: route('checkout.failure'),
    )
    ->externalId('order-123')
    ->create();

For multiple items, use Xoldy::items() or pass an array of XoldyItem instances:

$items = Xoldy::items(
    Xoldy::item('PRODUCT-001', 29.90, 'Example product'),
    Xoldy::item('SHIPPING', 5.00, 'Shipping'),
);

$response = Xoldy::checkout($items)
    ->reference('order-123')
    ->email('customer@example.com')
    ->bankTransfer()
    ->create();

Available checkout options include fiscalCode(), residenceAddress(), receipt(), withoutReceipt(), posId(), callbackUrl(), callbackParameters(), expirationDate(), and xInfo().

Authentication

Authentication is normally handled automatically when a checkout, cart, or receipt request is made. To authenticate explicitly:

$token = Xoldy::authenticate();

Tokens are cached when Laravel's cache service is available and refreshed automatically after an unauthorized response.

Cart status and cancellation

Use the cart hash returned by the checkout API:

$status = Xoldy::status($cartHash);
$cancelled = Xoldy::cancel($cartHash);

Receipts

Retrieve a receipt as a PDF response or save it to disk:

$download = Xoldy::receipt($cartHash)->download();

Xoldy::receipt($cartHash)->store(storage_path('app/receipts/order-123.pdf'));

You can override the download filename with download('order-123.pdf'). The default is configured by XOLDY_RECEIPT_FILENAME.

Webhooks

Webhooks are enabled by default at:

POST /webhook/xoldy

The route dispatches AntWorks\Xoldy\Events\XoldyWebhookReceived with the incoming Laravel request. Listen for the event in your application:

use Illuminate\Support\Facades\Event;
use AntWorks\Xoldy\Events\XoldyWebhookReceived;

Event::listen(XoldyWebhookReceived::class, function (XoldyWebhookReceived $event): void {
    $payload = $event->request->all();

    // Update the related order or payment here.
});

To restrict webhook requests by source IP, set a comma-separated allowlist:

XOLDY_WEBHOOK_ALLOWED_IPS=203.0.113.10,203.0.113.11

Set XOLDY_WEBHOOK_ENABLED=false to disable the package route. You may also customize XOLDY_WEBHOOK_PATH, XOLDY_WEBHOOK_ROUTE_NAME, and the middleware in the published configuration.

Payment methods

The built-in methods are:

Xoldy::creditCard() — CREDITCARD
Xoldy::bankTransfer() — FBKR2P

The values can be changed in config/xoldy.php if the provider supplies different codes.

Error handling

Validation errors throw InvalidArgumentException. HTTP and connection failures are surfaced through Laravel's HTTP client exceptions (RequestException and ConnectionException). Requests retry connection failures, HTTP 429 responses, and server errors according to the configured retry settings.

Contributing

Contributions, bug reports, and pull requests are welcome. Please keep changes focused and follow the existing PSR-12-compatible style.

License

Xoldy Laravel is open-sourced software licensed under the MIT license.

antworks / xoldy

Maintainers

Package info

Statistics

Security