PayService starts a payment, stores it in your database and returns the response. You describe the payment with PaymentMethodFactory.


How a payment works

  1. Start the payment. PayService sends the request to Buckaroo and stores the transaction in the buckaroo_transactions table.
  2. Redirect the customer to the redirect URL from the response.
  3. The customer comes back to the wrapper's return route.
  4. Buckaroo sends a push message to the wrapper's push route. The wrapper verifies it, updates the stored transaction and fires an event.

Update your order from the event that follows the push message, not from the customer returning. The customer can close the browser or lose connection before they return. See Push messages and events.


Start a payment

use Buckaroo\Laravel\Api\PayService;
use Buckaroo\Laravel\Handlers\PaymentMethodFactory;

[$response, $transaction] = PayService::make(
    PaymentMethodFactory::make('ideal')->setPayload([
        'invoice'     => 'INV-1001', // must be unique per payment
        'order'       => 'ORD-1001',
        'amountDebit' => 10.00,
        'currency'    => 'EUR',
        'description' => 'Order #1001',
    ])
)->pay();

if ($response->hasRedirect()) {
    return redirect()->away($response->getRedirectUrl());
}

pay() returns two values:

ValueWhat it is
$responseThe TransactionResponse from the PHP SDK
$transactionThe stored BuckarooTransaction model

The wrapper sets returnURL and pushURL to its own routes. Pass your own values in the payload to override them.

Swap ideal for another service code to use a different payment method.

Set the fields one by one

Every field also has a setter, which reads well when you build the payment in steps:

$payment = PaymentMethodFactory::make('ideal')
    ->setInvoice('INV-1001')
    ->setOrder('ORD-1001')
    ->setAmountDebit(10.00)
    ->setCurrency('EUR')
    ->setDescription('Order #1001');

[$response, $transaction] = PayService::make($payment)->pay();

Let the customer choose the payment method

Use noservice to send the customer to the Buckaroo payment page, where they choose from the methods you list:

[$response, $transaction] = PayService::make(
    PaymentMethodFactory::make('noservice')->setPayload([
        'invoice'                    => 'INV-1001',
        'order'                      => 'ORD-1001',
        'amountDebit'                => 10.00,
        'currency'                   => 'EUR',
        'description'                => 'Order #1001',
        'continueOnIncomplete'       => '1',
        'servicesSelectableByClient' => 'ideal,bancontactmrcash',
    ])
)->pay();

Fields and service codes

The payload goes to the PHP SDK unchanged, so the same fields and service codes apply.

Write field names in camelCase, such as amountDebit. The API reference uses PascalCase because it describes the raw JSON request. The SDK silently ignores names it does not recognise.


Read the response

$response is the same object the PHP SDK returns:

$response->isSuccess();         // status 190
$response->isPendingProcessing();
$response->isFailed();
$response->isRejected();
$response->isCanceled();

$response->hasRedirect();
$response->getRedirectUrl();

$response->getTransactionKey();
$response->getStatusCode();
$response->getSomeError();      // readable error message, if any

The stored transaction has the same information in your database:

$transaction->transaction_key;
$transaction->status;      // open, pending, paid, failed or cancelled
$transaction->status_code; // the Buckaroo status code

See Read the response in the PHP SDK documentation for the full list.


Handle errors

A payment that Buckaroo declines is a normal response: check $response or $transaction->status. When the request itself does not complete, the PHP SDK throws an exception and nothing is stored.

use Buckaroo\Exceptions\BuckarooException;

try {
    [$response, $transaction] = PayService::make($payment)->pay();
} catch (BuckarooException $e) {
    report($e);

    return back()->withErrors('The payment could not be started. Please try again.');
}

if ($response->hasRedirect()) {
    return redirect()->away($response->getRedirectUrl());
}

if (! $response->isSuccess()) {
    return back()->withErrors('The payment failed: ' . $response->getSomeError());
}

The exception types are described under Handle errors in the PHP SDK documentation.


Call the PHP SDK directly

For anything the services do not cover, Buckaroo::api() gives you the PHP SDK client:

use Buckaroo\Laravel\Facades\Buckaroo;

$response = Buckaroo::api()->method('ideal')->pay([
    'invoice'     => 'INV-1001',
    'amountDebit' => 10.00,
    'returnURL'   => route('buckaroo.return'),
    'pushURL'     => route('buckaroo.push'),
]);

A payment you start this way is not stored in the buckaroo_transactions table. The wrapper's push route only handles transactions it can find there, so use PayService unless you handle the push message yourself.



Did this page help you?