# FimiPay

> Collect Tanzanian mobile money with FimiPay wallet push: the payer approves a PIN prompt on M-Pesa, Airtel, Mixx by Yas or HaloPesa. Covers keys and webhook.

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

## Collect payments with FimiPay

`FIMIPAY` 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)**, in Tanzanian shillings. An
ISP that prices in another currency is refused at checkout, so a USD 10 plan is
never charged as TZS 10.

Centipid Billing uses two calls from
[FimiPay's Merchant API](https://docs.fimipay.com/docs/):

1. `POST /payment/create_order` sends the PIN prompt to the payer's number.
2. `POST /payment/order_status` reports whether it was paid.

Nothing is credited until the status reads `COMPLETED` or `SUCCESS`.

## Configure the gateway

#### Get a live key from FimiPay

Register at [fimipay.com](https://fimipay.com) as a Developer, complete
verification, then generate a live key in **Dashboard → API Keys**. FimiPay
shows it only once.

#### Open Settings → Payments → FimiPay in Centipid

Enter the **Live secret key**. Copy the **Webhook URL** shown on that page.

#### Set the webhook in FimiPay

Paste the URL in FimiPay's **Settings → Webhooks**, in the live slot, then
copy its secret into **Webhook secret** in Centipid.

#### 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 |
|---|---|---|
| Live secret key | Yes | Starts with `sk_live_`. Sent as a Bearer token from Centipid's servers only. Test keys (`sk_test_`) are refused, because they never send a prompt or take money. |
| Webhook secret | Yes | Checks the `X-Fimipay-Signature` on FimiPay's webhook. Without it every webhook is refused. |

## Webhook URL

The settings page shows `/api/fimipay/callback` on the ISP's domain. The webhook
only tells Centipid to look sooner: 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.

FimiPay's prompt can wait up to 7 minutes, and a network can confirm a payment
after the order was cancelled. Those late payments reach Centipid only through
the webhook, so it has to be set. If the ISP's domain changes, paste the new URL
into FimiPay.

## Fees

FimiPay publishes 2% on mobile money collections in Tanzania, deducted from the
amount paid, with no setup or monthly fee. Check
[FimiPay's pricing](https://docs.fimipay.com/docs/#pricing) for your account's
rate. Your balance is withdrawn from FimiPay's dashboard.

## Troubleshooting

- **"Unable to send the FimiPay payment prompt"**: FimiPay refused the request,
  usually because the key is wrong or revoked. Its exact response is in the
  application log.
- **"Enter a Tanzanian mobile number"**: the number is not a `255…` mobile
  number.
- **"FimiPay bills in TZS here"**: the ISP's prices are in another currency.
  Contact Centipid support to change it.
- **"Use your FimiPay live key"**: the key pasted into settings is a test key.
- **Paid, but connected only after several minutes, or not at all**: check the
  webhook URL and secret in FimiPay. FimiPay's **System events** page can resend
  the last 7 days of notices that never arrived.
