Skip to main content
This guide walks you through everything needed to send a payout, from authenticating your first request to confirming that funds have reached your beneficiary. A payout delivers local fiat (e.g. NGN, KES, GHS) to a beneficiary’s bank or mobile-money account, funded from crypto. You create payouts through a simple, quote-based flow. The authentication scheme on this page is a summary. API authentication is the source of truth for the signing spec.

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 use https://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.
Sign the body byte-for-byte as it is sent. If you re-serialize or reformat the JSON after signing, the signature will not match.

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.
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 a quote_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 exact beneficiary 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. For offchain 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 your callback_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 the X-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 set callback_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 the correlation_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 the correlation_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.