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 and recent withdrawal status.
  4. POST /api/v1/merchant-withdrawals with the same key and a new Idempotency-Key to request a verified withdrawal.

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

Withdrawals are available from the dashboard and API. First have your identity, business, phone, and payout destination approved. Mobile-money withdrawals start at UGX 901 and bank withdrawals at UGX 7,501. The requested amount is held from the UGX wallet; the recipient receives that amount minus the displayed fee. Every request is manually reviewed and paid. Rejected requests release the held funds.

Request a mobile-money withdrawal

curl -X POST 'https://billwebb.admin.yakani.org/api/v1/merchant-withdrawals' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
  -H 'Idempotency-Key: withdrawal-123456789' \
  -d '{"amountUgx":50000,"method":"mobile_money","phone":"0771234567"}'

Use method: "bank" with bankName, accountName, and accountNumber for a previously approved bank account. Reusing the same idempotency key with the same details returns the original request; using it with different details returns HTTP 409.

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