v3 Signature
v3 joins a fixed set of fields together with | and hashes the result. Which fields to use, and where to read them from, depends on which surface you're validating. For the reusable HMAC-SHA256 function in Java, C#, PHP, and Python, see Validating Payment Response with Signature.
Attributes for Creating the Signature - Transaction
The following attributes will be required to generate the signature on your server
| Attribute | Description |
|---|---|
signature_version | Use the signature_version in the transaction object returned by Nimbbl for the payment in the response |
invoice_id | Use the invoice_id of the order that is generated on your server, returned by Nimbbl in the response |
transaction_id | Use the transaction_id in the transaction object returned by Nimbbl for the payment in the response |
access_secret | The access_secret is generated from the Command Center. Available on your server |
transaction_amount | Use the transaction_amount in the transaction object returned by Nimbbl in the response. Always use the transaction_amount with 2 decimal places. |
transaction_currency | Use the transaction_currency in the transaction object returned by Nimbbl in the response |
status | Use the status in the transaction object returned by Nimbbl in the response |
transaction_type | Use the transaction_type in the transaction object returned by Nimbbl in the response |
Some JSON libraries convert the whole float numbers to integers (3.0 may be converted to 3).
Hence, we recommend to always convert the transaction_amount field into float with 2 decimal places.
However, if the transaction_amount has more than 2 decimal places, trim the transaction_amount to 2 decimal places.
For example
- If the
transaction_amountis 3, use thetransaction_amountvalue as 3.00 for signature creation. - If the
transaction_amountis 3.1, use thetransaction_amountvalue as 3.10 for signature creation. - If the
transaction_amountis 3.12, use thetransaction_amountvalue as 3.12 for signature creation. - If the
transaction_amountis 3.129, use thetransaction_amountvalue as 3.12 for signature creation.
Attributes for Creating the Signature - Payment Link
The following attributes will be required to generate the payment link signature on your server
| Attribute | Description |
|---|---|
signature_version | Use the signature_version returned by Nimbbl in the webhook/callback response |
invoice_id | Use the invoice_id of the payment link returned by Nimbbl in the response |
payment_link_status | Use the payment link status returned by Nimbbl in the response |
payment_link_currency | Use the payment link currency returned by Nimbbl in the response |
payment_link_total_amount | Use the payment link total_amount returned by Nimbbl in the response. Always use the amount with 2 decimal places. |
payment_link_hash | Use the payment_link_hash returned by Nimbbl in the response |
access_secret | The access_secret is generated from the Command Center. Available on your server |
- Payment Callback
- Checkout Callback
- Webhook
- Transaction Enquiry
- Payment Link
This covers the server-side result delivered to your callback_url. For the full payload shapes, see Payment Callback.
Compare against transaction.signature (the same value also appears at the top level as nimbbl_signature). Take invoice_id from order.invoice_id; take the other five fields from transaction:
generated_signature = hmac_sha256(order.invoice_id + "|" + transaction.transaction_id + "|" + transaction.transaction_amount + "|" + transaction.transaction_currency + "|" + transaction.status + "|" + transaction.transaction_type, <your_access_secret>);
if (generated_signature == transaction.signature) {
payment is successful
}
This covers the browser-side response the Sonic SDK fires via your callback_handler function. For the full payload shapes, see Checkout Callback.
This is the same formula as the payment callback and webhook — it's just nested one level deeper, inside payload. Take invoice_id from payload.order.invoice_id; take the other five fields from payload.transaction. Compare against payload.transaction.signature:
generated_signature = hmac_sha256(payload.order.invoice_id + "|" + payload.transaction.transaction_id + "|" + payload.transaction.transaction_amount + "|" + payload.transaction.transaction_currency + "|" + payload.transaction.status + "|" + payload.transaction.transaction_type, <your_access_secret>);
if (generated_signature == payload.transaction.signature) {
payment is successful
}
For the full payload shapes across every event category, see Webhook Payloads.
Same formula as the payment callback, and the same layout — invoice_id from order.invoice_id, the rest from transaction. Compare against transaction.signature (also appears at the top level as nimbbl_signature):
generated_signature = hmac_sha256(order.invoice_id + "|" + transaction.transaction_id + "|" + transaction.transaction_amount + "|" + transaction.transaction_currency + "|" + transaction.status + "|" + transaction.transaction_type, <your_access_secret>);
if (generated_signature == transaction.signature) {
payment is successful
}
Payment Links carry their own, payment-link-specific signature, separate from the transaction-level signature described here — see the Payment Link tab on this page.
This covers the Transaction Enquiry API — the surface you poll on demand. For everything else about this endpoint (when to use it, pre-authorization fields, datetime formats), see Transaction Enquiry.
Same formula as the payment callback and webhook, but the response is shaped a little differently: invoice_id comes from the top-level order object, and the signature plus the other five fields live inside each item of the transaction list — which uses nimbbl_transaction_id and payment_status instead of transaction_id and status. Compare against nimbbl_signature in that same item:
generated_signature = hmac_sha256(order.invoice_id + "|" + transaction.nimbbl_transaction_id + "|" + transaction.transaction_amount + "|" + transaction.transaction_currency + "|" + transaction.payment_status + "|" + transaction.transaction_type, <your_access_secret>);
if (generated_signature == transaction.nimbbl_signature) {
payment is successful
}
If your sub-merchant is configured on payment_callback_version v4, this endpoint returns null for both nimbbl_signature and signature_version — there is nothing to validate on this surface. See the v4 Signature Behavior section on the general Transaction Enquiry guide for the full explanation.
This covers the Payment Link surface — the fields on the payment link itself, separate from the transaction-level signature used by the payment callback, checkout callback, webhook, and Transaction Enquiry. The same formula applies to both the Payment Link Enquiry API's payment_link_signature and the old payment_link.signature field on payment-link webhook events:
generated_signature = hmac_sha256(invoice_id + "|" + payment_link_status + "|" + payment_link_currency + "|" + payment_link_total_amount + "|" + payment_link_hash, <your_access_secret>);
if (generated_signature == signature) {
payment is successful
}
On the Payment Link Enquiry API, this field is simply null on a v4 sub-merchant — there's nothing to validate on that surface. On payment-link webhook events, v4 doesn't leave you with nothing: the old field is dropped, but the whole event is signed instead — see v4 Signature.