> ## Documentation Index
> Fetch the complete documentation index at: https://docs.splashpay.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Selcom Pesa Disbursement

> Send funds instantly to Selcom Pesa wallets using the SplashPay Disbursement API.

# Selcom Pesa Disbursement

The Selcom Pesa Disbursement API allows you to transfer funds from your SplashPay wallet directly to a **Selcom Pesa wallet**.

Selcom Pesa transfers are processed instantly and are ideal for wallet-to-wallet transfers within the Selcom ecosystem.

***

## Endpoint

```http theme={null}
POST /disbursements/selcompesa
```

***

## Authentication

Every request must include your API credentials.

| Header          | Required | Description               |
| --------------- | :------: | ------------------------- |
| X-API-KEY       |     ✅    | Merchant API Key          |
| X-API-SECRET    |     ✅    | Merchant API Secret       |
| Idempotency-Key |     ✅    | Unique request identifier |
| Content-Type    |     ✅    | application/json          |

***

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request POST \
      --url https://api.splashpay.co.tz/api/v1/disbursements/selcompesa \
      --header "Content-Type: application/json" \
      --header "X-API-KEY: pk_live_xxxxxxxxx" \
      --header "X-API-SECRET: sk_live_xxxxxxxxx" \
      --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
      --data '{
          "reference":"SP-100001",
          "wallet_number":"255747123456",
          "wallet_name":"John Doe",
          "amount":50000,
          "currency":"TZS",
          "remarks":"Wallet Transfer",
          "metadata":{
              "customer_id":"CUS-1001"
          }
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.splashpay.co.tz/api/v1/disbursements/selcompesa",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.SPLASHPAY_KEY,
          "X-API-SECRET": process.env.SPLASHPAY_SECRET,
          "Idempotency-Key": crypto.randomUUID(),
        },
        body: JSON.stringify({
          reference: "SP-100001",
          wallet_number: "255747123456",
          wallet_name: "John Doe",
          amount: 50000,
          currency: "TZS",
          remarks: "Wallet Transfer"
        }),
      }
    );

    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import uuid
    import requests

    response = requests.post(
        "https://api.splashpay.co.tz/api/v1/disbursements/selcompesa",
        headers={
            "X-API-KEY": "pk_live_xxxxxxxxx",
            "X-API-SECRET": "sk_live_xxxxxxxxx",
            "Idempotency-Key": str(uuid.uuid4()),
            "Content-Type": "application/json",
        },
        json={
            "reference": "SP-100001",
            "wallet_number": "255747123456",
            "wallet_name": "John Doe",
            "amount": 50000,
            "currency": "TZS",
            "remarks": "Wallet Transfer",
        },
    )

    print(response.json())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $client = new \GuzzleHttp\Client();

    $response = $client->post(
        'https://api.splashpay.co.tz/api/v1/disbursements/selcompesa',
        [
            'headers' => [
                'X-API-KEY' => 'pk_live_xxxxxxxxx',
                'X-API-SECRET' => 'sk_live_xxxxxxxxx',
                'Idempotency-Key' => uniqid(),
            ],
            'json' => [
                'reference' => 'SP-100001',
                'wallet_number' => '255747123456',
                'wallet_name' => 'John Doe',
                'amount' => 50000,
                'currency' => 'TZS',
                'remarks' => 'Wallet Transfer',
            ],
        ]
    );

    echo $response->getBody();
    ```
  </Tab>
</Tabs>

***

## Request Body

| Field          | Type    | Required | Description                      |
| -------------- | ------- | :------: | -------------------------------- |
| reference      | string  |     ✅    | Unique merchant payout reference |
| wallet\_number | string  |     ✅    | Selcom Pesa wallet number        |
| wallet\_name   | string  |     ✅    | Wallet owner's full name         |
| amount         | decimal |     ✅    | Amount to transfer               |
| currency       | string  |     ✅    | Transaction currency (TZS)       |
| remarks        | string  |     ✅    | Payment description              |
| metadata       | object  |    No    | Additional merchant data         |

***

## Example Response

```json theme={null}
{
  "status": "success",
  "code": "DISBURSEMENT_INITIATED",
  "message": "Disbursement initiated successfully.",
  "data": {
    "reference": "SP-100001",
    "amount": "50000.00",
    "fee": "0.00",
    "total_amount": "50000.00",
    "currency": "TZS",
    "wallet_number": "255747123456",
    "wallet_name": "John Doe",
    "provider": "selcom",
    "status": "processing",
    "remarks": "Wallet Transfer",
    "metadata": {}
  },
  "request_id": "cb71e86c-8055-4e61-b59d-8dd82d92b624"
}
```

***

## Transaction Status

| Status     | Description                     |
| ---------- | ------------------------------- |
| pending    | Request received                |
| processing | Submitted to Selcom             |
| paid       | Transfer completed successfully |
| failed     | Transfer failed                 |
| cancelled  | Transfer cancelled              |

***

## Wallet Name Lookup

To minimize failed transactions, verify the wallet before initiating the transfer.

```http theme={null}
POST /disbursements/name-lookup
```

Example request:

```json theme={null}
{
  "type": "SELCOMPESA",
  "wallet_number": "255747123456"
}
```

Example response:

```json theme={null}
{
  "status": "success",
  "data": {
    "wallet_name": "John Doe"
  }
}
```

***

## Error Codes

| Code                  | Description                             |
| --------------------- | --------------------------------------- |
| INVALID\_WALLET       | Invalid Selcom Pesa wallet              |
| WALLET\_NOT\_FOUND    | Wallet does not exist                   |
| INSUFFICIENT\_BALANCE | Merchant wallet balance is insufficient |
| DUPLICATE\_REFERENCE  | Reference already exists                |
| DUPLICATE\_REQUEST    | Duplicate Idempotency-Key               |
| PROVIDER\_ERROR       | Provider returned an error              |

***

## Best Practices

<Steps>
  <Step title="Verify the wallet">
    Use the Name Lookup API before sending funds.
  </Step>

  <Step title="Generate unique references">
    Every disbursement should have a unique merchant reference.
  </Step>

  <Step title="Use Idempotency-Key">
    Always send an `Idempotency-Key` to prevent duplicate payouts.
  </Step>

  <Step title="Process webhooks">
    Use webhook events to receive the final transaction status instead of polling.
  </Step>
</Steps>