​

Failed transactions

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

​

Common Reasons for Failed Transactions

• 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

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

​

Example Failed Payment Response

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

• 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

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

​

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 Recommended

​

Retry Not Recommended

​

Duplicate Transaction Protection

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

​

Customer Communication Recommendations

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

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

​

Logging Recommendations

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

• 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