PHPackages                             quellabs/canvas-payments-xpay - 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. quellabs/canvas-payments-xpay

ActiveLibrary[Payment Processing](/categories/payments)

quellabs/canvas-payments-xpay
=============================

Nexi XPay Global payment gateway integration for the Canvas PHP framework

1.0.3(1mo ago)00MITPHPPHP ^8.3

Since Mar 25Pushed 1mo agoCompare

[ Source](https://github.com/quellabs/canvas-payments-xpay)[ Packagist](https://packagist.org/packages/quellabs/canvas-payments-xpay)[ RSS](/packages/quellabs-canvas-payments-xpay/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (12)Versions (5)Used By (0)

Nexi XPay Global Payment Provider
=================================

[](#nexi-xpay-global-payment-provider)

A Nexi XPay Global payment provider for the Canvas framework. Part of the Canvas payments ecosystem.

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

[](#installation)

```
composer require quellabs/canvas-payments-xpay
```

Architecture
------------

[](#architecture)

This package sits between the Nexi XPay Global JSON API and your application. Your application only ever touches the contracts layer — it never depends on this package directly. `PaymentRouter` (from `quellabs/canvas-payments`) discovers this package automatically via composer metadata and routes payment calls to it.

```
Your Application
      │
      ▼
PaymentRouter               (quellabs/canvas-payments — discovery + routing)
      │
      ▼
PaymentInterface            (quellabs/canvas-payments-contracts)
      │
      ▼
XPay Driver                 (this package — implements the interface)
      │
      ▼
XPayGateway                 (raw XPay JSON API calls)

```

Push processing is decoupled from your application via signals. When XPay posts to the push URL, the package emits a `payment_exchange` signal carrying a `PaymentState`. Your application listens for that signal and handles it.

Configuration
-------------

[](#configuration)

Create `config/xpay.php` in your Canvas application (done automatically on first install):

```
return [
    'api_key'           => '',
    'return_url'        => 'https://example.com/order/thankyou',
    'return_url_cancel' => 'https://example.com/order/cancelled',
    'return_url_error'  => 'https://example.com/order/error',
    'webhook_url'       => 'https://example.com/webhooks/xpay',
    'default_language'  => 'ENG',
];
```

KeyRequiredDescription`api_key`YesYour XPay API key. Generate in Back Office under Admin > APIKey > Add new APIKey.`return_url`YesURL the shopper is redirected to after a completed or pending payment`return_url_cancel`YesURL the shopper is redirected to after cancelling payment`return_url_error`NoURL for technical errors during payment. Falls back to `return_url_cancel` if empty`webhook_url`YesFull URL XPay POSTs push notifications to. Must be publicly reachable`default_language`No3-letter language code for the hosted page (ENG, ITA, DEU, FRA…). Defaults to `ENG`Payment modules
---------------

[](#payment-modules)

ModuleDescription`xpay`All payment methods enabled on the terminal`xpay_cards`Credit/debit cards only`xpay_applepay`Apple Pay`xpay_googlepay`Google Pay`xpay_paypal`PayPal`xpay_mybank`MyBank (EU bank transfers)`xpay_bancomatpay`Bancomat Pay (Italian debit scheme)`xpay_klarna`Klarna`xpay_alipay`Alipay`xpay_wechatpay`WeChat PayPayment methods must be enabled on your terminal in the XPay Back Office before use.

Usage
-----

[](#usage)

### Initiating a payment

[](#initiating-a-payment)

```
use Quellabs\Payments\Contracts\PaymentInterface;
use Quellabs\Canvas\Controllers\BaseController;
use Quellabs\Payments\Contracts\PaymentRequest;
use Quellabs\Payments\Contracts\PaymentInitiationException;

class CheckoutController extends BaseController {

    public function __construct(private PaymentInterface $router) {}

    /**
     * @Route("...")
     */
    public function checkout(): Response {
        $request = new PaymentRequest(
            paymentModule: 'xpay_cards',
            amount:        999,         // in minor units — €9.99
            currency:      'EUR',
            description:   'Order #12345',
            reference:     'ORDER-12345',
        );

        try {
            $result = $this->router->initiate($request);
            return $this->redirect($result->redirectUrl);
        } catch (PaymentInitiationException $e) {
            // handle error
        }
    }
}
```

### Handling refunds

[](#handling-refunds)

```
use Quellabs\Payments\Contracts\RefundRequest;
use Quellabs\Payments\Contracts\PaymentRefundException;

// Full refund (omit amount)
$request = new RefundRequest(
    paymentReference: $state->transactionId,
    paymentModule:    'xpay_cards',
    amount:           null,
    currency:         'EUR',
    description:      'Full refund for order #12345',
);

// Partial refund
$request = new RefundRequest(
    paymentReference: $state->transactionId,
    paymentModule:    'xpay_cards',
    amount:           500, // in minor units — €5.00
    currency:         'EUR',
    description:      'Partial refund for order #12345',
);

try {
    $result = $this->router->refund($request);
    echo $result->refundId;
} catch (PaymentRefundException $e) {
    // handle error
}
```

### Listening for payment state changes

[](#listening-for-payment-state-changes)

```
use Quellabs\Canvas\Annotations\ListenTo;
use Quellabs\Payments\Contracts\PaymentState;
use Quellabs\Payments\Contracts\PaymentStatus;

class OrderService {

    /**
     * @ListenTo("payment_exchange")
     */
    public function onPaymentExchange(PaymentState $state): void {
        match ($state->state) {
            PaymentStatus::Paid     => $this->markPaid($state->transactionId, $state->valuePaid),
            PaymentStatus::Canceled => $this->markCanceled($state->transactionId),
            PaymentStatus::Refunded => $this->handleRefund($state),
            PaymentStatus::Failed   => $this->markFailed($state->transactionId),
            default                 => null,
        };
    }
}
```

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance93

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

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

Total

4

Last Release

34d ago

PHP version history (2 changes)1.0.0PHP ^8.2

1.0.1PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/57e4ab872b3e37536367f2d26b192df3d3bb6a6a1cebec9a104d14a6d2ffe157?d=identicon)[noescom](/maintainers/noescom)

---

Tags

paymentscanvaspayment gatewayEuropenexixpaycanvas-payments

### Embed Badge

![Health badge](/badges/quellabs-canvas-payments-xpay/health.svg)

```
[![Health](https://phpackages.com/badges/quellabs-canvas-payments-xpay/health.svg)](https://phpackages.com/packages/quellabs-canvas-payments-xpay)
```

PHPackages © 2026

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