Iotec

Collect payments with Iotec

IOTEC collects Ugandan mobile money through Iotec Pay. Centipid Billing posts a collection request, the payer authorizes it on their handset, and the subscriber is provisioned once Iotec reports the collection successful.

Available to ISPs in Uganda (UG), alongside Centipid Collections, MTN MoMo, PawaPay, PesaPal, and DPO.

Before you start

1. Complete Iotec merchant onboarding in an account owned by the ISP.
2. From the Iotec dashboard collect the wallet ID, the client ID, and the API secret.
3. Confirm your workspace has a public HTTPS domain, so Iotec can post results.

Configure the gateway

1. Open Settings → Payments → Iotec

   Select Iotec from the payment marketplace.

2. Enter the wallet and client identifiers

   Iotec wallet ID and Iotec client ID are both required. The wallet ID decides which Iotec wallet the money lands in.

3. Enter the API secret

   Iotec API secret (required) is stored as a secret and is not echoed back into the form after saving.

4. Save and switch

   All three fields must be present to switch.

5. Run a controlled test payment

   Pay a small amount from the captive portal and confirm the prompt arrives, the payment reaches the ledger, and the package is applied.

Credentials

Field	Required	Notes
Iotec wallet ID	Yes	Identifies the collecting wallet.
Iotec client ID	Yes	API client identity.
Iotec API secret	Yes	Secret.

Callback URLs

Settings → Payments shows https://<your-host>/iotec/callback. Confirm it is not blocked by a firewall or WAF rule.

Note

The callback is treated as a hint, not as proof. Centipid Billing re-reads the collection’s status from Iotec before crediting anything, so a callback alone never provisions a subscriber.

What the payer must provide

A Ugandan mobile money number, which receives the authorization prompt. Because authorization happens on the handset, no Iotec domain needs to be added to the captive walled garden.

How a payment completes

1. Request

   Centipid Billing authenticates against Iotec (the access token is cached for just under five minutes) and posts the collection.

2. Acceptance

   Iotec answers with a collection id and a status. Pending, SentToVendor, and Success all count as accepted — the request is on its way to the mobile money vendor and the payer may already have been charged.

3. Authorization

   The payer approves on their handset.

4. Confirmation

   The status is read back from Iotec — by callback, and by a background sweep for collections that never got one. On Success the payment is recorded and the package applied.

Caution

Iotec’s collect response returns only a status and an id — it does not echo back the amount or the phone number that was sent. Reconcile against what Centipid Billing sent, not against the response.

Troubleshooting

Symptom	What it means	What to do
“Failed to authenticate with Iotec”	Iotec rejected the client ID or API secret.	Re-copy both from the Iotec dashboard. Confirm the account is live.
“Payment failed”	Iotec returned a terminal failure for the collection.	Ask the payer to confirm their wallet balance and status, then retry.
“Payment status unknown” or “Error code…”	The request may or may not have reached Iotec.	Do not retry blindly — the payer may already have been charged. Let the status sweep settle it, then check the ledger.
Payment sits pending long after the payer confirms	The terminal status has not been read back yet.	Wait for the sweep. If it stays pending, raise the collection id with Iotec.
Payer charged, service not applied	The status never reached Success locally.	Check the collection on the Iotec dashboard, then see Payment troubleshooting.

For every gateway’s fields in one place, see the credential reference.