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

# Płatności

> Sesje płatności, kanały i cykl życia płatności.

Płatność powstaje automatycznie przy tworzeniu zamówienia. Endpointy `/payments/sessions` służą do operacji administracyjnych i wymagają tokenu Bearer oraz dostępu do sklepu danego zamówienia.

## Cykl życia

<Steps>
  <Step title="Sesja">
    `POST /orders` tworzy zamówienie i sesję płatności u wybranego dostawcy. Odpowiedź zawiera `redirectUrl` do strony płatności.
  </Step>

  <Step title="Płatność u dostawcy">
    Klient płaci. Dostawca przetwarza transakcję po swojej stronie.
  </Step>

  <Step title="Webhook">
    Dostawca wysyła powiadomienie na `POST /payments/webhooks/{provider}/{shopId}/{webhookSecret}`. API weryfikuje podpis i aktualizuje status zamówienia. Zobacz [Webhooki](/pl/guides/webhooks).
  </Step>
</Steps>

## Kanały płatności

Metodę i kanał podaje się w jednym polu, rozdzielone dwukropkiem:

```json theme={null}
{ "paymentMethodName": "imojeTransfer:blik" }
```

Nazwy i zachowanie kanałów są zależne od adaptera oraz usług aktywnych na koncie sprzedawcy. Użyj wartości zwracanych przez skonfigurowaną metodę; brak kanału zwykle pozostawia wybór po stronie operatora. Nie zakładaj, że `blik`, `card` lub `pbl` są obsługiwane przez każdego operatora.

## Czas życia sesji

| Typ płatności                     | TTL sesji |
| --------------------------------- | --------- |
| Natychmiastowe (BLIK, karta, SMS) | 30 minut  |
| Przelew tradycyjny                | 14 dni    |

Wygasłe sesje są oznaczane i czyszczone cyklicznie. Status sprawdzisz przez `GET /orders/payment-status/{orderId}`; endpoint wymaga tokenu Bearer użytkownika z dostępem do sklepu. Kupujący korzysta z ograniczonego endpointu statusu oraz sekretnego tokenu otrzymanego przy tworzeniu zamówienia.

## Ponowna płatność

Jeśli płatność się nie powiodła lub wygasła, zalogowany pracownik sklepu może utworzyć nową sesję dla tego zamówienia:

```bash theme={null}
curl -X POST https://api.itemshop.dev/api/v2/orders/retry-payment/<orderId> \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodName": "imojeTransfer:card" }'
```

## Darmowe zamówienia

Gdy rabat obniża kwotę do zera, zamówienie omija bramkę płatności i przechodzi do procesu realizacji pluginem. Odpowiedź zawiera `free: true`, aktualny status, `statusToken` i adres strony statusu. Dostawa może poczekać na połączenie pluginu albo gracza online, jeśli produkt tego wymaga.

<Card title="Dostawcy płatności" icon="building-columns" href="/pl/guides/payment-providers">
  Lista obsługiwanych dostawców i ich konfiguracja.
</Card>