PHPackages                             hval/nexi-php - 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. [PSR & Standards](/categories/psr-standards)
4. /
5. hval/nexi-php

ActiveLibrary[PSR & Standards](/categories/psr-standards)

hval/nexi-php
=============

Unofficial PHP library for the Nexi XPay payment gateway: HPP, Pay-by-Link, recurring contracts, operations and webhooks

1.2.0(1mo ago)2127↓65.6%MITPHPPHP >=7.2CI passing

Since Apr 26Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/hvallieri/nexi-php)[ Packagist](https://packagist.org/packages/hval/nexi-php)[ RSS](/packages/hval-nexi-php/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (8)Dependencies (12)Versions (8)Used By (0)

hval/nexi-php
=============

[](#hvalnexi-php)

Unofficial PHP library for the [Nexi XPay](https://developer.nexigroup.com/) payment gateway: Hosted Payment Page (HPP), Pay-by-Link, recurring contracts, operations and webhooks.

Requirements
------------

[](#requirements)

- PHP >= 7.2
- Any PSR-18 compatible HTTP client (e.g. `guzzlehttp/guzzle`, `symfony/http-client`)
- A PSR-7 / PSR-17 implementation (e.g. `nyholm/psr7`, `guzzlehttp/psr7`)

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

[](#installation)

```
composer require hval/nexi-php
```

Install a PSR-18 client if you don't already have one:

```
# Guzzle
composer require guzzlehttp/guzzle

# Symfony HttpClient
composer require symfony/http-client nyholm/psr7
```

Quick Start
-----------

[](#quick-start)

### 1. Instantiate the client

[](#1-instantiate-the-client)

**With Guzzle:**

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory as GuzzleFactory;
use Hval\Nexi\Http\HttpFactory;
use Hval\Nexi\NexiClient;

$guzzle  = new GuzzleFactory();
$factory = new HttpFactory($guzzle, $guzzle);

$nexi = new NexiClient('your-api-key', NexiClient::ENV_SANDBOX, new Client(), $factory);
```

**With Symfony HttpClient:**

```
use Hval\Nexi\Http\HttpFactory;
use Hval\Nexi\NexiClient;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$psr17   = new Psr17Factory();
$factory = new HttpFactory($psr17, $psr17);

$nexi = new NexiClient('your-api-key', NexiClient::ENV_SANDBOX, new Psr18Client(), $factory);
```

### 2. Create an order (HPP flow)

[](#2-create-an-order-hpp-flow)

```
use Hval\Nexi\Model\Request\Order;
use Hval\Nexi\Model\Request\PaymentSession;

$order   = new Order('ORDER-001', '1000', 'EUR'); // 10.00 EUR
$session = new PaymentSession(
    PaymentSession::ACTION_PAY,
    '1000',
    'ita',
    'https://yoursite.com/payment/result',
    'https://yoursite.com/payment/cancel'
);

$response = $nexi->orders()->createHpp($order, $session);

// Save the securityToken in your DB linked to the order
$_SESSION['nexi_token'] = $response->getSecurityToken();

// Redirect the user
header('Location: ' . $response->getHostedPage());
```

To attach customer details, pass a `CustomerInfo` object:

```
use Hval\Nexi\Model\Request\Address;
use Hval\Nexi\Model\Request\CustomerInfo;
use Hval\Nexi\Model\Request\Order;

$billing = new Address('Mario Rossi', 'Via Roma 1', 'Milano', '20100', 'ITA');

$customerInfo = new CustomerInfo(
    'Mario Rossi',
    'mario@example.com',
    $billing,
    null,   // shippingAddress
    '39',   // mobilePhoneCountryCode
    '3331234567'
);

$order = new Order('ORDER-001', '1000', 'EUR', null, null, null, $customerInfo);
```

### 3. Handle the webhook

[](#3-handle-the-webhook)

```
use Hval\Nexi\Exception\WebhookSignatureException;

$payload    = file_get_contents('php://input');
$savedToken = '...'; // retrieved from your DB

try {
    $notification = $nexi->webhooks()->handle($payload, $savedToken);

    if ($notification->isAuthorized()) {
        // Fetch the full order to confirm server-side
        $order = $nexi->orders()->find($notification->getOrderId());

        if ($order->isAuthorized()) {
            // Order confirmed — use $notification->getOperationId() for
            // subsequent refund / capture operations
        }
    }
} catch (WebhookSignatureException $e) {
    http_response_code(400);
    exit;
}
```

### 4. Refund, capture, cancel

[](#4-refund-capture-cancel)

Pass the `operationId` from the webhook notification (or from `OrderResponse::getOperations()`):

```
use Hval\Nexi\Model\Request\CancelRequest;
use Hval\Nexi\Model\Request\CaptureRequest;
use Hval\Nexi\Model\Request\RefundRequest;

$operationId = $notification->getOperationId();

// Partial refund / capture — amount in cents as string, currency required
$result = $nexi->operations()->refund($operationId, new RefundRequest('1000', 'EUR'));
$result = $nexi->operations()->capture($operationId, new CaptureRequest('1000', 'EUR'));

// Full refund / capture — omit amount and currency
$result = $nexi->operations()->refund($operationId, new RefundRequest());
$result = $nexi->operations()->capture($operationId, new CaptureRequest());

$result = $nexi->operations()->cancel($operationId, new CancelRequest());

// Optionally pass your own idempotency key to make retries safe.
// If omitted, a UUID is generated automatically.
$result = $nexi->operations()->refund($operationId, new RefundRequest('1000', 'EUR'), 'your-uuid-v4');
```

### 5. List orders and operations

[](#5-list-orders-and-operations)

```
// List orders — all parameters are optional
$orders = $nexi->orders()->findAll(
    '2024-01-01T00:00:00.000Z',  // fromTime (ISO 8601)
    '2024-01-31T23:59:59.000Z',  // toTime   (ISO 8601, max 30-day range)
    50,                          // maxRecords (default 20, max 500)
    'promo2024'                  // customField
);

foreach ($orders as $order) {       // array
    $order->getOrderId();           // ?string
    $order->getAmount();            // ?string
    $order->getLastOperationType(); // ?string
}

// List operations — filter by channel or type
$operations = $nexi->operations()->findAll(
    fromTime: null,
    toTime: null,
    maxRecords: null,
    channel: 'ECOMMERCE',           // ECOMMERCE, POS, BACKOFFICE
    operationType: 'AUTHORIZATION'
);

// Retrieve a single operation
$operation = $nexi->operations()->find('operation-id');
$operation->getOperationResult(); // ?string
$operation->getWarnings();        // array
```

### 6. Payment methods

[](#6-payment-methods)

```
$methods = $nexi->paymentMethods()->listAll();

foreach ($methods as $method) {       // array
    $method->getMethodType();         // 'CARD' or 'APM'
    $method->getCircuit();            // 'VISA', 'MC', 'PAYPAL', ...
    $method->getImageLink();          // SVG logo URL
    $method->isRecurringSupported();  // ?bool
    $method->isOneClickSupported();   // ?bool
}
```

### 7. Pay-by-Link

[](#7-pay-by-link)

```
use Hval\Nexi\Model\Request\Order;
use Hval\Nexi\Model\Request\PaymentSession;

$order   = new Order('ORDER-001', '1000', 'EUR');
$session = new PaymentSession(
    PaymentSession::ACTION_PAY,
    '1000',
    'ita',
    'https://yoursite.com/payment/result',
    'https://yoursite.com/payment/cancel'
);

// expirationDate is required (max 90 days, YYYY-MM-DD)
$response = $nexi->payByLink()->create($order, $session, '2024-12-31');

$link = $response->getPaymentLink();
$link->getLinkId();        // ?string — use to cancel the link
$link->getLink();          // ?string — send this URL to the customer
$link->getSecurityToken(); // ?string — save in DB for webhook verification

// Cancel an active link
$nexi->payByLink()->cancel($link->getLinkId());
```

### 8. Recurring contracts

[](#8-recurring-contracts)

```
// Retrieve all contracts for a customer
$response = $nexi->contracts()->findByCustomer('customer-id');

$response->getCustomerId(); // ?string

foreach ($response->getContracts() as $contract) { // array
    $contract->getContractId();            // ?string
    $contract->getContractType();          // MIT_UNSCHEDULED, MIT_SCHEDULED, CIT
    $contract->getPaymentCircuit();        // ?string
    $contract->getPaymentInstrumentInfo(); // ?string
}

// Deactivate a contract
$nexi->contracts()->deactivate('contract-id');
```

### 9. Recurring payments

[](#9-recurring-payments)

Pass a `Recurrence` object as the last argument of `PaymentSession` to set up recurring payments:

```
use Hval\Nexi\Model\Request\PaymentSession;
use Hval\Nexi\Model\Request\Recurrence;

$recurrence = new Recurrence(
    Recurrence::ACTION_CONTRACT_CREATION,
    null,
    Recurrence::CONTRACT_TYPE_MIT_SCHEDULED
);

$session = new PaymentSession(
    PaymentSession::ACTION_PAY,
    '1000',
    'ita',
    'https://yoursite.com/payment/result',
    'https://yoursite.com/payment/cancel',
    null,
    null,
    null,
    null,
    $recurrence
);
```

Available actions: `ACTION_NO_RECURRING`, `ACTION_SUBSEQUENT_PAYMENT`, `ACTION_CONTRACT_CREATION`, `ACTION_CARD_SUBSTITUTION`.

Available contract types: `CONTRACT_TYPE_MIT_UNSCHEDULED`, `CONTRACT_TYPE_MIT_SCHEDULED`, `CONTRACT_TYPE_CIT`.

Response objects
----------------

[](#response-objects)

For the full list of available getters on each response model, see [docs/response-objects.md](docs/response-objects.md).

Exceptions
----------

[](#exceptions)

All exceptions extend `NexiException`, which can be used as a catch-all.

ExceptionWhen`AuthenticationException`401 — invalid API key`InvalidRequestException`400 — malformed request`ApiException`other 4xx / 5xx responses`WebhookSignatureException`security token mismatchRunning Tests
-------------

[](#running-tests)

```
composer install
./vendor/bin/phpunit
```

Credits
-------

[](#credits)

- [Hermann Vallieri](https://github.com/hvallieri)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance89

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

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

Total

8

Last Release

36d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/34038224?v=4)[Hermann Vallieri](/maintainers/hvallieri)[@hvallieri](https://github.com/hvallieri)

---

Top Contributors

[![hvallieri](https://avatars.githubusercontent.com/u/34038224?v=4)](https://github.com/hvallieri "hvallieri (45 commits)")

---

Tags

contractsrecurringwebhookspaymentgatewaynexiHPPhosted payment pagexpaypay by link

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/hval-nexi-php/health.svg)

```
[![Health](https://phpackages.com/badges/hval-nexi-php/health.svg)](https://phpackages.com/packages/hval-nexi-php)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60316.0M89](/packages/mollie-mollie-api-php)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B4.1k](/packages/guzzlehttp-psr7)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36789.4k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

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