Getting Started
1. How do I set up my API credentials? Log in to the payment portal and navigate to Workspace -> API Keys. Select Create New Integration and proceed to generate the credentials. Full guide: Getting Your API Credentials. 2. What countries are available to me? All countries listed in Supported Countries are available in the sandbox environment with the supported methods. Only the countries you select during onboarding are enabled in production. 3. How do I access test funds in the sandbox environment? Request a top-up of the specific currencies you want to test by emailing support@niobi.co. 4. Can I reuse the same signature across multiple requests? No. Every request must carry its own uniquely generated signature, computed from that request’s exact timestamp, salt, and parameters. Signatures cannot be reused, even for retries of the same logical action. See Authentication Basics.Errors & Status Codes
5. What does status code “000005” mean, and what should I check first?000005 means the request was rejected or the transaction failed. In sandbox, first confirm you’re using a valid test phone number for that country (Testing Guide), and that your country_id, currency, and payment_method_type are all correct for that channel.
6. Does a validation error mean my transaction actually failed?
No, these are two different things. A validation error (for example, a missing required field) means Niobi rejected the request before any transaction was created, so there’s nothing to reconcile. A real transaction failure is a terminal callback with payment_step: 2, status: "failed", and status_code: "000005". See Understanding Payment Steps. Treat these as categorically different: one means “fix your request,” the other means “the transaction ran and didn’t succeed.”
7. What do the transaction status codes 000000 / 000001 / 000005 / 000006 mean, and which ones are final?
000000 (success) and 000005 (failed) are terminal, treat them as the final word. 000001 (pending) and 000006 (timeout) are not terminal, so don’t act on them, just wait or re-query. Full breakdown: Status Codes & Action Matrix.
8. Why do some responses use status_code and others statusCode?
It depends on where you’re reading the response from, not random inconsistency. status_code (snake_case) appears at the root of direct, synchronous API responses: the initial response you get back right after submitting a collection or payout, and the response from querying transaction status. statusCode (camelCase) appears only inside params in asynchronous webhook callbacks (payment_step: 2 notifications). If you’re parsing a webhook payload, check params.statusCode. If you’re parsing a direct API response, check status_code.
9. What do I do when I encounter “You are restricted to access the site. Contact Niobi support for further information.”?
Your IP address hasn’t been whitelisted yet. If your account is already approved, you can whitelist your own IPs directly in the portal under Workspace -> IP Whitelisting -> Add New, no need to contact support. If your account hasn’t been verified/approved yet, email your sandbox and production IPs to support@niobi.co instead. Full guide: IP Whitelisting.
Confirming a Transaction Really Completed
10. How do I know a transaction is really done, not just acknowledged?payment_step: 1 on the initial response only means “accepted for processing,” don’t act on it yet. Wait for the terminal payment_step: 2 callback, then independently verify with POST /api/v3/get-unified-transaction-status, and only mark the transaction complete once both agree. Full recipe: Collections Best Practices and Payouts Best Practices.
11. Is /api/v3/get-unified-transaction-status deprecated in favor of a v4 endpoint?
No. Unlike collections and payouts, transaction status intentionally stays on v3, there’s no v4 version and none is planned. It’s a synchronous, direct status check outside the async payment flow, which is also why payment_step doesn’t appear in its response. See Transaction Status.
12. Is the API ever going to become synchronous?
No, this is intentional, not a current limitation. The underlying settlement process with mobile network operators and banks is inherently asynchronous, so callbacks and status polling are how you get the final result, not a workaround pending a future synchronous option.
Payouts
13. Do I need to approve payouts with OTP when using the API? No. OTP approval only applies to payments initiated manually through the payment portal. It never applies to payments sent via the API. 14. What’s the difference between M-Pesa PayBill and Till Number payouts?"pay bill" sends to a business PayBill account (requires a paybill array with paybill_number and account_number). "till number" sends to a Buy Goods till (requires a tillnumber array with just till_number). See the full method table on Kenya’s country page.
15. Is there an API to retrieve my sub_merchant_id?
No, there’s currently no endpoint to list or fetch sub-merchant IDs programmatically. Look them up in the Dashboard’s Sub-Merchant list after onboarding. See Sub-Merchant Management.