PHPackages quellabs/canvas-payments-buckaroo - 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-buckaroo ActiveLibrary[Payment Processing](/categories/payments) quellabs/canvas-payments-buckaroo ================================= Buckaroo payment gateway integration for the Canvas PHP framework 1.0.8(1mo ago)00MITPHPPHP ^8.2 Since Mar 20Pushed 2w agoCompare [ Source](https://github.com/quellabs/canvas-payments-buckaroo)[ Packagist](https://packagist.org/packages/quellabs/canvas-payments-buckaroo)[ RSS](/packages/quellabs-canvas-payments-buckaroo/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (12)Versions (9)Used By (0) Buckaroo Payment Provider ========================= [](#buckaroo-payment-provider) A Buckaroo payment provider for the Canvas framework. Part of the Canvas payments ecosystem. Installation ------------ [](#installation) ``` composer require quellabs/canvas-payments-buckaroo ``` Architecture ------------ [](#architecture) This package sits between the Buckaroo 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) │ ▼ Buckaroo Driver (this package — implements the interface) │ ▼ BuckarooGateway (raw Buckaroo JSON API calls) ``` Push processing is decoupled from your application via signals. When Buckaroo 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/buckaroo.php` in your Canvas application (this is done automatically on first install): ``` return [ 'website_key' => '', 'secret_key' => '', 'test_mode' => false, 'return_url' => 'https://example.com/order/thankyou', 'return_url_cancel' => 'https://example.com/order/cancelled', 'return_url_error' => 'https://example.com/order/error', 'return_url_reject' => 'https://example.com/order/rejected', 'push_url' => 'https://example.com/webhooks/buckaroo', 'default_culture' => 'nl-NL', ]; ``` KeyRequiredDescription`website_key`YesYour Buckaroo website key, found in Plaza under My Buckaroo > Websites > {your site}`secret_key`YesYour Buckaroo secret key, generated in Plaza under Configuration > Secret Key`test_mode`NoUse the Buckaroo test environment (`testcheckout.buckaroo.nl`). Defaults to `false``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`return_url_reject`NoURL for acquirer-rejected payments. Falls back to `return_url_cancel` if empty`push_url`YesFull URL Buckaroo POSTs push notifications to. Must be publicly reachable`default_culture`NoBCP 47 culture tag for hosted page language and email templates. Defaults to `nl-NL`### Buckaroo Plaza configuration [](#buckaroo-plaza-configuration) In addition to `config/buckaroo.php`, configure the following in [Buckaroo Plaza](https://plaza.buckaroo.nl): - **Push URL**: My Buckaroo > Websites > {your site} > Push Settings — set to your `push_url` value - **Return URLs** are per-request (sent in each transaction); Plaza values serve as fallback only Key differences from MultiSafepay --------------------------------- [](#key-differences-from-multisafepay) ### Authentication [](#authentication) Buckaroo uses HMAC-SHA256 request signing. Every request carries an `Authorization` header: ``` hmac ::: ``` The signing string is: `websiteKey + METHOD + urlencode(host+path, lowercase) + timestamp + nonce + base64(md5(body))` ### Amounts [](#amounts) Buckaroo amounts are **decimal floats** (`10.00` = €10.00), not minor units. The driver converts automatically — `PaymentRequest::$amount` stays in minor units (e.g. `1000` for €10.00). ### Transaction identity [](#transaction-identity) Buckaroo issues its own transaction key (`Key` in the response, 32-char hex). This key is stored as `transactionId` in `PaymentState` and `InitiateResult`. Your order reference is passed as `Invoice` and returned as `BRQ_INVOICENUMBER` in the return URL. ### Push vs webhook [](#push-vs-webhook) Buckaroo's push sends a **JSON body** (not form-encoded like MultiSafepay): ``` { "Transaction": { "Key": "", "Status": { ... }, ... } } ``` The controller reads `Transaction.Key` from the JSON body and falls back to `brq_transactions` query param for legacy configurations. ### Return URL parameters [](#return-url-parameters) Buckaroo appends these to the configured `ReturnURL`: ParameterValue`BRQ_TRANSACTIONS`Buckaroo transaction key (our `transactionId`)`BRQ_INVOICENUMBER`Your `Invoice` reference`BRQ_STATUSCODE`Numeric status code (informational only)We always call the API for the authoritative status and do not rely on the return URL params. ### Status codes [](#status-codes) CodeMeaningMaps to190Success — payment completed`PaymentStatus::Paid`790–793Pending — awaiting processor/consumer`PaymentStatus::Pending`890Cancelled by consumer`PaymentStatus::Canceled`490–492Failure`PaymentStatus::Failed`690Rejected by Buckaroo or acquirer`PaymentStatus::Failed`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: 'bkr_ideal', amount: 999, // in minor units — €9.99 currency: 'EUR', description: 'Order #12345', reference: 'ORDER-12345', issuerId: 'INGBNL2A', ); 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: 'bkr_ideal', amount: null, // null = full refund currency: 'EUR', description: 'Full refund for order #12345', ); // Partial refund $request = new RefundRequest( paymentReference: $state->transactionId, paymentModule: 'bkr_ideal', amount: 500, // in minor units — €5.00 currency: 'EUR', description: 'Partial refund for order #12345', ); try { $result = $this->router->refund($request); echo $result->refundId; // Buckaroo refund transaction Key } 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 40 — FairBetter than 86% of packages Maintenance95 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 ~9 days Total 8 Last Release 33d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/57e4ab872b3e37536367f2d26b192df3d3bb6a6a1cebec9a104d14a6d2ffe157?d=identicon)[noescom](/maintainers/noescom) --- Tags paymentsidealcanvaspayment gatewaynetherlandsbuckaroocanvas-payments ### Embed Badge ![Health badge](/badges/quellabs-canvas-payments-buckaroo/health.svg) ``` [![Health](https://phpackages.com/badges/quellabs-canvas-payments-buckaroo/health.svg)](https://phpackages.com/packages/quellabs-canvas-payments-buckaroo) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)