By default, when a payment fails, your customers are given the option to retry their payment. However, for certain e-commerce scenarios, you may want to suppress this retry functionality and redirect customers back to your website instead.
Overview
Payment retry suppression allows you to control what happens when an online payment fails:
– Default behaviour: Customer sees a “Try Again” button to retry the payment
– With retry suppression: Customer sees a “Return to Merchant” button to go back to your website
This feature is particularly useful for e-commerce integrations where you want to handle failed payments through your own checkout flow rather than Trustist’s payment pages.
How It Works
Without Retry Suppression (Default)
1. Customer attempts payment
2. Payment fails (e.g., insufficient funds, technical issue)
3. Customer sees “Start Transaction Again” button
4. Customer can retry payment immediately
5. Process continues until successful or customer abandons
With Retry Suppression Enabled
1. Customer attempts payment
2. Payment fails
3. Customer sees “Return to Merchant” button
4. Customer is redirected to your specified return URL
5. You handle the failed payment scenario in your own system
Enabling Retry Suppression
When creating a payment through the e-commerce API, set the `suppressRetryOnFailure` flag:
{
“amount”: 100.00,
“currency”: “GBP”,
“description”: “Product purchase”,
“returnUrl”: “https://yourstore.com/checkout/return”,
“workflow”: {
“suppressRetryOnFailure”: true
}
}
Important Requirements:
– You must provide a `returnUrl` when using retry suppression
– The return URL should handle both success and failure scenarios
– Without a return URL, customers will see a message to contact you directly
Customer Experience
Failed Payment with Retry Suppression
When a payment fails with retry suppression enabled:
1. Payment Failure Page: Customer sees a clear message that the payment couldn’t be processed
2. Return Option: A “Return to Merchant” button is displayed (if return URL provided)
3. No Retry Option: The “Try Again” button is not shown
4. Clear Messaging: Customer understands they need to return to your site
Failed Payment Without Return URL
If retry suppression is enabled but no return URL is provided:
– Customer sees the payment failure message
– No return button is displayed
– Customer is advised to contact the merchant directly
MOTO (Mail Order/Telephone Order) Payments
Retry suppression behaves differently for MOTO payments:
– Regular Payments: “Try Again” becomes “Return to Merchant”
– MOTO Payments: “Try Again” becomes “Take Another Payment”
This is because MOTO payments are processed by merchants (you) directly, so the retry option should remain available for you to attempt another payment with different details.
Integration Guidelines
Handling Return URL
When customers return to your site after a failed payment:
// Example return URL handling
const urlParams = new URLSearchParams(window.location.search);
const paymentId = urlParams.get(‘paymentId’);
const status = urlParams.get(‘status’);
if (status === ‘failed’) {
// Handle failed payment
showFailureMessage();
offerAlternativePaymentMethods();
} else if (status === ‘completed’) {
// Handle successful payment
redirectToSuccessPage();
}
Best Practices
1. Clear Communication: Inform customers about the payment failure and next steps
2. Alternative Methods: Offer alternative payment methods (different bank, card payment, etc.)
3. Order Preservation: Keep the customer’s order/cart intact for easy retry
4. Support Information: Provide clear contact information for payment assistance
Recommended Return URL Flow
Failed Payment → Return to Merchant → Your Checkout Page
↓
Show failure message
↓
Offer alternatives:
• Try different bank account
• Use card payment
• Contact support
Use Cases
E-commerce Checkout
– Problem: Customer abandons after failed payment on Trustist page
– Solution: Return customer to your checkout with failure message and alternatives
Subscription Services
– Problem: Failed subscription payment leaves customer confused
– Solution: Return to account page with clear renewal options
Marketplace Payments
– Problem: Complex payment flows need custom failure handling
– Solution: Return to marketplace with seller/buyer context preserved
When Not to Use Retry Suppression
Consider keeping the default retry behaviour when:
– Simple Payment Links: Single-use payment links where retry is appropriate
– Donation Pages: Donors may want to immediately try with different account
– Bill Payments: Customers often prefer immediate retry for utility bills
– No Custom Flow: You don’t have sophisticated failure handling on your site
Monitoring and Analytics
Track the effectiveness of retry suppression:
– Conversion Rates: Compare completion rates with/without suppression
– Return Rates: How many customers return vs abandon
– Alternative Method Usage: Success rate of alternative payment methods
– Support Requests: Impact on customer service inquiries
Technical Implementation
API Integration
POST /api/payments
{
“amount”: 150.00,
“currency”: “GBP”,
“description”: “Order #12345”,
“returnUrl”: “https://yourstore.com/payment/return?order=12345”,
“workflow”: {
“suppressRetryOnFailure”: true
},
“metadata”: {
“orderId”: “12345”,
“customerId”: “cust_789”
}
}
Webhook Integration
Use webhooks to track payment outcomes:
{
“eventType”: “PaymentFailed”,
“paymentId”: “pmt_123”,
“suppressRetryOnFailure”: true,
“returnUrl”: “https://yourstore.com/payment/return?order=12345”
}
Troubleshooting
Common Issues
Return Button Not Appearing
– Check that `returnUrl` is provided and valid
– Verify retry suppression is enabled in the request
Customers Getting Confused
– Ensure your return page clearly explains the payment failure
– Provide clear next steps and alternatives
High Abandonment Rates
– Review your failure messaging and alternatives offered
– Consider A/B testing with and without retry suppression
Best Practices for Return URLs
1. Include Context: Pass order/payment identifiers in the URL
2. HTTPS Required: Return URLs must use HTTPS
3. Handle All Scenarios: Account for both success and failure returns
4. User-Friendly: Ensure the return experience is seamless
5. Mobile Optimised: Test the return flow on mobile devices
Getting Help
If you need assistance with retry suppression:
– Review the payment request format and ensure all required fields are provided
– Test the complete flow including return URL handling
– Monitor webhook events to understand the payment lifecycle
– Contact support with specific payment IDs for detailed assistance
