### API Request Examples

Source: https://docs.splashpay.co.tz/authentication

Implementation examples for initiating mobile money payments across various programming languages.

```bash
curl --request GET \
  --url https://api.splashpay.co.tz/api/v1/payments/mobile-money \
  --header "X-API-KEY: pk_live_xxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxx" \
  --header "Idempotency-Key: Unique-Request-ID"
```

```php
$response = Http::withHeaders([
    'X-API-KEY' => env('SPLASHPAY_KEY'),
    'X-API-SECRET' => env('SPLASHPAY_SECRET'),
    'Idempotency-Key' => 'Unique-Request-ID',
])->get(
    'https://api.splashpay.co.tz/api/v1/payments/mobile-money'
);
```

```javascript
const response = await fetch(
  'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
  {
    headers: {
      'X-API-KEY': process.env.SPLASHPAY_KEY,
      'X-API-SECRET': process.env.SPLASHPAY_SECRET,
      'Idempotency-Key': 'Unique-Request-ID',
    },
  }
);
```

```python
import requests

response = requests.get(
    'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
    headers={
        'X-API-KEY': os.getenv('SPLASHPAY_KEY'),
        'X-API-SECRET': os.getenv('SPLASHPAY_SECRET'),
        'Idempotency-Key': 'Unique-Request-ID',
    }
)
```

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:uuid/uuid.dart';

Future<void> initiateMobileMoneyPayment() async {
 final response = await http.post(
   Uri.parse(
     'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
   ),
   headers: {
     'Content-Type': 'application/json',
     'X-API-KEY': const String.fromEnvironment('SPLASHPAY_KEY'),
     'X-API-SECRET': const String.fromEnvironment('SPLASHPAY_SECRET'),
     'Idempotency-Key': const Uuid().v4(),
   },
 );
}
```

--------------------------------

### Check Payment Status Request Examples

Source: https://docs.splashpay.co.tz/collections/status

Examples for querying payment status using various programming languages and tools.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/check-status \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxx" \
  --data '{
    "reference": "CIR-6723e6ss6"
}'
```

```javascript
const response = await fetch(
  "https://api.splashpay.co.tz/api/v1/payments/check-status",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": process.env.SPLASHPAY_KEY,
      "X-API-SECRET": process.env.SPLASHPAY_SECRET,
    },
    body: JSON.stringify({
      reference: "CIR-6723e6ss6",
    }),
  }
);

const data = await response.json();
```

```python
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/check-status",
    headers={
        "X-API-KEY": "pk_live_xxxxxxxxx",
        "X-API-SECRET": "sk_live_xxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "reference": "CIR-6723e6ss6"
    }
)

print(response.json())
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->post(
    'https://api.splashpay.co.tz/api/v1/payments/check-status',
    [
        'headers' => [
            'X-API-KEY' => 'pk_live_xxxxxxxxx',
            'X-API-SECRET' => 'sk_live_xxxxxxxxx',
            'Content-Type' => 'application/json',
        ],
        'json' => [
            'reference' => 'CIR-6723e6ss6',
        ],
    ]
);

echo $response->getBody();
```

--------------------------------

### Webhook Request Header Example

Source: https://docs.splashpay.co.tz/webhooks/overview

Example of the HTTP request structure including required SplashPay headers.

```http
POST /webhooks/splashpay HTTP/1.1
Content-Type: application/json
X-SplashPay-Event: transaction.success
X-SplashPay-Signature: 7fd3f5e1fbe9a7c7...
X-SplashPay-Timestamp: 1718966400
```

--------------------------------

### Webhook Testing Endpoint Example

Source: https://docs.splashpay.co.tz/webhooks/overview

Example URL format for testing webhook integrations using services like Webhook.site.

```text
https://webhook.site/your-unique-id
```

--------------------------------

### API Response Examples

Source: https://docs.splashpay.co.tz/disbursements/status

JSON structures for successful disbursement retrieval and error scenarios.

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

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

--------------------------------

### Local Webhook URL Example

Source: https://docs.splashpay.co.tz/collections/webhooks

Example of a public URL generated by ngrok to receive webhook notifications on a local server.

```text
https://abc123.ngrok.io/webhooks/splashpay
```

