> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eliteneobank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Failed transactions

# 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 theme={null}
{
  "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 theme={null}
{
  "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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.