[NEWS] Zwroty płatności do kupujących - wprowadzamy obsługę nowych pól / Payment refunds to buyers - introducing support for new fields

Wprowadzamy zmiany w obsłudze zasobów [/payments/refunds](https://developer.allegro.pl/tutorials/jak-obslugiwac-zamowienia-GRaj0qyvwtR#zwroty-platnosci), za pomocą których możesz zlecać zwroty płatności do kupujących oraz pobierać o nich informacje.

**Co zmieniliśmy?**

Dla [POST /payments/refunds](https://developer.allegro.pl/documentation/#operation/initiateRefund) dodaliśmy nowe pola, które możesz przekazać w żądaniu:
* **commandId** - unikalny identyfikator w formacie UUID, który zapewnia idempotentność tworzenia zwrotów. Wartość wygenerujesz we własnym zakresie.
* **order.id** - numer zamówienia, musi być powiązany z płatnością, której zlecasz zwrot. Pole zwrócimy również w odpowiedzi.

Pola aktualnie są opcjonalne, jednak **w grudniu 2025 planujemy oznaczyć je jako
wymagane**. O dokładnej dacie poinformujemy z odpowiednim wyprzedzeniem.

Dla [GET /payments/refunds](https://developer.allegro.pl/documentation/#operation/getRefundedPayments) dodaliśmy nowy parametr wyszukiwania **order.id** oraz dodatkowe pole o tej samej nazwie, które zawiera informację o numerze zamówienia powiązanym z danym zwrotem płatności.

Więcej o zarządzaniu zwrotami płatności przeczytasz w [naszym poradniku](https://developer.allegro.pl/tutorials/jak-obslugiwac-zamowienia-GRaj0qyvwtR#zwroty-platnosci).

**Dlaczego wprowadzamy zmianę?**

Obecnie, aby korzystać z [One Fulfillment](https://allegro.pl/kampania/fulfillment), sprzedawca musi posiadać dodatkowe konto.
W przyszłości usługa ta będzie dostępna bezpośrednio na koncie sprzedawcy. Oznacza to, że pojedyncza płatność będzie mogła obejmować więcej niż jedno zamówienie – na przykład, sprzedawca otrzyma jedną wpłatę za zamówienie realizowane przez One Fulfillment (obsługiwane przez Magazyn Allegro) oraz za zamówienie obsługiwane samodzielnie. Aby ułatwić ich rozróżnienie, wprowadzamy pole **order.id** w obsłudze zwrotów płatności.

Pole **commandId** zapewni idempotentność tworzenia zwrotów. Wcześniej, jeśli aplikacja zlecała zwrot na połowę płatności i połączenie zostało przerwane, a próba zwrotu ponowiona, istniało ryzyko podwójnego wykonania zwrotu. Działo się tak, ponieważ nie znaliśmy dokładnej intencji użytkownika. Aktualnie, jeśli aplikacja w kolejnym requeście przekaże taką samą wartość dla **commandId**, w odpowiedzi za każdym razem zwrócimy ten sam wynik - nie utworzymy nowej dyspozycji zwrotu, jeśli wcześniejsza zakończyła się powodzeniem.

-----

We are introducing changes in handling the [/payments/refunds](https://developer.allegro.pl/tutorials/jak-obslugiwac-zamowienia-GRaj0qyvwtR#zwroty-platnosci) resources, responsible for initiating refunds to buyers and retrieving information about them.

**What have we changed?**

For [POST /payments/refunds](https://developer.allegro.pl/documentation/#operation/initiateRefund), we have added new fields you can include in your request:
* **commandId** - a unique UUID identifier that ensures idempotency for creating refunds. You'll generate this value yourself.
* **order.id** - the order number, which must be associated with the payment you're refunding. This field is also included in the response.

These fields are currently optional, but **we plan to mark them as required in December 2025**. We'll inform you of the exact date well in advance.

For [GET /payments/refunds](https://developer.allegro.pl/documentation/#operation/getRefundedPayments), we have added a new query parameter **order.id** and a new field with the same name, which contains information about the order associated with the given refund.

You can read more about managing refunds in [our tutorial](https://developer.allegro.pl/tutorials/process-orders-PgPMlWDr8Cv).

**Why are we introducing this change?**

Currently, to use [One Fulfillment](https://allegro.pl/kampania/fulfillment), sellers must have an additional account. In the future, this service will be available directly within the seller's main account. This means a single payment may cover more than one order – for example, a seller might receive one payment for an order fulfilled via One Fulfillment (handled by Allegro's warehouse) and for an order they fulfill independently. To facilitate distinguishing between these, we are introducing the **order.id** field in payment refund handling.

The **commandId** field will ensure idempotency for creating refunds. Previously, if an application initiated a partial payment refund and the connection was interrupted, then the refund attempt was retried, there was a risk of the refund being processed twice. This occurred because we didn't know the exact intent of the user. Now, if the application provides the same **commandId** value in a subsequent request, we will return the same result every time – we won't create a new refund if the previous one was successful.