--------------------------------

### Laravel Webhook Handler

Source: https://docs.splashpay.co.tz/disbursements/webhooks

Example implementation for handling incoming webhooks and verifying signatures in a Laravel controller.

```php
public function handle(Request $request)
{
    // Raw request body
    $payload = file_get_contents('php://input');

    // Headers
    $signature = $request->header('X-SplashPay-Signature');
    $timestamp = $request->header('X-SplashPay-Timestamp');
    $event = $request->header('X-Webhook-Event');

    // Verify signature
    if (!$this->verifySignature($payload, $signature)) {
        return response()->json([
            'message' => 'Invalid signature'
        ], 400);
    }

    $data = json_decode($payload, true);

    switch ($event) {

        case 'disbursement.success':

            // Mark payout as completed

            break;

        case 'disbursement.failed':

            // Mark payout as failed

            break;

        case 'disbursement.cancelled':

            // Mark payout as cancelled

            break;
    }

    return response()->json([
        'status' => 'ok'
    ]);
}
```

--------------------------------

### Initiate Bank Disbursement Request

Source: https://docs.splashpay.co.tz/disbursements/bank

Examples of how to send a disbursement request using various programming languages. Ensure you provide a unique Idempotency-Key for every request.

```bash
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"
      }
  }'
```

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

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

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

--------------------------------

### Webhook Endpoint URL Example

Source: https://docs.splashpay.co.tz/webhooks/overview

The target URL format for receiving webhook POST requests.

```http
POST https://merchant.example.com/webhooks/splashpay
```

--------------------------------

### Generate Dynamic QR Code

Source: https://docs.splashpay.co.tz/collections/tanqr

Examples for creating a dynamic QR code request using different programming environments. Ensure you provide valid API credentials and a unique Idempotency-Key for each request.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/dynamic-qr \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
  --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "reference":"CIR-6723e8ss6",
    "buyer_email":"john.doe@example.com",
    "buyer_name":"John Doe",
    "buyer_phone":"255744123456",
    "amount":1000,
    "currency":"TZS",
    "billing_firstname":"John",
    "billing_lastname":"Doe",
    "billing_address":"Bwawani, Mkonze",
    "billing_city":"Dodoma",
    "billing_state":"Tanzania",
    "billing_postcode":"67116",
    "billing_country":"TZ",
    "billing_phone":"255744123456"
}'
```

```javascript
const response = await fetch(
  'https://api.splashpay.co.tz/api/v1/payments/dynamic-qr',
  {
    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: 'CIR-6723e8ss6',
      buyer_email: 'john.doe@example.com',
      buyer_name: 'John Doe',
      buyer_phone: '255744123456',
      amount: 1000,
      currency: 'TZS',
      billing_firstname: 'John',
      billing_lastname: 'Doe',
      billing_address: 'Bwawani, Mkonze',
      billing_city: 'Dodoma',
      billing_state: 'Tanzania',
      billing_postcode: '67116',
      billing_country: 'TZ',
      billing_phone: '255744123456'
    }),
  }
);

const payment = await response.json();
```

```python
import uuid
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/dynamic-qr",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY",
        "X-API-SECRET": "YOUR_API_SECRET",
        "Idempotency-Key": str(uuid.uuid4())
    },
    json={
        "reference":"CIR-6723e8ss6",
        "buyer_email":"john.doe@example.com",
        "buyer_name":"John Doe",
        "buyer_phone":"255744123456",
        "amount":1000,
        "currency":"TZS",
        "billing_firstname":"John",
        "billing_lastname":"Doe",
        "billing_address":"Bwawani, Mkonze",
        "billing_city":"Dodoma",
        "billing_state":"Tanzania",
        "billing_postcode":"67116",
        "billing_country":"TZ",
        "billing_phone":"255744123456"
    }
)

print(response.json())
```

--------------------------------

### Webhook Request Headers

Source: https://docs.splashpay.co.tz/disbursements/webhooks

Example of the HTTP headers included in every webhook notification.

```http
POST /api/webhooks/splashpay HTTP/1.1

