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

GET /disbursements/{reference}

Example:

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

cURL
JavaScript
Python
PHP

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"

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();

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())

$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();

Path Parameters

Parameter	Type	Description
reference	string	Merchant disbursement reference

Example Response

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

{
  "status": "error",
  "code": "DISBURSEMENT_NOT_FOUND",
  "message": "The specified disbursement could not be found."
}

Best Practices

Use unique references

Generate a unique reference for every disbursement. This reference is used to retrieve the transaction later.

Prefer Webhooks

Use the Status API for reconciliation or manual checks. For production integrations, rely on webhook notifications to receive transaction updates automatically.

Retry safely

If the status is processing, wait a few seconds before making another request instead of polling continuously.

Store the provider reference

Save the provider_reference returned by SplashPay for reconciliation with payment providers.

Getting Started

Collections

Disbursements

Status

Disbursement Status

Endpoint

Authentication

Example Request

Path Parameters

Example Response

Transaction Status

Error Response

Best Practices

​Disbursement Status

​Endpoint

​Authentication

​Example Request

​Path Parameters

​Example Response

​Transaction Status

​Error Response

​Best Practices

Disbursement Status

Endpoint

Authentication

Example Request

Path Parameters

Example Response

Transaction Status

Error Response

Best Practices