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. [Payment Processing](/categories/payments)
4. /
5. hval/nexi-php

ActiveLibrary[Payment Processing](/categories/payments)

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

PHP library for Nexi XPay payment gateway (Hosted Payment Page)

1.1.2(3w ago)1100↓54.2%MITPHPPHP >=7.2CI passing

Since Apr 26Pushed 3w 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 1w ago

READMEChangelog (7)Dependencies (6)Versions (7)Used By (0)

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

[](#hvalnexi-php)

PHP library for integrating [Nexi XPay](https://developer.nexigroup.com/) via the Hosted Payment Page (HPP) flow.

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',    // cardHolderName
    'mario@example.com', // cardHolderEmail
    $billing,         // billingAddress
    null,             // shippingAddress
    '39',             // mobilePhoneCountryCode
    '3331234567'      // mobilePhone
);

$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);

    // Quick check directly on the notification
    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');
$result = $nexi->operations()->capture($operationId, new CaptureRequest('1000', 'EUR'), 'your-uuid-v4');

// OperationResponse
$result->getOperationId();   // ?string
$result->getOperationTime(); // ?string
```

### 5. Recurring payments

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

### `HppResponse` — `orders()->createHpp()`

[](#hppresponse--orders-createhpp)

MethodReturns`getHostedPage()``?string``getSecurityToken()``?string`### `WebhookNotification` — `webhooks()->handle()`

[](#webhooknotification--webhooks-handle)

MethodReturns`getEventId()``?string``getEventTime()``?string``getSecurityToken()``?string``getOrderId()``?string``getOperationId()``?string``getChannel()``?string``getOperationType()``?string``getOperationResult()``?string``getOperationTime()``?string``getPaymentMethod()``?string``getPaymentCircuit()``?string``getOperationAmount()``?string``getOperationCurrency()``?string``isAuthorized()``bool` — `operationResult === 'AUTHORIZED'``isExecuted()``bool` — `operationResult === 'EXECUTED'``getRaw()``array`### `OrderResponse` — `orders()->find()`

[](#orderresponse--orders-find)

MethodReturns`getOrderId()``?string``getLastOperationResult()``?string``getAuthorizedAmount()``?string``getCapturedAmount()``?string``getLastOperationType()``?string``getLastOperationTime()``?string``getOperations()``array` — raw operation list from the API`isAuthorized()``bool` — last operation result is `AUTHORIZED``isExecuted()``bool` — last operation result is `EXECUTED``getRaw()``array`Available `operationResult` values as constants on `OrderResponse`:

```
OPERATION_RESULT_PENDING · AUTHORIZED · EXECUTED · DECLINED
OPERATION_RESULT_DENIED_BY_RISK · THREEDS_VALIDATED · THREEDS_FAILED
OPERATION_RESULT_CANCELED · VOIDED · REFUNDED · FAILED

```

### `OperationResponse` — `operations()->refund()` / `capture()` / `cancel()`

[](#operationresponse--operations-refund--capture--cancel)

MethodReturns`getOperationId()``?string``getOperationTime()``?string``getRaw()``array`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

39

—

LowBetter than 84% of packages

Maintenance94

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity33

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

Total

7

Last Release

26d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/48244a7c29f7c117f649cddf94beec24e959cb908c063bc20419d138dae588d5?d=identicon)[hvallieri](/maintainers/hvallieri)

---

Top Contributors

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

---

Tags

paymentgatewaynexiHPPhosted payment pagexpay

###  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.2k31.1k11](/packages/tempest-framework)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B3.7k](/packages/guzzlehttp-psr7)[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.

61315.4M74](/packages/mollie-mollie-api-php)[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.

35729.6k2](/packages/telnyx-telnyx-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)

PHPackages © 2026

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