Initiate Payout

Use this endpoint to initiate a payout to either a bank account or a mobile money wallet in Tanzania. The beneficiary receives funds based on the selected channel and processing system.

Endpoint

 POST /payment/wallet-to-mobile

Request

Headers

• Content-Type* — Must be application/json

• x-account-id* — Your unique TemboPlus account identifier

• x-secret-key* — Your TemboPlus API secret key

• x-request-id* — Unique UUID per request for tracing

Body Parameters

• serviceCode* (string) — The channel to be used for the payout. Supported values include: TZ-AIRTEL-B2C, TZ-TIGO-B2C, TZ-HALOTEL-B2C, TZ-VODACOM-B2C, TZ-BANK-B2C.

• msisdn* (string) — The recipient identifier. For mobile money: recipient's mobile number in format 255XXXXXXXXX. For banks: format SWIFT_CODE:ACCOUNT_NUMBER (e.g., CORUTZTZ:0150123456789).

• accountNo* (string) — Your disbursement wallet account number. Retrieve this using the Get Disbursement Wallet Balance endpoint.

• amount* (number) — The payout amount in Tanzanian Shillings (TZS). The value must be a positive integer.

• countryCode* (string) — Country code. Always TZ for Tanzania.

• currencyCode* (string) — Currency code. Always TZS for Tanzania.

• narration* (string) — A short description of the payout. This will appear in your statement.

• recipientNames* (string) — Recipient's full name or company name.

• transactionRef* (string) — Your unique transaction reference for reconciliation.

• transactionDate* (string) — The timestamp of the request in ISO 8601 format, e.g. 2025-09-11T10:30:00Z.

• callbackUrl* (string) — Your HTTPS endpoint where TemboPlus will send a POST notification once the payout status changes.

Matching msisdn to serviceCode

For Mobile Money Payouts:

The msisdn must belong to the same Mobile Network Operator (MNO) specified in the serviceCode field.

Examples:

• Use TZ-AIRTEL-B2C for numbers starting with Airtel prefixes (e.g. 068x, 078x).

• Use TZ-TIGO-B2C for Tigo prefixes (e.g. 065x, 071x).

• Use TZ-HALOTEL-B2C for Halotel prefixes (e.g. 062x).

Tanzania does not implement Mobile Number Portability (MNP), so mobile numbers remain tied to their original operator prefixes.

For precise validation, request the MNO Prefix Reference Document from TemboPlus Support for the current mapping of prefixes to channels.

For Bank Payouts:

Use serviceCode: TZ-BANK-B2C

The msisdn must follow the format: SWIFT_CODE:ACCOUNT_NUMBER where SWIFT_CODE is the bank's BIC code and ACCOUNT_NUMBER is the recipient's account number.

Example: CORUTZTZ:0150123456789

For a complete list of supported banks and their BIC/SWIFT codes, reference the Payout Page in the section "Supported Payout Channels"

Payout Limits

• Mobile Money: Minimum TZS 1,000, maximum TZS 5,000,000.

• Bank Payouts: Minimum TZS 1,000, no fixed maximum. Note: Some banks may not process transactions below TZS 5,000.

Example Request Payload

Mobile Money Payout

{
  "countryCode": "TZ",
  "accountNo": "9000123456",
  "serviceCode": "TZ-TIGO-B2C",
  "amount": 50000,
  "msisdn": "255712345678",
  "narration": "Salary Payment - September 2025",
  "currencyCode": "TZS",
  "recipientNames": "John Doe",
  "transactionRef": "SAL-2025-09-001",
  "transactionDate": "2025-09-11T10:30:00Z",
  "callbackUrl": "https://yourdomain.com/webhooks/payout"
}

Bank Payout

