Callback Payloads
What Is a Callback
A callback is how Nimbbl delivers the result of a payment attempt back to you — as opposed to a webhook, which is a separate, asynchronous notification. Nimbbl sends results in two ways:
- Payment callback — a server-side result delivered to your
callback_url, either as a redirect (redirect integrations) or a direct POST (no-redirect integrations). - Checkout callback — a client-side response the Sonic SDK fires in the browser after the customer completes checkout, delivered to your
callback_handlerfunction.
Both carry the outcome of the same payment attempt; the payment callback is authoritative and server-side, while the checkout callback lets your frontend react immediately. Never fulfill an order based on the checkout callback alone — always validate the signature and confirm the final status server-side via the payment callback, a webhook, or the Transaction Enquiry API.
Configuration
The callback version is a per-sub-merchant setting, configured independently for each callback through two fields on your sub-merchant profile:
checkout_callback_version— the client-side checkout callbackpayment_callback_version— the server-side payment callback
Each accepts v3 or v4. v4 is the latest and recommended version — it's compact and signed as a unit: a single HMAC over the entire payload instead of a per-field concatenation. Contact [email protected] to review or change either version — it is not something you set yourself.
Neither field runs both versions side by side — the moment payment_callback_version or checkout_callback_version flips to v4, v3 deliveries on that callback stop entirely. Deploy and verify your v4 parsing and signature logic, and prove it in test mode, before requesting the live flip. See Migrating Callbacks from v3 to v4 for the full sequence.
When payload encryption is enabled, v4 delivers only an encrypted payload — no signature is sent (neither callback's nimbbl_signature). AES-GCM already authenticates the data, so a separate HMAC signature is redundant. Encrypted payloads are not enabled by default — contact [email protected] to enable it. For AES-GCM key generation and decryption code, see Using Encrypted Payloads.
Validating the Signature
Signature validation is mandatory for every unencrypted callback. It protects your business from tampered responses. Always validate on your server — never trust the client-side response alone.
For the exact steps and code samples: v3 Signature covers the v3 payment and checkout callbacks, and v4 Signature covers the v4 payment and checkout callbacks, including the encrypted-callback case where there's no signature to validate.
Both callbacks are documented in full on their own pages — Payment Callback for the server-side result delivered to your callback_url, and Checkout Callback for the browser-side response fired by the Sonic SDK. If you're migrating a sub-merchant to v4, see Migrating Callbacks from v3 to v4.