One payment API for Paystack, PayHero and M‑Pesa

How it works

1. Register a business, then add the provider credentials you already hold (Paystack, PayHero and/or M‑Pesa).
2. Create a scoped API key for the environment you are integrating against (nup_test_… or nup_live_…).
3. Create a payment intent with the amount, currency and method. NunuaPay selects an eligible configured provider.
4. Send the customer to the returned checkoutUrl (hosted checkout) or let an STK push prompt them on their phone.
5. NunuaPay verifies the outcome server-side and notifies your app with a signed webhook.

Supported providers and methods

Support depends on the provider you have configured for your business. Enabling an integration does not automatically enable a method or provider for a given business.

Paystack

Card, bank transfer, mobile money and USSD. Currencies KES, NGN, GHS, ZAR, USD. Hosted checkout. Refunds including partial refunds.

PayHero

M‑Pesa mobile money (STK push). Currency KES. Server callback. No refunds.

M‑Pesa (Daraja)

M‑Pesa mobile money (STK push). Currency KES. Server callback. No refunds.

PayPal & Stripe

Not implemented. They are not available for payment processing in NunuaPay today.

Core concepts

Business and branch identifiers

A Business ID identifies your tenant. A Branch ID identifies a location inside exactly one business. Provider credentials are configured once per business and inherited by branches; method availability can be overridden per branch.

Test and live credentials

API keys are environment-scoped. Test keys operate against provider test environments; live keys move real money. NunuaPay never returns key secrets after creation.

Idempotency

Payment and refund creation require an Idempotency-Key header. Repeating an identical request returns the original resource instead of creating a duplicate; reusing a key with a different body returns 409 idempotency_conflict.

Create a payment

curl -X POST https://pay.nunuanow.com/v1/payment-intents \
  -H "Authorization: Bearer nup_live_<lookup>_<secret>" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "<businessId>",
    "method": "card",
    "amount": 1500,
    "currency": "KES",
    "email": "customer@example.com",
    "merchantRef": "ORDER-1001"
  }'

amount is an integer in minor units (whole shillings for KES). A successful creation only means the payment was initiated — it never implies the payment succeeded. See the documentation for the full reference.

Verify status, never trust the browser

Always confirm the outcome with GET /v1/payment-intents/:id/verify or the signed webhook. The hosted-checkout return page re-checks the transaction server-side and shows a pending, success or failure state, polling while a payment is still pending.

What NunuaPay does not do

• It does not provide PayPal or Stripe processing, or recurring/subscription billing.
• It does not store card data; card payments are handled by the provider’s hosted flow.
• It does not move a provider’s credentials between businesses — credentials stay business-scoped.

Explore further