Developers
Settlo Pay API reference.
Accept mobile money, bank and QR payments, send refunds and payouts, and get webhooks when anything changes. A REST API with JSON request and response bodies.
- Base URL
- https://api.settlopay.co.tz
- Content type
- application/json · UTF-8
- Version
- 2026-04-29Published
There's no sandbox yet. sk_test_ and sk_live_ keys both use the live API and move real money.
Getting started
Introduction
The Settlo Pay API is organised around REST. It has predictable resource URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes.
Amounts are objects with a value and a currency: {"value": 25000.00, "currency": "TZS"} is TZS 25,000. Send value as a number with up to two decimal places. Timestamps are ISO 8601 in UTC.
Every object has an id whose prefix tells you what it is: pi_ for payments, ref_ for refunds, po_ for payouts, cs_ for checkout sessions, dst_ for payout destinations and bil_ for bills. Payments, refunds and payouts also have a ref, a short reference such as PAYXYENP80MPB8X that you and your customers can quote.
Authentication
Authenticate by sending your secret key as a bearer token in the Authorization header. Keep secret keys on your server; never put them in a browser or a mobile app.
sk_test_ and sk_live_ keys both work against the live API and move real money.
A missing or invalid key returns 401 authentication_required. If your account can't transact yet, or has been suspended, the API returns 403 merchant_not_transactable on every request.
Authorization: Bearer sk_live_... (or sk_test_...)Idempotency
Send an Idempotency-Key header on every request that creates something. It's required: a request without one returns 400 parameter_invalid.
Use a unique key of up to 120 characters for each operation, such as your order id plus an attempt number. Retrying with the same key within 24 hours returns the original response. Reusing a key with a different body, or while the first request is still in progress, returns 409 idempotency_conflict. Keys starting with refund: are reserved.
For payouts, retrying with the same key after a timeout is safe: it picks up the same payout. If creating a payout returns 503 try_later, retry with a new key.
POST /v1/payments HTTP/1.1
Authorization: Bearer sk_live_...
Idempotency-Key: order-8451-attempt-1
Content-Type: application/jsonVersioning
Send Settlo-Version: 2026-04-29 to pin your requests to this version. Leave it out to use the current version. Any other value returns 400 parameter_invalid.
We add fields and event types without changing the version, so make sure your integration ignores fields it doesn't recognise. As the Terms of use say, we give notice before a change that breaks an existing version.
{
"type": "validation_error",
"code": "parameter_invalid",
"message": "Unsupported Settlo-Version: 2026-04 (current: 2026-04-29)",
"param": "Settlo-Version",
"request_id": "0d9f7c3a-4c2e-7d31-b2aa-91d2f2f4e9a1"
}Pagination
List endpoints return results newest first and page by cursor. Pass limit (1–50, default 20; a larger limit returns 50), and for each page after the first, pass the previous response's next_cursor as cursor.
Keep requesting pages until data comes back empty.
{
"data": [ … ],
"next_cursor": "2026-09-06T09:58:41Z",
"has_more": true
}Payments
The payment object
A payment collects an amount from a customer by mobile money, bank, QR or from their Settlo Pay balance. You create it, the customer pays, and its state moves forward until it succeeds or fails.
Customers can also pay you without an order: by scanning your printed QR code, or by paying your account number from the Mixx by Yas menu under Lipa Bili. These arrive as payments that are already SUCCEEDED, with origin payer_initiated. Such a payment has no merchant_reference unless it paid one of your bills (then the bill's reference) or counts toward a payment of yours (then that payment's, with linked_payment_id).
Fields without a value are left out of the response.
- id
- stringUnique identifier, starting pi_.
- ref
- stringA short reference you and your customer can quote, such as PAYXYENP80MPB8X.
- message
- stringA one-line summary of the current state, such as "TZS 25,000.00 is being collected."
- receipt_no
- stringThe receipt number, starting rcp_.
- object
- stringAlways "payment_intent".
- state
- enumThe payment's state. See Payment states.
- amount
- object{value, currency}, such as {"value": 25000.00, "currency": "TZS"}.
- method
- enummobile_money, bank, qr or settlo_balance.
- origin
- enummerchant_initiated if you started the payment (an API call, a hosted checkout or a bill); payer_initiated if the customer paid without an order; balance if the customer paid from their Settlo Pay balance.
- merchant_reference
- stringYour own order id, if you sent one.
- linked_payment_id
- stringOn a held QR payment our team credited to you: the id of the earlier payment it pays for. It carries that payment's merchant_reference, but its amount is what the customer actually paid.
- claim
- objectSet when an app connected to your account, such as Settlo POS, has claimed this payment for one of its orders: {claim_partner, claim_ref, claim_label?, amount_applied, claimed_at}. claim_ref is the app's order reference and amount_applied ({value, currency}) how much went to that order. A claim doesn't move money.
- payer_receipt
- stringThe transaction code on the customer's M-Pesa or Mixx by Yas confirmation, set once a mobile money payment succeeds. Never on QR or bank payments.
- created_at
- timestampWhen the payment was created.
- expires_at
- timestampWhen the payment expires if it isn't paid.
- amount_received
- objectQR only. {value, currency}: how much has arrived so far. A QR payment can be paid in parts.
- overpaid
- objectQR only. {value, currency}: how much arrived above amount.
- payments
- arrayQR only, when you retrieve a single payment: the payments that paid it, oldest first. Each has id, ref, amount, paid_at and relation (DURING if paid while it was open, AFTER_END if paid after).
- next_action
- objectWhat the customer needs to do next. Present only in PENDING_AUTH and AWAITING_CUSTOMER. See next_action.
- failure_code
- stringWhy the payment failed. Present only when state is FAILED.
- payer_account
- objectsettlo_balance only, once the payment succeeds: who paid, as {display_name, account_number_masked}, such as {"display_name": "Kibo Mini Market", "account_number_masked": "•••• 7895"}. The full account number is never shown.
{
"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"}
}{
"id": "pi_01J9X4M3K2J7Y2Q8R6T1V5W4AM",
"ref": "PAY4D7RKX9M2TQ6",
"message": "Waiting for the customer to complete this TZS 150,000.00 payment.",
"receipt_no": "rcp_N5W8HJ3QZ6CK1TB9FD4R",
"object": "payment_intent",
"state": "AWAITING_CUSTOMER",
"amount": {"value": 150000.00, "currency": "TZS"},
"method": "bank",
"origin": "merchant_initiated",
"created_at": "2026-09-06T10:30:02Z",
"expires_at": "2026-09-07T10:30:02Z",
"next_action": {
"type": "display_bank_reference",
"reference": "99441100223344",
"payable_at": ["CRDB Internet Banking", "CRDB SimBanking", "CRDB branch or Wakala"],
"expires_at": "2026-09-07T10:30:02Z"
}
}Payment methods
Set method to how the customer will pay. Payments customers make to your account number from the Mixx by Yas menu also show as mobile_money; you can't create those through the API.
- mobile_money
- Send method_data.phone, the customer's number in +255 format. The customer approves a prompt on their phone. We detect the network from the number; set method_data.network to override it.
- bank
- No method_data. The response gives the customer a reference to pay at their bank.
- qr
- No method_data. The response gives you a QR code for the customer to scan. The amount must be in whole shillings, or the payment fails with failure_code sub_unit_amount. If no code is available it fails with no_qr_available, so offer another method.
- settlo_balance
- Settlo Pay balance. Send method_data.account_number, the customer's 12-digit Settlo Pay account number. We send a code to the customer's registered contact, and you send it back to confirm the payment. See Pay from a Settlo Pay balance.
next_action
Tells you what the customer needs to do. Present only while the payment is PENDING_AUTH or AWAITING_CUSTOMER. A display_bank_reference comes with a reference and expires_at; a display_qr comes with an image.svg link and expires_at. Both can include a display map. An enter_code comes with channel, sent_to and expires_at.
- await_mobile_prompt
- Ask the customer to approve the prompt on their phone.
- display_bank_reference
- Show the customer the reference to pay at their bank. Also has payable_at (where they can pay), expires_at and an optional display map.
- display_qr
- Show the customer the QR image at image.svg as it is; the code is not available as text. The link changes when the code or amount changes, so always use the one from your latest read of the payment. display.qr_merchant_id is the 8-digit Merchant ID a customer can type if the code won't scan. For a dynamic code (qr_kind is "dynamic"), the customer must pay exactly display.amount to Settlo Pay; any other amount counts as a part payment. A static code (qr_kind is "static") is your own counter code: pay_exactly is absent, the customer types the amount, and their payment does not complete this payment by itself. It's recorded as a separate walk-in payment. expires_at is when the code stops being payable: two minutes before the payment expires for a dynamic code, or the payment's own expires_at for a static one.
- enter_code
- settlo_balance. Ask the customer for the 6-digit code we sent to their registered contact. channel (sms or email) says how it was sent, sent_to shows where (masked), and expires_at is when the code stops working. Send the code to verify-code; see Pay from a Settlo Pay balance.
{
"type": "display_qr",
"image": {"svg": "https://settlopay.co.tz/qr/pi_01J9XC7D9E1F3G5H7J9K1M3N5P.svg?v=8c41d2e0"},
"expires_at": "2026-09-06T10:43:02Z",
"display": {
"amount": "25000.00",
"currency": "TZS",
"recipient": "Settlo Pay",
"pay_exactly": "true",
"qr_merchant_id": "12345678",
"qr_kind": "dynamic"
}
}Create a payment
Creates a payment. For mobile_money, the customer gets a prompt on their phone. For bank, the response includes a reference the customer pays at their bank. For qr, it includes a code to scan. For settlo_balance, we send the customer a code to give you; see Pay from a Settlo Pay balance.
A qr payment expires after 15 minutes unless you set expires_at, anywhere from 5 minutes to 30 days ahead.
Returns 400 parameter_invalid, 400 unsupported_method or 400 unsupported_phone_network for an invalid request, 402 payment_failed if the payment can't be processed right now, 403 merchant_not_transactable if your account can't transact, and 409 idempotency_conflict if the key was reused. See Errors for the full list.
You can also cancel a payment (POST /v1/payments/{id}/cancel) from PENDING_AUTH, AWAITING_CUSTOMER or AUTHORIZED, or force a status check (POST /v1/payments/{id}/inquire) if it looks stuck.
Cancelling a prompt: cancelling a mobile money payment in PENDING_AUTH leaves the prompt live on the customer's phone. If they approve it anyway, the payment stays CANCELLED and you aren't credited; contact support to return their money.
- amountrequired
- object{value, currency}, such as {"value": 25000, "currency": "TZS"}. Up to two decimal places.
- methodrequired
- enummobile_money, bank, qr or settlo_balance. See Payment methods.
- method_data.phoneconditional
- stringRequired for mobile_money. The customer's number in E.164 format, starting +255.
- method_data.account_numberconditional
- stringRequired for settlo_balance. The customer's 12-digit Settlo Pay account number; spaces and dashes are fine.
- method_data.networkoptional
- stringOverrides the network detected from the phone number: vodacom, tigo, airtel or halotel.
- expires_atoptional
- timestampqr only. When the payment expires, 5 minutes to 30 days from now, in ISO 8601 with an offset. Defaults to 15 minutes.
- customer_idoptional
- stringThe id of an existing customer. Leave it out for guest payments.
- fee_beareroptional
- enumMERCHANT or CUSTOMER: who pays the collection fee. MERCHANT asks the customer for the amount and takes the fee from what you are credited. CUSTOMER adds the fee and its VAT to a mobile_money prompt; on bank and qr you pay it, because the customer enters the amount. Leave it out for your account's default.
- merchant_referenceoptional
- stringYour own order id, at most 120 characters. Returned on the payment and its webhooks.
- descriptionoptional
- stringFree text for your records. Not returned.
- statement_descriptoroptional
- stringUp to 22 characters.
- return_url / cancel_urloptional
- stringWhere hosted pages send the customer afterwards.
- metadataoptional
- objectAny JSON object for your records. Not returned.
curl -X POST https://api.settlopay.co.tz/v1/payments \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: order-8451-attempt-1" \
-H "Settlo-Version: 2026-04-29" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": 25000, "currency": "TZS"},
"method": "mobile_money",
"method_data": {"phone": "+255712345678"},
"merchant_reference": "ORD-8451",
"description": "Order 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"}
}Pay from a Settlo Pay balance
A customer with a Settlo Pay account can pay you from their balance. Use the calls below when your own app or till asks the customer for their account number and code, as Settlo POS does. To have Settlo Pay's hosted page ask for them instead, use a checkout session. In the examples, Kibo Mini Market pays Settlo Technologies TZS 30,000.
Create the payment with method settlo_balance and the customer's 12-digit Settlo Pay account number in method_data.account_number; spaces and dashes are fine. We send a 6-digit code to the payer's registered contact, by SMS or email as they've chosen, and the payment comes back 201 in AWAITING_CUSTOMER with next_action enter_code: its channel, a masked sent_to and the code's expires_at. Show the customer where the code went. Never ask the customer for a phone number or email: the code only ever goes to the contact on their own Settlo Pay account.
Send the code the customer types to POST /v1/payments/{id}/verify-code. The right code moves the money at once: the response is 200 with state SUCCEEDED and payer_account, the payer's display_name and account_number_masked. Show those on your receipt, never the full number. If the response still says CAPTURING, read the payment again shortly.
POST /v1/payments/{id}/resend-code sends a new code and answers 200 with the payment and its new next_action. Pass channel (sms or email) to choose how, or leave it out for the payer's own choice. A resend after the code expired sends a fresh one, so the customer never has to start again. To stop, cancel the payment with POST /v1/payments/{id}/cancel; its code stops working. A payment nobody completes expires after 30 minutes.
We say the balance is too low (insufficient_balance) only after the right code, so a mistyped number or code never reveals anyone's balance. code_invalid and code_expired leave the payment open: let the customer try again, or send a new code. too_many_attempts, insufficient_balance and pay_another_way fail the payment (pay_another_way can also refuse the create before the payment exists), so create a new one or offer another way to pay. The table below lists every refusal.
Your key needs only the payments:write scope. If the method is unavailable, create returns 400 unsupported_method. expires_at, fee_bearer, customer_id, statement_descriptor, return_url and cancel_url are ignored for this method; merchant_reference, description and metadata work as usual. verify-code and resend-code need no Idempotency-Key, return 404 resource_missing for a payment that isn't yours or isn't a settlo_balance payment, and 409 state_invalid when no code is waiting (the payment was cancelled, expired or failed). verify-code on a payment that already succeeded answers 200 with it, so a retried verify is safe.
Send an Idempotency-Key on create. A request refused before the payment exists (a malformed number, same_account, most account_not_payable) frees its key, so you can correct it and send it again. Once the payment exists, the key stays with it: if it then fails, for example too_many_attempts or 503 try_later because the code couldn't be sent, retry with a new Idempotency-Key. A same-key retry while the first request is still checking the account number answers 409 idempotency_conflict; once the payment exists but its code is still being sent, it returns the payment without next_action. Either way, wait a moment: read the payment again, or retry.
Webhooks are the usual payment_intent.* events, with method settlo_balance and origin balance; once the payment succeeds they also carry payer_account. There are no new event types. A refund of this payment goes straight back to the payer's Settlo Pay balance.
- account_not_payable
- 422, param account_number. "This Settlo Pay account can't pay here." The number is unknown, or that account can't pay right now. Usually refused before the payment exists; if it comes once the payment exists (while the code is sent, or on a resend), the payment fails.
- same_account
- 422. "You can't pay your own account." The payer's account is your own. Refused before the payment exists.
- code_invalid
- 422, param code. "That code isn't right." A blank code is refused the same way. The payment stays open: let the customer try again.
- code_expired
- 422, param code. "That code has expired. Send a new one." The payment stays open: resend a code.
- too_many_attempts
- 429. "Too many tries. Please choose another way to pay." Too many wrong codes, or too many codes sent. The payment fails.
- insufficient_balance
- 422. "Your Settlo Pay balance isn't enough for this payment." Said only after the right code. The payment fails.
- pay_another_way
- 422. "This payment can't be made from your Settlo Pay balance right now. Please choose another way to pay." Fails the payment, or refuses the request before the payment exists when your own account can't receive the money.
- resend_too_soon
- 429, with retry_after_seconds in the body and a Retry-After header. "Please wait a moment before asking for another code." The payment stays open: offer to send again once the wait is over.
- try_later
- 503. The code couldn't be sent or checked just now, and nothing was taken. If it couldn't be sent, the payment fails, so start again; if it couldn't be checked or resent, the payment stays open, so try again.
curl -X POST https://api.settlopay.co.tz/v1/payments \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: order-9120-attempt-1" \
-H "Settlo-Version: 2026-04-29" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": 30000, "currency": "TZS"},
"method": "settlo_balance",
"method_data": {"account_number": "1012 3456 7895"},
"merchant_reference": "ORD-9120"
}'{
"id": "pi_01JC7K2M8N4P6Q8R0S2T4V6W8X",
"ref": "PAYKB30SXN7TQ2E",
"message": "Waiting for the customer to complete this TZS 30,000.00 payment.",
"receipt_no": "rcp_8MXQ4T2KB7NH5VD9CR3W",
"object": "payment_intent",
"state": "AWAITING_CUSTOMER",
"amount": {"value": 30000.00, "currency": "TZS"},
"method": "settlo_balance",
"origin": "balance",
"merchant_reference": "ORD-9120",
"created_at": "2026-11-06T10:30:02Z",
"expires_at": "2026-11-06T11:00:02Z",
"next_action": {
"type": "enter_code",
"channel": "sms",
"sent_to": "+255******678",
"expires_at": "2026-11-06T10:40:02Z"
}
}curl -X POST https://api.settlopay.co.tz/v1/payments/pi_01JC7K2M8N4P6Q8R0S2T4V6W8X/verify-code \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"code": "123456"}'{
"id": "pi_01JC7K2M8N4P6Q8R0S2T4V6W8X",
"ref": "PAYKB30SXN7TQ2E",
"message": "TZS 30,000.00 was received on 2026-11-06 13:31.",
"receipt_no": "rcp_8MXQ4T2KB7NH5VD9CR3W",
"object": "payment_intent",
"state": "SUCCEEDED",
"amount": {"value": 30000.00, "currency": "TZS"},
"method": "settlo_balance",
"origin": "balance",
"merchant_reference": "ORD-9120",
"created_at": "2026-11-06T10:30:02Z",
"expires_at": "2026-11-06T11:00:02Z",
"payer_account": {"display_name": "Kibo Mini Market", "account_number_masked": "•••• 7895"}
}{
"type": "business_decline",
"code": "code_invalid",
"message": "That code isn't right.",
"param": "code",
"request_id": "0d9f7c3a-4c2e-7d31-b2aa-91d2f2f4e9a1"
}curl -X POST https://api.settlopay.co.tz/v1/payments/pi_01JC7K2M8N4P6Q8R0S2T4V6W8X/resend-code \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"channel": "email"}'{
"id": "0198f6f0-9c1d-7e2f-8a3b-4c5d6e7f8b0c",
"type": "payment_intent.succeeded",
"api_version": "2026-04-29",
"created": "2026-11-06T10:31:12Z",
"data": {
"id": "pi_01JC7K2M8N4P6Q8R0S2T4V6W8X",
"ref": "PAYKB30SXN7TQ2E",
"merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 30000.00,
"currency": "TZS",
"method": "settlo_balance",
"state": "SUCCEEDED",
"merchant_reference": "ORD-9120",
"origin": "balance",
"payer_account": {"display_name": "Kibo Mini Market", "account_number_masked": "•••• 7895"}
},
"delivery": {
"id": "0198f6f0-aaaa-7bbb-8ccc-ddddeeeeff00",
"attempt": 1
}
}List payments
Lists your payments, newest first, including the ones customers make by scanning your QR code. See Pagination.
- cursoroptional
- stringThe next_cursor from the previous page.
- limitoptional
- integer1–50. Default 20.
Retrieve a payment
Retrieves a payment by its pi_ id. If you can't receive webhooks, you can poll this endpoint within the rate limit.
curl https://api.settlopay.co.tz/v1/payments/pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK \
-H "Authorization: Bearer sk_live_..."Amend a payment
Changes the amount of a qr payment that's still AWAITING_CUSTOMER, for example when an order total changes. The QR code stays the same, so a code that's already printed or scanned still works. Returns the updated payment.
Sending the same amount again changes nothing. If the money already received covers the new amount, the payment succeeds immediately.
Returns 400 parameter_invalid for a different currency or an amount with cents, 409 if the payment is no longer waiting for the customer or the customer pays the fee, and 503 try_later if the change couldn't be made. Nothing changed, so send it again.
- amountrequired
- objectThe new total, {value, currency}, in whole shillings and in the payment's currency.
curl -X PATCH https://api.settlopay.co.tz/v1/payments/pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK \
-H "Authorization: Bearer sk_live_..." \
-H "Settlo-Version: 2026-04-29" \
-H "Content-Type: application/json" \
-d '{"amount": {"value": 30000, "currency": "TZS"}}'Payment states
BLOCKED, FAILED, EXPIRED, CANCELLED, REFUNDED, CHARGEBACK_WON and CHARGEBACK_LOST are final. A SUCCEEDED payment can still move to PARTIALLY_REFUNDED or REFUNDED when you refund it, or to DISPUTED if the customer disputes it.
A new payment usually comes back PENDING_AUTH (mobile money) or AWAITING_CUSTOMER (bank, QR and Settlo Pay balance), or FAILED if it's declined. A payment blocked by risk checks returns 201 with state BLOCKED, not an error. An unpaid payment becomes EXPIRED after expires_at.
- CREATEDPending
- Created; nothing has happened yet.
- RISK_REVIEWPending
- Being screened.
- ROUTEDPending
- Being sent to the payment network.
- PENDING_AUTHPending
- Waiting for the network. For mobile money, the customer is approving the prompt on their phone.
- AWAITING_CUSTOMERPending
- Waiting for the customer to pay a bank reference or QR code, or to enter a Settlo Pay code. See next_action.
- AUTHORIZEDPending
- Approved; the money is collected automatically.
- CAPTURINGPending
- The money is being collected.
- SUCCEEDEDSucceeded
- The money has arrived.
- BLOCKEDRejected
- Declined by risk checks. Returned with HTTP 201.
- FAILEDFailed
- Declined, or the customer didn't approve in time.
- EXPIREDFailed
- Not paid before expires_at.
- CANCELLEDCancelled
- Cancelled from PENDING_AUTH, AWAITING_CUSTOMER or AUTHORIZED.
- PARTIALLY_REFUNDEDRefunded
- Part of the amount has been refunded.
- REFUNDEDRefunded
- The full amount has been refunded.
- DISPUTEDNeeds review
- The customer's bank or network opened a dispute.
- CHARGEBACK_WONSucceeded
- The dispute was resolved in your favour.
- CHARGEBACK_LOSTFailed
- The dispute was resolved against you; the money was reversed.
Refunds
The refund object
A refund returns all or part of a successful payment to the customer. Fields without a value are left out. description and metadata aren't returned, so use merchant_reference for anything you need back.
- id
- stringUnique identifier, starting ref_.
- ref
- stringA short reference you can quote, such as RFD6VSS1TJBDF77.
- message
- stringA one-line summary of the current state, such as "Refund of TZS 5,000.00 is being processed."
- receipt_no
- stringThe receipt number, starting rcp_.
- object
- stringAlways "refund".
- state
- enumCREATED, PENDING, PENDING_REVIEW, SUCCEEDED, FAILED or CANCELLED.
- amount
- object{value, currency}: what the customer receives.
- payment_intent
- stringThe id of the refunded payment.
- reason
- enumREQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT or OTHER.
- merchant_reference
- stringYour own reference, if you sent one.
- created_at
- timestampWhen the refund was created.
{
"id": "ref_01J9XB2P8Q4R6S8T0V2W4X6Y8A",
"ref": "RFD6VSS1TJBDF77",
"message": "Refund of TZS 5,000.00 is being processed.",
"receipt_no": "rcp_3HV8QK2N6TB9XD4M1CR7",
"object": "refund",
"state": "PENDING",
"amount": {"value": 5000.00, "currency": "TZS"},
"payment_intent": "pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK",
"reason": "REQUESTED_BY_CUSTOMER",
"merchant_reference": "RMA-8451-1",
"created_at": "2026-09-06T11:02:41Z"
}Create a refund
Refunds all or part of a payment that is SUCCEEDED or PARTIALLY_REFUNDED, within 30 days of the payment. QR payments and payments the customer started (origin payer_initiated) can't be refunded through the API and return 422 refund_unsupported_method; contact support to return that money.
For a mobile money or bank payment, you pay the refund fee: the payout fee for that amount, plus 18% VAT, on top of the amount. The customer receives the full refund amount, so a TZS 50,000 refund to a mobile money wallet debits TZS 50,708 from your balance. One refund sends at most TZS 5,000,000; refund a larger payment in parts. If your balance can't cover it, the request returns 422 insufficient_balance.
A refund moves from CREATED to PENDING to SUCCEEDED or FAILED, and may pause in PENDING_REVIEW for a risk check. Listen for refund.succeeded and refund.failed to learn the outcome.
A refund of a settlo_balance payment goes straight back to the payer's Settlo Pay balance: the amount comes off your balance and is credited to theirs at once, so the response is usually already SUCCEEDED. If your balance can't cover it, the request returns 422 insufficient_balance, the refund is FAILED and nothing moves; retry with a new Idempotency-Key once your balance can cover it.
Other errors: 409 state_invalid if the payment can't be refunded in its current state, 422 payer_account_unknown after 30 days, 422 payment_disputed if it's under dispute, and 422 payment_not_refundable otherwise.
- payment_intentrequired
- stringThe id of the payment to refund.
- amountoptional
- object{value, currency}. Defaults to everything still refundable. Refunds can't add up to more than the payment.
- reasonrequired
- enumrequested_by_customer, duplicate, fraudulent or other.
- merchant_referenceoptional
- stringYour own reference, at most 120 characters. Returned on the refund and its webhooks.
- descriptionoptional
- stringFree text for your records; never returned.
- metadataoptional
- objectAny JSON object for your records; never returned.
curl -X POST https://api.settlopay.co.tz/v1/refunds \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: refund-ORD-8451-1" \
-H "Content-Type: application/json" \
-d '{
"payment_intent": "pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK",
"amount": {"value": 5000, "currency": "TZS"},
"reason": "requested_by_customer",
"merchant_reference": "RMA-8451-1"
}'{
"id": "ref_01J9XB2P8Q4R6S8T0V2W4X6Y8A",
"ref": "RFD6VSS1TJBDF77",
"message": "Refund of TZS 5,000.00 is being processed.",
"receipt_no": "rcp_3HV8QK2N6TB9XD4M1CR7",
"object": "refund",
"state": "PENDING",
"amount": {"value": 5000.00, "currency": "TZS"},
"payment_intent": "pi_01J9X4M3K2J7Y2Q8R6T1V5W3ZK",
"reason": "REQUESTED_BY_CUSTOMER",
"merchant_reference": "RMA-8451-1",
"created_at": "2026-09-06T11:02:41Z"
}Retrieve a refund
Retrieves a refund by its ref_ id.
Payouts
The payout object
A payout sends money from your balance to your settlement account or to a beneficiary. The destination receives amount; the fee and its VAT come off your balance on top. Fields without a value are left out.
- id
- stringUnique identifier, starting po_.
- ref
- stringA short reference you can quote, such as PYT4NWV12S83C73.
- message
- stringA one-line summary of the current state, such as "TZS 50,000.00 is on its way to Juma Stores Ltd."
- object
- stringAlways "payout".
- state
- enumREQUESTED, UNDER_REVIEW, AUTHORIZED, SUCCEEDED, FAILED_REVERSED, REJECTED_FUNDS, DECLINED, EXPIRED or CANCELLED.
- amount
- object{value, currency}: what the destination receives.
- fee
- object{value, currency}: the payout fee, charged on top of amount.
- vat
- object{value, currency}: 18% VAT on the fee.
- destination
- objectWhere the money went: destination_id, purpose (SETTLEMENT or BENEFICIARY), kind (MOMO, BANK or SETTLO), fsp_code (the bank or network, such as VODATZ; SETTLO for a Settlo Pay account), account_masked and account_name. label is included only in the create response.
- description
- stringYour note, if you sent one.
- merchant_reference
- stringYour own reference, if you sent one.
- failure_code
- stringWhy the payout failed or was rejected. Present only then.
- cancel_reason
- enumWhy a payout was cancelled: merchant_requested (you cancelled it), duplicate (closed as a repeat of another payout under review) or merchant_inactive. Present only on a CANCELLED payout.
- created_at
- timestampWhen the payout was created.
- updated_at
- timestampWhen the state last changed.
{
"id": "po_01J9XC7D9E1F3G5H7J9K1M3N5P",
"ref": "PYT4NWV12S83C73",
"message": "TZS 50,000.00 is on its way to Juma Stores Ltd.",
"object": "payout",
"state": "AUTHORIZED",
"amount": {"value": 50000.00, "currency": "TZS"},
"fee": {"value": 600.00, "currency": "TZS"},
"vat": {"value": 108.00, "currency": "TZS"},
"destination": {
"destination_id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"purpose": "SETTLEMENT",
"kind": "MOMO",
"fsp_code": "VODATZ",
"account_masked": "********0111",
"account_name": "Juma Stores Ltd"
},
"description": "Weekly cashout",
"merchant_reference": "CASHOUT-2026-W36",
"created_at": "2026-09-06T11:02:41Z",
"updated_at": "2026-09-06T11:02:41Z"
}Create a payout
Sends money from your balance. Leave out destination_id to pay your settlement account, or pass a beneficiary's dst_ id to pay them. Your balance is debited amount plus the fee and VAT; quote a payout first to see the total.
A payout moves from REQUESTED to AUTHORIZED (debited and sent) to SUCCEEDED. If it's returned, it moves to FAILED_REVERSED and the money is credited back to your balance.
Some payouts are reviewed before they are sent. A payout under review is still created: the response is 201 with state: "UNDER_REVIEW", and the amount, fee and VAT are set aside from your balance. Don't send it again. payout.under_review is sent when a payout waits. The outcome follows by webhook within 24 hours. If it's approved, payout.authorized follows, then payout.succeeded or payout.failed as usual. Otherwise you get payout.declined, payout.expired (it wasn't reviewed in time) or payout.cancelled, and the money returns to your balance. You can cancel it while it's under review. Retrying with the same Idempotency-Key returns the same payout.
Errors: 422 insufficient_funds if your balance is too low; 422 no_payout_destination if you leave out destination_id and have no settlement account; 400 parameter_invalid or 404 resource_missing for an invalid destination_id; 422 beneficiary_not_confirmed if the beneficiary isn't confirmed yet; 422 payout_limit_exceeded above your payout limits; 422 payout_unpriceable if the payout can't be priced; and 422 risk_blocked if risk checks decline it.
A payout to a Settlo Pay account (a beneficiary of kind SETTLO) moves at once when it's allowed: the response is 201 with state: "SUCCEEDED" and payout.succeeded follows, with no payout.authorized. A payout held for review moves when it's approved: payout.under_review, then payout.succeeded. If the account can't receive money right now, you get 422 beneficiary_account_not_found and nothing moves.
If you get 503 try_later, retry with a new Idempotency-Key.
- amountrequired
- object{value, currency}. TZS only.
- destination_idoptional
- stringA beneficiary's dst_ id. Leave it out to pay your settlement account. Returns 400 parameter_invalid if it isn't a valid id, 404 resource_missing if it isn't yours, and 422 beneficiary_not_confirmed if it isn't confirmed yet.
- descriptionoptional
- stringUp to 200 characters.
- merchant_referenceoptional
- stringYour own reference, at most 120 characters. Returned on the payout and its webhooks.
curl -X POST https://api.settlopay.co.tz/v1/payouts \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: cashout-2026-09-06-1" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": 50000, "currency": "TZS"},
"description": "Weekly cashout",
"merchant_reference": "CASHOUT-2026-W36"
}'{
"id": "po_01J9XC7D9E1F3G5H7J9K1M3N5P",
"ref": "PYT4NWV12S83C73",
"message": "TZS 50,000.00 is on its way to Juma Stores Ltd.",
"object": "payout",
"state": "AUTHORIZED",
"amount": {"value": 50000.00, "currency": "TZS"},
"fee": {"value": 600.00, "currency": "TZS"},
"vat": {"value": 108.00, "currency": "TZS"},
"destination": {
"destination_id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"purpose": "SETTLEMENT",
"kind": "MOMO",
"fsp_code": "VODATZ",
"account_masked": "********0111",
"account_name": "Juma Stores Ltd"
},
"description": "Weekly cashout",
"merchant_reference": "CASHOUT-2026-W36",
"created_at": "2026-09-06T11:02:41Z",
"updated_at": "2026-09-06T11:02:41Z"
}Cancel a payout under review
Cancels a payout that is still UNDER_REVIEW. It needs the payouts:write scope and no body. Cancelling the same payout twice answers 202 both times.
The response is 202 with the payout. It can still read UNDER_REVIEW for a moment; it then becomes CANCELLED with cancel_reason: "merchant_requested", a payout.cancelled webhook follows, and the amount, fee and VAT return to your balance.
Errors: 404 resource_missing if the payout doesn't exist or isn't yours; 409 payout_not_cancellable if the payout isn't under review, or its review already ended; 503 try_later (the cancel couldn't be confirmed just now; try again, and read the payout to see where it stands). The 409 body's outcome says which: approved (already approved and sent), declined, expired, cancelled, decided (the review was decided a moment ago; read the payout again shortly) or not_under_review.
curl -X POST https://api.settlopay.co.tz/v1/payouts/po_01J9XC7D9E1F3G5H7J9K1M3N5P/cancel \
-H "Authorization: Bearer sk_live_..."Quote a payout
Shows what a payout will cost before you send it. Pass an amount to price it, or leave amount out to get the most you can send right now. total_debit is what comes off your balance: amount + fee + vat.
A quote creates nothing, needs no Idempotency-Key and doesn't count toward your limits. The price isn't held. A quote for a set amount doesn't check your balance, so compare total_debit with your balance.
Here amount is a plain number with currency beside it. Errors: 400 parameter_invalid for a missing currency or an invalid destination_id, 404 resource_missing, 422 beneficiary_not_confirmed, 422 no_payout_destination, 422 payout_unpriceable (the message says what to do) and 503 try_later.
- destination_idoptional
- stringA beneficiary's dst_ id. Leave it out to price a payout to your settlement destination.
- currencyrequired
- stringTZS.
- amountoptional
- numberWhat the destination should receive, such as 50000. Leave it out to get the most you can send.
curl -X POST https://api.settlopay.co.tz/v1/payouts/quote \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"destination_id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"currency": "TZS",
"amount": 50000
}'{
"amount": {"value": 50000.00, "currency": "TZS"},
"fee": {"value": 600.00, "currency": "TZS"},
"vat": {"value": 108.00, "currency": "TZS"},
"total_debit": {"value": 50708.00, "currency": "TZS"}
}List payouts
Lists your payouts, newest first. See Pagination.
- stateoptional
- enumOnly payouts in this state: REQUESTED, UNDER_REVIEW, AUTHORIZED, SUCCEEDED, FAILED_REVERSED, REJECTED_FUNDS, DECLINED, EXPIRED or CANCELLED.
- cursoroptional
- stringThe next_cursor from the previous page.
- limitoptional
- integer1–50. Default 20.
Retrieve a payout
Retrieves a payout by its po_ id.
curl https://api.settlopay.co.tz/v1/payouts/po_01J9XC7D9E1F3G5H7J9K1M3N5P \
-H "Authorization: Bearer sk_live_..."Retrieve your payout limits
Returns your payout limits, one row for each purpose (SETTLEMENT, BENEFICIARY) and destination kind (BANK, MOMO, and SETTLO for beneficiaries). per_txn_cap is the most you can send in one payout and daily_cap the most in a day, in the row's currency.
{
"limits": [
{"purpose": "SETTLEMENT", "destination_kind": "BANK", "per_txn_cap": 1000000.00, "daily_cap": 5000000.00, "currency": "TZS", "source": "HARD_CAP"},
{"purpose": "SETTLEMENT", "destination_kind": "MOMO", "per_txn_cap": 1000000.00, "daily_cap": 5000000.00, "currency": "TZS", "source": "HARD_CAP"},
{"purpose": "BENEFICIARY", "destination_kind": "BANK", "per_txn_cap": 1000000.00, "daily_cap": 5000000.00, "currency": "TZS", "source": "HARD_CAP"},
{"purpose": "BENEFICIARY", "destination_kind": "MOMO", "per_txn_cap": 1000000.00, "daily_cap": 5000000.00, "currency": "TZS", "source": "HARD_CAP"},
{"purpose": "BENEFICIARY", "destination_kind": "SETTLO", "per_txn_cap": 1000000.00, "daily_cap": 5000000.00, "currency": "TZS", "source": "HARD_CAP"}
]
}Beneficiaries
The beneficiary object
A beneficiary is someone you pay out to, by its dst_ id. A new beneficiary is pending_confirmation until your account holder confirms it with a code we send them. You can't pay it before then.
The 6-digit code goes to the Settlo Pay account holder by SMS or email, as they've chosen in their Dashboard settings, never to an address you supply. It's valid for 10 minutes and 5 tries. While a beneficiary is pending, confirmation shows how the code was sent and when it expires. Confirm it, resend the code, or delete the beneficiary.
- id
- stringThe dst_ id you pay this beneficiary by.
- object
- stringAlways "beneficiary".
- status
- enumpending_confirmation or active.
- kind
- enumMOMO, BANK or SETTLO (a Settlo Pay account).
- fsp_code
- stringThe bank or network, such as VODATZ or CRDBTZ; SETTLO for a Settlo Pay account.
- account_masked
- stringThe last four digits of the account, such as ****1234.
- account_name
- stringThe account holder's name.
- verified_name
- stringThe name the bank, network or Settlo Pay returned for this account. Show it beside the code input so the user can check it's the right payee.
- label
- stringYour own name for this beneficiary, if you gave one.
- created_via
- enumapi or dashboard.
- confirmation
- objectOnly while pending: channel (sms or email), sent_to (masked) and expires_at.
- confirmed_at
- timestampWhen the beneficiary was confirmed.
- created_at
- timestampWhen the beneficiary was created.
{
"id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"object": "beneficiary",
"status": "pending_confirmation",
"kind": "BANK",
"fsp_code": "CRDBTZ",
"account_masked": "****1234",
"account_name": "JUMA SUPPLIES LTD",
"verified_name": "JUMA SUPPLIES LTD",
"label": "Juma Supplies",
"created_via": "api",
"confirmation": {"channel": "sms", "sent_to": "+255******678", "expires_at": "2026-10-11T10:25:00Z"},
"created_at": "2026-10-11T10:15:00Z"
}List beneficiaries
Lists your beneficiaries, newest first, including pending ones. See Pagination.
Requires the beneficiaries:read scope, which a key has only if you chose it when you created the key.
- statusoptional
- enumpending_confirmation or active.
- cursoroptional
- stringThe next_cursor from the previous page.
- limitoptional
- integer1–50. Default 20.
curl "https://api.settlopay.co.tz/v1/beneficiaries?status=pending_confirmation&limit=20" \
-H "Authorization: Bearer sk_live_..."{
"data": [
{
"id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"object": "beneficiary",
"status": "pending_confirmation",
"kind": "BANK",
"fsp_code": "CRDBTZ",
"account_masked": "****1234",
"account_name": "JUMA SUPPLIES LTD",
"verified_name": "JUMA SUPPLIES LTD",
"label": "Juma Supplies",
"created_via": "api",
"confirmation": {"channel": "sms", "sent_to": "+255******678", "expires_at": "2026-10-11T10:25:00Z"},
"created_at": "2026-10-11T10:15:00Z"
}
],
"next_cursor": "2026-10-11T10:15:00Z",
"has_more": true
}Create a beneficiary
Adds a beneficiary and sends your account holder a code to confirm it. To set one up from your app: create the beneficiary, show its verified_name next to a code input, have the account holder enter the code we sent them, confirm it, then pay it by destination_id.
We check the account with the bank or network before creating the beneficiary. You can leave out account_name when the check returns the holder's name.
To pay another Settlo Pay account, create a beneficiary with kind and fsp_code both SETTLO and the 12-digit Settlo Pay account number. We look the account up before saving it; its account_name and verified_name are the name Settlo Pay holds, and any name you send is ignored. An unknown or closed account returns 422 beneficiary_account_not_found, and your own account 422 beneficiary_own_account. A payout to it moves at once when it's allowed, and a payout held for review moves when it's approved, with the usual payout.* events. A Settlo Pay account can't be added to a beneficiary group.
Requires the beneficiaries:write scope and an Idempotency-Key.
Errors: 400 parameter_invalid, 422 beneficiary_account_not_found if the account doesn't exist, 422 beneficiary_own_account for your own Settlo Pay account, 422 beneficiary_limit_reached if you've reached the maximum number of beneficiaries, 422 beneficiary_rejected if screening declines it, and 422 no_confirmation_channel if the account holder has no phone number on file.
- kindrequired
- enumMOMO, BANK or SETTLO. SETTLO is a Settlo Pay account.
- fsp_coderequired
- stringThe bank or network code, such as VODATZ or CRDBTZ. SETTLO for kind SETTLO.
- account_numberrequired
- stringFor MOMO, the mobile number as 255 followed by nine digits. For BANK, the account number: 6–32 letters or digits. For SETTLO, the 12-digit Settlo Pay account number; spaces and dashes are fine.
- account_nameoptional
- stringUp to 140 characters. Needed only when the bank or network can't return the holder's name. Ignored for SETTLO.
- labeloptional
- stringUp to 60 characters. Your own name for the beneficiary.
curl -X POST https://api.settlopay.co.tz/v1/beneficiaries \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: supplier-juma-2026-10-11" \
-H "Content-Type: application/json" \
-d '{
"kind": "BANK",
"fsp_code": "CRDBTZ",
"account_number": "0150001234",
"label": "Juma Supplies"
}'{
"id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"object": "beneficiary",
"status": "pending_confirmation",
"kind": "BANK",
"fsp_code": "CRDBTZ",
"account_masked": "****1234",
"account_name": "JUMA SUPPLIES LTD",
"verified_name": "JUMA SUPPLIES LTD",
"label": "Juma Supplies",
"created_via": "api",
"confirmation": {"channel": "sms", "sent_to": "+255******678", "expires_at": "2026-10-11T10:25:00Z"},
"created_at": "2026-10-11T10:15:00Z"
}Retrieve a beneficiary
Retrieves a beneficiary by its dst_ id. Requires beneficiaries:read.
curl https://api.settlopay.co.tz/v1/beneficiaries/dst_01K3VF16GJFAY9VVR14D2PF2DB \
-H "Authorization: Bearer sk_live_..."Confirm a beneficiary
Confirms a pending beneficiary with the code the account holder received, and returns it as active, ready to pay. A code is valid for 10 minutes and 5 wrong tries.
A wrong code returns 422 confirmation_code_invalid, with the tries left in the message. An expired code returns 422 confirmation_code_expired; resend a new one. A beneficiary that isn't pending returns 409 confirmation_not_pending. Requires beneficiaries:write.
- coderequired
- stringThe 6-digit code.
curl -X POST https://api.settlopay.co.tz/v1/beneficiaries/dst_01K3VF16GJFAY9VVR14D2PF2DB/confirm \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"code": "482913"}'{
"id": "dst_01K3VF16GJFAY9VVR14D2PF2DB",
"object": "beneficiary",
"status": "active",
"kind": "BANK",
"fsp_code": "CRDBTZ",
"account_masked": "****1234",
"account_name": "JUMA SUPPLIES LTD",
"verified_name": "JUMA SUPPLIES LTD",
"label": "Juma Supplies",
"created_via": "api",
"confirmed_at": "2026-10-11T10:17:00Z",
"created_at": "2026-10-11T10:15:00Z"
}Resend the code
Sends a new code and cancels the old one. Pass {"channel": "sms"} to send it by SMS whatever the account holder's setting.
You can resend once a minute and five times an hour per beneficiary, up to 20 codes an hour per account holder. Beyond that you get 429 confirmation_throttled with a Retry-After header. Requires beneficiaries:write.
- channeloptional
- stringsms. Sends the code by SMS.
curl -X POST https://api.settlopay.co.tz/v1/beneficiaries/dst_01K3VF16GJFAY9VVR14D2PF2DB/resend_code \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"channel": "sms"}'Delete a beneficiary
Deletes a beneficiary, including a pending one. To change a beneficiary's account, delete it and create a new one. Requires beneficiaries:write.
curl -X DELETE https://api.settlopay.co.tz/v1/beneficiaries/dst_01K3VF16GJFAY9VVR14D2PF2DB \
-H "Authorization: Bearer sk_live_..."{"id": "dst_01K3VF16GJFAY9VVR14D2PF2DB", "object": "beneficiary", "retired": true}Balance
Retrieve the balance
Returns your balance in TZS.
Returns 503 try_later if the balance is temporarily unavailable; try again shortly.
curl https://api.settlopay.co.tz/v1/balance \
-H "Authorization: Bearer sk_live_..."{
"amount": {"value": 1248000.00, "currency": "TZS"},
"as_of": "2026-09-06T11:00:12Z"
}Checkout sessions
Create a checkout session
Creates a hosted checkout page. Redirect the customer to the returned url. They choose how to pay there, and are sent to your return_url or cancel_url when they're done.
Sessions expire after 30 minutes. If a payment attempt fails, the customer can try again on the same session. Each attempt is a payment with the session's merchant_reference.
Retrieve a session with GET /v1/checkout/sessions/{id} and cancel it with POST /v1/checkout/sessions/{id}/cancel.
- amountrequired
- object{value, currency}.
- merchant_referenceoptional
- stringYour own order id, at most 120 characters. Returned on the session, its webhooks and every payment made through it.
- descriptionoptional
- string
- customer_email / customer_phone / customer_nameoptional
- stringPrefills the hosted page.
- return_url / cancel_urloptional
- stringWhere the hosted page sends the customer afterwards.
- allowed_methodsoptional
- arrayLimits the methods the hosted page offers, such as ["mobile_money", "settlo_balance"]. Leave it out or empty to offer every available method, Settlo Pay balance included.
- metadataoptional
- object
curl -X POST https://api.settlopay.co.tz/v1/checkout/sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: cs-ORD-8452" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": 25000, "currency": "TZS"},
"merchant_reference": "ORD-8452",
"return_url": "https://shop.example.co.tz/return",
"cancel_url": "https://shop.example.co.tz/cancel"
}'{
"id": "cs_01J9XD8E0F2G4H6J8K0M2N4P6Q",
"object": "checkout_session",
"state": "CREATED",
"url": "https://settlopay.co.tz/pay/cs_01J9XD8E0F2G4H6J8K0M2N4P6Q",
"amount": {"value": 25000.00, "currency": "TZS"},
"merchant_reference": "ORD-8452",
"return_url": "https://shop.example.co.tz/return",
"cancel_url": "https://shop.example.co.tz/cancel",
"expires_at": "2026-09-06T12:00:02Z",
"created_at": "2026-09-06T11:30:02Z"
}Pay from a Settlo Pay balance on a session
The hosted checkout page offers Settlo Pay balance itself, so there's nothing to build: the customer picks it, types their 12-digit Settlo Pay account number (spaces and dashes are fine), and enters the code we send them. Leave allowed_methods out or empty to offer every available method, Settlo Pay balance included, or list settlo_balance in it.
If you drive a session from your own page instead, these are the calls the hosted page makes. They take the session's cs_ id and no API key. POST /v1/public/checkout/sessions/{id}/confirm with method settlo_balance and account_number sends a 6-digit code to the payer's registered contact and answers with the attempt's attempt_id and next_action enter_code (channel, a masked sent_to, expires_at). Never ask the payer for a phone number or email: the code only ever goes to the contact on their own Settlo Pay account.
/verify-code with the code answers with the session's status: success is session_state PAID with latest_attempt.state SUCCEEDED. If latest_attempt.state says CAPTURING, read GET /v1/public/checkout/sessions/{id}/status again shortly. /resend-code, with an optional channel (sms or email), answers like /confirm, with the new next_action; a resend after the code expired sends a fresh one. /cancel-attempt cancels an open code so the customer can choose again.
A refusal ends at most that attempt: the session stays open, and the customer can choose another way to pay on it. code_invalid and code_expired leave the attempt open. We say the balance is too low (insufficient_balance) only after the right code. In the examples, Kibo Mini Market pays Settlo Technologies TZS 30,000.
When the session is paid you get checkout_session.paid and the payment's payment_intent.succeeded, with method settlo_balance and payer_account, the payer's display_name and account_number_masked. There are no new event types.
- account_not_payable
- 422, param account_number. "This Settlo Pay account can't pay here." The number is unknown, or that account can't pay right now. Usually refused before the attempt exists; if it comes once the attempt exists (while the code is sent, or on a resend), the attempt fails.
- same_account
- 422. "You can't pay your own account." The payer's account is your own. Refused before the attempt exists.
- code_invalid
- 422, param code. "That code isn't right." A blank code is refused the same way. The attempt stays open: let the customer try again.
- code_expired
- 422, param code. "That code has expired. Send a new one." The attempt stays open: resend a code.
- too_many_attempts
- 429. "Too many tries. Please choose another way to pay." Too many wrong codes, or too many codes sent. The attempt fails.
- insufficient_balance
- 422. "Your Settlo Pay balance isn't enough for this payment." Said only after the right code. The attempt fails.
- pay_another_way
- 422. "This payment can't be made from your Settlo Pay balance right now. Please choose another way to pay." Fails the attempt, or refuses the request before the attempt exists when your own account can't receive the money.
- resend_too_soon
- 429, with retry_after_seconds in the body and a Retry-After header. "Please wait a moment before asking for another code." The attempt stays open: offer to send again once the wait is over.
- try_later
- 503. The code couldn't be sent or checked just now, and nothing was taken. If it couldn't be sent, the attempt fails, so start again; if it couldn't be checked or resent, the attempt stays open, so try again.
- PAIDSucceeded
- session_state after the right code: latest_attempt.state is SUCCEEDED and the money has moved.
- AWAITING_PAYMENTPending
- The session is still open. latest_attempt.state says where the attempt is: AWAITING_CUSTOMER (the code is waiting), CAPTURING (read the status again shortly), FAILED (choose another way to pay), CANCELLED (after cancel-attempt) or EXPIRED (the attempt ran out of time).
curl -X POST https://api.settlopay.co.tz/v1/public/checkout/sessions/cs_01JC7K3A9B5C7D9E1F3G5H7J9M/confirm \
-H "Content-Type: application/json" \
-d '{"method": "settlo_balance", "account_number": "1012 3456 7895"}'{
"attempt_id": "pi_01JC7K3A9B5C7D9E1F3G5H7J9K",
"state": "AWAITING_CUSTOMER",
"method": "settlo_balance",
"next_action": {
"type": "enter_code",
"channel": "sms",
"sent_to": "+255******678",
"expires_at": "2026-11-06T10:40:05Z"
}
}curl -X POST https://api.settlopay.co.tz/v1/public/checkout/sessions/cs_01JC7K3A9B5C7D9E1F3G5H7J9M/verify-code \
-H "Content-Type: application/json" \
-d '{"code": "123456"}'{
"session_state": "PAID",
"expires_at": "2026-11-06T11:00:02Z",
"latest_attempt": {
"state": "SUCCEEDED",
"method": "settlo_balance",
"amount": 30000.00,
"created_at": "2026-11-06T10:30:05Z"
}
}curl -X POST https://api.settlopay.co.tz/v1/public/checkout/sessions/cs_01JC7K3A9B5C7D9E1F3G5H7J9M/resend-code \
-H "Content-Type: application/json" \
-d '{"channel": "sms"}'curl -X POST https://api.settlopay.co.tz/v1/public/checkout/sessions/cs_01JC7K3A9B5C7D9E1F3G5H7J9M/cancel-attemptQR code
Your QR code
Your account has one QR code: an image you print and put where customers pay. Customers scan it with their bank or wallet app. It's created when your account is activated.
image.svg is a public link to the finished image, available once the code is ACTIVE. It never changes, scales to any size, and works in an <img> tag or for printing.
When a customer pays by scanning it, you get a payment with origin payer_initiated (see Event types). qr_code.activated and qr_code.failed tell you when the code is ready or couldn't be set up.
Scopes: qr_code:read to retrieve it and qr_code:write to request it. Keys created without a scope list have both.
- id
- stringUnique identifier, starting qr_.
- state
- enumPENDING, ACTIVE or FAILED.
- label
- stringThe code's name, up to 60 characters.
- image
- object{svg}: a public link to the QR image. Show it as it is; the code isn't available as text. Only when ACTIVE.
- qr_merchant_id
- stringThe 8-digit Merchant ID a customer can type if the code won't scan. Only when ACTIVE.
- qr_kind
- stringstatic: the code is yours and doesn't change. Only when ACTIVE.
- failure_message
- stringWhy it couldn't be set up. Only when FAILED.
- created_at / updated_at
- stringISO 8601 with offset.
- PENDINGPending
- Being set up. Wait for `qr_code.activated`.
- ACTIVESucceeded
- Ready to print. `image.svg` is the image.
- FAILEDFailed
- Couldn't be set up; `failure_message` says why. Request it again to retry.
Retrieve your QR code
Retrieves your QR code. Requires qr_code:read. Returns 404 resource_missing if you don't have one yet; request one with POST /v1/qr_code.
curl https://api.settlopay.co.tz/v1/qr_code \
-H "Authorization: Bearer sk_live_..."{
"id": "qr_01J9XC7D9E1F3G5H7J9K1M3N5P",
"state": "ACTIVE",
"label": "Duka la Mwanza",
"image": {"svg": "https://settlopay.co.tz/qr/qr_01J9XC7D9E1F3G5H7J9K1M3N5P.svg"},
"qr_merchant_id": "12345678",
"qr_kind": "static",
"created_at": "2026-10-17T09:12:03+03:00",
"updated_at": "2026-10-17T09:14:40+03:00"
}Request your QR code
Requests your QR code. Requires qr_code:write and an Idempotency-Key. Returns 201 when it starts setting one up, for a new code or to retry a FAILED one, and 200 when you already have a PENDING or ACTIVE code. Reusing a key with a different body returns 409 idempotency_conflict.
label defaults to your trading name and can be up to 60 characters. You'll get qr_code.activated or qr_code.failed when setup finishes.
- labeloptional
- stringUp to 60 characters. Defaults to your trading name.
curl -X POST https://api.settlopay.co.tz/v1/qr_code \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: qr-duka-mwanza" \
-H "Content-Type: application/json" \
-d '{"label": "Duka la Mwanza"}'{
"id": "qr_01J9XC7D9E1F3G5H7J9K1M3N5P",
"state": "PENDING",
"label": "Duka la Mwanza",
"created_at": "2026-10-17T09:12:03+03:00",
"updated_at": "2026-10-17T09:12:03+03:00"
}Webhooks
Receiving webhooks
Add an HTTPS endpoint in the Dashboard and choose the events to receive, or "*" for all of them. You can have up to 5 endpoints. The signing secret (whsec_…) is shown once, when you create the endpoint or rotate its secret.
Verify every delivery. The Settlo-Signature header has a timestamp t and a signature v1: an HMAC-SHA256 of t, a . and the raw request body, keyed with your full whsec_… secret. Reject deliveries more than five minutes old, and compare signatures in constant time.
Each delivery has a Settlo-Event-Id header; retries reuse it, so use it to skip duplicates. Take the version from the body's api_version. The sample is shortened: Event bodies lists every field. We may add fields, so ignore any you don't use.
{
"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();
}Delivery, retries, and rotation
Return a 2xx status quickly. We wait 2 seconds to connect and 10 seconds to read, so do slow work after you respond. Failed deliveries are retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours, then every 24 hours three times: about 3 days in all.
After 50 consecutive failures, the endpoint is disabled. Rotate its secret in the Dashboard to turn it back on. Missed events aren't resent, so use GET /v1/payments to catch up. Redirects aren't followed.
A rotated secret takes effect immediately, so update your server as soon as you rotate. Deliveries that fail in between are retried.
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.
- Connect timeout
- 2 s
- Read timeout
- 10 s
- Auto-disable after
- 50 failures
Event types
Subscribe only to the events you need. Events can arrive out of order, so act on the object's current state.
Every payment_intent.* event has an origin: merchant_initiated if you started the payment (by API, hosted checkout or bill), balance if the customer paid from their Settlo Pay balance, or payer_initiated if the customer paid without an order, by scanning your QR code or paying your account number under Lipa Bili in the Mixx by Yas menu. A payer-initiated payment is already SUCCEEDED, so payment_intent.created and payment_intent.succeeded arrive together. Its method is qr for a scan and mobile_money for Lipa Bili. It has no merchant_reference unless it paid one of your bills (then the bill's reference) or counts toward a payment of yours (then that payment's, with linked_payment_id).
To help you match these payments, a payer_initiated event can also include paid_at, when the customer paid; on a QR payment, payer_institution, the code of the customer's bank or wallet; and on Lipa Bili, account_number, the number the customer entered. Any mobile money payment that succeeds, yours or the customer's, also carries payer_receipt: the transaction code on the customer's confirmation message.
A QR payment that doesn't match its order, because the amount differs or it was paid after the code expired, is held for review. If our team credits it to a payment of yours, it carries linked_payment_id and that payment's merchant_reference. Its amount is what the customer actually paid, so check it before you fulfil the order.
A qr payment can be paid in parts. Each part is its own payment, and payment_intent.partially_paid reports it on the payment it counts toward. payment_intent.amended follows an amount change. When separate payments complete a QR payment, its payment_intent.succeeded has settled_by linked_payments: the money is on those payments, not this one.
An app connected to your account, such as Settlo POS, can claim a customer-started payment for one of its orders. You get payment_intent.claimed, and payment_intent.unclaimed if it lets go. Use claim_ref to find the order the payment went to. A claim doesn't move money.
A payment from a Settlo Pay balance has method settlo_balance, and once it succeeds its events also carry payer_account: the payer's display_name and account_number_masked. It uses the event types below; there are no new ones.
bill.* events cover the bills you send customers. A bill can be paid in any number of payments, and each one also sends payment_intent.succeeded.
Subscribing to "*" sends every event below, including refund.created and payout.rejected, which you can't choose one by one.
- payment_intent.created
- A payment was created.
- payment_intent.requires_action
- The customer needs to act. See next_action.
- payment_intent.authorized
- The payment was approved.
- payment_intent.partially_paid
- Part of a qr payment's amount arrived and a balance is still owed.
- payment_intent.amended
- A qr payment's amount was changed.
- payment_intent.claimed
- An app connected to your account claimed a customer-started payment for one of its orders.
- payment_intent.unclaimed
- That claim was released.
- payment_intent.succeeded
- The money has arrived.
- payment_intent.failed
- The payment was declined, or the customer didn't approve in time.
- payment_intent.cancelled
- The payment was cancelled.
- payment_intent.expired
- The payment wasn't paid before it expired.
- refund.succeeded
- A refund completed. Carries payout_ref and payout_transaction_no, the reference and transaction number of the payout that sent the money. A refund of a settlo_balance payment has neither: it went straight back to the payer's Settlo Pay balance.
- refund.created
- A refund was created. Sent only to "*" subscriptions.
- refund.failed
- A refund failed.
- payout.authorized
- A payout was debited from your balance and sent.
- payout.succeeded
- The destination received the money.
- payout.failed
- A payout was returned; the amount and fee were credited back.
- payout.under_review
- A payout is waiting for review; its money is set aside. The outcome follows.
- payout.declined
- A payout under review was declined. Nothing was sent, and the amount, fee and VAT returned to your balance.
- payout.expired
- A payout under review wasn't reviewed within 24 hours. Nothing was sent, and the money returned to your balance.
- payout.cancelled
- A payout under review was cancelled. Nothing was sent, and the money returned to your balance.
- payout.rejected
- Your balance couldn't cover a payout, so nothing was debited. Sent only to "*" subscriptions.
- checkout_session.created
- A checkout session was created.
- checkout_session.confirmed
- The customer chose a method and confirmed on the hosted page.
- checkout_session.paid
- The session's payment succeeded.
- checkout_session.cancelled
- The session was cancelled.
- checkout_session.expired
- The session expired unpaid.
- bill.paid
- A bill has been paid.
- bill.voided
- A bill was voided and can no longer be paid.
- bill.payment_received
- A payment arrived on a bill: in part, in full, or after it was closed (after_final).
- bill.expired
- A bill expired unpaid or part-paid and can no longer be paid.
- qr_code.activated
- Your QR code is ready to print; the event carries its image link.
- qr_code.failed
- Your QR code couldn't be set up; request it again.
Event bodies
An event's data holds the object's fields. Fields without a value are left out. Amounts are numbers with a separate currency field, such as "amount": 25000.00, "currency": "TZS". external_id and transaction_no are older names for id and ref.
- payment_intent.*
- id, ref, merchant_id, amount, currency, method, state, origin and occurred_at on every event. merchant_reference, description and customer_name when the payment has them; payer_masked and payer_network for a payment with a phone number; next_action while the customer needs to act; failure_code on payment_intent.failed; customer_fee, customer_fee_vat and total_charged when the customer pays the fee; fee, fee_vat, net and fee_bearer on payment_intent.succeeded (not on a settlo_balance payment); payer_receipt once a mobile money payment succeeds; payer_account ({display_name, account_number_masked}) once a settlo_balance payment succeeds. A qr payment adds amount_received and overpaid on payment_intent.succeeded, payment_intent.cancelled and payment_intent.expired; settled_by (linked_payments) when separate payments completed it; amount_received, balance, received_payment_id and received_payment_ref on payment_intent.partially_paid; previous_amount and amount on payment_intent.amended. A customer-started payment can add linked_payment_id, paid_at, payer_institution and account_number. A claimed payment's events add claim_partner, claim_ref, claim_label (when given), claim_amount and claimed_at; payment_intent.unclaimed carries only claim_partner, claim_ref and claim_label.
- refund.*
- id, ref, payment_intent (the refunded payment's pi_ id), merchant_id, amount, currency, state, reason and occurred_at; merchant_reference when you gave one; payout_ref and payout_transaction_no on refund.succeeded (none for a settlo_balance refund); failure_code on refund.failed.
- payout.*
- id, ref, merchant_id, amount, currency, fee, vat, destination_purpose, destination_fsp_code, destination_account_masked and occurred_at; destination_account_name when the destination has one; merchant_reference when you gave one; destination_id (dst_) and destination_kind on payout.authorized (a payout to a Settlo Pay account reads SETTLO in destination_fsp_code and has no payout.authorized); failure_code on payout.failed and payout.rejected; cancel_reason on payout.cancelled.
- checkout_session.*
- id, merchant_id, amount, currency, state, merchant_reference, return_url, cancel_url and expires_at.
- bill.*
- external_id (bil_), number (REQ…), merchant_id, amount, amount_paid, balance, currency, description, customer_name, state, expires_at and occurred_at; reference (the reference you gave the bill) and due_at when the bill has them; overpaid once more than the balance has arrived; payment_id (the payment's own), payment_amount, payment_ref, received_at, relation (DURING, AFTER_END or UNEXPECTED for a QR code payment, CHECKOUT for the bill's page, PROMPT for a phone prompt) and after_final on bill.payment_received; payment_id, paid_by_ref (the ref of the payment that settled it) and paid_at on bill.paid.
- qr_code.*
- id (qr_), merchant_id, state, label and occurred_at; image (svg, the public link), qr_merchant_id and qr_kind (static) on qr_code.activated; failure_message on qr_code.failed.
Reference
Errors
Errors return a JSON body with a type, a code you can handle in your code, a readable message, the param at fault when there is one, and a request_id. Include the request_id when you contact support.
- 400 invalid_requestvalidation_error
- The body isn't valid JSON, or a value has the wrong type.
- 400 parameter_invalidvalidation_error
- A field or header is invalid or missing; param names it.
- 400 unsupported_currencyvalidation_error
- Payouts accept TZS only.
- 400 unsupported_methodvalidation_error
- The payment method isn't supported.
- 400 unsupported_phone_networkvalidation_error
- We couldn't find a network for the phone number, or the network isn't recognised.
- 401 authentication_requiredauthentication_error
- The API key is missing, invalid or revoked.
- 402 payment_failedbusiness_decline
- The payment can't be processed right now.
- 403 permission_deniedauthorization_error
- Your key isn't allowed to do this, for example because it lacks a scope.
- 403 merchant_not_transactablepermission_denied
- Your account can't transact: it isn't approved yet, or it's suspended.
- 404 resource_missinginvalid_request_error
- There's no such object on your account.
- 409 idempotency_conflictidempotency_error
- The key was used with a different body, or the first request is still in progress.
- 409 state_invalidinvalid_request_error
- The action isn't allowed in the object's current state.
- 409 confirmation_not_pendingstate_invalid
- The beneficiary isn't waiting for a code.
- 409 payout_not_cancellableinvalid_request_error
- The payout isn't under review, or its review already ended. The body's outcome says which.
- 422 insufficient_fundsbusiness_decline
- Your balance can't cover the payout.
- 422 no_payout_destinationbusiness_decline
- You left out destination_id and have no settlement account.
- 422 payout_limit_exceededbusiness_decline
- The payout is above your per-payout or daily limit; param is amount or daily.
- 422 payout_unpriceablebusiness_decline
- The payout can't be priced right now. The message says what to do.
- 422 refund_unsupported_methodbusiness_decline
- QR payments and customer-started (payer_initiated) payments can't be refunded through the API; contact support.
- 422 insufficient_balancebusiness_decline
- Your balance can't cover the refund and its fee. On a settlo_balance payment: the payer's Settlo Pay balance isn't enough, said only after the right code.
- 422 account_not_payablebusiness_decline
- settlo_balance: this Settlo Pay account can't pay here. param is account_number.
- 422 same_accountbusiness_decline
- settlo_balance: the payer's Settlo Pay account is your own.
- 422 code_invalidbusiness_decline
- settlo_balance: the code isn't right. The payment stays open; try again.
- 422 code_expiredbusiness_decline
- settlo_balance: the code has expired. The payment stays open; resend a code.
- 422 pay_another_waybusiness_decline
- settlo_balance: this payment can't be made from a Settlo Pay balance right now. The payment fails, or the create is refused before the payment exists; offer another way to pay.
- 422 payer_account_unknownbusiness_decline
- The payment is too old to refund (over 30 days).
- 422 payer_name_unknownbusiness_decline
- Settlo Pay could not find the account holder's name for the customer's number, so the refund can't be sent.
- 422 payment_disputedbusiness_decline
- The payment is under dispute, so it can't be refunded.
- 422 payment_not_refundablebusiness_decline
- The payment can't be refunded.
- 422 risk_blockedbusiness_decline
- Risk checks declined the payout.
- 422 merchant_not_activatedbusiness_decline
- Your account isn't activated yet.
- 422 merchant_suspendedbusiness_decline
- Your account is suspended.
- 422 beneficiary_account_not_foundvalidation_error
- The bank, network or Settlo Pay has no account with that number. On a payout to a Settlo Pay account (type business_decline), that account can't receive money right now, and nothing moved.
- 422 beneficiary_own_accountvalidation_error
- That Settlo Pay account is your own, so it can't be a beneficiary.
- 422 beneficiary_limit_reachedvalidation_error
- You've reached the maximum number of beneficiaries, pending ones included.
- 422 beneficiary_not_confirmedbusiness_decline
- The beneficiary isn't confirmed yet. Confirm it, then pay.
- 422 beneficiary_rejectedvalidation_error
- Screening declined the beneficiary.
- 422 confirmation_code_expiredinvalid_request_error
- The code has expired or run out of tries; resend a new one.
- 422 confirmation_code_invalidinvalid_request_error
- Wrong code; the message says how many tries are left.
- 422 no_confirmation_channelinvalid_request_error
- The account holder has no phone number or email on file to send the code to.
- 429 rate_limit_exceededrate_limit_error
- Too many requests. Wait for the Retry-After seconds.
- 429 confirmation_throttledrate_limit_error
- Codes were resent too often. Wait for the Retry-After seconds.
- 429 too_many_attemptsrate_limit_error
- settlo_balance: too many wrong codes, or too many codes sent. The payment fails; offer another way to pay.
- 429 resend_too_soonrate_limit_error
- settlo_balance: a new code was asked for too soon. Wait retry_after_seconds (also the Retry-After header); the payment stays open.
- 500 api_errorapi_error
- Something went wrong on our side. Contact support with the request_id.
- 502 provider_errorprovider_error
- The payment network returned an error.
- 503 service_unavailableapi_error
- Temporarily unavailable. Try again later.
- 503 try_laterapi_error
- Temporarily unavailable. Try again later; for a payout, or a settlo_balance payment whose code couldn't be sent, use a new Idempotency-Key.
- 504 provider_timeoutprovider_error
- The payment network didn't respond in time.
{
"type": "business_decline",
"code": "insufficient_funds",
"message": "Insufficient funds to complete this payout",
"param": "amount.value",
"request_id": "0d9f7c3a-4c2e-7d31-b2aa-91d2f2f4e9a1"
}Rate limits
You can make up to 200 requests per minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, you get 429 rate_limit_exceeded with a Retry-After header in seconds.
Webhook deliveries don't count toward your limit.
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187Version 2026-04-29Last updated 6 Nov 2026