Refusal Reasons
Payment decline reasons and how to handle them
Refusal Reasons
When a payment is declined, the response includes a decline code indicating the reason.
Common decline codes
| Code | Description | Recoverable |
|---|---|---|
generic_decline | Card declined for unspecified reason | Maybe |
insufficient_funds | Not enough funds available | Yes |
lost_card | Card reported lost | No |
stolen_card | Card reported stolen | No |
expired_card | Card has expired | No |
incorrect_cvc | CVC verification failed | Yes |
incorrect_number | Card number is incorrect | Yes |
processing_error | Processing error occurred | Yes |
do_not_honor | Issuer declined without reason | Maybe |
pickup_card | Card should be retained | No |
Decline response
{
"id": "pay_abc123",
"status": "failed",
"failure_code": "insufficient_funds",
"failure_message": "The card has insufficient funds.",
"outcome": {
"type": "issuer_declined",
"reason": "insufficient_funds",
"ripr_level": "normal",
"seller_message": "The card has insufficient funds to complete the purchase."
}
}Handling declines
Recoverable declines
For recoverable errors, prompt the customer to:
- Use a different payment method
- Enter correct card details
- Contact their bank
if (payment.failure_code === 'insufficient_funds') {
showMessage('Your card has insufficient funds. Please try a different card.');
showPaymentForm();
}Non-recoverable declines
For permanent declines, advise the customer to use a different payment method:
if (
['lost_card', 'stolen_card', 'pickup_card'].includes(payment.failure_code)
) {
showMessage(
'This card cannot be used. Please try a different payment method.',
);
}Customer messaging
| Decline Code | Recommended Message |
|---|---|
generic_decline | "Your payment was declined. Please try a different card or contact your bank." |
insufficient_funds | "Your card has insufficient funds. Please try a different card." |
lost_card | "This card cannot be used. Please use a different payment method." |
expired_card | "Your card has expired. Please update your card details." |
incorrect_cvc | "The security code is incorrect. Please check and try again." |
incorrect_number | "The card number is incorrect. Please check and try again." |
do_not_honor | "Your bank declined the payment. Please contact your bank or try a different card." |
Retry recommendations
| Category | Action |
|---|---|
| Card details wrong | Let customer retry with correct details |
| Insufficient funds | Suggest different card |
| Fraud-related | Don't retry, suggest different method |
| Bank declined | Suggest contacting bank |
Reduce declines
- Collect complete billing address - Improves AVS matching
- Request CVC - Reduces fraud declines
- Use 3D Secure - Shifts liability, improves approval
- Update stored cards - Use Account Updater for subscriptions