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:

• Why payments fail

Decline fields

When a payment fails, the error response may include:

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

{
  "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:

{
  "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

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.”

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

• Understand payment outcomes
• Error handling
• Acquirer response codes