> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooki płatności

> Odbieranie powiadomień od dostawców i weryfikacja podpisów.

Dostawcy potwierdzają płatność, wysyłając powiadomienie na publiczny endpoint webhooka. Po weryfikacji podpisu API aktualizuje status zamówienia.

## Endpoint

```http theme={null}
POST /api/v2/payments/webhooks/{provider}/{shopId}/{webhookSecret}
```

* `provider` — nazwa dostawcy (np. `imojeTransfer`, `zen`, `paymentic`)
* `shopId` — sklep, do którego należy metoda
* `webhookSecret` — sekret metody płatności (ustalany przy konfiguracji)

URL webhooka skonfiguruj po stronie dostawcy lub jest przekazywany automatycznie przy tworzeniu sesji.

## Weryfikacja podpisu

Każdy dostawca podpisuje powiadomienie własnym sekretem i przekazuje podpis w nagłówku. ItemShop weryfikuje ten podpis na oryginalnej, niezmienionej treści żądania, zanim ją przetworzy. Mechanizm podpisu jest opisany w dokumentacji danego dostawcy:

| Dostawca  | Nagłówek podpisu                           |
| --------- | ------------------------------------------ |
| imoje     | `X-Imoje-Signature`                        |
| ZEN       | hash IPN przekazany w treści powiadomienia |
| Paymentic | `X-Paymentic-Signature`                    |
| Stripe    | `Stripe-Signature`                         |

<Warning>
  Webhook z nieprawidłowym podpisem jest odrzucany. Weryfikacja działa na oryginalnej treści, dlatego nie modyfikuj powiadomienia po stronie proxy.
</Warning>

## Mapowanie statusów

Dostawca przekazuje status transakcji, który API mapuje na status zamówienia:

| Status dostawcy (przykłady)                  | Status zamówienia                       |
| -------------------------------------------- | --------------------------------------- |
| `settled`, `ACCEPTED`, `PAID`                | `paid` (opłacone, gotowe do realizacji) |
| `cancelled`, `rejected`, `FAILED`, `EXPIRED` | `cancelled`                             |
| `pending`, `CREATED`                         | brak akcji                              |

Po przejściu w `paid` ItemShop automatycznie wysyła e-mail potwierdzający oraz powiadomienie na Discord.

## Odpowiedź

Po pomyślnym przetworzeniu endpoint zwraca `200` z `{ "received": true }`. Dostawcy traktują kod `2xx` jako potwierdzenie odbioru.