Starting Point
When an online payment or a security deposit hold fails, knowing the reason helps you quickly decide what to do next.
From the booking details page, Avantio now shows more information about failed payments. Instead of just displaying the Failed status, you can see the reason for the error and find out if it’s a technical issue or a problem related to the card or payer’s details.
Depending on the type of error, you can take different actions directly from the booking, such as retrying the payment, contacting the guest, cancelling the booking, or reaching out to our customer support team.
What will you learn in this article?
You’ll learn how to check the reason for a failed payment, identify the type of error, and see what actions you can take to try to resolve it.
Benefits
Quickly identify the reason for the failure without having to interpret technical codes.
Take action directly from the booking based on the type of error detected.
Resolve card or guest data issues more easily, without always needing to contact customer support.
When should you use this feature?
Use this information when an online payment or security deposit hold appears as failed in the payment breakdown of a booking.
You can also access the error details from a failed payment notification, which will take you directly to the relevant booking.
Before you start
Keep in mind that:
This feature is applied automatically and does not require activation or additional configuration.
It’s available for bookings that use online payments or security deposit holds.
The details shown depend on the information provided by the payment gateway.
You don’t need to change your gateway configuration to use it.
Follow these steps
Go to the relevant booking details page.
Go to the payment breakdown.
Find the payment or security deposit hold that shows as Failed and click on it.
Review the information shown in the detail window. Avantio will identify the error as:
Technical error, related to Avantio or the payment gateway.
Error related to the card or payer, when the issue is with the card or the details provided.
Follow the recommended action based on the type of error.
Expected result
When you open a failed payment, you’ll see an explanation of the problem and the available actions to manage it.
This way, you can decide if you can resolve the issue yourself or if you need to contact our customer support team.
What can you do depending on the type of error?
A) If it’s a technical error
You can:
Retry the payment.
Contact customer support.
Close the window and check the payment again later.
If you retry the payment and it fails again, the reason for the new attempt will be shown.
If the payment goes through successfully, the payment status will update in the booking’s payment breakdown.
B) If the error is related to the card or payer
The message will tell you what problem was detected. For example:
Card declined.
Card expired.
Insufficient funds.
Incorrect CVC.
Incorrect card number.
Incorrect expiry date.
Incorrect cardholder name.
Invalid card type.
Card currency not supported.
Depending on the error, you can:
Contact the guest to ask them to check their details or provide another card.
Retry the payment.
Cancel the booking using the usual cancellation process.
Close the window without taking any action.
The Contact the guest option opens the relevant conversation in the Unified inbox so you can communicate with the guest without losing the booking context.
Main fields and options
When you check the details of a failed payment, you’ll find:
Error reason: explanation of the detected problem.
Retry payment: lets you try the payment again.
Contact customer support: available when the issue needs technical review.
Contact the guest: available for certain errors related to the card or payer’s details.
Cancel booking: lets you access the usual cancellation process when the error is related to the card or payer.
Limitations and considerations
Keep in mind that:
If Avantio can’t identify the error code, a generic message will be shown indicating there’s a problem and you should contact customer support.
You’ll never see untranslated technical codes, internal information, or technical details like traces or JSON data.
If there have been several payment attempts, only the reason for the most recent failed attempt will be shown.
Some errors that happen asynchronously, for example during certain 3D Secure processes, may temporarily show the generic message instead of the specific reason.
The level of detail available may depend on the information provided by each payment gateway.
Best practices
Always check the reason shown before retrying a payment.
If the error is related to the card, use the information shown to tell the guest what they need to check.
If the system says it’s a technical error, contact customer support if the problem continues.
Avoid making multiple consecutive attempts without first checking the cause of the failure.
After resolving the issue, check the payment breakdown to confirm the status has updated correctly.
Practical example
A guest has a pending payment and when you try to process it, it shows as Failed.
You go to the booking’s payment breakdown and click on the payment. The message says the card has been declined.
From the same window, you can contact the guest via Unified inbox and ask them to provide a new card. Once the details are updated, you can try the payment again.
If the new attempt is successful, the payment breakdown will show the updated status.
Common errors
Only a generic message appears: this can happen when the gateway doesn’t provide an identifiable reason or when the error can’t be classified yet.
The payment has failed several times but only one reason appears: Avantio only shows the reason for the most recent attempt.
The option to contact the guest doesn’t appear: the available actions depend on the type of error detected.
After retrying the payment, the error appears again: check the new reason shown, as it may be different from the previous attempt.
If something isn’t working
If you can’t manage the payment as expected, check these points before contacting our customer support team:
Make sure you’re checking the latest payment attempt.
Review the message shown in the payment details.
Check if the problem is identified as technical or as an error related to the card or payer.
If you’ve retried the payment, see if a new error reason has been generated.
Refresh the booking details and check the payment status again in the breakdown.
If the problem continues, contact our customer support team and, whenever possible, include screenshots and the details of the affected booking and payment.
Frequently asked questions
Why do I only see one reason if the payment has failed several times?
Why do I only see one reason if the payment has failed several times?
Because only the reason for the most recent payment attempt is shown. This way you can focus on the current cause of the problem.
Can I retry a payment from the error window?
Can I retry a payment from the error window?
Yes. If the option is available, you can select Retry payment.
If the new attempt fails again, the reason for the latest attempt will be shown. If it’s successful, the status will update in the payment breakdown.
Can I cancel a booking from the error details?
Can I cancel a booking from the error details?
Yes, when the failure is related to the card or payer’s details. The option will take you to Avantio’s usual cancellation process while keeping the booking context.
Can I contact the guest directly from the error?
Can I contact the guest directly from the error?
Yes. For errors related to the card or payer, the Contact the guest option opens the relevant conversation in the Unified inbox.
What happens if Avantio doesn’t recognize the error?
What happens if Avantio doesn’t recognize the error?
A generic message will be shown indicating an error has occurred and you should contact our customer support team.
No technical codes or internal system information will be shown.
Does it work the same with all payment gateways?
Does it work the same with all payment gateways?
Technical errors show the same type of message regardless of the gateway used.
For errors related to the card or payer, the level of detail available will depend on the information provided by each gateway.