Content-Type: application/json
X-Webhook-Event: disbursement.success
X-SplashPay-Timestamp: 2026-07-05T14:25:40Z
X-SplashPay-Signature: 8b0f8eb9a6c5a7c6...
```

--------------------------------

### Example Payment Status Response

Source: https://docs.splashpay.co.tz/collections/status

A sample JSON response returned when checking the status of a payment.

```json
{
    "status": "success",
    "code": "PAYMENT_STATUS_CHECKED",
    "message": "Payment status checked",
    "data": {
        "reference": "CIR-6723e6ss6",
        "provider_reference": "1782388280",
        "amount": "1000.00",
        "currency": "TZS",
        "status": "success",
        "provider": "selcom",
        "channel": "tanqr",
        "network": "SELCOMTANQR",
        "created_at": "2026-07-03T14:42:13.000000Z",
        "processing_at": "2026-07-03T14:42:13Z",
        "completed_at": null
    },
    "meta": [],
    "request_id": "f0ee4a32-bc56-49f7-92a5-82f965e8c555"
}
```

--------------------------------

### Initiate Card Payment Request

Source: https://docs.splashpay.co.tz/collections/card

Examples for sending a POST request to the card payment endpoint with required authentication headers and payment details.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/card \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
  --header "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "reference":"CIR-6723sg",
    "buyer_email":"john.doe@example.com",
    "buyer_name":"John Doe",
    "buyer_phone":"255744123456",
    "amount":1000,
    "currency":"TZS",
    "redirect_url":"https://example.com",
    "cancel_url":"https://example.com",
    "billing_firstname":"John",
    "billing_lastname":"Doe",
    "billing_address":"123 Main St",
    "billing_city":"Dar es Salaam",
    "billing_state":"Tanzania",
    "billing_postcode":"67116",
    "billing_country":"TZ",
    "billing_phone":"255744123456"
}'
```

```javascript
const response = await fetch(
  'https://api.splashpay.co.tz/api/v1/payments/card',
  {
    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: 'CIR-6723sg',
      buyer_email: 'john.doe@example.com',
      buyer_name: 'John Doe',
      buyer_phone: '255744123456',
      amount: 1000,
      currency: 'TZS',
      redirect_url: 'https://example.com',
      cancel_url: 'https://example.com',
      billing_firstname: 'John',
      billing_lastname: 'Doe',
      billing_address: '123 Main St',
      billing_city: 'Dar es Salaam',
      billing_state: 'Tanzania',
      billing_postcode: '67116',
      billing_country: 'TZ',
      billing_phone: '255744123456'
    }),
  }
);

const payment = await response.json();
```

```python
import uuid
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/card",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY",
        "X-API-SECRET": "YOUR_API_SECRET",
        "Idempotency-Key": str(uuid.uuid4())
    },
    json={
        "reference":"CIR-6723sg",
        "buyer_email":"john.doe@example.com",
        "buyer_name":"John Doe",
        "buyer_phone":"255744123456",
        "amount":1000,
        "currency":"TZS",
        "redirect_url":"https://example.com",
        "cancel_url":"https://example.com",
        "billing_firstname":"John",
        "billing_lastname":"Doe",
        "billing_address":"123 Main St",
        "billing_city":"Dar es Salaam",
        "billing_state":"Tanzania",
        "billing_postcode":"67116",
        "billing_country":"TZ",
        "billing_phone":"255744123456"
    }
)

print(response.json())
```

--------------------------------

### Webhook URL Configuration

Source: https://docs.splashpay.co.tz/disbursements/webhooks

Example of a publicly accessible HTTPS endpoint for receiving webhook notifications.

```text
https://merchant.example.com/api/webhooks/splashpay
```

--------------------------------

### Mobile Money Disbursement Request

Source: https://docs.splashpay.co.tz/disbursements/mobile-money

Examples of how to initiate a mobile money disbursement request across different programming environments.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/disbursements/mobile-money \
  --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":"PAYOUT-100001",
      "recipient_phone":"255747123456",
      "recipient_name":"John Doe",
      "amount":1000,
      "currency":"TZS",
      "network":"MPESA",
      "remarks":"Salary Payment",
      "metadata":{
          "employee_id":"EMP-1001"
      }
  }'
