Authentication

Payment & status (public key)

For initiate payment, transaction status, virtual accounts — public key only.

Transfers & merchant wallets

Both X-API-Key and X-API-Secret. Server-side only.

JWT (dashboard / webhooks)

POST /auth/login then Authorization: Bearer <token>

Base URL

Use sandbox keys with the sandbox host for testing.

Response format

Responses include status, responseCode, and data or message.

See the example response on the right.

API console

Send real requests from the browser. Keys stay in sessionStorage for this tab.

Initiate payment

Call from your backend. Returns paymentUrl — open in popup or iframe.

Headers: Content-Type: application/json, X-API-Key

Body: amount, email, currency, optional accountNumber (omit = default wallet; pass per checkout for multiple wallets or from your app’s .env), idempotencyKey, metadata.

Popup integration

Open paymentUrl, poll GET /pay/session/:sessionId/status every ~3s, or listen for postMessage with paybitt_success.

Webhook payment.completed also fires on success.

Verify recipient account

Resolve account holder name before payout.

Headers: X-API-Key, X-API-Secret, Content-Type: application/json

Body: bankCode or network (2=MTN, 3=AirtelTigo, 4=Vodafone), plus accountNumber.

Single payout

Headers: public + secret keys.

Body: recipient accountNumber, accountName, amount, currency, network or bankCode, idempotencyKey, optional sourceAccountNumber (merchant wallet to debit).

Fees: Debit = amount + fee. Fee depends on route — mobile money (network) uses the transfer structure; bank (bankCode) uses bank_transfer. Preview public fee tiers with GET /reference/fees before calling payout.

Bulk payout

recipients array; each row needs amount, account details, and MoMo network or bankCode. Optional sourceAccountNumber.

Fee per row follows the same MoMo vs bank rules as single payout — see GET /reference/fees.

Transfer status

reference is disb_… or bulk_…. Requires public + secret headers.

Statuses: pending, processing, completed, partially_failed, failed.

Get networks

Header: X-API-Key. Query: countryCode (from GET /settings/countries).

Use each network’s value in payment/transfer requests.

Get banks

Header: X-API-Key. Returns code for use as bankCode.

Transfer fees (mobile money & bank)

Use this before single or bulk payouts. Header: X-API-Key (public key identifies the merchant).

Merchant lookup (recommended)

Call without countryId. The API resolves your business from X-API-Key and returns:

• feeExempt — if true, no PayBitt fees apply for the merchant.
• adminFees — default tiers for MoMo (transfer) and bank (bank_transfer) for your currency.
• customFees — per-wallet overrides (by accountNumber) when configured; otherwise admin tiers apply for that wallet.

Optional query: currency (defaults to your business country currency, else GHS), type = transfer or bank_transfer to narrow rows.

For one wallet’s full fee table (admin rows, custom rows, and resolved effective fees per transaction type), use GET /reference/account-fees.

Country lookup (legacy)

?countryId=<UUID>&currency=GHS — raw admin fee rows for that country only (no merchant-specific or custom pricing). Same optional type. Use only if you need generic country tables; integrations should prefer merchant lookup.

Wallet fee snapshot

Returns everything needed to mirror PayBitt fee rules for a single wallet in your own app (e.g. sync into your user database). Header: X-API-Key only (same as GET /reference/fees).

Query

• accountNumber — required. The PayBitt wallet number (e.g. from POST /merchant/wallets or list).

Scope

The wallet must belong to the merchant linked to your key, and the key’s environment must match the wallet: test keys only resolve test wallets; live keys only live wallets. Inactive wallets are still returned so you can read fee metadata.

Response (data)

• wallet — id, accountNumber, accountName, currency, environment, isActive
• feeExempt — merchant-wide; if true, PayBitt charges no fees on any wallet
• adminFeeSettings — all admin fee rows for the merchant’s country
• customFeeSettingsForWallet — custom_fees rows for this account number
• effectiveFees — one row per transaction type (payment, transfer, internal, bank_transfer) in the wallet’s currency, with resolution: fee_exempt | custom | admin | none, plus percentage, caps, and tier fields (same logic as live charging)
• note — short explanation of resolution order

Transaction history

Query: from, to, limit, offset. Public key only.

Transaction status

Works for txn_…, disb_…, bulk_…, or metadata orderId. Public key.

Merchant wallets

Create extra balance accounts; each gets a unique accountNumber. Test keys only create test wallets; live keys only live.

Create

Headers: public + secret. Body: accountName, currency (3 letters).

List

Get one

Check balance

Optional query accountNumber. Defaults to default account for key environment.

Account information

Default account for the key’s environment (test/live).

Virtual accounts

Generate virtual account numbers for receiving payments. See dashboard for full fields.

Webhooks

Configure a callback URL. Verify X-PayBitt-Signature (HMAC-SHA256).

Events: payment.completed, transfer.completed

cURL examples

Every endpoint in the sidebar has a Shell snippet on the right. Copy from there or use the API console to run requests live.

Replace pk_test_xxx / sk_test_xxx with your keys and use the sandbox base URL while testing.