{
  "countryCode": "TZ",
  "accountNo": "9000123456",
  "serviceCode": "TZ-BANK-B2C",
  "amount": 150000,
  "msisdn": "CORUTZTZ:0150987654321",
  "narration": "Vendor Payment - Invoice #2025-123",
  "currencyCode": "TZS",
  "recipientNames": "ABC Supplies Ltd",
  "transactionRef": "VEN-2025-09-001",
  "transactionDate": "2025-09-11T10:30:00Z",
  "callbackUrl": "https://yourdomain.com/webhooks/payout"
}

Responses

200 OK

If the request is valid and the request was successfully sent to the provider for processing.

{
  "statusCode": "PAYMENT_ACCEPTED",
  "transactionId": "ddZFz7rWkIvU", // sample value; will differ per request
  "transactionRef": "ODR-2025-09-001" // sample reference from your system
}

Response Fields:

• statusCode — Indicates the current state of the initiated payout. Possible values include PENDING, PAYMENT_ACCEPTED, PAYMENT_REJECTED, GENERIC_FAILURE, and PROVIDER_FAILED.

• transactionId — A unique identifier for this transaction, generated by TemboPlus.

• transactionRef — Echo of your original transaction reference.

400 BAD REQUEST

Most commonly happens in the following two cases:

1. Insufficient Balance

Triggered when the partner’s disbursement wallet does not have enough funds to complete the transfer.

Response Format

{
    "statusCode": 400,
    "reason": "INSUFFICIENT_BALANCE",
    "details": {}
}

---

2. Validation Error

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

Response Format

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

Fields inside details and message are optional and vary depending on the specific validation failure.

---

Common Validation Errors to Avoid

• Ensure all required fields are included in the request body.

• amount must be an integer (whole number) — decimals are not allowed.

• msisdn must be in the correct international format, according to the serviceCode used.

• Use only supported channel codes that correspond to valid msisdn used.

• x-request-id must be included in the request headers.

401 UNAUTHORIZED

Returned when authentication headers are missing or invalid.

Response Format

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

404 NOT FOUND

This error typically occurs when the account number provided is invalid. Ensure you use a valid account number by querying the Get Disbursement Wallet Balance endpoint.

Response Format

{
  "statusCode": 404,
  "reason": "WALLET_NOT_FOUND",
  "details": {}
}

500 INTERNAL SERVER ERROR

Indicates a temporary issue within TemboPlus. Retry later or contact TemboPlus Support with your x-request-id.

Response Format

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

Webhook Notification

After the payout is processed, TemboPlus sends a POST request to your configured callbackUrl with the final transaction outcome.

The webhook body contains the same identifiers returned in the initial response, along with an updated statusCode value. Possible values for statusCode include PAYMENT_ACCEPTED, PAYMENT_REJECTED and GENERIC_FAILURE.

Example:

{
  "statusCode": "PAYMENT_ACCEPTED",
  "transactionId": "ddZFz7rWkIvU",
  "transactionRef": "SAL-2025-09-001",
  "meta": {}
}

Values above are examples only; actual transactionId and transactionRef will vary per request.

Webhook Delivery Notes

• TemboPlus will make a POST request to your callbackUrl after receiving the final response from the provider.

• Each webhook contains a JSON payload with statusCode, transactionId, transactionRef, and optional meta object.

• Webhook delivery is asynchronous; the callback may arrive seconds to hours after the initial API response, depending on the channel.

• Always validate both transactionId and transactionRef before updating your internal records.

• Your endpoint should return an HTTP 200 OK response upon successful receipt to acknowledge the notification.

Status Code Behavior

The statusCode returned in the initial response can vary significantly depending on the Mobile Network Operator or bank processing the transaction.

Observed Behaviors:

• Immediate Acceptance: Some providers return PAYMENT_ACCEPTED immediately upon successful validation.

• Pending Processing: Other providers may return PENDING or similar status codes initially, with final confirmation coming later via callback.

Recommendation: Always implement webhook callback handling and use the Check Transaction Status endpoint to verify final transaction outcomes.