Push messages

A push message is how Buckaroo tells your application that a payment succeeded, failed or changed status. It is sent from server to server, independently of the customer's browser.

Update orders from the push message, never from the return page. A customer returning to your return URL only proves that their browser came back, not that the payment completed.


What you need in place

  • A push URL that is reachable from the internet over HTTPS, with a valid certificate
  • No basic authentication, maintenance mode or login in front of it
  • Buckaroo's push IP addresses and ports allowed through your firewall. See Push messages for the current list

Set the push URL per request with pushURL, as a default in the client configuration, or in the push settings of your store in Plaza. Push messages explains the Plaza settings.


Verify and handle a push message

Every push message is signed with your secret key. Verify the signature before you act on the message. Without that check, anyone who knows your push URL can post a message claiming that a payment succeeded.

The SDK provides ReplyHandler for this. This example handles the JSON push format:

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

$body       = file_get_contents('php://input');
$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$pushUrl    = 'https://example.com/buckaroo/push'; // must match the push URL that Buckaroo called

$reply = new ReplyHandler($buckaroo->client()->config(), $body, $authHeader, $pushUrl);

try {
    $reply->validate();
} catch (ReplyValidationException $e) {
    // Not a Buckaroo push message, for example an empty request
    http_response_code(400);
    exit;
}

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

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

$invoice    = $transaction['Invoice'];
$txKey      = $transaction['Key'];
$statusCode = (string) $transaction['Status']['Code']['Code'];

if ($statusCode === ResponseStatus::BUCKAROO_STATUSCODE_SUCCESS) {
    // markOrderAsPaid($invoice, $txKey);
} elseif (in_array($statusCode, [
    ResponseStatus::BUCKAROO_STATUSCODE_FAILED,
    ResponseStatus::BUCKAROO_STATUSCODE_REJECTED,
    ResponseStatus::BUCKAROO_STATUSCODE_CANCELLED_BY_USER,
    ResponseStatus::BUCKAROO_STATUSCODE_CANCELLED_BY_MERCHANT,
], true)) {
    // markOrderAsFailed($invoice, $txKey);
}

http_response_code(200);

The signature covers the push URL. Pass the URL that Buckaroo called, with the same host, path and query string. A mismatch, such as an internal hostname behind a proxy, makes a genuine push message fail validation.


JSON and HTTP POST format

Buckaroo can send push messages as JSON or as an HTTP POST form. Which one you receive depends on the push settings of your store in Plaza. ReplyHandler detects the format from the data you pass.

FormatCreate the handlerRead the result
JSONnew ReplyHandler($config, $body, $authHeader, $pushUrl)Decode the body and read Transaction
HTTP POSTnew ReplyHandler($config, $_POST)$reply->data('brq_statuscode'), $reply->data('brq_invoicenumber'), $reply->data('brq_transactions')

In both cases $config is $buckaroo->client()->config().


Handle the status

Mark an order as paid on status 190 only. Pending statuses such as 790, 791 and 792 mean the result is still to come, and a later push message follows.

See Status and Substatus for the full list. Use the subcode and message for diagnostics, not for business logic.

Buckaroo can send the same push message more than once. Make your handler idempotent: processing a message twice must have the same result as processing it once. Check whether you have already handled that transaction key and status before you update the order.


Respond with a 200

Return HTTP 200 as soon as you have verified and stored the message, and do slow work such as emails, stock updates and invoicing afterwards. Buckaroo retries a push message that does not get a 200.


The return page

Buckaroo sends the customer back to your return URL with a form POST that contains the result. Verify it the same way, and use it only to show the customer the right page:

$reply = new ReplyHandler($buckaroo->client()->config(), $_POST);

try {
    $reply->validate();
} catch (ReplyValidationException $e) {
    // Not a Buckaroo return, for example the customer refreshed the page
    http_response_code(400);
    exit('No payment result found.');
}

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

switch ($reply->data('brq_statuscode')) {
    case ResponseStatus::BUCKAROO_STATUSCODE_SUCCESS:
        echo 'Thank you, your payment was received.';
        break;
    case ResponseStatus::BUCKAROO_STATUSCODE_CANCELLED_BY_USER:
        echo 'You cancelled the payment.';
        break;
    case ResponseStatus::BUCKAROO_STATUSCODE_PENDING_PROCESSING:
    case ResponseStatus::BUCKAROO_STATUSCODE_WAITING_ON_CONSUMER:
        echo 'Your payment is being processed.';
        break;
    default:
        echo 'Your payment failed. Please try again.';
}


Did this page help you?