Before you begin
You will need:Test in sandbox first
Always test end-to-end in sandbox first. Sandbox lets you complete a full payout, including funding, without moving real money. There is no separate sandbox host. Both environments usehttps://api.bitnob.com, and the secret you sign with selects the environment. To go live, swap the secret, not the URL.
Authentication
Every API request is authenticated with an HMAC-SHA256 signature. You sign each request with your Client Secret and send four headers. Signatures are time-limited: a request stops being accepted about five minutes after its timestamp.Required headers
How to build the signature
Build the payload string by joining four parts with colons, then sign it with your Client Secret using HMAC-SHA256 and hex-encode the result. REQUEST_BODY is the exact raw JSON body you send. For requests with no body (e.g.GET, or the finalize call), use an empty string.
Common auth errors
Understanding funding: offchain vs onchain
When you create a quote you choose a source, which decides where the funds come from:
Everything else in the flow is identical; only the funding step differs.
Reference lookups (recommended first)
Use these read-only calls to build a valid request. They help you pick a supported country, the exact beneficiary fields it needs, valid bank codes, and transaction limits. Verify a beneficiary account before paying it. The lookup returns the resolved account name.Step 1: create a quote
Locks in the exchange rate and fees for your payout. The response returns aquote_id, the rate, fees, and an expiry. Quotes expire, continue promptly.
Step 2: add the beneficiary (initialize)
Attach the recipient’s details to the quote. The exactbeneficiary fields depend on the country (see Reference Lookups).
callback_url is where we’ll notify your system of status changes. Recommended.
customer_id (optional) links the payout to a customer in your account.
Step 3: finalize (approve and submit)
Approves the payout and submits it for processing. No request body: remember to sign with an empty body string. Foroffchain payouts, your account balance is charged at this step.
Step 4: fund the payout
offchain: nothing to do. Your balance was charged at finalize, and the payout proceeds automatically to settlement. onchain: send a crypto deposit to the address / instruction returned from the previous step. You can fund it with BTC (on-chain), Lightning, or stablecoins. Once the deposit confirms, settlement proceeds.Sandbox has no endpoint that simulates a crypto deposit for a payout, so an onchain payout you don’t fund stays in
PENDING_ADDRESS_DEPOSIT.Step 5: track to completion
We settle the fiat to the beneficiary and update the payout status. Track it by polling, or (preferred) by receiving webhooks at yourcallback_url.
Payout statuses
A payout moves through these states:
Treat
SUCCESS as the only success state. Always confirm final status via a status lookup or webhook: don’t assume success from the finalize response alone.
Full worked example (offchain)
Use a signed-request helper that sets theX-Auth-* headers for each call. Create a quote with the body below, attach the beneficiary, finalize, and track by reference, reusing one reference throughout.
Webhooks
If you setcallback_url when initializing, we send a notification to that URL whenever the payout’s status changes. Best practices:
Respond quickly with a 2xx. Do heavy processing asynchronously.
Be idempotent. The same event may be delivered more than once.
Use your reference to reconcile events against your own records.
Error handling
Errors use standard HTTP status codes with a consistent JSON body. Include thecorrelation_id from the response when contacting support, it identifies the exact request. Responses also carry request_id with the same value.
Go-live checklist
Completed a full sandbox payout end-to-end (SUCCESS status observed).
Signature generation verified for both bodied and empty-body requests.
Store your reference for every payout and reconcile via lookups/webhooks.
Handle PENDING, PROCESSING, SUCCESS, FAILED, and EXPIRED in your system.
Client Secret stored securely (never in client-side code or version control).
Switched from the sandbox secret to the production secret.
Support
Include thecorrelation_id from the failing response and your payout reference when reaching out. Reach your Bitnob integration contact or the support channel provided with your account.