Decline Handling

This feature allows you to automatically guide customers through failed payment attempts, improving conversion rates and customer experience without any additional integration effort - handled entirely within the Hosted Checkout session.

Benefits

Improved Conversion Rates: Many common declines (e.g., insufficient funds, 3-D Secure errors) can be resolved with simple, on-screen guidance.
Better Customer Experience: Clear, instant messaging reduces customer frustration and enhances trust during the checkout journey.
Minimal Merchant Effort: Transaction recovery is managed by Acquired.com, allowing merchants to recover failed payments without handling redirects or creating new payment links.

Enabling Decline Recovery

The Decline Recovery feature is managed through your Hosted Checkout settings. To enable this feature navigate to Hosted Checkout Settings in the Hub and open the Responses configuration modal. Locate the Decline Recovery configuration and select enable.

How it works

A transaction that fails with a recoverable reason will redirect the customer back to the payment page, and a temporary on-screen message will be displayed to guide their next attempt.

Each flow is considered a single session, which can contain multiple payment attempts (transactions).

Prompt: A toast notification (message pop-up) is displayed at the top of the Hosted Checkout page for 10 seconds.
Attempts: The customer can re-attempt the payment by interacting with the payment methods displayed on the page.
Maximum Attempts: The decline flow can re-loop up to the configured count_retry limit for the order (default is 3 attempts). Once this limit is reached, or the transaction is successful, the session concludes.

Example:

Available Decline Flow Messages

The message displayed to the customer is tailored based on the decline reason code received from the payment processor.

Flow Name	Trigger Event (Transaction Status & Reason)	Toast Notification Message (Displayed for 10s)
Insufficient Funds	`status: declined` & `reason: insufficient_funds`	Insufficient Funds. Please add funds to your account, or try a different card.
Card Restricted	`status: declined` & `reason: restricted_card`	Card Restricted. This card is not supported for this payment. Please try another card or alternative payment method.
Generic Decline	`status: declined` & `reason: generic_decline`	Something went wrong. Sorry there was an error processing your payment. Please try again.
3-D Secure Error (Technical)	`status: tds_error` & `reason: acs_technical_issue` or `bad_gateway`	3-D Secure Error. There was an error completing 3-D Secure. Please try again or choose a different payment method.
3-D Secure Not Completed	`status: tds_failed` & `reason: challenge_not_completed` or `card_authentication_failed` or `challenge_failed`	3-D Secure not completed. Please try again or try another payment method.

Transaction Tracking and Outcomes

When a customer is in a Decline Recovery flow, multiple payment attempts are made within a single order session. This requires specific handling for transaction IDs, order IDs, and final outcome communication.

All payment attempts within a single decline recovery session share the same order_id for tracking and reconciliation purposes.

Each individual payment attempt within the session is assigned a unique transaction_id for accurate tracking, reporting and invoicing.

Acquired.com ensures that you only receive the final result of the order session, preventing unnecessary data handling for intermediate failures.

Scenario	Communication Method	Data Sent/Displayed
Merchant Handles Redirect	Form POST	Only the final transaction outcome (success or final failure after reaching `count_retry`) is sent via a Form POST to the merchant's redirect_url.
Acquired.com Handles Redirect	Payment Outcome Screen	The final transaction outcome (success or final failure) is presented to the customer on the Acquired.com payment outcome screen.

Webhooks & Order Active Status

A status_update webhook is sent for every single transaction attempt within the decline flow session. This provides you with a complete, real-time record of all attempts, including intermediate failures.

order_active Field in Form POST: When the final Form POST is sent to your redirect_url, the order_active field accurately reflects the payment link's status:

true: If the count_retry limit has not been reached, and the payment link is still valid for further attempts (e.g., in a subsequent session).
false: If the count_retry limit has been reached, or the order is successful, and no further attempts can be made on the link.