Error Codes

This page lists the error responses you can encounter while integrating Apple Pay on Custom Checkout, what triggers each one and how to handle them.

canMakePayment Reasons

When canMakePayment() returns { available: false }, the reason field indicates why:

Error Response Structure

{
  "status": "failure",
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "Payment failed due to insufficient funds",
    "step": "payment_authentication",
    "reason": "insufficient_funds",
    "source": "customer",
    "metadata": { "payment_id": "pay_xxx", "order_id": "order_xxx" }
  }
}

Payment Error Responses

Returned from createPayment() or the onFailure callback:

For backend payment failures (for example, card declined, insufficient funds, invalid order), all error fields (code, reason, description, source, step, metadata) are propagated directly from the Razorpay backend. Refer to the

Razorpay Payment Error Codes

documentation for the full list of possible values.

Client Error Responses

Thrown as exceptions during initialization and setup — before any payment flow. Merchants should wrap these calls in try/catch:

Handling Guide