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 push_url, 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 the Json verifier for the JSON push format. This example uses Flask, and the same four values are available in every web framework: the Authorization header, the URL that was called, the HTTP method and the raw request body.

import json

from flask import Flask, request

from buckaroo.models.payment_response import BuckarooStatusCode
from buckaroo.services.reply import Json

app = Flask(__name__)
verifier = Json("STORE_KEY", "SECRET_KEY")

PUSH_URL = "https://example.com/buckaroo/push"  # must match the push URL that Buckaroo called


@app.post("/buckaroo/push")
def buckaroo_push():
    body = request.get_data()  # the raw body, not the parsed JSON

    if not verifier.validate(request.headers.get("Authorization"), PUSH_URL, "POST", body):
        return "", 400

    transaction = json.loads(body)["Transaction"]

    invoice = transaction["Invoice"]
    tx_key = transaction["Key"]
    status_code = transaction["Status"]["Code"]["Code"]

    if status_code == BuckarooStatusCode.SUCCESS:
        pass  # mark_order_as_paid(invoice, tx_key)
    elif status_code in (490, 690, 890, 891):  # failed, rejected or cancelled
        pass  # mark_order_as_failed(invoice, tx_key)

    return "", 200

The signature covers the push URL and the request body. Pass the URL that Buckaroo called, with the same host, path and query string, and pass the body exactly as it was received. A mismatch, such as an internal hostname behind a proxy or a body that was parsed and serialised again, 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.

FormatVerifyRead the result
JSONJson(store_key, secret_key).validate(authorization, url, "POST", body)Decode the body and read Transaction
HTTP POSTHttpPost(secret_key).validate(form_fields)brq_statuscode, brq_invoicenumber and brq_transactions in the form fields

Both verifiers are in buckaroo.services.reply and return True or False.


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, for example in a background task. 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 with HttpPost, and use it only to show the customer the right page:

from buckaroo.services.reply import HttpPost


@app.post("/buckaroo/return")
def buckaroo_return():
    fields = request.form.to_dict()

    if not HttpPost("SECRET_KEY").validate(fields):
        return "No valid payment result found.", 400

    status_code = fields.get("brq_statuscode")

    if status_code == "190":
        return "Thank you, your payment was received."
    if status_code == "890":
        return "You cancelled the payment."
    if status_code in ("791", "792"):
        return "Your payment is being processed."
    return "Your payment failed. Please try again."


Did this page help you?