# Zdarzenie: transaction_refund:status_changed

Zdarzenie `transaction_refund:status_changed` służy do informowania Twojej aplikacji o zmianach na ścieżce procesowania
zwrotu środków dla klienta (tzw. refund).

Ponieważ zwroty w systemach bankowych realizowane są asynchronicznie, nie otrzymujesz potwierdzenia o udanym zwrocie
natychmiast w odpowiedzi na żądanie z API. Zamiast tego, Twój system dowiaduje się o ostatecznym wyniku operacji właśnie
z tego powiadomienia IPN.

## Kiedy wysyłany jest ten event?

Powiadomienie to jest wyzwalane za każdym razem, gdy zlecenie zwrotu zmienia swój status w systemie SimPay. Otrzymasz je
w szczególności, gdy:

* Zwrot zostanie pomyślnie przetworzony i środki zostaną wysłane do klienta (zmiana na status `refund_completed`).
* Zlecenie zwrotu zostanie odrzucone, np. z powodu niewystarczającego salda na Twoim koncie w SimPay lub zbyt starej
transakcji (zmiana na `refund_rejected` lub `refund_failed`).


## Struktura obiektu `data`

Gdy pole `type` w głównym obiekcie powiadomienia ma wartość `transaction_refund:status_changed`, obiekt `data` będzie
zawierał następujące informacje:

| Pole | Typ | Opis | Przykładowa wartość |
|  --- | --- | --- | --- |
| `id` | `UUID` | ID zwrotu w systemie SimPay | `0194837c-69df-71dd-adff-4b3058f3fb58` |
| `service_id` | `char(8)` | Identyfikator usługi | `e65c7519` |
| `status` | `RefundStatusEnum` | Aktualny [status zwrotu](/payment/statuses#statusGroup=Statusy+zwrot%C3%B3w) (np. `refund_completed`) | `refund_completed` |
| `amount` | `object` | Obiekt informacji o kwocie |  |
| `amount.currency` | `ISO 4217` | Waluta, w której zlecono zwrot | `PLN` |
| `amount.value` | `string` (%.2f) | Kwota, zlecona w zwrocie | `8.47` |
| `amount.wallet_currency` | `ISO 4217` | Waluta portfela, z którego pobrano środki na poczet zwrotu | `EUR` |
| `amount.wallet_value` | `string` (%.2f) | Kwota, którą ostatecznie pobrano z portfela (salda) | `2.00` |
| `transaction` | `object` | Pole z informacjami o transakcji, której dotyczy ten zwrot |  |
| `transaction.id` | `UUID` | ID pierwotnej transakcji SimPay | `00554475-7ebb-4f16-b30b-0ce21da1a03b` |
| `transaction.payment_channel` | `string` | Kanał płatności, którym zapłacił płacący | `blik` |
| `transaction.payment_type` | `string` | Typ/grupa metody płatności | `blik` |


Wskazówka
Gdy otrzymasz to powiadomienie, sprawdź pole `status`. Jeśli ma ono wartość **`refund_completed`**, oznacza to, że
pieniądze zostały wysłane do klienta – w tym momencie powinieneś oznaczyć zwrot w swoim systemie księgowym /
e-commerce jako zrealizowany i ewentualnie wysłać klientowi maila z powiadomieniem.

## Przykładowy Payload JSON

Poniżej znajduje się kompletny zrzut (payload) powiadomienia wysyłanego dla zdarzenia
`transaction_refund:status_changed`.

*(Przykładowa sygnatura została wygenerowana przy użyciu klucza IPN: **`UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ`**. Możesz użyć
tego klucza i poniższych danych do przetestowania swojego algorytmu walidacji).*


```json
{
  "type": "transaction_refund:status_changed",
  "notification_id": "0196ff00-376d-7399-a457-d166c9adf073",
  "date": "2025-05-23T23:15:26+02:00",
  "data": {
    "id": "0194837c-69df-71dd-adff-4b3058f3fb58",
    "service_id": "e65c7519",
    "status": "refund_completed",
    "amount": {
      "currency": "PLN",
      "value": "1.00",
      "wallet_currency": "PLN",
      "wallet_value": "1.00"
    },
    "transaction": {
      "id": "e568d9ba-a85a-444c-87c4-3b1e431428d1",
      "payment_channel": "paysafecard",
      "payment_type": "paysafe"
    }
  },
  "signature": "835819c5720c74f01b8d10a58b2dc43185f05379ea26f25a15158061f3bce10c"
}
```

details
summary
Zobacz wyliczenie sygnatury
1. Flatten wszystkich elementów po kolei + separacja `|`:


Nasz ciąg będzie wyglądać tak:


```
transaction_refund:status_changed|0196ff00-376d-7399-a457-d166c9adf073|2025-05-23T23:15:26+02:00|0194837c-69df-71dd-adff-4b3058f3fb58|e65c7519|refund_completed|PLN|1.00|PLN|1.00|e568d9ba-a85a-444c-87c4-3b1e431428d1|paysafecard|paysafe
```

1. Dodaj klucz IPN na końcu ciągu:
`...|UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ`
2. Oblicz SHA256 z powyższego ciągu i zakoduj go w hex:



```php
<?php

$signature = hash('sha256', 'transaction_refund:status_changed|0196ff00-376d-7399-a457-d166c9adf073|2025-05-23T23:15:26+02:00|0194837c-69df-71dd-adff-4b3058f3fb58|e65c7519|refund_completed|PLN|1.00|PLN|1.00|e568d9ba-a85a-444c-87c4-3b1e431428d1|paysafecard|paysafe|UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ');
```

1. Porównaj bezpieczną funkcją porównującą (np. `hash_equals` w PHP) obliczoną sygnaturę z tą przesłaną w polu
`signature` powiadomienia. W tym przypadku wynikiem hashowania będzie
`835819c5720c74f01b8d10a58b2dc43185f05379ea26f25a15158061f3bce10c`.