# PlusPesa

> Collect Tanzanian mobile money with PlusPesa wallet push: the payer approves a PIN prompt on M-Pesa, Tigo Pesa, Airtel or HaloPesa. Covers keys and callbacks.

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

## Collect payments with PlusPesa

`PLUSPESA` 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)**. PlusPesa works out the
network from the number, so payers on Vodacom M-Pesa, Tigo Pesa, Airtel Money,
HaloPesa and AzamPesa can all pay.

Centipid Billing uses two calls from PlusPesa's
[Collections API](https://docs.pluspesa.com/):

1. `POST /api/v1/collections` sends the PIN prompt to the payer's number.
2. `GET /api/v1/collections/{reference}/status` reports whether it was paid.

Nothing is credited until the status reads `success`.

## Configure the gateway

#### Get an API key pair from PlusPesa

Register a merchant account at [pluspesa.com](https://pluspesa.com) and
copy the public and secret keys from the dashboard.

#### Open Settings → Payments → PlusPesa in Centipid

Enter the **Public key** and **Secret key**. Add the **Callback secret**
too if PlusPesa gave you one.

#### 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 |
|---|---|---|
| Public key | Yes | Sent as `X-Public-Key`. |
| Secret key | Yes | Sent as `X-Secret-Key`, from Centipid's servers only. |
| Callback secret | No | Checks the `X-PlusPesa-Signature` on PlusPesa's webhook. When set, unsigned or wrongly signed webhooks are refused. |

## Callback URL

Nothing to paste. Centipid sends `/api/pluspesa/callback` on the ISP's domain
with every payment request. The webhook only tells Centipid to look sooner:
Centipid also 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 PlusPesa payment prompt"**: a key is wrong or revoked.
  PlusPesa's exact response is in the application log.
- **"Enter a Tanzanian mobile number"**: the number is not a `255…` mobile
  number.
- **The payer paid but did not connect**: search the payment by PlusPesa's
  reference (`col_…`), shown in the PlusPesa dashboard.