If your business sends SMS every day, running out of credits at the wrong moment is painful. A reminder does not go out, a customer waits for a code, and someone has to log in, pay, and wait. The Yoola SMS Top-up API removes that step: your own app, website or system starts the payment, and the credits are added to your account automatically.
How it works
- Your server asks Yoola SMS to start a payment: the amount in UGX and the MTN or Airtel number that will pay.
- That phone gets a Mobile Money prompt and the person approves it with their PIN.
- Yoola SMS confirms the payment with the mobile money network and adds the credits to your account.
- Your server asks for the status and sees
successful.
The money goes straight to Yoola SMS through our payment partner, and you never have to open the dashboard.
What it looks like
One request starts the payment:
POST https://yoolasms.com/api/v1/topup
{"api_key":"YOUR_KEY","amount":50000,"phone":"0771234567","client_ref":"INV-1001"}A second request checks the result:
GET https://yoolasms.com/api/v1/topup-status?api_key=YOUR_KEY&client_ref=INV-1001The full details, error codes and code examples in PHP, Node.js and Python are in the Top-up API documentation.
Built to be safe
- Retries never charge twice. Every payment carries your own reference. Send the same reference again and you get the original payment back, not a second prompt.
- Credits only after confirmation. We check every payment with the mobile money network before adding anything.
- Limits protect you. There are caps on the amount per payment, on prompts per hour and per day, and on how many can wait for approval at once, so a bug in a loop cannot spam your customers' phones.
- Approved accounts only. The API is switched on for each account after we review the request.
Who it is for
- Schools, SACCOs and companies whose systems send SMS all day and should never run dry.
- Software companies and resellers that top up credits for many clients from their own platform.
- Anyone who would rather their finance team pay once in their own system than log in to a dashboard.
Good to know
- It works for Uganda (UGX) accounts, with MTN and Airtel Mobile Money.
- The payer pays the amount plus a 0.5% mobile money fee. Sending 50,000 charges the phone 50,252, and 50,000 is added to your balance.
- For very large amounts, such as a lump-sum deposit, a bank transfer is cheaper and avoids mobile money limits. Just ask us.
- Call the API from your server only, and keep your API key private.
How to get access
- Create a Yoola SMS account if you do not have one.
- Fill in the short request form with your account email and how you will use it.
- We review it, usually within 1 to 2 working days, and email you the decision. If approved, the email links to the documentation and you can test with as little as UGX 2,500.
Questions? Write to support@yoolasms.com or call +256 704 487 563.
Comments (0)