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"
}'| Field | Type | Description |
|---|
| amount | integer | TZS 100 – 50,000,000 (or the limit set by NORIPESA) |
| phone | string | Tanzanian number: 2557XXXXXXXX or 07XXXXXXXX |
| customer_name | string | Customer name |
| customer_email | string | Customer email |
| merchant_reference | string? | Your internal reference (optional) |
| description | string? | 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.