```

```javascript
const response = await fetch(
  "https://api.splashpay.co.tz/api/v1/disbursements/mobile-money",
  {
    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: "PAYOUT-100001",
      recipient_phone: "255747123456",
      recipient_name: "John Doe",
      amount: 1000,
      currency: "TZS",
      network: "MPESA",
      remarks: "Salary Payment",
      metadata: {
        employee_id: "EMP-1001"
      }
    }),
  }
);

const data = await response.json();
```

```python
import uuid
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/disbursements/mobile-money",
    headers={
        "X-API-KEY": "pk_live_xxxxxxxxx",
        "X-API-SECRET": "sk_live_xxxxxxxxx",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "reference": "PAYOUT-100001",
        "recipient_phone": "255747123456",
        "recipient_name": "John Doe",
        "amount": 1000,
        "currency": "TZS",
        "network": "MPESA",
        "remarks": "Salary Payment",
        "metadata": {
            "employee_id": "EMP-1001"
        }
    },
)

print(response.json())
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->post(
    'https://api.splashpay.co.tz/api/v1/disbursements/mobile-money',
    [
        'headers' => [
            'X-API-KEY' => 'pk_live_xxxxxxxxx',
            'X-API-SECRET' => 'sk_live_xxxxxxxxx',
            'Idempotency-Key' => uniqid(),
        ],
        'json' => [
            'reference' => 'PAYOUT-100001',
            'recipient_phone' => '255747123456',
            'recipient_name' => 'John Doe',
            'amount' => 1000,
            'currency' => 'TZS',
            'network' => 'MPESA',
            'remarks' => 'Salary Payment',
            'metadata' => [
                'employee_id' => 'EMP-1001'
            ]
        ],
    ]
);

echo $response->getBody();
```

--------------------------------

### Initiate Mobile Money Payment

Source: https://docs.splashpay.co.tz/introduction

Example request for processing a mobile money payment using cURL. Requires valid API credentials and an idempotency key.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/mobile-money \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
  --header "Idempotency-Key: Unique-Request-ID" \
  --data '{
    "amount": 1000,
    "currency": "TZS",
    "reference": "INV-323",
    "phone": "255754000000",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "metadata": {
      "order_id": "12345",
      "product": "Test Product"
    }
  }'
```

--------------------------------

### Display QR Code in HTML

Source: https://docs.splashpay.co.tz/collections/tanqr

Example of embedding the Base64 QR code string into an HTML image tag.

```html
<img src="data:image/png;base64,{qr}" alt="SplashPay TANQR" />
```

--------------------------------

### Request Disbursement Status

Source: https://docs.splashpay.co.tz/disbursements/status

Examples of how to query the disbursement status API using various programming languages.

```bash
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"
```

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

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

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

--------------------------------

### Selcom Pesa Disbursement Request

Source: https://docs.splashpay.co.tz/disbursements/selcompesa

Examples of how to initiate a disbursement request to the Selcom Pesa endpoint using various programming languages.

```http
POST /disbursements/selcompesa
```

```bash
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"
      }
  }'
```

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

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

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

--------------------------------

### Successful API Response JSON

Source: https://docs.splashpay.co.tz/collections/mobile-money

Example of a 200 OK response returned when a payment request is successfully initiated.

```json
{
  "status": "success",
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255712345678",
    "reference": "INV-1234",
    "amount": "1000.00",
    "fee": 15.00,
    "net_amount": 985.00,
    "currency": "TZS",
    "payment_method": "mobile_money",
    "provider": "selcom",
    "provider_reference": "S20618089300",
    "status": "pending",
    "metadata": null,
    "created_at": "2026-07-03T10:28:57Z",
    "processing_at": "2026-07-03T13:28:57Z"
  },
  "meta": [],
  "request_id": "85323840-963b-4464-897f-12613975b8e3"
}
```

--------------------------------

### Name Lookup Request and Response

Source: https://docs.splashpay.co.tz/disbursements/selcompesa

Example JSON payload for the name lookup request and the corresponding successful response.

```json
{
  "type": "SELCOMPESA",
  "wallet_number": "255747123456"
}
```

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

--------------------------------

### Initiate Mobile Money Payment

Source: https://docs.splashpay.co.tz/collections/mobile-money

