Check Payment / Order Status

Quickly verify the final status of a payment using the original payment_id you received when initiating STK Push or B2C.

Ideal for:

Polling status if webhook is delayed/missed
Manual reconciliation
Showing accurate order status to customers

Endpoint

POST /check_payment_status

Production
https://payments.pesavoucher.com/api/v1/check_payment_status

Request Example

curl --location 'https://payments.pesavoucher.com/api/v1/check_payment_status' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: pk_live_xxxxxxxxxxxxxxxx' \
  --header 'X-API-Secret: sk_live_xxxxxxxxxxxxxxxx' \
  --data '{
    "payment_id": "45cfa41f-cebe-488e-9294-e93935e21b6e"
  }'

Request Body

Field	Type	Required	Description
`payment_id`	string	Yes	The `payment_id` from your initial request/response

Success Response (Paid)

{
  "success": true,
  "payment": {
    "payment_id": "45cfa41f-cebe-488e-9294-e93935e21b6e",
    "amount": 1500.00,
    "currency": "KES",
    "payment_status": "SUCCESS",
    "status": "Success",
    "is_success": true
  },
  "message": "Payment completed successfully",
  "user_message": "Payment completed successfully!"
}

Failure Response Examples

User didn’t respond / timed out

{
  "success": true,
  "payment": {
    "payment_id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
    "amount": 500.00,
    "currency": "KES",
    "payment_status": "FAILED",
    "status": "Failed",
    "is_success": false
  },
  "message": "Payment status: FAILED",
  "user_message": "No response from user."
}

User cancelled

{
  "success": true,
  "payment": { ... },
  "message": "Payment status: CANCELLED",
  "user_message": "Payment was cancelled by user."
}

Possible Status Values

`payment_status` / `status`	`is_success`	Meaning	Recommended Action
`SUCCESS` / `Success`	`true`	Payment completed	Fulfill order, credit user
`FAILED` / `Failed`	`false`	Technical issue or insufficient funds	Show error, allow retry
`CANCELLED` / `Cancelled`	`false`	User pressed cancel	Allow retry
`PENDING` / `Processing`	`false`	Still waiting for user response	Show "Waiting for payment..."
`TIMEOUT`	`false`	User didn’t respond in time	Allow retry

Best Practices

Always prefer webhooks for real-time updates (this endpoint is for fallback/polling)
Safe to call repeatedly — no rate limit penalty for same payment_id
Cache results for 30–60 seconds to reduce load
Use user_message directly in your frontend for customer-facing text