# Failed transactions

Failed transactions occur when a payment or payout request cannot be completed successfully due to banking issues, validation failures, authentication problems, insufficient balance, network interruptions, or processing errors.

Merchants should always handle failed transactions gracefully and verify the final transaction status before taking further action.

Proper failed transaction handling helps ensure:

* Accurate reconciliation
* Better customer experience
* Stable payout workflows
* Duplicate transaction prevention
* Reliable settlement tracking

***

## Common Reasons for Failed Transactions

Transactions may fail due to:

* Insufficient wallet balance
* Invalid beneficiary details
* Invalid UPI ID or IFSC code
* Authentication failures
* Expired timestamps
* Banking partner downtime
* Network interruptions
* Duplicate transaction IDs
* Regulatory or compliance checks

***

## Payment Transaction Failures

Payment transactions may fail when:

* Customer cancels payment
* Bank declines transaction
* UPI authorization fails
* Payment session expires
* Network interruptions occur
* Payment authentication fails

***

## Example Failed Payment Response

```json
{
  "code": "200",
  "status": "failed",
  "message": "Payment failed.",
  "return_data": {
    "kwikX_order_id": "kp_40dec464",
    "order_id": "6116229263036",
    "order_status": "FAILED",
    "transaction_id": null,
    "amount": "105.00",
    "currency": "INR"
  }
}
```

## Payout Transaction Failures

Payouts may fail when:

* Wallet balance is insufficient
* Beneficiary details are invalid
* Bank rejects transaction
* Banking network is unavailable
* Transaction exceeds limits
* Compliance validation fails

## Example Failed Payout 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"
  }
}
```

## Failed Transaction Status Values

| Status      | Description                    |
| ----------- | ------------------------------ |
| `FAILED`    | Transaction failed permanently |
| `REVERSED`  | Amount reversed back           |
| `EXPIRED`   | Transaction session expired    |
| `DECLINED`  | Bank declined transaction      |
| `CANCELLED` | Transaction cancelled          |

## Recommended Failed Transaction Workflow

1. Receive failed transaction response
2. Log transaction details
3. Verify transaction status using APIs
4. Check webhook notifications
5. Notify customer or operations team
6. Retry only if applicable
7. Reconcile transaction records

***

## Retry Recommendations

Retry transactions only when failures are temporary.

### Retry Recommended

| Scenario                | Retry |
| ----------------------- | ----- |
| Processing timeout      | Yes   |
| Temporary banking issue | Yes   |
| Network interruption    | Yes   |
| Service unavailable     | Yes   |

***

### Retry Not Recommended

| Scenario                    | Retry |
| --------------------------- | ----- |
| Invalid beneficiary details | No    |
| Invalid signature           | No    |
| Insufficient balance        | No    |
| Duplicate transaction ID    | No    |

***

## Duplicate Transaction Protection

Never retry failed transactions blindly.

Before retrying:

* Verify transaction status first
* Use unique transaction references
* Check payout/order IDs carefully
* Validate webhook events

***

## Customer Communication Recommendations

For payment failures:

* Inform customers clearly
* Allow secure retry flow
* Avoid duplicate debits
* Provide support references

For payout failures:

* Notify operations teams
* Validate beneficiary details
* Check wallet balance
* Verify bank responses

***

## Logging Recommendations

Always log:

* Transaction IDs
* API request payloads
* API responses
* Webhook payloads
* Retry attempts
* Error messages
* UTR/reference numbers

This helps with:

* Reconciliation
* Audit tracking
* Dispute management
* Technical debugging

***

## Security Recommendations

* Validate all webhook signatures
* Verify transaction status server-side
* Use HTTPS only
* Generate fresh signatures for retries
* Never expose API credentials publicly

***

## Best Practices

* Handle failures gracefully
* Implement retry logic carefully
* Avoid duplicate transactions
* Verify final status using APIs
* Maintain reconciliation systems
* Store transaction audit logs

***

## Important Notes

* Banking failures may take time to finalize
* Some failed payouts may later reverse automatically
* Webhooks may arrive after API responses
* Final transaction confirmation should always happen server-side


---

# 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/error-handling/failed-transactions.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.