# PayHero

> Collect Kenyan M-Pesa with PayHero: the payer approves an STK prompt on their phone and the money goes to your own PayHero channel. See credentials and errors.

Source: https://docs.centipidbilling.com/billing/payment-gateways/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](https://docs.payhero.co.ke/):

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

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