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

# Bank Disbursement

> Send funds securely from your SplashPay wallet to supported bank accounts.

# Bank Disbursement

The Bank Disbursement API enables merchants to transfer funds directly from their SplashPay wallet to supported bank accounts in Tanzania.

Each request is processed securely and can be tracked using the transaction reference or provider reference.

***

## Endpoint

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

***

## 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/bank \
      --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":"BANK-100001",
          "bank_code":"NMIBTZTZ",
          "account_number":"1234567890",
          "account_name":"John Doe",
          "amount":100000,
          "currency":"TZS",
          "remarks":"Supplier Payment",
          "metadata":{
              "invoice":"INV-10001"
          }
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.splashpay.co.tz/api/v1/disbursements/bank",
      {
        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: "BANK-100001",
          bank_code: "NMIBTZTZ",
          account_number: "1234567890",
          account_name: "John Doe",
          amount: 100000,
          currency: "TZS",
          remarks: "Supplier Payment"
        }),
      }
    );

    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/bank",
        headers={
            "X-API-KEY": "pk_live_xxxxxxxxx",
            "X-API-SECRET": "sk_live_xxxxxxxxx",
            "Idempotency-Key": str(uuid.uuid4()),
            "Content-Type": "application/json",
        },
        json={
            "reference": "BANK-100001",
            "bank_code": "NMIBTZTZ",
            "account_number": "1234567890",
            "account_name": "John Doe",
            "amount": 100000,
            "currency": "TZS",
            "remarks": "Supplier Payment",
        },
    )

    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/bank',
        [
            'headers' => [
                'X-API-KEY' => 'pk_live_xxxxxxxxx',
                'X-API-SECRET' => 'sk_live_xxxxxxxxx',
                'Idempotency-Key' => uniqid(),
            ],
            'json' => [
                'reference' => 'BANK-100001',
                'bank_code' => 'NMIBTZTZ',
                'account_number' => '1234567890',
                'account_name' => 'John Doe',
                'amount' => 100000,
                'currency' => 'TZS',
                'remarks' => 'Supplier Payment',
            ],
        ]
    );

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

***

## Request Body

| Field           | Type    | Required | Description                                                    |
| --------------- | ------- | :------: | -------------------------------------------------------------- |
| reference       | string  |     ✅    | Unique merchant payout reference                               |
| bank\_code      | string  |     ✅    | Destination bank code (use the shortcode from the table below) |
| account\_number | string  |     ✅    | Recipient bank account number                                  |
| account\_name   | string  |     ✅    | Recipient account name                                         |
| amount          | decimal |     ✅    | Amount to transfer                                             |
| currency        | string  |     ✅    | Transaction currency                                           |
| remarks         | string  |     ✅    | Payment description                                            |
| metadata        | object  |    No    | Additional merchant metadata                                   |

## Supported Banks

SplashPay supports payouts to the following financial institutions.

| Bank                                   | Shortcode      | Name Lookup |
| -------------------------------------- | -------------- | :---------: |
| ABSA Bank                              | `ABSA`         |      ✅      |
| Selcom Microfinance Bank (Selcom Pesa) | `SPSCASHIN`    |      ✅      |
| Akiba Commercial Bank                  | `AKIBA`        |      ✅      |
| Amana Bank                             | `AMANABANK`    |      ✅      |
| Azania Bank                            | `AZANIA`       |      ✅      |
| Access Bank Tanzania                   | `BANCABC`      |      ✅      |
| Bank of Africa Tanzania                | `BOA`          |      ✅      |
| Bank of Baroda Tanzania                | `BANKOFBARODA` |      ✅      |
| Bank of India Tanzania                 | `BANKOFINDIA`  |      ✅      |
| China Dasheng Bank                     | `CHINADASHENG` |      ✅      |
| Citibank Tanzania                      | `CITIBANK`     |      ✅      |
| CRDB Bank                              | `CRDBBANK`     |      ✅      |
| DCB Commercial Bank                    | `DCBBANK`      |      ✅      |
| Diamond Trust Bank                     | `DTB`          |      ✅      |
| Ecobank Tanzania                       | `ECOBANK`      |      ✅      |
| Equity Bank Tanzania                   | `EQUITYBANK`   |      ✅      |
| Exim Bank                              | `EXIMBANK`     |      ✅      |
| FINCA Microfinance Bank                | `FINCA`        |      ✅      |
| Guaranty Trust Bank Tanzania           | `GTBANK`       |      ✅      |
| Habib African Bank                     | `HABIBBANK`    |      ✅      |
| I\&M Bank Tanzania                     | `IMBANK`       |      ✅      |
| International Commercial Bank          | `ICB`          |      ✅      |
| KCB Bank Tanzania                      | `KCB`          |      ✅      |
| Coop Bank Tanzania                     | `KILIMANJARO`  |      ✅      |
| Letshego Bank Tanzania                 | `LETSHEGO`     |      ✅      |
| Maendeleo Bank                         | `MAENDELEO`    |      ✅      |
| Mkombozi Commercial Bank               | `MKOMBOZI`     |      ✅      |
| Mwalimu Commercial Bank                | `MWALIMU`      |      ✅      |
| Mwanga Hakika Microfinance Bank        | `MWANGA`       |      ✅      |
| National Microfinance Bank (NMB)       | `NMB`          |      ✅      |
| NBC Bank                               | `NBC`          |      ✅      |
| NCBA Bank Tanzania                     | `NCBA`         |      ✅      |
| People's Bank of Zanzibar              | `PBZ`          |      ✅      |
| Stanbic Bank Tanzania                  | `STANBIC`      |      ✅      |
| Tanzania Commercial Bank               | `TCB`          |      ✅      |
| Uchumi Commercial Bank                 | `UCHUMI`       |      ✅      |
| United Bank for Africa                 | `UBA`          |      ✅      |

<Warning>
  Use the **Shortcode** value when specifying the `bank_code` field in your request. You can also verify the recipient's account details using the **Name Lookup API** before initiating a bank disbursement.
</Warning>

## Example Response

```json theme={null}
{
  "status": "success",
  "code": "DISBURSEMENT_INITIATED",
  "message": "Disbursement initiated successfully.",
  "data": {
    "reference": "BANK-100001",
    "amount": "100000.00",
    "fee": "500.00",
    "total_amount": "100500.00",
    "currency": "TZS",
    "bank_code": "NMIBTZTZ",
    "bank_name": "National Microfinance Bank",
    "account_number": "1234567890",
    "account_name": "John Doe",
    "provider": "selcom",
    "status": "processing",
    "remarks": "Supplier Payment",
    "metadata": {}
  },
  "request_id": "6d878d91-fdfa-4763-b74c-8321c11c9b6b"
}
```

***

## Transaction Status

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

***

## Name Lookup

Before initiating a bank transfer, you can verify the account details.

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

Example request:

```json theme={null}
{
  "type": "BANK",
  "bank_code": "NMIBTZTZ",
  "account_number": "1234567890"
}
```

***

## Error Codes

| Code                    | Description                             |
| ----------------------- | --------------------------------------- |
| INVALID\_BANK           | Unsupported bank                        |
| INVALID\_ACCOUNT        | Invalid account number                  |
| ACCOUNT\_NAME\_MISMATCH | Account verification failed             |
| 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 account details">
    Use the Name Lookup API before initiating a bank transfer.
  </Step>

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

  <Step title="Include an Idempotency-Key">
    Prevent duplicate transfers when retrying requests.
  </Step>

  <Step title="Use webhooks">
    Listen for webhook events instead of continuously polling the Status API.
  </Step>
</Steps>