API Reference

The Payout API Reference provides all the technical details you need to integrate with TemboPlus — including authentication, environments, supported channels, and standard response formats.

Use this reference as the foundation for all Payout endpoints.

🔐 Authentication

All Payout API requests require two headers for authentication:

• x-account-id — Your unique partner account identifier provided by TemboPlus

• x-secret-key — Your API secret key used to authorize and sign each request

Each request is authenticated by verifying these headers. Requests without valid credentials will return a 401 INVALID_CREDENTIALS error.

Never share your secret key publicly or embed it in client-side code.

🧾 Required Request Headers

Each API request must include the following headers:

• Content-Type: application/json Defines the request body format.

• x-account-id: Partner account identifier. Used to identify the organization making the call.

• x-secret-key: Secret key assigned by TemboPlus. Used for authentication.

• x-request-id: A unique UUID generated by you for every request. Helps TemboPlus trace and support your transactions when needed.

Example:

POST /collection HTTP/1.1
Content-Type: application/json
x-account-id: 6da81b2c
x-secret-key: a72f0e03c42e8b52
x-request-id: 734cc91d-4291-46cf-b96b-9f223d3c1be9

---

🌍 Environments

TemboPlus provides separate environments for testing and production.

Sandbox Environment

Used for testing and development. All transactions here are simulated and do not move real funds.

https://sandbox.temboplus.com/tembo/v1

Production Environment

Used for live transactions once integration is complete.

https://api.temboplus.com/tembo/v1

You will receive unique credentials (x-account-id, x-secret-key) for each environment.

---

📡 Supported Channels

Each environment supports specific mobile money channels.

Sandbox

• TZ-AIRTEL-B2C

• TZ-TIGO-B2C

Production

• TZ-AIRTEL-B2C

• TZ-TIGO-B2C

• TZ-HALOTEL-B2C

• TZ-VODACOM-B2C

• TZ-BANK-B2C

---

⚠️ Common Error Responses

These standard error responses may apply to all Payout endpoints.

400 BAD REQUEST

Returned when the request payload is missing required fields or has invalid data.

Response Format

{
  "statusCode": 400,
  "reason": "VALIDATION_ERROR",
  "details": {
    "fieldName": "\"fieldName\" is required"
  },
  "message": "{\"fieldName\":\"\\\"fieldName\\\" is required\"}"
}

401 UNAUTHORIZED

Returned when x-account-id or x-secret-key is incorrect or missing.

Response Format

{
    "statusCode": 401,
    "reason": "INVALID_CREDENTIALS",
    "details": {}
}

500 INTERNAL SERVER ERROR

Indicates a temporary issue with TemboPlus service.

Response Format

{
    "statusCode": 500,
    "reason": "SERVER_ERROR"
}