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

> Collect payments using Selcom Pesa Push.

# Selcom Pesa

Use this endpoint to initiate an **in-app Selcom Pesa** payment. A push notification is sent to the customer's device where the **Selcom Mobile App** is installed. The customer opens the notification, reviews the payment request, and authorizes the transaction within the app.

## Endpoint

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

## Authentication

Include your API key in the request headers.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
```

## Request Body

| Field           | Type   | Required | Description                                                         |
| --------------- | ------ | -------- | ------------------------------------------------------------------- |
| amount          | number | Yes      | Amount to collect.                                                  |
| currency        | string | Yes      | Currency code. Currently `TZS`.                                     |
| reference       | string | Yes      | Unique merchant transaction reference.                              |
| phone           | string | Yes      | Selcom Pesa Mobile Number (e.g. `255787123123`).                    |
| customer\_name  | string | Yes      | Customer full name.                                                 |
| customer\_email | string | Yes      | Customer email address.                                             |
| metadata        | object | No       | Additional transaction metadata (e.g., order details, customer ID). |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.splashpay.co.tz/api/v1/payments/selcompesa \
    --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": 200,
      "currency": "TZS",
      "reference": "INV-3809993j",
      "phone": "255787123123",
      "customer_name": "John Doe",
      "customer_email": "johndoe@gmail.com"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.splashpay.co.tz/api/v1/payments/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({
        amount: 200,
        currency: 'TZS',
        reference: 'INV-3809993j',
        phone: '255787123123',
        customer_name: 'John Doe',
        customer_email: 'johndoe@gmail.com',
      }),
    }
  );

  const payment = await response.json();

  console.log(payment);
  ```

  ```python Python theme={null}
  import uuid
  import requests

  response = requests.post(
      "https://api.splashpay.co.tz/api/v1/payments/selcompesa",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "YOUR_API_KEY",
          "X-API-SECRET": "YOUR_API_SECRET",
          "Idempotency-Key": str(uuid.uuid4())
      },
      json={
          "amount": 200,
          "currency": "TZS",
          "reference": "INV-3809993j",
          "phone": "255787123123",
          "customer_name": "John Doe",
          "customer_email": "johndoe@gmail.com"
      }
  )

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

  ```php PHP theme={null}
  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/selcompesa',
      [
          'amount' => 200,
          'currency' => 'TZS',
          'reference' => 'INV-3809993j',
          'phone' => '255787123123',
          'customer_name' => 'John Doe',
          'customer_email' => 'johndoe@gmail.com',
      ]
  );

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

  ```dart Dart theme={null}
  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/selcompesa',
      ),
      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': 200,
        'currency': 'TZS',
        'reference': 'INV-3809993j',
        'phone': '255787123123',
        'customer_name': 'John Doe',
        'customer_email': 'johndoe@gmail.com',
      }),
    );

    print(response.body);
  }
  ```
</CodeGroup>

## Successful Response

```json theme={null}
{
  "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": "selcompesa",
    "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"
}
```

## Transaction Status

| Status     | Description                                    |
| ---------- | ---------------------------------------------- |
| pending    | Payment request has been sent to the customer. |
| processing | Payment is being processed.                    |
| success    | Payment completed successfully.                |
| failed     | Payment failed.                                |
| cancelled  | Customer cancelled the payment request.        |
| expired    | Payment request expired before authorization.  |

## Error Response

```json theme={null}
{
    "success": false,
    "message": "The phone number is invalid.",
    "errors": {
        "phone": [
            "The phone number must be in international format."
        ]
    }
}
```

## Validation Rules

| Field           | Rules                                           |
| --------------- | ----------------------------------------------- |
| amount          | Required, numeric, greater than 0               |
| currency        | Required, supported currency (`TZS`)            |
| reference       | Required, unique merchant reference             |
| phone           | Required, international format (`255XXXXXXXXX`) |
| customer\_name  | Required                                        |
| customer\_email | Nullable, valid email address                   |

## Notes

* The `reference` must be unique for every payment request.
* Phone numbers must use the international format without the `+` sign.
* A payment prompt is sent immediately to the customer's mobile device.
* Monitor the transaction status using webhooks or the transaction status endpoint.
* Keep your API key secure and never expose it in client-side applications.