> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iotec

> Configure Iotec Pay collections for Ugandan mobile money.

# 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

<Steps>
  <Step title="Open Settings → Payments → Iotec">
    Select Iotec from the payment marketplace.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Enter the API secret">
    **Iotec API secret** (required) is stored as a secret and is not echoed back
    into the form after saving.
  </Step>

  <Step title="Save and switch">
    All three fields must be present to switch.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.
</Note>

## 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

<Steps>
  <Step title="Request">
    Centipid Billing authenticates against Iotec (the access token is cached for
    just under five minutes) and posts the collection.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Authorization">
    The payer approves on their handset.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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](/billing/payment-gateways/troubleshooting). |

For every gateway's fields in one place, see the
[credential reference](/billing/payment-gateways/credentials-reference).