orderId returned at initiation, or rely on a webhook to be notified the moment a transaction reaches a final state — COMPLETED or FAILED.
Authentication
API key
All endpoints require a validPublicKey header containing your SeerBit public key. Obtain your public key from your SeerBit account team.
Request hashing
Every call must include aHash header — an HMAC-SHA256 signature of the request body, computed with your SeerBit secret key and Base64-encoded. Generate it before you initiate the request. This protects the request from tampering in transit and is validated on the server against the raw bytes it receives.
Important: The signature must be computed over the exact bytes your HTTP client transmits — not a re-serialized copy of the JSON. Differences in whitespace, key order, or encoding between the hashed bytes and the transmitted bytes will produce a hash mismatch and an INVALID_HASH response.
Security Note: Never expose your secret key in client-side code — generate the hash on your server or backend service, not in a browser.
Generating the hash
Use the snippet in your language of choice to hash your exact request body with your SeerBit secret key — found on your SeerBit dashboard under API/Integration settings — before you initiate a request. Whichever language you use, the result is the same: a Base64-encoded HMAC-SHA256 signature, sent in theHash header.
Before you integrate
- PublicKey authentication: every request must include a valid
PublicKeyheader. Obtain your public key from your SeerBit account team. - Request hashing: every call must include a
Hashheader, generated before you initiate the request (see Request hashing above). - Webhooks are optional: pass a
webhookUrlin the initiate payload if you’d rather receive a push notification than poll the status endpoint. - The terminal must be linked: the terminal referenced by
posidmust already be linked to your SeerBit account.
Where to go next
Initiate transaction
Start a payment on a connected terminal.
Transaction status
Poll for the outcome and settlement detail.
Webhooks
Get notified the moment a transaction resolves.
Error handling
All error responses share a consistent shape:Error codes
Worked examples
1. Invalid API key
Occurs when thePublicKey provided cannot be validated.
401 Unauthorized
2. Missing or invalid hash
Occurs when a request omits theHash header, or the header does not match the request body.
401 Unauthorized
3. Terminal not assigned
Occurs when theposid submitted is not linked to your business.
403 Forbidden
4. Duplicate order ID
Occurs when theorderId submitted has already been used on a previous transaction.
409 Conflict
5. Duplicate transaction reference
Occurs when thetransactionRef submitted has already been used on a previous transaction.
409 Conflict