Download the PHP package quellabs/canvas-payments-paypal without Composer

PayPal Payment Provider

A PayPal payment provider for the Canvas framework. Part of the Canvas payments ecosystem. Implements the modern PayPal Orders v2 REST API with webhook-based payment notifications.

Installation

Architecture

This package sits between the PayPal REST 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.

Webhook processing is decoupled from your application via signals. When PayPal sends a webhook notification, the package emits a payment_exchange signal carrying a PaymentState. Your application listens for that signal and handles it. The buyer return URL works the same way — both the return and cancel cases are handled by the same route and emit the same signal, so your application does not need to distinguish between them at the routing level.

Configuration

Create config/paypal.php in your Canvas application:

Usage

Initiating a payment

Inject PaymentInterface via Canvas DI and call initiate():

Handling refunds

Pass amount: null for a full refund, or a minor-unit integer for a partial refund.

When your payment_exchange listener receives a PaymentStatus::Paid state, store $state->metadata['paymentReference'] — you'll need it as RefundRequest::$paymentReference.

Listening for payment state changes

PayPal-specific quirks

Two transaction identifiers

PayPal uses two different identifiers across the payment lifecycle:

• Order ID — created by POST /v2/checkout/orders and returned by initiate() as InitiateResult::$transactionId. Used to drive the checkout flow and passed to exchange().
• Capture ID — available in PaymentState::$metadata['paymentReference'] when a PaymentStatus::Paid event fires. Persist this value — it is required as RefundRequest::$paymentReference for refunds and getRefunds().

Webhooks vs. return URL

PayPal notifies your application of payment state changes in two independent ways:

• Webhooks — a server-to-server POST from PayPal to webhook_url, verified by cryptographic signature. This is the authoritative source of truth and may arrive before or after the buyer returns to your site. Only PAYMENT.CAPTURE.* events trigger a signal; all other event types are acknowledged and ignored.
• Return URL — a browser redirect after the buyer completes or cancels at PayPal.

Both routes call exchange() and emit the payment_exchange signal. Your application should be idempotent when handling this signal, as it may fire twice for the same transaction.

Webhook setup

Register your webhook_url in the PayPal Developer Dashboard under Apps & Credentials → your app → Webhooks. Subscribe at minimum to these event types:

• PAYMENT.CAPTURE.COMPLETED
• PAYMENT.CAPTURE.DENIED
• PAYMENT.CAPTURE.REFUNDED
• PAYMENT.CAPTURE.REVERSED

Copy the resulting Webhook ID into your config/paypal.php as webhook_id. Without it, all webhook notifications will be rejected.

Refund type determination

Pass amount: null to RefundRequest for a full refund. The driver omits the amount field from the API request, which causes PayPal to refund the full captured amount internally. Pass a minor-unit integer for a partial refund. Do not attempt to calculate the refundable amount yourself and pass it as a full refund — use null instead.

License

MIT