One integration, every Tanzanian payment rail.
Mobile money and bank payments behind a single set of objects. Signed webhooks, required idempotency keys and one API version. Your first test key reaches a real rail.
curl -X POST https://api.settlopay.co.tz/v1/payments \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: order-8451-attempt-1" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": 25000.00, "currency": "TZS"},
"method": "mobile_money",
"method_data": {"phone": "+255712345678"},
"merchant_reference": "ORD-8451"
}'{
"id": "pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK",
"ref": "PAYXYENP80MPB8X",
"message": "TZS 25,000.00 is being collected.",
"receipt_no": "rcp_7KQ2M9XB4T1HV8D3NC6R",
"object": "payment_intent",
"state": "PENDING_AUTH",
"amount": {"value": 25000.00, "currency": "TZS"},
"method": "mobile_money",
"origin": "merchant_initiated",
"merchant_reference": "ORD-8451",
"created_at": "2026-09-06T10:30:02Z",
"expires_at": "2026-09-06T10:45:02Z",
"next_action": {"type": "await_mobile_prompt"}
}Shapes from the API reference, version 2026-04-29.
Seven resources. Predictable URLs.
A REST API over HTTPS with JSON bodies. API amounts are {"value", "currency"} in whole TZS, returned with two decimals; webhooks send amount and currency as separate fields. Timestamps are ISO 8601 UTC, and payments, refunds, payouts, beneficiaries and checkout sessions carry prefixed ids (pi_, ref_, po_, dst_, cs_).
Payments
pi_One object from created to succeeded, whichever rail the customer chooses.
- POST /v1/payments
- GET /v1/payments/{id}
- POST /v1/payments/{id}/cancel
Refunds
ref_Full or partial, against a succeeded payment. Never more than the customer paid. The money goes to the customer's phone, and the payout fee for that amount, plus VAT, is on top, paid by you. QR payments can't be refunded through the API yet.
- POST /v1/refunds
- GET /v1/refunds/{id}
Payouts
po_To your settlement destination or a saved beneficiary. Fee and VAT returned on the object.
- POST /v1/payouts
- POST /v1/payouts/{id}/cancel
- GET /v1/payouts
- GET /v1/payout-limits
Beneficiaries
dst_Payees you add through the API; payable once the account holder confirms them by code.
- POST /v1/beneficiaries
- POST /v1/beneficiaries/{id}/confirm
- GET /v1/beneficiaries
Balance
TZSOne TZS balance with an as-of timestamp. If the ledger is unreachable you get a 503, never a made-up zero.
- GET /v1/balance
Checkout sessions
cs_Create a hosted checkout server-side, redirect the customer, and let the page collect the method.
- POST /v1/checkout/sessions
- GET /v1/checkout/sessions/{id}
Webhooks
whsec_Up to five HTTPS endpoints per merchant, each with its own signing secret and event subscription.
- EVENT payment_intent.succeeded
- EVENT payout.succeeded
Built the way you would build it.
Payment intents
One object follows a payment through an explicit state machine. Final states never change again; a refund is its own object, and it moves a succeeded payment to partially refunded or refunded.
Webhooks
Signed events for payment, refund, payout and checkout outcomes, deduplicated on an event id and retried on a fixed schedule for about three days rather than forever.
Idempotency keys
Required on every request that creates something. The same key returns the same result for 24 hours; the same key with a different body returns 409, never a second charge.
Versioning
One version today, 2026-04-29. Send it in Settlo-Version or leave it out; anything else is a 400. Fields can be added at any time, so ignore what you don't recognise.
Errors
A flat JSON object with a stable code, a readable message and the offending param. Every error carries a request_id you can quote to support.
Rate limits
Up to 200 requests a minute per merchant. Authenticated responses report X-RateLimit-Limit and X-RateLimit-Remaining; a 429 adds Retry-After. Webhook deliveries never count against it.
Every state has a name.
Risk screening, waiting on the customer, the provider's answer and capture are all visible states, so you never have to infer what happened. Act on the object's current state, not on the order events arrive in.
Risk
Every payment and payout is screened before it reaches a provider. A blocked payment returns 201 with state BLOCKED, not an error; a blocked payout returns 422 risk_blocked and is never created. Some payouts are reviewed before they are sent: those return 201 with state UNDER_REVIEW, and the outcome follows by webhook.
Disputes
If a customer disputes a payment, our team works it through with you and the operator. The payment moves to DISPUTED, then CHARGEBACK_WON or CHARGEBACK_LOST.
Collecting
- CREATED
- RISK_REVIEW
- ROUTED
- PENDING_AUTH
- AWAITING_CUSTOMER
- AUTHORIZED
- CAPTURING
- SUCCEEDED
Mobile money waits in PENDING_AUTH while the customer approves; bank and QR payments wait in AWAITING_CUSTOMER. Live rails capture automatically.
Did not complete
- BLOCKED
- FAILED
- EXPIRED
- CANCELLED
After success
- PARTIALLY_REFUNDED
- REFUNDED
- DISPUTED
- CHARGEBACK_WON
- CHARGEBACK_LOST
Signed, deduplicated, retried on a schedule.
Register an HTTPS endpoint in the dashboard and pick the events you want. Every delivery is signed with HMAC-SHA256 over the timestamp and the raw body, so you know it came from us and when.
- Reject anything older than five minutes and compare digests in constant time.
- Deduplicate on
Settlo-Event-Id. Retries reuse it; events can arrive out of order. - Any 2xx counts as success. Answer within 10 seconds and do slower work afterwards.
- Fifty failed attempts in a row disable the endpoint. Rotate its secret in the dashboard to turn it back on, then reconcile with
GET /v1/payments. - Rotate the secret from the dashboard. The new one takes effect immediately and is shown once.
Delivery attempts: the first attempt at once, then retries after waits of 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 24 hours, 24 hours, 24 hours.
The first attempt, then eight retries, each a fixed wait after the last failure. After that the delivery is marked dead.
{
"id": "0198f6f0-9c1d-7e2f-8a3b-4c5d6e7f8a9b",
"type": "payment_intent.succeeded",
"api_version": "2026-04-29",
"created": "2026-09-06T10:30:46Z",
"data": {
"id": "pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK",
"ref": "PAYXYENP80MPB8X",
"merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 25000.00,
"currency": "TZS",
"method": "mobile_money",
"state": "SUCCEEDED",
"merchant_reference": "ORD-8451",
"origin": "merchant_initiated"
},
"delivery": {
"id": "0198f6f0-aaaa-7bbb-8ccc-ddddeeeeffff",
"attempt": 1
}
}const header = req.headers["settlo-signature"] ?? ""; // "t=1757154602,v1=6f2a…"
const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
const expected = crypto
.createHmac("sha256", process.env.SETTLO_WEBHOOK_SECRET) // the whole whsec_… string
.update(parts.t + ".")
.update(rawBody) // raw bytes, not re-serialized JSON
.digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const given = Buffer.from(parts.v1 ?? "");
const wanted = Buffer.from(expected);
if (!fresh || given.length !== wanted.length || !crypto.timingSafeEqual(given, wanted)) {
return res.status(400).end();
}Test keys, real rails.
There is no sandbox
Both key types are accepted by the same live API and reach real payment rails. The environment stamped on a key is bookkeeping only. Treat every request as a real payment, so what you build against is what you ship.
Approval before your first key
Create an account and verify your business (KYB) in the dashboard. Keys can be created once you're approved and work while your account is active; otherwise a request gets 403 merchant_not_transactable.
Secrets shown once
API keys are shown once, when you create them; webhook secrets once at creation and on each rotation. Your merchant identity always comes from the key, never from the request, and reading another merchant's payment returns 404 rather than confirming it exists.
The reference is the source of truth.
Endpoints with their request and response shapes, payment states, event types and error codes, on one page.
Ready to get started?
Create an account, verify your business, and make your first request against a real rail.