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:
- Verifies the signature. A message with an invalid signature is rejected with HTTP
400. - Finds the transaction in the
buckaroo_transactionstable. - Updates the transaction with the new status, status code and amount.
- 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
| Event | Fired when |
|---|---|
PayTransactionCompleted | A push message for a payment or authorization is processed. Also fired straight away for a payment that needs no redirect |
RefundTransactionCompleted | A refund is created, or a push message for a refund is processed |
CaptureTransactionCompleted | A capture is created |
VoidTransactionCompleted | An authorization is cancelled |
All events are in the Buckaroo\Laravel\Events namespace, and each one has two properties:
| Property | What it is |
|---|---|
$event->buckarooTransaction | The stored transaction, with its current status |
$event->transaction | The data that triggered the event: the push message or the API response |
"Completed" means that the wrapper finished processing, not that the payment succeeded.
PayTransactionCompletedis 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
cancelledbut 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:
| Status | Meaning | Final |
|---|---|---|
open | An accepted authorization or a group transaction | No |
pending | The payment is waiting for the customer or for processing | No |
paid | The payment succeeded | Yes |
failed | The payment failed or was rejected | Yes |
cancelled | The payment was cancelled by the customer or by you | Yes |
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.pushandbuckaroo.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.
Updated about 7 hours ago