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

# Payment Status

> Check the latest status of a payment initiated through the SplashPay Collections API.

# Payment Status

The Payment Status API allows you to retrieve the current status of a payment using the merchant reference.

SplashPay first checks the local transaction record. If the payment is still pending, it automatically queries the payment provider to retrieve the latest status and updates the transaction before returning the response.

> **Tip**
> For real-time payment updates, configure **Webhooks**. The Status API is ideal for reconciliation, manual verification, and fallback scenarios.

***

## Endpoint

```http theme={null}
POST /payments/check-status
```

***

## Authentication

Every request must include your API credentials.

| Header       | Required | Description         |
| ------------ | :------: | ------------------- |
| X-API-KEY    |     ✅    | Merchant API Key    |
| X-API-SECRET |     ✅    | Merchant API Secret |
| Content-Type |     ✅    | application/json    |

***

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
    }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $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();
    ```
  </Tab>
</Tabs>

***

## Request Body

| Field     | Type   | Required | Description                       |
| --------- | ------ | :------: | --------------------------------- |
| reference | string |     ✅    | Unique merchant payment reference |

***

## Example Response

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

***

## Payment Statuses

| Status       | Description                                               |
| ------------ | --------------------------------------------------------- |
| `pending`    | Payment has been created and is awaiting customer action. |
| `processing` | Payment is being processed by the payment provider.       |
| `success`    | Payment completed successfully.                           |
| `failed`     | Payment failed.                                           |
| `cancelled`  | Payment was cancelled.                                    |
| `expired`    | Payment request expired before completion.                |

***

## Error Response

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

***

## Best Practices

<Steps>
  <Step title="Use unique references">
    Generate a unique reference for every payment. This reference is used throughout the payment lifecycle.
  </Step>

  <Step title="Prefer Webhooks">
    Use webhooks to receive payment updates automatically. The Status API should primarily be used for reconciliation and manual verification.
  </Step>

  <Step title="Avoid excessive polling">
    If a payment is still `pending` or `processing`, wait a few seconds before checking again.
  </Step>

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

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Mobile Money" href="/collections/mobile-money" icon="smartphone">
    Collect payments from Mobile Money wallets.
  </Card>

  <Card title="Card Payments" href="/collections/card" icon="credit-card">
    Accept Visa and Mastercard payments.
  </Card>

  <Card title="Dynamic TanQR" href="/collections/tanqr" icon="qr-code">
    Accept payments using Dynamic TanQR.
  </Card>

  <Card title="Webhooks" href="/collections/webhooks" icon="webhook">
    Receive real-time payment notifications.
  </Card>
</CardGroup>