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

# Selcom

> Configure Selcom wallet push for Tanzanian mobile-money collection.

# Collect payments with Selcom

`SELCOM` collects by **wallet push**. The payer enters their number on the
portal, a PIN prompt appears on their phone, and they approve it there. They
never leave the portal page.

Offered in the country catalog for **Tanzania (TZ)**.

Centipid Billing uses three calls from Selcom's
[Checkout API](https://developers.selcommobile.com/#checkout-api):

1. `create-order-minimal` opens an order for the amount.
2. `wallet-payment` sends the PIN prompt for that order to the payer's number.
3. `order-status` reports whether the order was paid.

Nothing is credited until `order-status` reports the order `COMPLETED`.

## Before you start

Ask Selcom's business team for Checkout API access on an account owned by the
ISP. They issue three values: a **Vendor ID** (the till, often starting with
`TILL`), an **API key**, and an **API secret**. Selcom's public docs list no
test environment. If you want to test before going live, ask Selcom for test
keys and the test host that goes with them.

## Configure the gateway

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

  <Step title="Enter the Vendor ID, API key, and API secret">
    All three are required. The key and secret are stored as secrets.
  </Step>

  <Step title="Enter the API host, only if Selcom gave you one">
    Leave **API host** blank for Selcom's live gateway
    (`https://apigw.selcommobile.com`). Enter the test host here while testing,
    then clear it when you switch to live keys.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal, approve the prompt on the
    phone, and confirm the payment reaches the ledger.
  </Step>
</Steps>

## Credentials

| Field | Required | Notes |
| - | - | - |
| Vendor ID | Yes | The till Selcom settles into. |
| API key | Yes | Sent, base64-encoded, on every request. |
| API secret | Yes | Signs every request and checks Selcom's webhook. Never sent. |
| API host | No | Blank means the live gateway. Must be `https://`. Changing it needs the same verification as a credential change. |

## Callback URL

There is nothing to paste into Selcom. Every order carries its own webhook
(`/api/selcom/callback`) on the ISP's domain.

Selcom calls the webhook only when a payment succeeds. So Centipid also asks
Selcom for the order's status every 5 seconds for about 3 minutes after the
prompt is sent. That check is what connects the payer, and what tells the
portal when a payer declined the prompt. A webhook whose signature does not
match the API secret is rejected.

## Troubleshooting

* **"Unable to send the Selcom payment prompt"**: the Vendor ID, API key, or
  API secret is wrong, or the account has no Checkout API access. Selcom's
  exact response is in the application log.
* **No prompt arrives**: check the number is a Tanzanian mobile-money number.
  Selcom only accepts it as `255…`, and Centipid converts `07…` numbers
  automatically.
* **The payer paid but did not connect**: search the payment by the
  transaction ID on their receipt. Payments are stored under Selcom's
  transaction ID.