Payments
Every payment method uses the same pattern: $buckaroo->method('<service code>')-><action>([...]). Which fields the request takes depends on the payment method.
How a payment works
Most online payment methods follow the same flow:
- Start the payment. Your server calls
pay(). Buckaroo responds with a transaction key and, for most methods, a redirect URL. - Redirect the customer to that URL to complete the payment.
- The customer comes back to your return URL. Use this to show a "thank you" or "payment failed" page.
- Buckaroo sends a push message to your push URL. Use the push message to update the order.
Do not treat the customer returning to your return URL as proof of payment. The customer can close the browser or lose connection before they return.
The push message is always sent. See Push messages.
Start a payment
$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',
]);
// Store the transaction key with your order so you can match the push message later
// saveTransactionKey('INV-1001', $response->getTransactionKey());
if ($response->hasRedirect()) {
header('Location: ' . $response->getRedirectUrl());
exit;
}Swap ideal for another service code to use a different payment method. Some methods need an extra field. A card payment, for example, takes the card brand in name:
$response = $buckaroo->method('creditcard')->pay([
'name' => 'visa', // card brand: visa, mastercard, amex, maestro, ...
'invoice' => 'INV-1002',
'amountDebit' => 10.00,
'returnURL' => 'https://example.com/buckaroo/return',
]);Shared fields
These fields are shared by all payment methods. Each method can add its own.
| Field | Required | Description |
|---|---|---|
invoice | Yes | Your unique invoice number |
amountDebit | Yes | The amount to charge |
currency | No | ISO currency code. Defaults to the configured currency |
order | No | Your order number |
description | No | Shown to the customer and in Plaza |
returnURL | For redirect methods | Where the customer is sent after paying |
returnURLCancel, returnURLError, returnURLReject | No | Alternative return pages |
pushURL | No | Where Buckaroo sends the push message. Falls back to the push settings in Plaza |
clientIP | Depends on the method | The customer's IP address. Required by some methods, such as the buy now, pay later methods |
customParameters, additionalParameters | No | Your own key and value data. It is returned in the push message |
Write field names in camelCase, as in the table (
amountDebit,originalTransactionKey). The API reference uses PascalCase (AmountDebit) because it describes the raw JSON request, which the SDK builds for you.The SDK silently ignores keys it does not recognise, including PascalCase ones. A request with
'AmountDebit' => 10.00is sent without an amount.
Service codes and method fields
- The service code list in the repository has every service code, with a runnable example for each method
- Payment methods and the API reference describe the parameters each method accepts
Read the response
pay(), refund(), authorize() and most other actions return a TransactionResponse:
$response->isSuccess(); // status 190
$response->isWaitingOnUserInput(); // status 790
$response->isPendingProcessing(); // status 791
$response->isAwaitingConsumer(); // status 792
$response->isFailed(); // status 490
$response->isValidationFailure(); // status 491
$response->isRejected(); // status 690
$response->isCanceled(); // status 890 or 891
$response->hasRedirect(); // does the customer need to be redirected?
$response->getRedirectUrl();
$response->getTransactionKey(); // store this: you need it for refunds and lookups
$response->getStatusCode();
$response->getSomeError(); // readable error message, if any
$response->toArray(); // the full raw responseSee Status and Substatus for what each code means.
Handle errors
A declined payment and a failed request are handled differently:
- Buckaroo declined the payment. The request completed and you get a normal response. Check it with
isSuccess(),isFailed()and the other status methods. - The request did not complete. The SDK throws an exception and you do not get a response.
Every exception extends Buckaroo\Exceptions\BuckarooException. Catch a subclass to handle a specific cause:
| Exception | Thrown when |
|---|---|
ParameterValidationException | The input is invalid, for example an unknown payment method or a card payment without name. Nothing was sent |
AuthenticationException | The keys are missing, or Buckaroo rejected them. Check the store key, the secret key and the mode |
TransferException | Buckaroo could not be reached because of a connection failure or timeout |
BuckarooApiException | Buckaroo returned a response the SDK could not process. Also the parent of TransferException |
ReplyValidationException | The push handler received data that is not a Buckaroo return or push message |
use Buckaroo\Exceptions\AuthenticationException;
use Buckaroo\Exceptions\BuckarooException;
use Buckaroo\Exceptions\ParameterValidationException;
use Buckaroo\Exceptions\TransferException;
try {
$response = $buckaroo->method('ideal')->pay([
'invoice' => 'INV-1001',
'amountDebit' => 10.00,
'returnURL' => 'https://example.com/buckaroo/return',
]);
} catch (ParameterValidationException $e) {
exit('Invalid input (' . $e->getParameterName() . '): ' . $e->getMessage());
} catch (AuthenticationException $e) {
exit('Check your Buckaroo keys and mode.');
} catch (TransferException $e) {
exit('Buckaroo could not be reached. Please try again later.');
} catch (BuckarooException $e) {
exit('Payment could not be started: ' . $e->getMessage());
}
if (! $response->isSuccess() && ! $response->hasRedirect()) {
// Buckaroo declined the payment
exit('Payment failed: ' . $response->getSomeError());
}After a
TransferException, Buckaroo may still have processed the payment. Wait for the push message before you retry, so the customer is not charged twice.
Encrypted card data
Card and Bancontact payments can be sent with the card data encrypted in the browser, using the JS Client Side Encryption SDK. The card data then never reaches your server unencrypted.
$response = $buckaroo->method('creditcard')->payEncrypted([
'name' => 'visa',
'invoice' => 'INV-1003',
'amountDebit' => 10.00,
'encryptedCardData' => 'ENCRYPTED_STRING', // produced by the JavaScript library
]);Updated about 4 hours ago