# New returnUrl format in payment API with enhanced security

{% hint style="danger" %}
**Breaking changes!**\
Сhanges listed below may break some apps' logic.
{% endhint %}

#### 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.

{% content-ref url="/spaces/bMnrDOrph8biE23TpY18/pages/fkhtJxsOdYxW2SuJGLTJ" %}
[Broken mention](broken://spaces/bMnrDOrph8biE23TpY18/pages/fkhtJxsOdYxW2SuJGLTJ)
{% endcontent-ref %}

#### 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.

{% hint style="warning" %}
You must use the specific `returnUrl` received in the payment request for redirecting customers back to the storefront.
{% endhint %}

#### 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`**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecwid.com/changelog/march-2025/march-20/new-returnurl-format-in-payment-api-with-enhanced-security.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.