Payments
PayService starts a payment, stores it in your database and returns the response. You describe the payment with PaymentMethodFactory.
How a payment works
- Start the payment.
PayServicesends the request to Buckaroo and stores the transaction in thebuckaroo_transactionstable. - Redirect the customer to the redirect URL from the response.
- The customer comes back to the wrapper's return route.
- 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:
| Value | What it is |
|---|---|
$response | The TransactionResponse from the PHP SDK |
$transaction | The 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.
- Payments in the PHP SDK documentation lists the shared fields
- The service code list in the PHP SDK repository has every service code
- Payment methods describes the parameters each method accepts
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 anyThe 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 codeSee 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_transactionstable. The wrapper's push route only handles transactions it can find there, so usePayServiceunless you handle the push message yourself.
Updated about 7 hours ago