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

1. Sesja

   POST /orders tworzy zamówienie i sesję płatności u wybranego dostawcy. Odpowiedź zawiera redirectUrl do strony płatności.

2. Płatność u dostawcy

   Klient płaci. Dostawca przetwarza transakcję po swojej stronie.

3. Webhook

   Dostawca wysyła powiadomienie na POST /payments/webhooks/{provider}/{shopId}/{webhookSecret}. API weryfikuje podpis i aktualizuje status zamówienia. Zobacz Webhooki.

​

Kanały płatności

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

{ "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:

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.

Dostawcy płatności

Lista obsługiwanych dostawców i ich konfiguracja.