Skip to main content
When a payment fails due to a card issue, the error response includes a decline_code field inside the payment_error type. Use this code to determine why a card was declined and display an appropriate message to your customer.

​
Decline error response

{
  "error": {
    "type": "payment_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "decline_code": "insufficient_funds",
    "param": null,
    "doc_url": "https://docs.leanrails.com/errors/decline-codes"
  }
}

​
Decline codes

CodeDescriptionSuggested Customer Message
generic_declineThe card was declined for an unspecified reason.Your card was declined. Please try a different payment method.
insufficient_fundsThe card has insufficient funds to complete the purchase.Your card has insufficient funds. Please try a different card.
lost_cardThe card has been reported lost.Your card was declined. Please contact your card issuer.
stolen_cardThe card has been reported stolen.Your card was declined. Please contact your card issuer.
expired_cardThe card has expired.Your card has expired. Please update your card details.
incorrect_cvcThe CVC number is incorrect.The CVC code is incorrect. Please check and try again.
processing_errorAn error occurred while processing the card.An error occurred processing your card. Please try again.
do_not_honorThe card issuer declined the transaction.Your card was declined. Please contact your card issuer.

​
Testing declines

Use the pm_card_declined payment method in test mode to simulate a card decline: 
curl -X POST https://api.leanrails.com/v1/payment_intents \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "payment_method": "pm_card_declined"
  }'

​
Handling declines

if (!response.ok) {
  const { error } = body;

  if (error.type === "payment_error" && error.code === "card_declined") {
    switch (error.decline_code) {
      case "insufficient_funds":
        showMessage("Your card has insufficient funds.");
        break;
      case "expired_card":
        showMessage("Your card has expired. Please update your card.");
        break;
      case "incorrect_cvc":
        showMessage("The CVC code is incorrect. Please try again.");
        break;
      default:
        showMessage("Your card was declined. Please try another card.");
    }
  }
}