Payments
Collect money from customers via mobile money, cards, or QR codes
The Payments API allows you to collect money from customers through various channels.
Payment Types
Mobile Money
Airtel Money, M-Pesa, Mixx by Yas, Halotel. Customer receives USSD push to authorize.
Card Payments
Visa, Mastercard, local debit cards. Customer redirected to secure checkout.
Dynamic QR
QR code customers scan with their mobile money app to pay.
Payment Flow
Customer Completes Payment - Mobile: USSD push to customer's phone -
Card: Redirect to payment_url - QR: Customer scans
payment_qr_code
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/v1/payments | POST | Create payment intent |
/v1/payments | GET | List all payments |
/v1/payments/{reference} | GET | Get payment status |
/v1/payments/{reference}/push | POST | Trigger USSD push |
/v1/payments/balance | GET | Get account balance |
/v1/payments/search | GET | Search payments |
Payment Status
| Status | Description |
|---|---|
pending | Payment created, awaiting customer action |
completed | Payment successful, funds received |
failed | Payment failed (declined, timeout, etc.) |
voided | Payment cancelled before completion |
expired | Payment expired (4 hour timeout) |
Payments expire after 4 hours if not completed. Create a new payment if the customer wants to retry.
List Payments
Retrieve all payments for your account with pagination.
GET /v1/payments?limit=20&offset=0
Authorization: Bearer <api_key>Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Results per page (max 100) |
offset | integer | 0 | Pagination offset |
Response
{
"status": "success",
"code": 200,
"data": {
"items": [
{
"amount": {
"currency": "TZS",
"value": 500
},
"api_version": "2026-01-25",
"channel": {
"provider": "selcomtanqr",
"type": "other"
},
"completed_at": "2026-01-25T00:50:44.105159Z",
"created_at": "2026-01-25T00:47:50.243311Z",
"customer": {
"email": "customer@email.com",
"first_name": "Customer",
"last_name": "Name",
"phone": "+255781000000"
},
"external_reference": "S20388368013",
"id": "672ad0e0-f95b-46b8-a91a-09490351055b",
"metadata": {
"order_id": "ORD-12345"
},
"object": "payment",
"payment_type": "dynamic-qr",
"reference": "6a490816-799b-4fc9-b9b6-2ec67c54e17e",
"settlement": {
"fees": { "currency": "TZS", "value": 9 },
"gross": { "currency": "TZS", "value": 500 },
"net": { "currency": "TZS", "value": 491 }
},
"status": "completed"
}
],
"total": 81,
"limit": 20,
"offset": 0
}
}Get Payment Status
Retrieve the current status of a payment by its reference.
GET /v1/payments/{reference}
Authorization: Bearer <api_key>Response
{
"status": "success",
"code": 200,
"data": {
"amount": {
"currency": "TZS",
"value": 500
},
"api_version": "2026-01-25",
"channel": {
"provider": "selcomtanqr",
"type": "other"
},
"completed_at": "2026-01-25T00:50:44.105159Z",
"created_at": "2026-01-25T00:47:50.243311Z",
"expires_at": "2026-01-25T04:47:50.159178Z",
"object": "payment",
"payment_type": "dynamic-qr",
"reference": "6a490816-799b-4fc9-b9b6-2ec67c54e17e",
"status": "completed"
}
}Get Account Balance
Retrieve your current account balance.
GET /v1/payments/balance
Authorization: Bearer <api_key>Response
{
"status": "success",
"code": 200,
"data": {
"api_version": "2026-01-25",
"available": {
"currency": "TZS",
"value": 6943
},
"balance": {
"currency": "TZS",
"value": 6943
},
"object": "balance"
}
}Search Payments
Search for payments by reference.
GET /v1/payments/search?reference={payment_reference}
Authorization: Bearer <api_key>Query Parameters
| Parameter | Type | Description |
|---|---|---|
reference | string | Payment reference to search |
Idempotency
Always use the Idempotency-Key header to prevent duplicate payments when
retrying failed requests.
POST /v1/payments
Idempotency-Key: order-12345-attempt-1- Keys are valid for 24 hours
- Same key + same request body = returns cached response
- Same key + different body = returns error