Skip to main content
The SeerBit ISV POS Transaction API enables third-party applications such as ERP systems, POS software, and retail management solutions to initiate payment requests on a connected SeerBit POS terminal and monitor transaction progress until completion. Initiating a transaction pushes it directly to the target POS terminal for processing. Once the terminal completes the payment, the transaction record is updated automatically. Integrating applications can either poll the status endpoint using the 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 valid PublicKey header containing your SeerBit public key. Obtain your public key from your SeerBit account team.

Request hashing

Every call must include a Hash 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 the Hash header.
Whichever language you use, this produces a request in the following shape:

Before you integrate

  • PublicKey authentication: every request must include a valid PublicKey header. Obtain your public key from your SeerBit account team.
  • Request hashing: every call must include a Hash header, generated before you initiate the request (see Request hashing above).
  • Webhooks are optional: pass a webhookUrl in 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 posid must 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 the PublicKey provided cannot be validated.
401 Unauthorized
2. Missing or invalid hash
Occurs when a request omits the Hash header, or the header does not match the request body.
401 Unauthorized
3. Terminal not assigned
Occurs when the posid submitted is not linked to your business.
403 Forbidden
4. Duplicate order ID
Occurs when the orderId submitted has already been used on a previous transaction.
409 Conflict
5. Duplicate transaction reference
Occurs when the transactionRef submitted has already been used on a previous transaction.
409 Conflict