> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.senjaropay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.senjaropay.com/_mcp/server.

# Payment status

Use this endpoint to read the **current state** of a payment after you [create a payment](/create-payment). It complements [webhooks](/webhooks): webhooks push updates; status is for checks and reconciliation.

All merchant calls use **POST**, **`Content-Type: application/json`**, **`x-api-key`**, and **`x-api-secret`**.

***

## Endpoint

```
POST https://api.senjaropay.com/senjaropay/merchant/payments/status
```

***

## Request

**Headers**

| Header         | Required | Description                                              |
| -------------- | -------- | -------------------------------------------------------- |
| `Content-Type` | Yes      | `application/json`                                       |
| `x-api-key`    | Yes      | Dashboard Public Key ([Authentication](/authentication)) |
| `x-api-secret` | Yes      | Secret API secret ([Authentication](/authentication))    |

**Body**

| Field         | Type          | Required | Description                                                          |
| ------------- | ------------- | -------- | -------------------------------------------------------------------- |
| `referenceId` | string (UUID) | Yes      | `data.reference` from the [create payment](/create-payment) response |

**Example**

```http
POST /senjaropay/merchant/payments/status HTTP/1.1
Host: api.senjaropay.com
Content-Type: application/json
x-api-key: <secret>
x-api-secret: <secret>

{"referenceId":"mock-ref-7b2a4f3e"}
```

```bash
curl -sS -X POST "https://api.senjaropay.com/senjaropay/merchant/payments/status" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${SENJARO_API_KEY}" \
  -H "x-api-secret: ${SENJARO_API_SECRET}" \
  -d '{"referenceId":"mock-ref-7b2a4f3e"}'
```

***

## Response

Successful responses return transaction status information for the provided reference.

**Example**

```json
{
  "message": "Transaction status retrieved from database",
  "transactionId": "TXN-MOCK-000123",
  "displayId": "SPMOCK.0001.000123",
  "method": "MOBILE",
  "status": "PENDING",
  "reference_id": "mock-ref-7b2a4f3e",
  "amount": "1000.00",
  "currency": "TZS",
  "created_at": "2026-01-01T10:30:00.000Z"
}
```

All values in this response snippet are mock values.

***

## Payment states

Interpret `status` in your integration. Common values:

| Value       | Meaning                                                                          |
| ----------- | -------------------------------------------------------------------------------- |
| `PENDING`   | Awaiting customer action (for example USSD authorization) or still processing    |
| `COMPLETED` | Funds captured successfully; safe to fulfill per your policy                     |
| `FAILED`    | Terminal failure; do not fulfill; inspect `message` or provider codes if present |

Confirm enum values and extra fields (failure reasons, operator references) against your live API or OpenAPI definition.

***

## Errors

| HTTP status | Typical `error_code` | When                                      |
| ----------- | -------------------- | ----------------------------------------- |
| **400**     | `validation_error`   | Malformed body or missing `referenceId`   |
| **401**     | `unauthorized`       | Missing or invalid `x-api-key`            |
| **404**     | `not_found`          | No payment for the supplied `referenceId` |

**Example (validation)**

```json
{
  "status": "error",
  "code": 400,
  "error_code": "validation_error",
  "message": "referenceId is required"
}
```

***

## Operations

* **Prefer webhooks** for timely updates; use status to **backfill** missed events or to **verify** before shipping or crediting wallets.
* When polling, use **bounded retries** and **exponential backoff**; avoid tight loops against production.
* Make fulfillment **idempotent** (key orders or references) so duplicate status reads or duplicate webhooks never double-apply side effects.