New returnUrl format in payment API with enhanced security

Breaking changes! Сhanges listed below may break some apps' logic.

What's new

Payment API requests' got enhanced security: for every payment request, the returnUrl now has a unique generated hash (timestamp and key params).

The returnUrl defines a specific link where your payment app redirects customers after they complete the transaction.

Changes in API

From now on, any payment requests coming from Ecwid API to payment apps contain a new format for the returnUrl.

Format example: https://mystore.com/01234567?clientId=client_id&timestamp=1751294405226&key=abcdefgh

where:

• https://mystore.com/01234567 - base store URL (link to the main store page on the website).

• clientId=client_id - app's client_id value.

• &timestamp=1751294405226&key=abcdefgh - hash value passed as timestamp and key params. It is unique for every payment request coming to the app.

You must use the specific returnUrl received in the payment request for redirecting customers back to the storefront.

Why the changes are breaking

If the app generates returnUrl using some custom logic or tries to use returnUrl without the unique hash, customers won't see a purchase confirmation on the "Thank you for order" page which leads to a worse overall UX on the website.

How to update the app

1. Check if your app works with payment requests and allows customers to pay for the order online.

2. In the app code, ensure that the returnUrl value for every payment request is saved and later used to redirect customers back to the storefront without any changes to the returnUrl.