# PaySwitch (theTeller)

> Collect Ghanaian mobile money with PaySwitch theTeller wallet push: the payer approves a prompt on MTN, Telecel or AirtelTigo. Covers credentials and checks.

Source: https://docs.centipidbilling.com/billing/payment-gateways/payswitch

## Collect payments with PaySwitch

`PAYSWITCH` collects through PaySwitch's **theTeller** by **wallet push**. The
payer enters their number on the portal, a prompt appears on their phone, and
they approve it there. They never leave the portal page.

Offered in the country catalog for **Ghana (GH)**, in cedis. An ISP that prices
in another currency is refused at checkout, so a USD 10 plan is never charged as
GHS 10.

Centipid Billing uses two calls from
[theTeller's API](https://theteller.net/documentation):

1. `POST /v1.1/transaction/process` sends the prompt to the payer's number. The
   network (MTN, Telecel, Airtel or Tigo) is picked from the number.
2. `GET /v1.1/users/transactions/{id}/status` reports whether it was paid.

Nothing is credited until the status reads code `000` (approved).

## Configure the gateway

#### Get live credentials from theTeller

Sign in at [dashboard.theteller.net](https://dashboard.theteller.net) and
open **My Account** for your merchant ID, API user and API key. Live keys
come from theTeller support once your account is approved.

#### Open Settings → Payments → PaySwitch in Centipid

Enter the **Merchant ID**, **API user** and **API key**.

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

## Credentials

| Field | Required | Notes |
|---|---|---|
| Merchant ID | Yes | Starts with `TTM-`. |
| API user | Yes | Sent with the API key as HTTP Basic authentication. |
| API key | Yes | Stored encrypted. Only live keys work: Centipid always calls theTeller's live host, and a test key is refused there. |

## No callback URL

theTeller sends no callback for a wallet push, so there is nothing to paste into
its dashboard. Centipid checks the payment's status every 5 seconds for about 3
minutes after the prompt is sent, and only that check credits a payment.

## Troubleshooting

- **"Unable to send the PaySwitch payment prompt"**: theTeller refused the
  request, usually because a credential is wrong. Its exact response is in the
  application log.
- **"Enter a Ghanaian mobile number"**: the number is not a `233…` mobile
  number.
- **"PaySwitch takes MTN, Telecel and AirtelTigo numbers"**: the number's prefix
  belongs to no network theTeller charges. A number moved to another network
  keeps its old prefix and gets its prompt on the wrong one.
- **"PaySwitch bills in GHS"**: the ISP's prices are in another currency.
  Contact Centipid support to change it.
- **The payer approved after about 3 minutes and was not connected**: the
  status check had stopped. Find the payment in theTeller's dashboard and record
  it manually.
