Initiate Local Payout

Use this endpoint to initiate a payout to either a bank account or a mobile money wallet. 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, KE-SAFARICOM-B2C, KE-BANK-B2C.

• msisdn* (string) — The recipient identifier. For mobile money: recipient's mobile number in format 25(4|5)XXXXXXXXX. 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. The value must be a positive integer.

• countryCode* (string) — Country code. Supported values are TZ and KE.

• currencyCode* (string) — Currency code. Supported values are TZS and KES.

• 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.

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"
}