Error Recovery Patterns

Payment transactions can fail, get stuck, or return ambiguous results. This guide provides decision trees for every scenario so you know exactly what to do.

#Decision Tree: Payment Failed

When a payment returns FAILED status (synchronously or via webhook):

#Decision Tree: Transaction Stuck in PENDING

Use the same recovery pattern for transactions stuck in CUSTOMER_VERIFICATION: confirm the customer was redirected to the returned challenge or redirect URL, wait for the webhook, poll as fallback, and do not create a duplicate transaction for the same order.

#Decision Tree: 3DS Challenge Flow

Critical: The successRedirectUrl is for user experience only. Always treat the webhook callback as the authoritative payment result. A customer can be redirected to the success URL even if the payment ultimately fails (rare edge case with async processing).

#Webhook vs Redirect Disagree

Always trust the webhook. The successRedirectUrl is for user experience only — never use it as payment confirmation.

#Retry Strategy

#When to Retry

#Retry with Idempotency

Always use the same requestId when retrying a failed payment. This ensures:

• You won't be charged twice if the first attempt actually succeeded
• Exirom returns the existing transaction result instead of creating a new one

async function payWithRetry(paymentData, token, maxRetries = 3) {
  // Use a stable requestId for all retries
  const requestId = paymentData.requestId;
 
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const res = await fetch('https://sandbox.api.exirom.com/api/api/v1/payments/card', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify(paymentData),
    });
 
    const result = await res.json();
 
    // Stop API retry. SUCCEED is final; CUSTOMER_VERIFICATION needs customer action.
    if (['SUCCEED', 'CUSTOMER_VERIFICATION'].includes(result.transactionStatus)) {
      return result;
    }
 
    if (result.transactionStatus === 'FAILED') {
      const retryable = [1, 9, 12, 13, 61, 63, 70, 72, 73];
      if (!retryable.includes(result.declineCode) || attempt === maxRetries) {
        return result; // Non-retryable or exhausted retries
      }
    }
 
    // Exponential backoff
    await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
  }
}

#Common Mistakes

#Related Guides

• Webhook Best Practices — Deduplication, signatures, polling
• Decline Codes Reference — Full code list
• Idempotency — How requestId prevents duplicate charges
• Callback Retry Mechanism — Retry schedule and behavior