Accept Payments

Declines

A decline occurs when a payment attempt is not approved.

Declines can be caused by the issuer, the card details provided by the customer, authentication requirements, or downstream processing conditions.

Your integration should distinguish between declines that can be retried and declines that require a different action.

Where to find decline information

Decline details are surfaced on the Payment object.

See:

Decline fields

When a payment fails, the error response may include:

  • code
  • decline_code
  • advice_code
  • network_decline_code
  • network_advice_code
  • message
  • message_code

You do not need to reverse-engineer the possible message strings by testing different cards. Always display message directly (it is provider-neutral and customer-safe), and branch your logic on the stable slugs decline_code and advice_code. message_code is the stable localization key that pairs with message, so you can supply your own translations without matching on English text. The advice codes are defined below, and every decline code is listed with its network code, category, and advice in the complete response code reference.

Example decline response 
{
  "type": "card_error",
  "code": "card_declined",
  "decline_code": "insufficient_funds",
  "advice_code": "do_not_try_again",
  "network_decline_code": "51",
  "message": "Your card has insufficient funds. Please try another card or use a different payment method.",
  "trace_id": "trc_123"
}

Types of declines

Hard declines

Hard declines should not be retried with the same payment details.

Typical examples include:

  • Expired card
  • Lost or stolen card
  • Insufficient funds
  • Restricted card
  • Transaction not permitted

In these cases, your platform should ask the customer to use a different card or payment method.

Soft declines

Soft declines may succeed later or after customer action.

Typical examples include:

  • Temporary issuer unavailability
  • Generic issuer refusal
  • Temporary network issues
  • Retry-later advice

In these cases, your platform may retry later or prompt the customer to try again.

Authentication-required outcomes

Some payments require additional authentication.

Example:

Example authentication-required response 
{
  "type": "card_error",
  "code": "card_declined",
  "decline_code": "authentication_required",
  "message": "This payment requires additional authentication. Please try again.",
  "trace_id": "trc_123"
}

When this occurs, your integration should direct the customer through the required authentication flow instead of retrying the payment unchanged.

Invalid request or card data errors

Some payment failures are caused by invalid or incomplete customer input.

Typical examples include:

  • Invalid card number
  • Expired card
  • Incorrect security code
  • Invalid amount

These should be handled as customer-correctable input errors.

Retry guidance

Use the decline and advice codes to determine whether a retry is appropriate.

Retry later

Retry only when the decline indicates a temporary or recoverable condition.

Examples include:

  • Issuer unavailable
  • Temporary processing issue
  • Generic retry-later advice

Do not retry

Do not retry with the same payment details when the decline indicates a permanent condition.

Examples include:

  • Lost or stolen card
  • Expired card
  • Insufficient funds
  • Transaction not permitted

Request customer action

Ask the customer to take action when the payment requires:

  • Additional authentication
  • Updated card details
  • A different payment method

Do not automatically retry hard declines. Repeated attempts on permanently declined cards degrade customer experience and can create unnecessary issuer friction.

Customer messaging

Use the message field when presenting decline information to the customer.

For card errors, the message is designed to be customer-safe.

Examples:

  • “Your card number is incorrect. Please check your card details and try again.”
  • “Your card has insufficient funds. Please try another card or use a different payment method.”
  • “This payment requires additional authentication. Please try again.”

Advice codes reference

advice_code tells you what to do next. It is the field to branch on for retry logic. The complete set of values:

advice_code Meaning What to do
try_again_later Temporary or recoverable condition Retry after a short delay
do_not_try_again Permanent condition Do not retry with the same details; ask for another payment method
adjust_amount The amount was not acceptable Retry with a different amount
confirm_card_data The card details look wrong Ask the customer to check and re-enter their card details
confirm_payment_method_data The payment-method input looks wrong Ask the customer to check and re-enter the details (for example, a one-time code)
use_alternative_payment_method This payment method cannot complete the payment Ask the customer to use a different payment method
refresh_state The outcome is not final yet Refresh the payment status before deciding whether to retry
no_further_refunds No further refunds are possible Applies to refunds; stop attempting further refunds on this payment

Best practices

  • Use decline_code for programmatic handling
  • Use advice_code to decide whether to retry
  • Use message for customer-facing messaging
  • Use network_decline_code for diagnostics and reporting
  • Log trace_id for support and investigation

Related pages

Previous
Understand payment outcomes
Next
Acquirer response codes