Use these examples to send a POST request to the mobile money endpoint. Ensure you include the required API keys and a unique idempotency key for each transaction.

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/mobile-money \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxxxxxx" \
  --header "Idempotency-Key: UniqueKey123" \
  --data '{
    "amount": 1000,
    "currency": "TZS",
    "reference": "INV-1234`",
    "phone": "255712345678",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com"
  }'
```

```javascript
const response = await fetch(
  'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
  {
    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({
      amount: 1000,
      currency: 'TZS',
      reference: 'INV-1234',
      phone: '255712345678',
      customer_name: 'John Doe',
      customer_email: 'john.doe@example.com',
    }),
  }
);

const payment = await response.json();

console.log(payment);
```

```python
import uuid
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/mobile-money",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY",
        "X-API-SECRET": "YOUR_API_SECRET",
        "Idempotency-Key": str(uuid.uuid4())
    },
    json={
        "amount": 1000,
        "currency": "TZS",
        "reference": "INV-1234",
        "phone": "255712345678",
        "customer_name": "John Doe",
        "customer_email": "john.doe@example.com"
    }
)

print(response.status_code)
print(response.json())
```

```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withHeaders([
    'X-API-KEY' => env('SPLASHPAY_KEY'),
    'X-API-SECRET' => env('SPLASHPAY_SECRET'),
    'Idempotency-Key' => (string) Str::uuid(),
])->post(
    'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
    [
        'amount' => 1000,
        'currency' => 'TZS',
        'reference' => 'INV-1234',
        'phone' => '255712345678',
        'customer_name' => 'John Doe',
        'customer_email' => 'john.doe@example.com',
    ]
);

return $response->json();
```

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:uuid/uuid.dart';

Future<void> initiatePayment() async {
  final response = await http.post(
    Uri.parse(
      'https://api.splashpay.co.tz/api/v1/payments/mobile-money',
    ),
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'YOUR_API_KEY',
      'X-API-SECRET': 'YOUR_API_SECRET',
      'Idempotency-Key': const Uuid().v4(),
    },
    body: jsonEncode({
      'amount': 1000,
      'currency': 'TZS',
      'reference': 'INV-1234',
      'phone': '255712345678',
      'customer_name': 'John Doe',
      'customer_email': 'john.doe@example.com',
    }),
  );

  print(response.body);
}
```

--------------------------------

### Status API Error Response

Source: https://docs.splashpay.co.tz/collections/status

Example of the JSON structure returned when a payment request fails.

```json
{
    "status": "error",
    "code": "PAYMENT_NOT_FOUND",
    "message": "Payment not found."
}
```

--------------------------------

### GET /disbursements/{reference}

Source: https://docs.splashpay.co.tz/disbursements/status

Retrieves the status and details of a specific disbursement by its merchant reference.

```APIDOC
## GET /disbursements/{reference}

### Description
Retrieves the current status and transaction details for a disbursement using the unique merchant reference.

### Method
GET

### Endpoint
https://api.splashpay.co.tz/api/v1/disbursements/{reference}

### Parameters
#### Path Parameters
- **reference** (string) - Required - Merchant disbursement reference

### Request Example
GET /disbursements/PAYOUT-100001

### Response
#### Success Response (200)
- **status** (string) - Status of the request
- **code** (string) - Response code
- **message** (string) - Human-readable message
- **data** (object) - Disbursement details including reference, provider_reference, amount, status, and timestamps

#### Response Example
{
  "status": "success",
  "code": "DISBURSEMENT_FOUND",
  "message": "Disbursement retrieved successfully.",
  "data": {
    "reference": "PAYOUT-100001",
    "provider_reference": "S20618298751",
    "amount": "50000.00",
    "status": "paid",
    "created_at": "2026-07-05T14:20:00Z"
  }
}
```

--------------------------------

### Verify Webhook Signature

Source: https://docs.splashpay.co.tz/collections/webhooks

Instructions and examples for verifying the authenticity of webhook payloads using the provided headers and your secret key.

