Skip to content

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:

  1. POST /api/v2/payments sends the STK prompt.
  2. GET /api/v2/transaction-status reports whether it was paid.

Nothing is credited until the status reads SUCCESS.

Configure the gateway

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

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

  3. 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… or 2541… 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.