Payment status | SenjaroPay Docs

Use this endpoint to read the current state of a payment after you create a payment. It complements 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)
`x-api-secret`	Yes	Secret API secret (Authentication)

Body

Field	Type	Required	Description
`referenceId`	string (UUID)	Yes	`data.reference` from the create payment response

Example

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

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

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

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