Error Codes

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be positive"
      }
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be positive"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Payment order not found"
  }
}

{
  "error": {
    "code": "DUPLICATE",
    "message": "Payment with this externalId already exists",
    "existingResource": {
      "id": "ord_abc123",
      "externalId": "order-12345",
      "status": "COMPLETED"
    }
  }
}

{
  "error": {
    "code": "DECLINED",
    "message": "Payment declined by issuing bank",
    "declineReason": "insufficient_funds"
  }
}

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient funds for this transaction"
  }
}

{
  "error": {
    "code": "EXPIRED_CARD",
    "message": "This card has expired"
  }
}

{
  "error": {
    "code": "INVALID_CARD",
    "message": "Invalid card number"
  }
}

{
  "error": {
    "code": "INVALID_CVC",
    "message": "Invalid security code"
  }
}

{
  "paymentOrder": {
    "status": "PAYER_AUTHENTICATION_CHALLENGE_REQUIRED"
  },
  "payerAuthentication": {
    "stepUpUrl": "...",
    "jwt": "..."
  }
}

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Customer failed to complete authentication"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_TIMEOUT",
    "message": "Authentication session expired"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

{
  "error": {
    "code": "NOT_REFUNDABLE",
    "message": "Payment cannot be refunded",
    "details": "Only completed payments can be refunded"
  }
}

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Refund amount exceeds available balance",
    "details": {
      "originalAmount": 10000,
      "alreadyRefunded": 8000,
      "maxRefundable": 2000,
      "requested": 5000
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "retryAfter": 60
  }
}

function getCustomerMessage(error) {
  const messages = {
    'DECLINED': 'Payment couldn\'t be processed. Please try a different card.',
    'EXPIRED_CARD': 'This card has expired. Please use a different card.',
    'INSUFFICIENT_FUNDS': 'Payment couldn\'t be completed. Please try another method.'
  };
  
  return messages[error.code] || 
         'Unable to process payment. Please try again.';
}

async function createPaymentWithRetry(data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await createPayment(data);
    } catch (error) {
      // Only retry server errors
      if (error.status >= 500 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

function logError(error, context) {
  logger.error('Payment error', {
    code: error.code,
    message: error.message,
    status: error.status,
    context: {
      externalId: context.externalId,
      amount: context.amount
    }
    // Never log: card numbers, CVCs, API keys
  });
}

try {
  const payment = await createPayment(data);
} catch (error) {
  switch (error.code) {
    case 'DECLINED':
      return showDeclineMessage();
    case 'AUTHENTICATION_REQUIRED':
      return show3DSChallenge(error.payerAuthentication);
    case 'RATE_LIMIT_EXCEEDED':
      return retryAfter(error.retryAfter);
    case 'INTERNAL_ERROR':
      return retryWithBackoff();
    default:
      return showGenericError();
  }
}