Transaction Status Query¶

Description¶

Looks up the current status of a previously initiated transaction by merchant reference.

Auth¶

Bearer token required.

Endpoint & Method¶

POST /payments/status-query/

Parameters¶

Parameter	Type	Required	Notes
`merchant_id`	string	Yes	Your merchant account number
`merchant_reference`	string	Yes	The `reference` you supplied when initiating the transaction

Example Request¶

curl -X POST "https://api.cloudpay365.com/api/v1/payments/status-query/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "merchant_reference": "<YOUR_UNIQUE_REFERENCE>"
  }'

Example Response¶

{
  "success": true,
  "data": {
    "status": "success",
    "status_description": "Transaction proccessed successfully",
    "transaction_type": "B2C",
    "transaction_id": "<TRANSACTION_ID>",
    "gateway_reference": null,
    "merchant_reference": "<YOUR_UNIQUE_REFERENCE>",
    "rail_reference": "<RAIL_REFERENCE>",
    "amount": 10,
    "is_paid": true,
    "charges": 0,
    "currency_code": "KES",
    "payment_method": "mpesa",
    "created_at": "2026-04-08T22:43:58.620181+03:00",
    "completed_at": null
  }
}

Response fields¶

Field	Notes
`status`	Transaction outcome, e.g. `success`; confirm the full set of possible values (`processing`, `failed`, etc.) with Hivemind Payments
`status_description`	Human-readable description of `status`
`is_paid`	Boolean settlement flag — appears alongside `status` and may not always agree with it while a transaction is still `processing`
`gateway_reference` / `rail_reference`	Downstream payment-rail identifiers; either may be `null` depending on `payment_method` and how far the transaction has progressed
`completed_at`	Nullable — was `null` in the captured example even though `status` was `success`; confirm with Hivemind Payments whether this is reliably populated on completion

Example error response¶

{
  "success": false,
  "message": "Your IP address is not whitelisted."
}

Returned as 403 Forbidden when the calling IP isn't on the application's whitelist — see IP Whitelisting.

Notes / Gotchas¶

Prefer the webhook callback for reacting to final transaction state; use this endpoint for manual checks or as a fallback if a webhook is missed. The webhook payload carries the same fields as this response's data object — see Payload Reference.
Don't rely solely on status/is_paid agreeing, or on completed_at being populated — check status_description and, if in doubt, confirm the exact semantics with Hivemind Payments before gating business logic on these fields.