README

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

Installation

composer require quellabs/canvas-payments-contracts

What's in this package

All amounts are in minor units (e.g. 999 for €9.99). All classes are in the Quellabs\Payments\Contracts namespace.

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

$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

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

License

MIT