```APIDOC
## Verify Webhook Signature

### Description
Verify that a webhook request originated from SplashPay by validating the HMAC SHA-256 signature provided in the request headers.

### Headers
- **X-SPLASHPAY-SIGNATURE** (string) - Required - HMAC SHA-256 signature of the payload.
- **X-SPLASHPAY-TIMESTAMP** (string) - Required - Unix timestamp used to generate the signature.

### Verification Logic
Compute the HMAC using your Webhook Secret:
`HMAC_SHA256(timestamp + "." + request_body, WEBHOOK_SECRET)`

If the computed signature matches the `X-SPLASHPAY-SIGNATURE` header, the request is authentic.
```

--------------------------------

### Selcom Pesa Disbursement Response

Source: https://docs.splashpay.co.tz/disbursements/selcompesa

Example of a successful JSON response returned after initiating a disbursement request.

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

--------------------------------

### Cancel Payment Request

Source: https://docs.splashpay.co.tz/collections/cancel

Examples of how to send a POST request to the cancel payment endpoint using various programming languages.

```http
POST /payments/cancel
```

```bash
curl --request POST \
  --url https://api.splashpay.co.tz/api/v1/payments/cancel \
  --header "Content-Type: application/json" \
  --header "X-API-KEY: pk_live_xxxxxxxxx" \
  --header "X-API-SECRET: sk_live_xxxxxxxxx" \
  --data '{
    "reference": "CIR-6723dg"
}'
```

```javascript
const response = await fetch(
  "https://api.splashpay.co.tz/api/v1/payments/cancel",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": process.env.SPLASHPAY_KEY,
      "X-API-SECRET": process.env.SPLASHPAY_SECRET,
    },
    body: JSON.stringify({
      reference: "CIR-6723dg",
    }),
  }
);

const data = await response.json();
```

```python
import requests

response = requests.post(
    "https://api.splashpay.co.tz/api/v1/payments/cancel",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "pk_live_xxxxxxxxx",
        "X-API-SECRET": "sk_live_xxxxxxxxx",
    },
    json={
        "reference": "CIR-6723dg"
    }
)

print(response.json())
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->post(
    'https://api.splashpay.co.tz/api/v1/payments/cancel',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'X-API-KEY' => 'pk_live_xxxxxxxxx',
            'X-API-SECRET' => 'sk_live_xxxxxxxxx',
        ],
        'json' => [
            'reference' => 'CIR-6723dg',
        ],
    ]
);

echo $response->getBody();
```

--------------------------------

### Sample Payment Cancelled Webhook Payload

Source: https://docs.splashpay.co.tz/collections/cancel

Example JSON structure of the webhook notification received after a payment cancellation.

```json
{
  "event": "payment.cancelled",
  "created_at": "2026-07-12T11:01:56Z",
  "data": {
    "reference": "CIR-6723e8hs6",
    "provider_reference": "S20629971309",
    "amount": "1000.00",
    "currency": "TZS",
    "status": "cancelled",
    "payment_method": "tanqr",
    "provider": "selcom",
    "channel": "tanqr",
    "network": "SELCOMTANQR",
    "cancelled_at": "2026-07-12T11:01:56Z"
  }
}
```

--------------------------------

### Retrieve Disbursement Status Endpoint

Source: https://docs.splashpay.co.tz/disbursements/status

The base endpoint structure and a concrete example for requesting a specific disbursement status.

```http
GET /disbursements/{reference}
```

```http
GET /disbursements/PAYOUT-100001
```

--------------------------------

### Rendering the QR Code

Source: https://docs.splashpay.co.tz/collections/tanqr

Instructions on how to display the Base64-encoded QR code returned in the API response.

```APIDOC
### Rendering
To display the QR code in a web browser, prepend the prefix `data:image/png;base64,` to the string provided in the `qr` field.

### HTML Example
<img src="data:image/png;base64,{qr}" alt="SplashPay TANQR" />
```

--------------------------------

### API Credentials Configuration

Source: https://docs.splashpay.co.tz/authentication

HTTP header format for Test and Live environment credentials.

```http
X-API-KEY: pk_test_xxxxxxxxxxxxx
X-API-SECRET: sk_test_xxxxxxxxxxxxx
```

```http
X-API-KEY: pk_live_xxxxxxxxxxxxx
X-API-SECRET: sk_live_xxxxxxxxxxxxx
```

--------------------------------

### Webhook Integration

