Configure handling of browser back button action at hosted payment page
Edit on GitHubWhen integrating payment service providers (PSPs) that use hosted payment pages, the application needs to handle browser navigation to maintaining order consistency and stock management. This document explains how to configure applications with hosted payment pages to handle the browser back button action.
Order persistence issue
When a customer is redirected from the Spryker checkout summary page to an external PSP’s hosted payment page, using the back button creates an order persistence issue. The order is already created in the system with a unique OrderReference, preventing the customer from completing the purchase if they attempt to proceed again through checkout.
This issue is particularly critical in the following cases:
- The last item in stock was part of the order
- The customer wants to change their order after being redirected to the payment page
- The order reference is already generated and persisted
Solution
Implement a mechanism to detect and handle cases where customers return from a hosted payment page using the back button. Сonfigure the system to cancel a previously created order and let the customer proceed with a new order.
Implement back button handling
- To support browser back button behavior for hosted payment pages, register
PaymentAppCancelOrderOnSummaryPageAfterRedirectFromHostedPaymentPagePlugin
in your project’sCheckoutPageDependencyProvider
.
Add the following methods to src/Pyz/Yves/CheckoutPage/CheckoutPageDependencyProvider.php
:
<?php
namespace Pyz\Yves\CheckoutPage;
use SprykerShop\Yves\PaymentAppWidget\Plugin\CheckoutPage\PaymentAppCancelOrderOnSummaryPageAfterRedirectFromHostedPaymentPagePlugin;
class CheckoutPageDependencyProvider extends SprykerCheckoutPageDependencyProvider
{
/**
* @return array<\SprykerShop\Yves\CheckoutPageExtension\Dependency\Plugin\CheckoutStepPreConditionPluginInterface>
*/
protected function getCheckoutSummaryStepPreConditionPlugins(): array
{
return [
new PaymentAppCancelOrderOnSummaryPageAfterRedirectFromHostedPaymentPagePlugin(),
];
}
/**
* @return array<\SprykerShop\Yves\CheckoutPageExtension\Dependency\Plugin\CheckoutStepPostConditionPluginInterface>
*/
protected function getCheckoutSummaryStepPostConditionPlugins(): array
{
return [
new PaymentAppCancelOrderOnSummaryPageAfterRedirectFromHostedPaymentPagePlugin(),
];
}
}
- Update the OMS state configuration by adding the
exclude from customer
flag to thepayment cancellation pending
state:
SalesPayment/config/Zed/Oms/Subprocess/PaymentCancel01.xml
<state name="payment cancellation pending" display="oms.state.reservation-cancellation-pending">
<flag>exclude from customer</flag>
</state>
The exclude from customer
flag is used to prevent cancelled payment orders from appearing in registered customers’ order history. For more information about the flag, see Order Process Modelling via State Machines.
Testing
Test the implementation by executing the following tests.
Basic flow test
- Add products to cart
- Proceed to checkout
- Reach the payment step and get redirected to hosted payment page
- Use the browser back button
Make sure the following applies:
- The original order has been cancelled
- You can place a new order with the same items
Stock verification test
- Add the last available item of a product to cart
- Proceed to checkout
- Reach the payment step and get redirected to hosted payment page
- Use the browser back button
Make sure the following applies:
- The item becomes available
- You can place a new order with the same item
Order status test
- Log in as a customer
- Add products to cart
- Proceed to checkout
- Reach the payment step and get redirected to hosted payment page
- Use the browser back button
Make sure the following applies:
- In the Back Office, order status changes to payment cancellation pending
- Order is not displayed in customer account
Troubleshooting
Solutions to common issues.
Order still visible in customer account
- Verify that the
exclude from customer
flag is properly set in the state machine configuration - Check if the order state transition to
payment cancellation pending
is executed successfully - Verify that the state is properly configured in the OMS
Stock issues
- Verify that the order cancellation workflow works properly
- Verify stock update triggers
0134259848974eeabe413347a75c5cdc2d7a2a89
Thank you!
For submitting the form