General & Account Management
Q: How do I verify my account to remove team and app restrictions?
A: After verifying your email, your account is initially limited to one team and one application. To fully verify your account and lift these restrictions (allowing up to 5 teams and apps), one of your applications must interact with the API in a production capacity, such as sending a live SMS or performing an airtime top-up.
Q: What is the difference between my "Stash" and my "Wallet"?
A: The AT Stash is your primary application balance used to pay for operational costs like SMS, Voice, USSD, and Airtime fees. The Payments Wallet is a separate balance used specifically for funds being moved via Payment products (e.g., B2C disbursements or B2B transfers).
Q: How do I top up my account using M-Pesa B2B (Kenya)?
A: You can top up by initiating a B2B request to Paybill 525900. Use the account number your_username.api to credit your stash, or walletXXXX (where XXXX is your wallet code) for your payment wallet. Ensure you use the BusinessPaybill command ID for automatic crediting.
Q: How do I handle the "UserInBlackList" error in Kenya?
A: This occurs if a user has opted out of marketing messages. To whitelist a number, the user must dial *456*9# on their handset, choose Option 5 (Marketing Messages), and select the option to "Activate all promo messages".
SMS Services
Q: Why was I billed for multiple messages when my text was under 160 characters?
A: Standard SMS units are 160 characters using GSM 7-bit encoding. If your message contains a single Unicode character (like an emoji, special symbol, or "smart" quote from a word processor), the entire message switches to 8-bit encoding, which reduces the limit to 70 characters per unit. Hidden characters from rich-text editors can also cause this; using plain-text editors like Notepad++ is recommended.
Q: Can I send SMS to "Do Not Disturb" (DND) numbers in Nigeria?
A: Yes, but only for Transactional messages (OTPs or alerts requested by the user). You must register your Sender ID on a "Transactional Bind," which requires a whitelisting process with telcos that typically takes 2 weeks and specific KYC documentation.
Q: What does the "Risk Hold" error mean?
A: This is a security measure triggered when fraudulent traffic is detected or when a user continues to use the default AFRICASTKNG sender ID after being assigned a personal one. To resolve this, you must acquire and use your own unique Sender ID.
Voice & USSD
Q: What is the difference between a Callback URL and an Events URL?
A: The Callback URL is used to receive requests from the API to determine call logic (e.g., providing XML instructions like Say or Play). The Events URL is used solely for status notifications, such as when a call is ringing, answered, or completed.
Q: Why do my users see "network technical problems" when dialing my USSD code?
A: This generic error indicates that the USSD gateway received an invalid response or a timeout from your server. Ensure your callback URL is publicly accessible, responds within the timeout limit, and that every response is prefixed with either CON (to continue the session) or END (to terminate it).
Q: Can I test Voice features in the Sandbox?
A: No, the Voice sandbox is not currently operational. To test voice functionality, you should request a "Test Number" through your production dashboard.
Payments & Mobile Data
Q: How do I activate Mobile Data on my account?
A: Mobile Data is disabled by default for security reasons. To enable it, you must submit a signed and stamped request on your company letterhead, fill out a contact form, and sign a formal service agreement with the team.
Q: How can I move money from my wallet to my bank account?
A: You can initiate a B2B transaction via the Payments API. Set the destination channel to your bank's paybill (e.g., 247247 for Equity Bank) and the destination account to your specific bank account number.
Q: How do I download the SDK if I am using shared hosting?
A: Shared hosting often restricts the use of package managers like Composer. The solution is to install the SDK in a local "vendor" folder using Composer first, and then upload the entire zipped project (including the vendor folder) to your hosting server.