Source: https://docs.splashpay.co.tz/collections/webhooks

Guidelines for configuring and handling incoming webhook notifications from SplashPay.

```APIDOC
## Webhook Integration

### Description
SplashPay sends real-time notifications via HTTP POST requests to your configured webhook URL when a payment reaches a final state.

### Requirements
- Must support HTTPS
- Must accept HTTP POST requests
- Must return HTTP 200 OK upon successful processing
- Must be publicly accessible

### Supported Events
| Event | Description |
| --- | --- |
| payment.success | Payment completed successfully. |
| payment.failed | Payment failed. |
| payment.cancelled | Payment was cancelled by the customer or provider. |
| payment.expired | Payment expired before completion. |
```

--------------------------------

### Configure Authentication Headers

Source: https://docs.splashpay.co.tz/disbursements/overview

Required headers for authenticating requests and ensuring idempotency.

```http
X-API-KEY: pk_live_xxxxxxxxxxxxx
X-API-SECRET: sk_live_xxxxxxxxxxxxx
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
```

--------------------------------

### Verify Webhook Signature in PHP

Source: https://docs.splashpay.co.tz/collections/webhooks

Implementation for verifying signatures in a PHP environment using hash_hmac and hash_equals.

```php
$timestamp = $_SERVER['HTTP_X_SPLASHPAY_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_SPLASHPAY_SIGNATURE'];

$payload = file_get_contents('php://input');

$expected = hash_hmac(
    'sha256',
    $timestamp.'.'.$payload,
    env('SPLASHPAY_WEBHOOK_SECRET')
);

if (!hash_equals($expected, $signature)) {
    abort(401, 'Invalid Signature');
}
```

--------------------------------

### Webhook Event Flow Diagram

Source: https://docs.splashpay.co.tz/webhooks/overview

Visual representation of the lifecycle of a webhook event from generation to merchant response.

```text
Customer Action
       │
       ▼
SplashPay
       │
       ▼
Webhook Event Generated
       │
       ▼
POST Request Sent
       │
       ▼
Merchant Endpoint
       │
       ▼
200 OK Response
```

--------------------------------

### Invalid API Credentials Error Response

Source: https://docs.splashpay.co.tz/collections/mobile-money

Returned when authentication fails due to invalid credentials.

```json
{
    "success": false,
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials."
}
```

--------------------------------

### Webhook Endpoint Specification

Source: https://docs.splashpay.co.tz/disbursements/webhooks

Details on how to configure and handle incoming webhook POST requests from SplashPay.

```APIDOC
## POST [Your Webhook URL]

### Description
Receives real-time notifications for disbursement status changes. Your endpoint must be publicly accessible over HTTPS and return an HTTP 2xx response within 30 seconds.

### Headers
- **X-Webhook-Event** (string) - The event type (e.g., disbursement.success)
- **X-SplashPay-Signature** (string) - HMAC SHA-256 signature for verification
- **X-SplashPay-Timestamp** (string) - Event timestamp

### Request Body
- **event** (string) - The event type
- **created_at** (string) - Timestamp of the event
- **data** (object) - Disbursement details including reference, amount, currency, and status

### Response
#### Success Response (200)
- **status** (string) - Returns 'ok' upon successful processing
```

--------------------------------

### QR Code Data Prefix

Source: https://docs.splashpay.co.tz/collections/tanqr

The required prefix for converting the Base64 string into a displayable image source.

```text
data:image/png;base64,
```

--------------------------------

### POST /payments/card

Source: https://docs.splashpay.co.tz/collections/card

Initiates a card payment transaction by redirecting the customer to a secure hosted checkout page.

```APIDOC
## POST /payments/card

### Description
Initiates a card payment transaction. Customers are redirected to a secure payment page hosted by SplashPay's payment provider, ensuring card details are never transmitted through your servers.

### Method
POST

### Endpoint
https://api.splashpay.co.tz/api/v1/payments/card
```

--------------------------------

### Webhook Response

Source: https://docs.splashpay.co.tz/webhooks/overview

After successfully receiving and processing the webhook, return a 200 OK status.

```APIDOC
## Webhook Response

### Success Response
HTTP/1.1 200 OK

### Response Body
{
  "success": true
}
```