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

# Status

> Retrieve the current status and details of a disbursement.

# Disbursement Status

The Disbursement Status API allows you to retrieve the latest status of a disbursement using its unique merchant reference.

Use this endpoint to:

* Check whether a payout has been processed
* Retrieve the provider reference
* View processing and completion timestamps
* Obtain the latest transaction status

> **Tip**
> For real-time updates, use the **Webhooks API**. The Status API is useful for manual checks, reconciliation, and retry logic.

***

## Endpoint

```http theme={null}
GET /disbursements/{reference}
```

Example:

```http theme={null}
GET /disbursements/PAYOUT-100001
```

***

## Authentication

Every request must include your API credentials.

| Header       | Required | Description         |
| ------------ | :------: | ------------------- |
| X-API-KEY    |     ✅    | Merchant API Key    |
| X-API-SECRET |     ✅    | Merchant API Secret |

***

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url https://api.splashpay.co.tz/api/v1/disbursements/PAYOUT-100001 \
      --header "X-API-KEY: pk_live_xxxxxxxxx" \
      --header "X-API-SECRET: sk_live_xxxxxxxxx"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      "https://api.splashpay.co.tz/api/v1/disbursements/PAYOUT-100001",
      {
        method: "GET",
        headers: {
          "X-API-KEY": process.env.SPLASHPAY_KEY,
          "X-API-SECRET": process.env.SPLASHPAY_SECRET,
        },
      },
    );

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

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

    response = requests.get(
        "https://api.splashpay.co.tz/api/v1/disbursements/PAYOUT-100001",
        headers={
            "X-API-KEY": "pk_live_xxxxxxxxx",
            "X-API-SECRET": "sk_live_xxxxxxxxx",
        },
    )

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

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

    $response = $client->get(
        'https://api.splashpay.co.tz/api/v1/disbursements/PAYOUT-100001',
        [
            'headers' => [
                'X-API-KEY' => 'pk_live_xxxxxxxxx',
                'X-API-SECRET' => 'sk_live_xxxxxxxxx',
            ]
        ]
    );

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

***

## Path Parameters

| Parameter | Type   | Description                     |
| --------- | ------ | ------------------------------- |
| reference | string | Merchant disbursement reference |

***

## Example Response

```json theme={null}
{
  "status": "success",
  "code": "DISBURSEMENT_FOUND",
  "message": "Disbursement retrieved successfully.",
  "data": {
    "reference": "PAYOUT-100001",
    "provider_reference": "S20618298751",
    "amount": "50000.00",
    "fee": "0.00",
    "total_amount": "50000.00",
    "currency": "TZS",
    "channel": "mobile_money",
    "provider": "selcom",
    "recipient_name": "Medson Naftali",
    "recipient_account": "255717879919",
    "status": "paid",
    "remarks": "Salary Payment",
    "metadata": {
      "employee_id": "EMP-1001"
    },
    "created_at": "2026-07-05T14:20:00Z",
    "processing_at": "2026-07-05T14:20:03Z",
    "completed_at": "2026-07-05T14:20:07Z"
  },
  "request_id": "cb71e86c-8055-4e61-b59d-8dd82d92b624"
}
```

***

## Transaction Status

| Status       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `pending`    | Disbursement has been received and is waiting to be processed. |
| `processing` | The payout has been submitted to the payment provider.         |
| `paid`       | Funds have been successfully delivered to the recipient.       |
| `failed`     | The payout could not be completed.                             |
| `cancelled`  | The payout was cancelled before completion.                    |

***

## Error Response

```json theme={null}
{
  "status": "error",
  "code": "DISBURSEMENT_NOT_FOUND",
  "message": "The specified disbursement could not be found."
}
```

***

## Best Practices

<Steps>
  <Step title="Use unique references">
    Generate a unique reference for every disbursement. This reference is used to retrieve the transaction later.
  </Step>

  <Step title="Prefer Webhooks">
    Use the Status API for reconciliation or manual checks. For production integrations, rely on webhook notifications to receive transaction updates automatically.
  </Step>

  <Step title="Retry safely">
    If the status is `processing`, wait a few seconds before making another request instead of polling continuously.
  </Step>

  <Step title="Store the provider reference">
    Save the `provider_reference` returned by SplashPay for reconciliation with payment providers.
  </Step>
</Steps>