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

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

quellabs/canvas-payments-contracts
==================================

Payment gateway contracts and interfaces for the Canvas PHP framework

1.0.9(1mo ago)0211MITPHPPHP ^8.2

Since Mar 17Pushed 1mo agoCompare

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

READMEChangelogDependencies (3)Versions (11)Used By (11)

Canvas Payments Contracts
=========================

[](#canvas-payments-contracts)

Shared contracts for the Canvas payments ecosystem. Contains the interfaces and value objects that connect payment provider packages to your application.

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

[](#installation)

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

What's in this package
----------------------

[](#whats-in-this-package)

Class / InterfaceDescription`PaymentInterface`Interface for application code — exposes `initiate`, `refund`, `getRefunds`, `getPaymentOptions``PaymentProviderInterface`Interface all driver packages must implement — extends `PaymentInterface`, adds discovery methods`PaymentRequest`Input for initiating a payment`InitiateResult`Result of a successful payment initiation`PaymentState`Payment snapshot delivered via the `payment_exchange` signal`PaymentStatus`Enum of possible payment states`RefundRequest`Input for issuing a refund`RefundResult`Result of a successful refund`PaymentAddress`Billing or shipping address attached to a payment`PaymentException`Base exception for all payment failures`PaymentInitiationException`Thrown when `initiate()` fails`PaymentRefundException`Thrown when `refund()` or `getRefunds()` fails`PaymentExchangeException`Thrown internally by the controller layerAll amounts are in minor units (e.g. `999` for €9.99). All classes are in the `Quellabs\Payments\Contracts` namespace.

Usage
-----

[](#usage)

```
use Quellabs\Payments\Contracts\PaymentInterface;
use Quellabs\Payments\Contracts\PaymentRequest;
use Quellabs\Payments\Contracts\PaymentInitiationException;

class CheckoutService {
    public function __construct(private PaymentInterface $payment) {}

    public function pay(): string {
        try {
            $result = $this->payment->initiate(new PaymentRequest(
                paymentModule: 'mollie_ideal',
                amount:        999,
                currency:      'EUR',
                description:   'Order #12345',
            ));

            return $result->redirectUrl;
        } catch (PaymentInitiationException $e) {
            // handle error
        }
    }
}
```

PaymentState
------------

[](#paymentstate)

`PaymentState` is an immutable snapshot of a payment's current status. Your application receives it by subscribing to the `payment_exchange` signal, which is emitted by the controller layer after a return URL visit or webhook.

PropertyTypeDescription`$provider``string`Provider identifier, e.g. `'mollie'`, `'paypal'``$transactionId``string`Provider's unique identifier for this payment`$state``PaymentStatus`Normalised payment status`$currency``string`ISO 4217 currency code, e.g. `'EUR'``$valuePaid``int`Amount actually captured, in minor units. `0` if not yet paid`$valueRefunded``int`Total amount refunded so far, in minor units`$internalState``?string`Raw status string from the provider, before normalisation`$metadata``array`Provider-specific data, e.g. `captureId` required for refunds`$valuePaid` is only non-zero when `$state` is `PaymentStatus::Paid` or `PaymentStatus::Refunded`. For all other states — including `Pending` — it is `0`. Use `$state` to determine whether funds have actually moved, and `$valuePaid` to know how much.

To issue a refund after a successful payment, persist `$metadata['paymentReference']` from the `PaymentState` — it is required as `RefundRequest::$paymentReference`.

Exceptions
----------

[](#exceptions)

All exceptions extend `PaymentException`, which exposes `getProvider(): string` and `getErrorId(): int`. Catch the base class to handle any payment failure, or catch a specific subclass to handle a particular operation.

```
use Quellabs\Payments\Contracts\PaymentException;
use Quellabs\Payments\Contracts\PaymentInitiationException;
use Quellabs\Payments\Contracts\PaymentRefundException;

// Catch all payment failures
} catch (PaymentException $e) {
    $e->getProvider();  // e.g. 'mollie'
    $e->getErrorId();   // provider error ID
    $e->getMessage();   // human-readable message
}

// Or catch specific failures
} catch (PaymentInitiationException $e) { ... }  // initiate() failed
} catch (PaymentRefundException $e) { ... }      // refund() or getRefunds() failed
```

PaymentStatus values
--------------------

[](#paymentstatus-values)

CaseDescription`PaymentStatus::Pending`Payment is open or pending`PaymentStatus::Paid`Payment completed successfully`PaymentStatus::Canceled`Customer canceled — definitive`PaymentStatus::Expired`Customer abandoned, or bank transfer timed out`PaymentStatus::Failed`Payment failed and cannot be retried`PaymentStatus::Refunded`Payment was refunded`PaymentStatus::Redirect`Redirect user back to provider. Internally handled.`PaymentStatus::Unknown`Unrecognised status from providerLicense
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance93

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity53

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

Recently: every ~16 days

Total

10

Last Release

35d ago

### Community

Maintainers

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

---

Tags

interfacescontractsabstractionspaymentscanvascanvas-payments

### Embed Badge

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

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

###  Alternatives

[symfony/translation-contracts

Generic abstractions related to translation

2.6k730.8M602](/packages/symfony-translation-contracts)[symfony/cache-contracts

Generic abstractions related to caching

2.4k324.3M287](/packages/symfony-cache-contracts)[symfony/http-client-contracts

Generic abstractions related to HTTP clients

2.0k419.3M387](/packages/symfony-http-client-contracts)[symfony/contracts

A set of abstractions extracted out of the Symfony components

3.9k65.5M127](/packages/symfony-contracts)

PHPackages © 2026

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