Hosted checkout — business rules

These rules apply specifically to the Bluebox hosted checkout flow. For the general rules that apply to every Merchant / PSP integration, see QR Code Payments business rules — most of those apply here too.

Request rules

Rule	Detail
Endpoint	`POST /bluebox/secure/createTx` (different from the general code-create endpoint)
Auth	Basic Auth or JWT Bearer with `EXTERNAL` role. See Authentication.
Content-Type	`application/json`
HTTPS only	Plain HTTP is rejected
`reference` is required	Unique per merchant. The platform rejects duplicate references — see Idempotency.
`callbackUrl` is required	The page on your site that receives CB1 (browser redirect). Up to 400 characters.
`amount` is required	In your merchant's configured currency. Two decimal places.

Callback rules

Bluebox sends two callbacks per transaction:

Callback	Where	When	What
CB1 — browser redirect	The `callbackUrl` you supplied on `createTx`	After the customer finishes (success, cancel, or failure)	A 302 redirect with `?transactionId={id}&status={value}` query params. Unencrypted.
CB2 — encrypted webhook	Your merchant notification URL (configured in the Portal)	After the transaction reaches a terminal state	The full encrypted `TransactionNotificationV3` payload. See Webhooks.

CB1 and CB2 can arrive in either order. Build your handlers to be order-independent. Match them by transactionId.

Trust model

What you can trust	What you cannot trust
CB2 (decrypted) — payload decrypts only with your notification key, so if decryption succeeds, the message is authentic	CB1 query parameters alone — a browser redirect can be forged by an attacker
`transactionId` matched across CB1 and CB2	Reading `status=SUCCESS` from CB1 query string without CB2 verification

Don't release goods on CB1 alone. Wait for the encrypted CB2 to confirm.

Reversal-on-failure safety net

The reversal mechanism that applies to all webhook deliveries also applies to CB2:

Scan to Pay schedules a reversal job before sending CB2
If CB2 receives a non-200 response (or no response within 45 seconds), the reversal fires
The original transaction is reversed and the customer is not charged

This means a broken CB2 handler in production will reverse your customers' payments — silently, from their perspective. Monitor CB2 acknowledgement rates carefully on go-live.

See Webhooks > How it works for full detail.

Optional fields

These are documented on the hosted checkout page; recapping the business rules here.

Field	Constraint
`description`	5–45 characters. Shown to the customer at checkout.
`requestShipping`	If `true`, Bluebox asks the customer for a shipping address. The address is included on the CB2 payload.
`terminalId`	Up to 40 characters. Overrides the default terminal ID for this transaction.
`subMerchantName`	For super merchants. Shows on the consumer's bank statement (if supported by the acquirer).
`mcc`	4-digit numeric. Overrides the merchant category code.
`rrn2`	12 characters, left-padded with zeros. Secondary RRN passed through to the bank message.
`cartItems`	Array of basket items for airtime limit checking. See QR Code Payments — business rules.
`notificationUrl`	Per-transaction override of the merchant notification URL. Most integrators don't need this.

Currency, amount, and limits

Currency is fixed per merchant, set at onboarding. Always the merchant's configured currency (typically ZAR for South African merchants).
Amount must be greater than zero. Variable-amount Bluebox transactions are not supported — the customer can't change the amount on the hosted page.
Limit baskets (airtime / data bundles) apply if cartItems includes AIRTIME or AIRTIME_BUNDLE. Same daily and monthly thresholds as QR — see qr-payments-business-rules.

What's next

Build the integration → Bluebox hosted checkout
Switch to custom-built checkout → Custom checkout
Webhook payload reference → Webhooks
Refund or reverse → Refunds and reversals