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

POST /api/v3/banking/payment/status

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

➡️ API Resources

---

Authentication required.

Refer to: ➡️ Headers ➡️ Signature Generation ➡️ Timestamp Validation

---

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

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

---

Example cURL Request

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

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

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

---

Failed Transaction Response

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

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