Push messages and events

A push message is how Buckaroo tells your application that a payment succeeded, failed or changed status. The wrapper receives and verifies push messages for you. You only decide what happens next, by listening to an event.


What the wrapper does

When a push message arrives on the push route, the wrapper:

  1. Verifies the signature. A message with an invalid signature is rejected with HTTP 400.
  2. Finds the transaction in the buckaroo_transactions table.
  3. Updates the transaction with the new status, status code and amount.
  4. Fires an event that your application can listen to.

A transaction that is already paid, failed or cancelled is not changed back by a later push message with a pending status.


What you need in place

  • The push route is excluded from CSRF verification
  • Your application is reachable from the internet over HTTPS, with a valid certificate
  • No basic authentication, maintenance mode or login in front of the push route
  • Buckaroo's push IP addresses and ports are allowed through your firewall. See Push messages for the current list
  • Laravel generates the public URL of your application. Behind a proxy or load balancer, configure trusted proxies. For payments started from a queue or a command, set APP_URL

Listen to the events

EventFired when
PayTransactionCompletedA push message for a payment or authorization is processed. Also fired straight away for a payment that needs no redirect
RefundTransactionCompletedA refund is created, or a push message for a refund is processed
CaptureTransactionCompletedA capture is created
VoidTransactionCompletedAn authorization is cancelled

All events are in the Buckaroo\Laravel\Events namespace, and each one has two properties:

PropertyWhat it is
$event->buckarooTransactionThe stored transaction, with its current status
$event->transactionThe data that triggered the event: the push message or the API response

"Completed" means that the wrapper finished processing, not that the payment succeeded. PayTransactionCompleted is also fired for failed and pending payments, so always check the status in your listener.

There is one exception: when the customer cancels the payment, the wrapper updates the transaction to cancelled but does not fire the event.

Example listener

namespace App\Listeners;

use App\Models\Order;
use Buckaroo\Laravel\Constants\BuckarooTransactionStatus;
use Buckaroo\Laravel\Events\PayTransactionCompleted;

class UpdateOrderAfterPayment
{
    public function handle(PayTransactionCompleted $event): void
    {
        $transaction = $event->buckarooTransaction;
        $order = Order::where('number', $transaction->order)->first();

        if (! $order) {
            return;
        }

        match ($transaction->status) {
            BuckarooTransactionStatus::STATUS_PAID => $order->markAsPaid(),
            BuckarooTransactionStatus::STATUS_FAILED,
            BuckarooTransactionStatus::STATUS_CANCELLED => $order->markAsFailed(),
            default => null, // open or pending: a later push message follows
        };
    }
}

On Laravel 11 and higher, a listener in app/Listeners is discovered automatically.
On Laravel 9 and 10, register it in the $listen array of your EventServiceProvider.

Buckaroo can send the same push message more than once, so the event can fire more than once for the same status. Make your listener idempotent: check whether the order is already paid before you send an email or reduce stock.


Transaction statuses

The wrapper translates the Buckaroo status code into one of five statuses:

StatusMeaningFinal
openAn accepted authorization or a group transactionNo
pendingThe payment is waiting for the customer or for processingNo
paidThe payment succeededYes
failedThe payment failed or was rejectedYes
cancelledThe payment was cancelled by the customer or by youYes

The constants are in Buckaroo\Laravel\Constants\BuckarooTransactionStatus. The original Buckaroo code is kept in the status_code column. See Status for what each code means.


The return page

After paying, the customer is sent to the return route. The wrapper verifies the request and finds the transaction, and by default it responds with the stored transaction as JSON. That is useful for an API or a single page application, but a customer in a browser needs a page.

To show your own page, turn off the wrapper's routes and define both routes yourself with the same names:

BPE_LOAD_ROUTES=false
// routes/web.php
use Buckaroo\Laravel\Constants\BuckarooTransactionStatus;
use Buckaroo\Laravel\Http\Controllers\PushController;
use Buckaroo\Laravel\Http\Requests\ReplyHandlerRequest;
use Buckaroo\Laravel\PaymentProcessing\ReturnService;

Route::post('buckaroo/push', PushController::class)->name('buckaroo.push');

Route::match(['GET', 'POST'], 'buckaroo/return', function () {
    $transaction = ReturnService::make(app(ReplyHandlerRequest::class))->handleReturnRequest();

    return match ($transaction->status) {
        BuckarooTransactionStatus::STATUS_PAID => redirect()->route('checkout.thank-you'),
        BuckarooTransactionStatus::STATUS_OPEN,
        BuckarooTransactionStatus::STATUS_PENDING => redirect()->route('checkout.pending'),
        default => redirect()->route('checkout.failed'),
    };
})->name('buckaroo.return');

Keep the route names buckaroo.push and buckaroo.return.
The wrapper uses them to build the URLs it sends to Buckaroo and to verify the signature.

The push message can arrive after the customer returns.
When that happens the stored status is still pending, so give those customers a page that says the payment is being processed.



Did this page help you?