API Docs

Creates a new card payment and returns a link to NBC's hosted card-entry page. Your customer enters their card details there, never on your site or ours.

Request headers

Request body fields

Full example

curl -X POST https://accesspay.eopsprimax.com/api/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-07-13-00042" \
  -d '{
    "amount": 5000,
    "currency": "TZS",
    "email": "customer@example.com",
    "redirect_url": "https://your-domain.com/payment-result/"
  }'

Response — 200 OK

{
  "orderReference": "82732295-74f3-421d-a528-e0bacc474ddd",
  "paymentPageUrl": "https://paypage.nbc.ngenius-payments.com/?code=55ca6510320c9525",
  "status": "PENDING"
}

Error responses

Refunds all or part of one of your own paid orders, back to the card the customer paid with. Can be called more than once on the same order for multiple partial refunds, up to the original amount.

Request body fields (all optional)

Full example — refund everything left

curl -X POST https://accesspay.eopsprimax.com/api/v1/payments/82732295-74f3-421d-a528-e0bacc474ddd/refund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "customer requested cancellation"}'

Full example — partial refund

curl -X POST https://accesspay.eopsprimax.com/api/v1/payments/82732295-74f3-421d-a528-e0bacc474ddd/refund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500, "reason": "one item out of stock"}'

Response — 200 OK

{
  "orderReference": "82732295-74f3-421d-a528-e0bacc474ddd",
  "status": "REFUNDED",
  "refundedAmount": "5000.00",
  "totalAmount": "5000.00"
}

Error responses

Creates a new M-Pesa payment — sends an approval prompt directly to the customer's phone. Same endpoint as card, different payment_method.

Request headers

Request body fields

Full example

curl -X POST https://accesspay.eopsprimax.com/api/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-07-13-00043" \
  -d '{
    "amount": 5000,
    "currency": "TZS",
    "payment_method": "mpesa",
    "phone_number": "0712345678"
  }'

Response — 200 OK (once available)

No paymentPageUrl — there's no hosted page, the prompt goes straight to the customer's phone. A message field replaces it.

{
  "orderReference": "a1b2c3d4e5f6...",
  "status": "PENDING",
  "message": "Check your phone to approve the M-Pesa payment request."
}

Error responses

These two endpoints work the same way regardless of payment method — a M-Pesa order and a card order both show up here with a paymentMethod field telling you which is which.

Looks up a single payment you already created, by the reference you got back when creating it.

Full example

curl https://accesspay.eopsprimax.com/api/v1/payments/82732295-74f3-421d-a528-e0bacc474ddd \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "orderReference": "82732295-74f3-421d-a528-e0bacc474ddd",
  "status": "PAID",
  "paymentMethod": "CARD",
  "amount": "5000.00",
  "currency": "TZS",
  "phoneNumber": null,
  "createdAt": "2026-07-13T08:30:47.551072+00:00",
  "updatedAt": "2026-07-13T08:31:02.112904+00:00"
}

Error responses

Returns every payment your platform has ever created here — card and M-Pesa mixed together, newest first, paginated. This is how you'd build your own "payment history" screen.

Query parameters (all optional, add as ?param=value)

Full example

curl "https://accesspay.eopsprimax.com/api/v1/payments?page=1&page_size=25&status=PAID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "count": 42,
  "page": 1,
  "totalPages": 2,
  "hasNext": true,
  "hasPrevious": false,
  "results": [
    {
      "orderReference": "82732295-74f3-421d-a528-e0bacc474ddd",
      "status": "PAID",
      "paymentMethod": "CARD",
      "amount": "5000.00",
      "currency": "TZS",
      "email": "customer@example.com",
      "phoneNumber": null,
      "createdAt": "2026-07-13T08:30:47.551072+00:00",
      "updatedAt": "2026-07-13T08:31:02.112904+00:00"
    },
    {
      "orderReference": "37930c8d-b070-4bbf-9cd8-16891c67fb3d",
      "status": "PENDING",
      "paymentMethod": "MPESA",
      "amount": "1000.00",
      "currency": "TZS",
      "email": null,
      "phoneNumber": "255712345678",
      "createdAt": "2026-07-13T08:46:33.408918+00:00",
      "updatedAt": "2026-07-13T08:46:33.408918+00:00"
    }
  ]
}

Sends money out to someone directly — not tied to any prior payment. Different from a refund: there's no existing order involved.

Request body fields

Full example

curl -X POST https://accesspay.eopsprimax.com/api/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jane Customer",
    "recipient_identifier": "255700000000",
    "amount": 5000,
    "currency": "TZS",
    "reason": "goodwill refund via mobile money"
  }'

Response — 200 OK (once enabled)

