Integration status

Payment API guide

Collect Uganda mobile money from Collections & wallet or through a server-side API key. Read this guide here, copy it for your developer, or open the plain-text version for an LLM.

Open plain-text guide for LLMs
Live payment prompts

Collections send a real prompt to the payer. The wallet is credited only after ioTec confirms success. Withdrawals are requests for manual review; submitting one does not send money.

Collection rules

Enter the UGX amount the merchant should receive. Billwebb adds YakaApp's 1% app charge and a withdrawal reserve of UGX 600, 1,200, 2,000 or 2,400 according to amount. ioTec charges its 4% separately to the payer. The merchant wallet receives the requested UGX amount after confirmation. Keep the API key private on your server.

API endpoints

Use https://billwebb.admin.yakani.org as the base URL. Create an API key in Collections & wallet and store it on your server. Never paste it into an LLM prompt or put it in browser code.

  1. POST /api/v1/transactions with x-api-key and a unique Idempotency-Key header (12–100 letters, numbers or hyphens). Amount is the merchant's UGX credit before charges; minimum UGX 500.
  2. GET /api/v1/transactions?reference=BW-… to verify final status. Only success means paid; a sent prompt is pending.
  3. GET /api/v1/merchant-wallet with the same key to view the confirmed UGX balance.

Create a collection

curl -X POST 'https://billwebb.admin.yakani.org/api/v1/transactions' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
  -H 'Idempotency-Key: order-123456789' \
  -d '{"amount":50000,"phone":"0771234567","payerName":"Customer"}'

Check its status

curl 'https://billwebb.admin.yakani.org/api/v1/transactions?reference=BW-YOUR_REFERENCE' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY'

These are live requests. Replace the placeholders with your own private key and reference. Do not run the collection example against a real phone just to test the guide.

Withdrawals

Choose MTN/Airtel mobile money or a bank account. The requested amount is deducted from your UGX wallet; the recipient receives that amount minus the flat fee shown on the withdrawal form. Submit your ID, business and phone in Verification and have them approved before any withdrawal. Bank payouts additionally require approval of the exact bank account. Requests are reviewed and paid manually. Funds are held when requested and released if rejected.

For developers and LLM tools

Read the complete plain-text API guide for response shapes, error codes, idempotency and payment verification. Copy the full guide above and paste it into your coding assistant without your secret key.

Back to Billwebb