README

Buckaroo PHP SDK

About · Requirements · Installation · Getting started · Documentation · Tests · Support · Contribute

About

Buckaroo is a Dutch Payment Service Provider. More than 54,000 organisations rely on the Buckaroo platform to process their payments, subscriptions and unpaid invoices.

This is Buckaroo's official PHP SDK: a modern, open source library that connects a PHP application to the Buckaroo API. It handles authentication, request signing and response parsing, so you can start payments, verify return and push requests, and refund or look up transactions for more than 40 payment methods.

If you run a shop on an e-commerce platform, use the ready-made plugin for Magento 2, Shopware 6, WooCommerce, PrestaShop or Odoo instead. For Laravel applications there is a dedicated Laravel wrapper built on this SDK.

Full API documentation on docs.buckaroo.io

Requirements

You also need a Buckaroo account. Don't have one yet? Request an account.

Installation

Install the SDK with Composer:

composer require buckaroo/sdk

Composer pulls in the SDK's own dependencies (Guzzle, Monolog, ramsey/uuid and composer/ca-bundle), so there is nothing else to set up.

Getting started

Configuring the client

You can find your Store key and Secret key under API credentials in Buckaroo Plaza. The third argument is the mode: test while developing, live in production. It defaults to test.

require __DIR__ . '/vendor/autoload.php';

$buckaroo = new \Buckaroo\BuckarooClient('STORE_KEY', 'SECRET_KEY', 'test');

Tip

Keep your Secret key out of version control. Load both keys from environment variables instead — the repository ships an .env.example to start from.

Starting a payment

Start an iDEAL payment and send the customer to the payment page:

$response = $buckaroo->method('ideal')->pay([
    'invoice'     => 'INV-1001',  // must be unique per payment
    'amountDebit' => 10.00,
    'description' => 'Order #1001',
    'returnURL'   => 'https://example.com/buckaroo/return',
    'pushURL'     => 'https://example.com/buckaroo/push',
]);

if ($response->hasRedirect()) {
    header('Location: ' . $response->getRedirectUrl());
    exit;
}

Swap ideal for any other service code to use a different payment method. See Payment methods.

Handling the push

When the payment is completed, Buckaroo sends a push (server-to-server notification) to your pushURL. Verify it with the SDK, then update the order:

use Buckaroo\Handlers\Reply\ReplyHandler;
use Buckaroo\Resources\Constants\ResponseStatus;

$body  = file_get_contents('php://input');
$reply = new ReplyHandler(
    $buckaroo->client()->config(),
    $body,
    $_SERVER['HTTP_AUTHORIZATION'] ?? '',
    'https://example.com/buckaroo/push' // must exactly match the pushURL you sent
);
$reply->validate();

if (! $reply->isValid()) {
    http_response_code(400);
    exit;
}

$transaction = json_decode($body, true)['Transaction'];

if ((string) $transaction['Status']['Code']['Code'] === ResponseStatus::BUCKAROO_STATUSCODE_SUCCESS) {
    // markOrderAsPaid($transaction['Invoice'], $transaction['Key']);
}

Important

Update the order in your database from the push, not from the return page. The customer may close the browser before returning, but the push is always sent.

The full checkout example adds error handling, the return page and the HTTP POST push format.

Documentation

For all API parameters, see the API reference on docs.buckaroo.io. With the SDK, use camelCase (amountDebit). See Usage for details.

Running the SDK tests

The repository defines Composer scripts for the test suites and code style:

composer test          # run the full suite
composer test:unit     # unit tests only
composer test:feature  # feature tests only
composer cs            # check code style
composer cs:fix        # fix code style

Feature tests talk to the Buckaroo test environment, so copy .env.example to .env and fill in your test credentials first.

Support

Having trouble? Work through this list before reaching out:

1. Check the API reference for the service and action you are calling.
2. Confirm you are on the latest release.
3. Reproduce the issue in test mode and inspect the response, including the status subcode and message.
4. Verify that your push URL is reachable from outside your network. Buckaroo sends push messages from fixed IP addresses and ports, so make sure these are on your allow list. See push messages for the current list.

Still stuck? Contact us and include your PHP version, SDK version, the service and action you called, the error message and the transaction key.

• Questions: start a discussion
• Bug reports and feature requests: open an issue
• Technical support: support@buckaroo.nl
• Phone: +31 (0)30 711 50 50
• Gateway status: status.buckaroo.io

Contribute

We really appreciate it when developers help improve the Buckaroo SDKs. Please read our Contribution Guidelines before opening a pull request, and target the develop branch.

Found a security issue? Please report it privately to support@buckaroo.nl instead of opening a public issue.

Versioning

We follow semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR — breaking changes that require additional testing and caution.
• MINOR — new functionality with limited impact.
• PATCH — bug fixes and hotfixes only.

All changes are documented in the changelog and on the releases page.

License

This SDK is open source software licensed under the MIT license.

_{Made with care by Buckaroo.
This document is subject to change; typos and language errors are possible.}