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:

  1. Start the payment. Your server calls pay(). Buckaroo responds with a transaction key and, for most methods, a redirect URL.
  2. Redirect the customer to that URL to complete the payment.
  3. The customer comes back to your return URL. Use this to show a "thank you" or "payment failed" page.
  4. 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.

FieldRequiredDescription
invoiceYesYour unique invoice number
amountDebitYesThe amount to charge
currencyNoISO currency code. Defaults to the configured currency
orderNoYour order number
descriptionNoShown to the customer and in Plaza
returnURLFor redirect methodsWhere the customer is sent after paying
returnURLCancel, returnURLError, returnURLRejectNoAlternative return pages
pushURLNoWhere Buckaroo sends the push message. Falls back to the push settings in Plaza
clientIPDepends on the methodThe customer's IP address. Required by some methods, such as the buy now, pay later methods
customParameters, additionalParametersNoYour 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.00 is sent without an amount.


Service codes and method fields


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 response

See 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:

ExceptionThrown when
ParameterValidationExceptionThe input is invalid, for example an unknown payment method or a card payment without name. Nothing was sent
AuthenticationExceptionThe keys are missing, or Buckaroo rejected them. Check the store key, the secret key and the mode
TransferExceptionBuckaroo could not be reached because of a connection failure or timeout
BuckarooApiExceptionBuckaroo returned a response the SDK could not process. Also the parent of TransferException
ReplyValidationExceptionThe 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
]);


Did this page help you?