For developers

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.

Approval (KYB) comes first: you can create keys once your business is verified.
POST/v1/paymentscurl
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"
  }'
201payment_intentjson
{
  "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.

Resources

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

TZS

One 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
Principles

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.

Payment states

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

  1. CREATED
  2. RISK_REVIEW
  3. ROUTED
  4. PENDING_AUTH
  5. AWAITING_CUSTOMER
  6. AUTHORIZED
  7. CAPTURING
  8. 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
Webhooks

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.
Retry scheduleabout 3¼ days

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.

EVENTpayment_intent.succeededsigned· abridged
{
  "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
  }
}
Verify the signaturenode
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();
}
Keys and access

Test keys, real rails.

sk_test_sk_live_

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.

API referencePublished · 2026-04-29

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.

For developers | Settlo Pay