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

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

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