> For the complete documentation index, see [llms.txt](https://developers.kwikpaisa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.kwikpaisa.com/v3-guide/payment-gateway-integration/check-status.md).

# Check Status

Use the Order Status API to fetch the real-time status of a payment order created using the KwikPaisa Payment Gateway.

This API helps merchants:

* Verify payment completion
* Track transaction status
* Validate redirected payments
* Reconcile transactions securely

The Order Status API should always be used for final payment verification instead of relying only on frontend redirects.

***

## Endpoint

```http
POST /api/v3/pg/order/status
```

#### To view all available base URLs and environments, refer to:

➡️ [API Resources](/v3-guide/quick-start/api-resources.md)

## Authentication required.

Refer to:\
➡️ [Headers](/v3-guide/authentication/headers.md)\
➡️ [Signature Generation](/v3-guide/authentication/signature.md)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp.md)

***

## Request Parameters

| Parameter  | Type           | Required | Description       |
| ---------- | -------------- | -------- | ----------------- |
| `order_id` | Integer/String | Yes      | Merchant order ID |

***

## Example Request Body

```json
{
  "order_id": 6116229263036
}
```

***

## Example cURL Request

```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/order/status \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
  "order_id": 6116229263036
}'
```

***

## Example Success Response

```json
{
  "code": "200",
  "status": "success",
  "message": "API authentication successful!",
  "return_data": {
    "kwikX_order_id": "kp_9b9e725b-b415-40fd-ac1c-068ab508f7e7",
    "order_id": "6873654104683",
    "order_amount": "105.00",
    "order_currency": "INR",
    "order_status": "PAID",
    "payment_id": "pay_dfg4fgffghfh454",
    "order_source": "API",
    "created_at": null
  }
}
```

***

## Response Parameters

| Parameter        | Description                                   |
| ---------------- | --------------------------------------------- |
| `kwikX_order_id` | Unique KwikPaisa order ID                     |
| `order_id`       | Merchant order ID                             |
| `order_amount`   | Transaction amount                            |
| `order_currency` | Transaction currency                          |
| `order_status`   | Current payment status                        |
| `payment_id`     | Unique payment transaction ID                 |
| `order_source`   | Source of order creation                      |
| `paymentDetails` | Payment method and transaction details object |
| `created_at`     | Order creation timestamp                      |
| `paid_at`        | Payment completion timestamp                  |

***

## Payment Status Values

| Status       | Description                    |
| ------------ | ------------------------------ |
| `UN_PAID`    | Payment pending                |
| `PROCESSING` | Payment under processing       |
| `PAID`       | Payment completed successfully |
| `FAILED`     | Payment failed                 |
| `EXPIRED`    | Payment session expired        |

***

## Recommended Verification Flow

1. Create Order API
2. Redirect customer to hosted checkout
3. Customer completes payment
4. Receive redirect/webhook
5. Call Order Status API
6. Verify final payment status server-side

***

## Why Order Status Verification is Important

Frontend redirects may not always guarantee successful payments due to:

* Browser interruptions
* Network failures
* Customer closing the payment page
* Delayed bank confirmations

Always verify transactions using the Order Status API before marking orders as successful.

***

## Best Practices

* Always validate payment status server-side
* Verify webhook notifications
* Store `kwikX_order_id` for reconciliation
* Retry status checks for processing transactions
* Avoid duplicate order IDs

***

## Common Errors

### 400 Bad Request

Possible reasons:

* Missing `order_id`
* Invalid payload structure
* Incorrect request format

***

### 401 Unauthorized

Possible reasons:

* Invalid API key
* Incorrect signature
* Expired timestamp

***

### Order Not Found

Possible reasons:

* Invalid order ID
* Order does not exist
* Incorrect merchant credentials

***

## Recommended Retry Logic

If the payment status is:

```
PROCESSING
```

Retry the status check after a few seconds before marking the transaction as failed.

***

## Security Recommendations

* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS only
* Validate webhook signatures
* Verify timestamps before processing responses


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.kwikpaisa.com/v3-guide/payment-gateway-integration/check-status.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.