# Check Payout Status

Use the Payout Status API to fetch the real-time status of a payout transaction initiated using the KwikPaisa Banking APIs.

This API helps merchants:

* Verify payout completion
* Track transaction processing
* Monitor payout failures
* Validate fund settlement
* Reconcile payout transactions

The Payout Status API should always be used for final payout verification instead of relying only on payout initiation responses.

***

## Endpoint

```http
POST /api/v3/banking/payment/status
```

## Base URLs

### Sandbox

```
https://sandbox.kwikpaisa.com
```

### Production

```
https://api.kwikpaisa.com
```

***

## 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              |
| -------------------- | -------------- | -------- | ------------------------ |
| `kwikx_wallet_id`    | String         | Yes      | Merchant wallet ID       |
| `debit_account_type` | String         | Yes      | Source account type      |
| `payout_order_id`    | String/Integer | Yes      | Merchant payout order ID |

***

## Example Request Body

```json
{
  "kwikx_wallet_id": "177s8761897",
  "debit_account_type": "kwikx_wallet",
  "payout_order_id": "177s8761897"
}
```

***

## Example cURL Request

```http
curl -X POST https://sandbox.kwikpaisa.com/api/v3/banking/payment/status \
     -H "X-API-KEY: pk_test_xxxxxxxxx" \
     -H "X-SIGNATURE: GENERATED_SIGNATURE" \
     -H "X-TIMESTAMP: GENERATED_TIMESTAMP" \
     -H "Content-Type: application/json" \
     -d '{
  "kwikx_wallet_id": "177s8761897",
  "debit_account_type": "kwikx_wallet",
  "payout_order_id": "177s8761897"
}'
```

***

## Example Success Response

```json
{
  "status": true,
  "code": 200,
  "message": "Payout status fetched successfully.",
  "data": {
    "payout_id": "payout_a782fdb71b5e1659",
    "payout_order_id": "1778761734",
    "wallet_id": "2026-04-30 13:01:32",
    "status": "SUCCESS",
    "amount": "99",
    "currency": "INR",
    "utr_number": "UAT1778761735",
    "message": "Funds debited successfully",
    "amount_debited": "YES",
    "created_at": "14-05-2026"
  }
}
```

***

## Response Parameters

| Parameter         | Description                          |
| ----------------- | ------------------------------------ |
| `payout_id`       | Unique KwikPaisa payout reference ID |
| `payout_order_id` | Merchant payout order ID             |
| `wallet_id`       | Wallet transaction reference         |
| `status`          | Current payout status                |
| `amount`          | Payout amount                        |
| `currency`        | Transaction currency                 |
| `utr_number`      | Bank UTR/reference number            |
| `message`         | Transaction processing message       |
| `amount_debited`  | Indicates whether amount was debited |
| `created_at`      | Payout transaction creation date     |

***

## Payout Status Values

| Status       | Description                    |
| ------------ | ------------------------------ |
| `SUCCESS`    | Payout completed successfully  |
| `FAILED`     | Payout failed                  |
| `PROCESSING` | Payout under processing        |
| `PENDING`    | Awaiting bank confirmation     |
| `REVERSED`   | Amount reversed back to wallet |

***

## Example Failed Response

### Transaction Not Found

```json
{
  "status": false,
  "code": 404,
  "message": "Payout transaction not found."
}
```

***

### Failed Transaction Response

```json
{
  "status": true,
  "code": 200,
  "message": "Payout status fetched successfully.",
  "data": {
    "payout_id": "payout_b7c9d4d780db71e8",
    "payout_order_id": "1778761897",
    "wallet_id": "2026-04-30 13:01:32",
    "status": "FAILED",
    "amount": "9999999999",
    "currency": "INR",
    "utr_number": "NA",
    "message": "Txn failed due to insufficient funds",
    "amount_debited": "NO",
    "created_at": "14-05-2026"
  }
}
```

***

### Invalid Wallet ID

```json
{
  "status": false,
  "code": 403,
  "message": "Invalid wallet ID for selected environment."
}
```

***

## Recommended Verification Flow

1. Initiate payout transaction
2. Store `payout_id` and `payout_order_id`
3. Call Payout Status API
4. Verify final payout status
5. Reconcile payout transactions
6. Update transaction records

***

## Important Notes

* `payout_order_id` must always be unique
* Wallet ID must belong to the selected environment
* Sandbox and production wallet IDs are different
* UTR numbers may take time to generate
* Always verify payout status server-side

***

## Common Errors

### 400 Bad Request

Possible reasons:

* Missing required parameters
* Invalid request payload
* Incorrect request structure

***

### 401 Unauthorized

Possible reasons:

* Invalid API key
* Incorrect signature
* Expired timestamp

***

### 403 Invalid Wallet ID

Possible reasons:

* Wrong environment wallet ID
* Invalid merchant wallet

***

### 404 Payout Transaction Not Found

Possible reasons:

* Invalid payout order ID
* Transaction does not exist
* Incorrect merchant credentials

***

## Security Recommendations

* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS for all payout requests
* Store payout references securely
* Validate payout responses before processing

***

## Best Practices

* Verify every payout transaction server-side
* Store UTR/reference numbers
* Maintain payout audit logs
* Retry processing payouts carefully
* Enable webhook notifications for real-time updates


---

# Agent Instructions: 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:

```
GET https://developers.kwikpaisa.com/v3-guide/payout-integration/check-payout-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.