> For the complete documentation index, see [llms.txt](https://tembo.gitbook.io/tembo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tembo.gitbook.io/tembo/momo-collection-and-payout-api/api-reference/payout/initiate-local-payout.md).

# Initiate Local Payout

### Endpoint

```
 POST /payment/wallet-to-mobile
```

### Request

#### **Headers**

* **`Content-Type`**<mark style="color:red;">**\***</mark> — Must be `application/json`&#x20;
* **`x-account-id`**<mark style="color:red;">**\***</mark> — Your unique TemboPlus account identifier
* **`x-secret-key`**<mark style="color:red;">**\***</mark> — Your TemboPlus API secret key
* **`x-request-id`**<mark style="color:red;">**\***</mark> — Unique UUID per request for tracing

#### Body Parameters

* **`serviceCode`**<mark style="color:red;">**\***</mark> *(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`**<mark style="color:red;">**\***</mark> *(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`**<mark style="color:red;">**\***</mark> *(string)* — Your disbursement wallet account number. Retrieve this using the Get Disbursement Wallet Balance endpoint.
* **`amount`**<mark style="color:red;">**\***</mark> *(number)* — The payout amount. The value must be a positive integer.
* **`countryCode`**<mark style="color:red;">**\***</mark> *(string)* — Country code. Supported values are `TZ` and `KE`.
* **`currencyCode`**<mark style="color:red;">**\***</mark> *(string)* — Currency code. Supported values are `TZS` and `KSH`.
* **`narration`**<mark style="color:red;">**\***</mark> *(string)* — A short description of the payout. This will appear in your statement.
* **`recipientNames`**<mark style="color:red;">**\***</mark> *(string)* — Recipient's full name or company name.
* **`transactionRef`**<mark style="color:red;">**\***</mark> *(string)* — Your unique transaction reference for reconciliation.
* **`transactionDate`**<mark style="color:red;">**\***</mark> *(string)* — The timestamp of the request in ISO 8601 format, e.g. `2025-09-11T10:30:00Z`.
* **`callbackUrl`**<mark style="color:red;">**\***</mark> *(string)* — Your HTTPS endpoint where TemboPlus will send a POST notification once the payout status changes.

### Example Request Payload

#### Mobile Money Payout

```json
{
  "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

```json
{
  "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

<details>

<summary><code>200</code> OK</summary>

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

```json
{
  "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.

</details>

<details>

<summary><code>400</code> BAD REQUEST</summary>

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**

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

***

#### **2. Validation Error**

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

**Response Format**

```json
{
  "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.

</details>

<details>

<summary><code>401</code> UNAUTHORIZED</summary>

Returned when authentication headers are missing or invalid.

#### Response Format

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

</details>

<details>

<summary><code>404</code> NOT FOUND</summary>

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

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

</details>

<details>

<summary><code>500</code> INTERNAL SERVER ERROR</summary>

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

#### Response Format

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

</details>