> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/changelog/march-2025/march-20/new-returnurl-format-in-payment-api-with-enhanced-security.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.