Payouts API — Integration Guide

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:

Authenticate → Create quote → Add beneficiary → Finalize → Fund → Track to completion

1. Account setup

1.1 Create your account

Visit https://app.bitnob.com/ and create an account with the company name of your choice. Once you're set up, let us know on Slack immediately so the compliance team can enable your account for payouts.

From the home page, open the Settings page and click API Keys. There you'll obtain:

1.3 Whitelist your IP

For extra security, whitelist your server's IP address before going live. In the dashboard, go to Settings → IP (bottom-left of the vertical navigation), or use this shortcut: http://app.bitnob.com/settings?section=ip&view=endpoints

Requests from non-whitelisted IPs will be rejected once whitelisting is enabled.

2. Authentication

All API requests are made against the Bitnob base URL https://api.bitnob.com and authenticated with an HMAC-SHA256 signature. You sign each request with your Client Secret and send four headers. Both your CLIENT_ID and CLIENT_SECRET are required. Signatures are time-limited, so requests can't be replayed.

2.1 Required headers

2.2 How to build the signature

1. Build the payload string by joining four parts with colons:

2. Sign it with your Client Secret using HMAC-SHA256 and hex-encode the result:

2.3 Signing example (bash)

2.4 Signing example (Node.js)

2.5 Common auth errors

3. 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.

4. 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 (returns the resolved account name):

For mobile-money destinations, pass type=mobile_money and use the mobile-money provider as the bank_code (e.g. MTN). The account_number is the recipient's phone number in international format.

Example response:

Check is_verified is true and confirm account_name is who you expect before continuing. (For mobile money, bank_code / bank_name may come back empty.)

5. The payout flow

Step 1 — Create a quote

Locks in the exchange rate and fees for your payout.

Request:

Response — the created quote is returned under data.payout. Note the status is QUOTE and it carries a short expires_at, so continue promptly.

Key response fields:

Another example — Ghana (GHS)

Request:

Response:

Step 2 — Add the beneficiary (initialize)

Attach the recipient's details to the quote. The exact beneficiary fields depend on the country (see the reference lookup in Section 4).

Request:

Response — the payout moves to status PENDING_ADDRESS_DEPOSIT and, for onchain funding, returns the address to pay. For chain: lightning this is a BOLT11 Lightning invoice (lnbc…); pay it to fund the payout.

The address field is your funding instruction — pay it in Step 4 before expires_at:

Another example — Ghana mobile money (GHS)

For mobile money, the beneficiary uses the recipient's phone number as account_number and has no bank_code.

Request:

Response:

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.

Confirms the payout and submits it for settlement.

Step 4 — Fund the payout

Response:

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.

Example response (single payout):

The list endpoint returns the same objects inside a data.payouts array along with pagination fields (limit, offset, total).

6. Payout statuses

A payout moves through these states (status values are upper-case):

Treat COMPLETED as the only success state. Always confirm final status via a status lookup or webhook — don't assume success from the finalize response alone.

7. Full worked example (onchain)

8. Webhooks

If you set callback_url when initializing, we send a notification to that URL whenever the payout's status changes.

Example webhook payload (sent to your callback_url):

The event reflects the new state, e.g. payout.processing, payout.completed, or payout.failed (a failed event includes a reason). Field names above are illustrative — always key your logic off status and your own reference.

Best practices:

9. Error handling

Errors use standard HTTP status codes with a consistent JSON body:

Include the request_id from the response when contacting support — it helps us trace the exact request.

10. Go-live checklist

Support

Include the request_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.