{
  "reference": "payout-1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "SENT"
}

Error responses

Same pattern as payments: look up one payout by reference, or list all of your platform's payouts (paginated, supports page/page_size, newest first).

Full example — one payout

curl https://accesspay.eopsprimax.com/api/v1/payouts/payout-1a2b3c4d5e6f7a8b9c0d1e2f \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "reference": "payout-1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "FAILED",
  "recipientName": "Jane Customer",
  "recipientIdentifier": "255700000000",
  "amount": "5000.00",
  "currency": "TZS",
  "reason": "goodwill refund via mobile money",
  "createdAt": "2026-07-14T09:00:00.000000+00:00",
  "updatedAt": "2026-07-14T09:00:01.000000+00:00"
}

Full example — list

curl "https://accesspay.eopsprimax.com/api/v1/payouts?page=1&page_size=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response shape matches the payments list endpoint (count, page, totalPages, hasNext, hasPrevious, results) — results contains objects with the same fields as the single-payout response above.

A common thing to build on your side: a table showing your platform's own payment history, with columns like Reference, Amount, Method, Status, Email/Phone, Created, plus whatever action buttons make sense for you. Note there's no "Platform" column on your side — every row already belongs to you, that column only makes sense on our internal admin view where staff see multiple platforms at once.

Example — JavaScript (fetch)

async function loadMyPayments(page = 1) {
  const res = await fetch(
    `https://accesspay.eopsprimax.com/api/v1/payments?page=${page}&page_size=25`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await res.json();

  // data.results is your row data -- render it into your own table:
  // Reference      -> row.orderReference
  // Amount         -> `${row.amount} ${row.currency}`
  // Method         -> row.paymentMethod
  // Status         -> row.status
  // Email/Phone    -> row.email ?? row.phoneNumber ?? "—"
  // Created        -> new Date(row.createdAt).toLocaleString()
  // Actions        -> whatever your own UI needs
  return data;
}

Example — Python (requests)

import requests

def load_my_payments(page=1, page_size=25, status=None):
    params = {"page": page, "page_size": page_size}
    if status:
        params["status"] = status

    response = requests.get(
        "https://accesspay.eopsprimax.com/api/v1/payments",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        params=params,
    )
    response.raise_for_status()
    return response.json()  # ["results"] is your row data, same fields as above

Is amount in cents or whole units?

Whole units. Send 5000 for 5,000 TZS, not 500000. We convert to the smallest currency unit internally before talking to the gateway — you never need to think about that conversion.

What timezone are the timestamps in?

UTC, always, in ISO 8601 format (2026-07-13T08:30:47.551072+00:00). Convert to your own local timezone on your side for display.

Is there a sandbox / test mode?

No — this integration talks to the live gateways. There is no separate sandbox environment. Use small real amounts when testing, and note test transactions still show up in your payment history like any other.

How is M-Pesa different from card, from my side?

You send phone_number instead of redirect_url/email, and there's no paymentPageUrl to redirect your customer to — the approval prompt appears directly on their phone. Everything else is identical: same endpoint, same auth, same idempotency handling, same status-check and list endpoints, same webhook/callback notification once they approve or decline.

Is there a rate limit?

Yes, per platform (your key, not shared with anyone else): creating a payment is limited to 120 requests/minute, refunds and payouts to 30/minute each, and status polling (any GET endpoint) to 300/minute. Going over any of these returns 429 with {"error": "Too many requests. Please try again shortly."}. In practice you shouldn't be near any of these — the webhook already tells you the moment a payment's status changes, so polling should be a backup, not your primary mechanism.

My redirect_url keeps getting rejected with 403 — why?

Its domain isn't on your platform's approved list. Ask whoever manages your Haminass Pay platform entry (on the Platforms page) to add it, or drop redirect_url entirely to use the default. Card only — M-Pesa doesn't use this.

I created a payment but never got a webhook — what do I do?

Poll GET /api/v1/payments/<orderReference> for that specific order to check its real status directly, rather than waiting indefinitely.

Can I cancel or refund a payment through this API?

Refund — see the Card tab (card payments only), but as flagged there, it's not currently available. There's no separate "cancel" endpoint; a PENDING order that's never paid just stays PENDING and eventually auto-expires (see the EXPIRED status) rather than needing to be explicitly cancelled.

Can I send money to a customer who didn't pay me, through this API?

That's the Payouts tab — but as flagged there, it's not currently available. The endpoint exists and is documented so you're ready for it once it is.

What happens if I lose my API key?

Ask an admin to rotate it for you on your platform's page (Platforms → your platform → Rotate key). The old key stops working immediately, so coordinate the swap on your side first.