PayHero integration

What this integration supports

Methods

M-Pesa mobile money (STK push).

Currency

KES.

Country

Kenya (KE).

Checkout

No hosted URL. The customer confirms the prompt on their phone (STK push).

Webhooks

PayHero posts a server callback. NunuaPay treats the callback as untrusted and re-verifies.

Refunds

Not supported by PayHero.

Status query

Yes — NunuaPay can query PayHero for the transaction status.

How to configure it

1. In Providers, add a PayHero account for your business.
2. Enter the credentials from your own PayHero dashboard and select the environment.
3. Confirm the callback base URL is reachable from PayHero.

Payment initiation flow

1. Create a payment intent with method: "mobile_money" and the customer’s phone number.
2. NunuaPay asks PayHero to send an STK push to that number.
3. The customer confirms in M-Pesa. The payment stays pending / processing until confirmed.
4. PayHero calls NunuaPay; NunuaPay verifies and notifies your endpoint.

Callbacks and verification

PayHero does not sign its callbacks, so a callback alone is never enough to mark a payment paid. NunuaPay correlates the callback to the payment attempt and verifies the status before completing the payment, then sends you a signed payment.succeeded or payment.failed event.

Common errors

• Invalid phone number — use an MSISDN in international format (e.g. 2547XXXXXXXX).
• Request cancelled by user — the customer dismissed the STK prompt; treat the intent as failed and allow a retry.
• Duplicate reference — reuse the same Idempotency-Key for retries instead of sending a new request.

Related