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. It takes the raw request body as a string. This example uses Express and handles the HTTP POST push format:

import express from 'express';
import { ReplyHandler, ResponseStatus } from '@buckaroo/buckaroo_sdk';

const app = express();

// express.text() keeps the body as the raw string that ReplyHandler needs
app.post('/buckaroo/push', express.text({ type: '*/*' }), async (req, res) => {
    const reply = new ReplyHandler(buckaroo.credentials, req.body).validate();

    if (!reply.isValid()) {
        return res.sendStatus(400);
    }

    const push = reply.data(); // only filled when the message is valid

    const invoice = push.brq_invoicenumber;
    const txKey = push.brq_transactions;
    const statusCode = push.brq_statuscode;

    if (statusCode === ResponseStatus.STATUSCODE_SUCCESS) {
        // await markOrderAsPaid(invoice, txKey);
    } else if (
        [
            ResponseStatus.STATUSCODE_FAILED,
            ResponseStatus.STATUSCODE_REJECTED,
            ResponseStatus.STATUSCODE_CANCELLED_BY_USER,
            ResponseStatus.STATUSCODE_CANCELLED_BY_MERCHANT,
        ].includes(statusCode)
    ) {
        // await markOrderAsFailed(invoice, txKey);
    }

    res.sendStatus(200);
});

Read the push values from reply.data(), not from your own parse of the body. data() only returns the fields after they pass validation, and returns undefined when they do not.


JSON and HTTP POST format

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

FormatCreate the handlerRead the result
HTTP POSTnew ReplyHandler(buckaroo.credentials, rawBody)brq_statuscode, brq_invoicenumber and brq_transactions in reply.data()
JSONnew ReplyHandler(buckaroo.credentials, rawBody, req.headers.authorization, pushUrl)reply.data().Transaction, with Invoice, Key and Status.Code.Code

For the JSON format, pushUrl is 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.

For the HTTP POST format, the handler also checks that the store key in the message matches the store key of your client.


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:

app.post('/buckaroo/return', express.text({ type: '*/*' }), (req, res) => {
    const reply = new ReplyHandler(buckaroo.credentials, req.body).validate();

    if (!reply.isValid()) {
        return res.status(400).send('No valid payment result found.');
    }

    switch (reply.data().brq_statuscode) {
        case ResponseStatus.STATUSCODE_SUCCESS:
            return res.send('Thank you, your payment was received.');
        case ResponseStatus.STATUSCODE_CANCELLED_BY_USER:
            return res.send('You cancelled the payment.');
        case ResponseStatus.STATUSCODE_PENDING_PROCESSING:
        case ResponseStatus.STATUSCODE_WAITING_ON_CONSUMER:
            return res.send('Your payment is being processed.');
        default:
            return res.send('Your payment failed. Please try again.');
    }
});


Did this page help you?