PayHero
Collect payments with PayHero
PAYHERO collects by M-Pesa STK 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 Kenya (KE), in Kenyan shillings. An ISP that prices in another currency is refused at checkout, so a USD 10 plan is never charged as KES 10. The money goes to your own PayHero payment channel; Centipid never holds it.
Centipid Billing uses two calls from PayHero’s API:
POST /api/v2/paymentssends the STK prompt.GET /api/v2/transaction-statusreports whether it was paid.
Nothing is credited until the status reads SUCCESS.
Configure the gateway
Get your API credentials and channel ID from PayHero
In the PayHero dashboard, create API credentials (an API username and password) and note the ID of the payment channel that should receive the money.
Open Settings → Payments → PayHero in Centipid
Enter the API username, API password and Channel ID. There is no URL to paste into PayHero: Centipid sends its callback URL with each payment.
Run a controlled test payment
Pay KES 10 from the captive portal, approve the prompt on the phone, and confirm the payment reaches the ledger.
Credentials
| Field | Required | Notes |
|---|---|---|
| API username | Yes | Sent as HTTP Basic authentication from Centipid’s servers only. |
| API password | Yes | Stored encrypted. Left blank on save, the stored one is kept. |
| Channel ID | Yes | The number of the PayHero channel that receives the money. |
Callback
Each payment carries /api/payhero/callback on the ISP’s domain as its
callback URL, so a domain change needs nothing in PayHero. PayHero does not
sign its callbacks, so Centipid never credits from one: the callback only makes
Centipid ask PayHero for the payment’s status sooner. Centipid also checks the
status every 5 seconds for about 3 minutes after the prompt is sent. A payment
is credited once, however many callbacks arrive.
Troubleshooting
- “Unable to send the PayHero payment prompt”: PayHero refused the request, usually because the credentials or channel ID are wrong. Its exact response is in the application log.
- “Enter a Kenyan mobile number”: the number is not a
2547…or2541…number. - “PayHero bills in KES here”: the ISP’s prices are in another currency. Contact Centipid support to change it.
- A payment stays pending after the payer approved it: PayHero did not answer the request that sent the prompt, so Centipid has no PayHero reference to check it with. Don’t ask the payer to pay again: the first payment is not lost, only unconfirmed. Find the M-Pesa receipt in the PayHero dashboard and record the payment manually. A payment PayHero still reports as queued is re-checked after 10 and 30 minutes and credited if it succeeds.
