All systems operationalSupport Tanzania · English
Developer documentation

NORIPESA API

Accept mobile money payments with a single REST API. API keys are available in your dashboard once your business has been verified (KYC).

Introduction

Base URL for all APIs:

https://noripesa.com/api/v1
  • All requests and responses are JSON (Content-Type: application/json).
  • The amount is a whole number in TZS — no decimals.
  • All keys are Live (nori_live_…) and process real payments — there is no test environment. Try a small amount (e.g. TZS 100) first.
  • All payments are processed and managed by NORIPESA; you only ever deal with NORIPESA.

Authentication

Send your API key with every request as a Bearer token. Store the key only on your server (as an environment variable) — never put it in a mobile app or browser JavaScript.

Authorization: Bearer nori_live_xxxxxxxxxxxxxxxxxxxx

Test your key:

curl https://noripesa.com/api/v1/ping \
  -H "Authorization: Bearer $NORIPESA_API_KEY"

Rate limits: 60 requests/minute for /collect and 120 for /status, per key.

POST/collect

Send a payment request (USSD push) to the customer's phone. The Idempotency-Key header is required — use a unique order ID to prevent duplicate payments.

curl -X POST https://noripesa.com/api/v1/collect \
  -H "Authorization: Bearer $NORIPESA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 25000,
    "phone": "255712345678",
    "customer_name": "Asha Juma",
    "customer_email": "asha@example.com",
    "merchant_reference": "order-1042",
    "description": "Payment for order #1042"
  }'
FieldTypeDescription
amountintegerTZS 100 – 50,000,000 (or the limit set by NORIPESA)
phonestringTanzanian number: 2557XXXXXXXX or 07XXXXXXXX
customer_namestringCustomer name
customer_emailstringCustomer email
merchant_referencestring?Your internal reference (optional)
descriptionstring?Short description (optional)

Response — 202 Accepted

{
  "status": "success",
  "message": "Payment request sent to the customer. Await final confirmation...",
  "data": {
    "reference": "NPM3K9Q2ABCDEF",
    "merchant_reference": "order-1042",
    "source": "api",
    "status": "pending",
    "amount": 25000,
    "fee": 500,
    "net_amount": 24500,
    "currency": "TZS",
    "phone": "25571•••678",
    "provider": "NORIPESA",
    "provider_reference": null,
    "created_at": "2026-11-12T10:00:00.000Z"
  }
}

fee is the NORIPESA fee of 2% on each payment; net_amount is what is added to your balance when the payment succeeds. Withdraw your balance from the dashboard (Withdraw); each withdrawal carries a 5% fee.

Important: 202 only means the request was accepted — it is not confirmation of payment. Wait for the webhook or query /status. If you get 502 PROVIDER_OUTCOME_UNKNOWN, do not retry with a new Idempotency-Key; check the status of the reference you were given.

POST/status

Get the current status of a payment by its NORIPESA reference or your merchant_reference. For payments that are not yet final, NORIPESA checks directly with the payment network.

curl -X POST https://noripesa.com/api/v1/status \
  -H "Authorization: Bearer $NORIPESA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "NPM3K9Q2ABCDEF" }'

GET/transactions

A list of the merchant's recent transactions. Query params: status, limit (1–100).

curl "https://noripesa.com/api/v1/transactions?status=success&limit=20" \
  -H "Authorization: Bearer $NORIPESA_API_KEY"

Webhooks

Set your webhook URL (HTTPS) in Dashboard → Developers. When a transaction's status changes, NORIPESA sends a payment.updated event:

POST https://your-domain.co.tz/webhooks/noripesa
X-NORIPESA-Event: payment.updated
X-NORIPESA-Signature: t=1731405600,v1=5f2c...e9

{ "event": "payment.updated", "created_at": "...", "data": { "reference": "NP...", "status": "success", ... } }

Verifying the signature (Node.js)

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay guard
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

After verifying the signature, confirm again with /status before delivering goods or services. Respond to the webhook quickly with an HTTP 2xx.

Payment statuses

initiatingNORIPESA has received the request and is sending it to the provider
pendingThe customer has received the request on their phone and must confirm it
processingThe payment is being processed or the outcome is not yet confirmed
successThe payment completed (final)
failedThe payment failed (final)
cancelledThe customer cancelled (final)
expiredThe confirmation window expired (final)

Error codes

{ "status": "error", "code": "INVALID_API_KEY", "message": "Invalid or revoked NORIPESA API key." }
HTTPCodeMeaning
400INVALID_REQUEST · INVALID_PHONE · IDEMPOTENCY_KEY_REQUIRED · AMOUNT_TOO_LARGEThe request is invalid
401UNAUTHORIZED · INVALID_API_KEYThe key is missing, invalid or revoked
403MERCHANT_NOT_APPROVED · ACCOUNT_SUSPENDEDYou do not have permission
404PAYMENT_NOT_FOUNDThe reference was not found
429RATE_LIMITEDToo many requests — wait a minute
502PROVIDER_OUTCOME_UNKNOWNThe provider outcome is unconfirmed — check the status
503PAYMENTS_PAUSED · PROVIDER_UNAVAILABLEThe service is temporarily paused