PHPackages                             nanonulla/xoldy-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. nanonulla/xoldy-laravel

ActiveLibrary

nanonulla/xoldy-laravel
=======================

Xoldy Payment Gateway Integration for Laravel

1.3.2(yesterday)01↑2900%MITPHPPHP ^8.2

Since Jul 27Pushed yesterdayCompare

[ Source](https://github.com/NanoNulla/laravel-xoldy)[ Packagist](https://packagist.org/packages/nanonulla/xoldy-laravel)[ RSS](/packages/nanonulla-xoldy-laravel/feed)WikiDiscussions v1.x Synced today

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Xoldy Laravel
=============

[](#xoldy-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3b1625e87065be59b96e748e05355118d02b5051eb6c128ff5d5aff11648d96e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e616e6f6e756c6c612f786f6c64792d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nanonulla/xoldy-laravel)[![Total Downloads](https://camo.githubusercontent.com/b24e5c82e97fa90509b7e1c3e630b21ebdb96e85adfc986a884777e0e1c57b98/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e616e6f6e756c6c612f786f6c64792d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nanonulla/xoldy-laravel)[![License](https://camo.githubusercontent.com/942e017bf0672002dd32a857c95d66f28c5900ab541838c6c664442516309c8a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE)

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
------------

[](#requirements)

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

Installation
------------

[](#installation)

Install the package with Composer:

```
composer require nanonulla/xoldy-laravel
```

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
-------------

[](#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`](config/xoldy.php), including HTTP timeout/retry settings, payment method codes, receipt filenames, and webhook settings.

Creating a checkout
-------------------

[](#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 NanoNulla\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)

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
----------------------------

[](#cart-status-and-cancellation)

Use the cart hash returned by the checkout API:

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

Receipts
--------

[](#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)

Webhooks are enabled by default at:

```
POST /webhook/xoldy

```

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

```
use Illuminate\Support\Facades\Event;
use NanoNulla\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
---------------

[](#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
--------------

[](#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
------------

[](#contributing)

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

License
-------

[](#license)

Xoldy Laravel is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

1d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/21290137?v=4)[Hamid Afghan](/maintainers/NanoNulla)[@NanoNulla](https://github.com/NanoNulla)

---

Top Contributors

[![NanoNulla](https://avatars.githubusercontent.com/u/21290137?v=4)](https://github.com/NanoNulla "NanoNulla (2 commits)")

### Embed Badge

![Health badge](/badges/nanonulla-xoldy-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/nanonulla-xoldy-laravel/health.svg)](https://phpackages.com/packages/nanonulla-xoldy-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M348](/packages/psalm-plugin-laravel)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M137](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M134](/packages/roots-acorn)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45444.2k1](/packages/pressbooks-pressbooks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)