Przejdź do głównej zawartości

Metody płatności (payment_methods)

Zarządzanie skonfigurowanymi metodami płatności, które klienci wybierają w checkoucie. Za każdym wierszem PaymentMethod stoi zarejestrowany adapter (zobacz Mechanizm adapterów niżej) oraz lista kanałów sprzedaży, w których metoda jest widoczna.

API publiczne​

Trasy administracyjne są chronione przez payment_methods:read (odczyt) i payment_methods:write (zmiany) — własne kody modułu od 2026-08-28. Wcześniej były to catalog:read / catalog:write, co oznaczało, że każdy, kto mógł edytować produkt, mógł też decydować o tym, jak sklep przyjmuje płatności. Rola, która korzystała z kodów katalogu przy tym ekranie, musi dostać nowe kody na /admin-roles; nic nie przyznaje ich automatycznie — celowo.

Wybór kanałów sprzedaży metody wymaga tych kodów i żadnych innych. To, gdzie metoda jest dostępna, jest częścią konfiguracji metody, więc payment_methods:write wystarcza, aby przypisać, zmienić i usunąć jej kanały sprzedaży, a payment_methods:read — aby zobaczyć kanały do wyboru (GET /api/v1/admin/payment-methods/sales-channels). Ani sales_channels:read, ani sales_channels:write nie są wymagane — to decyzja, nie przeoczenie — a kody payment_methods nie dają żadnych uprawnień na ekranach kanałów sprzedaży.

Jedynym wyjątkiem jest GET /api/v1/admin/order-statuses i jest to warunek „jedno z”, a nie poszerzenie uprawnień: trasa jest zarejestrowana w tym module, ale korzystają z niej dwa edytory — ekran tego modułu i delivery_methods — więc akceptuje kod odczytu któregokolwiek z tych modułów. Drugim kodem było catalog:read, dopóki delivery_methods korzystało z uprawnień katalogu; po wprowadzeniu przez tamten moduł własnej pary kodów stało się nim delivery_methods:read, więc samo uprawnienie do katalogu nie daje już dostępu do wspólnej listy.

Metoda i ścieżkaKtoUprawnieniePrzeznaczenie
GET /api/v1/payment-methodsanonimowy—Metody dostępne w checkoucie storefrontu (aktywne ∩ kanał sprzedaży ∩ lista dozwolonych dla organizacji ∩ zarejestrowany adapter ∩ validateUseOnStorefront)
GET /api/v1/admin/payment-methodsadministratorpayment_methods:readPełna konfiguracja (aktywne i nieaktywne), łącznie z adapter, additionalPrice, statusOn* i kanałami sprzedaży
GET /api/v1/admin/payment-methods/adaptersadministratorpayment_methods:readZarejestrowane klucze adapterów, do listy wyboru w panelu
GET /api/v1/admin/payment-methods/sales-channelsadministratorpayment_methods:readKanały sprzedaży, do których można przypisać metodę — { id, code, name, active } dla każdego kanału, także nieaktywnych
GET /api/v1/admin/order-statusesadministratorpayment_methods:read albo delivery_methods:readStatusy zamówienia do list wyboru statusOn*, tutaj i na ekranie metod dostawy
PUT /api/v1/admin/payment-methods/:codeadministratorpayment_methods:writeUtworzenie lub aktualizacja według kodu; adapter domyślnie przyjmuje wartość kind, a statusOn* jest sprawdzane względem rejestru statusów zamówienia
PATCH /api/v1/admin/payment-methods/:id/statusadministratorpayment_methods:writeWyłącznie dostępność — jedyna zmiana, do której odsyłają cztery ekrany bramek płatności
DELETE /api/v1/admin/payment-methods/:idadministratorpayment_methods:writeUsunięcie — zablokowane odpowiedzią 409 PAYMENT_METHOD_IN_USE (details: paymentMethodId, paymentMethodCode, paymentCount), gdy metoda jest używana przez płatność Payment, oraz odpowiedzią 409 PAYMENT_METHOD_USAGE_UNKNOWN (details: paymentMethodId, module: "payments"), gdy moduł payments jest wyłączony; zamiast tego ustaw inactive. Do zgłoszenia #635 obie były odpowiedzią 409 VALIDATION_FAILED

Encje​

PaymentMethod — code, kind, adapter (klucz w rejestrze), name domyślne i dla poszczególnych języków, status, additionalPrice (stała dopłata w walucie zamówienia) oraz trzy odwołania do statusów zamówienia: statusOnPending / statusOnSuccess / statusOnFailure. Przypisanie do kanałów sprzedaży przez sales_channel_payment_methods; dostępność dla organizacji przez organization_payment_methods.

Mechanizm adapterów​

Działanie metody płatności zapewnia PaymentAdapter zarejestrowany w PaymentAdapterRegistry. Platforma rozpoznaje moduł jako dostawcę metody płatności wtedy i tylko wtedy, gdy rejestruje adapter — nie ma innego warunku. Wbudowane adaptery bank_transfer, pickup, credit_limit i gateway to implementacje wzorcowe (packages/modules/payments/src/backend/adapters/built-in-adapters.ts).

Kontrakt​

PaymentAdapter (z @endora-commerce/contracts) zawiera:

  • adapterKey — stały identyfikator; odpowiada payment_methods.adapter.
  • type — jedno z bank_transfer | pickup | credit_limit | gateway.
  • validateUseOnStorefront / validateUseOnAdmin / validateUseInApi — dodatkowe warunki dostępności dla poszczególnych miejsc; zwracaj stałe true, gdy nie ma ograniczeń.
  • onStorefrontOrderCreated — wywoływane przy storefront_order_created; zwraca StartPaymentResult (awaiting_transfer | redirect | none).
  • onReceivePayment — przekłada powiadomienie zwrotne receive_payment na wynik PaymentOutcome (sukces albo porażka).
  • renderers? — opcjonalne klucze szablonów { storefront?, admin?, email? }; brak ⇒ używany jest szablon domyślny platformy.

Cykl życia​

  1. storefront_order_created — order-service.placeOrder tworzy zamówienie w statusie statusOnPending metody, dolicza additionalPrice do wartości zamówienia, otwiera oczekującą płatność Payment i wywołuje adapter.onStorefrontOrderCreated.
  2. receive_payment — POST /api/v1/payments/receive odnajduje płatność Payment (po paymentId albo orderId + externalReference), zapisuje wynik i przestawia status zamówienia przez statusOnSuccess / statusOnFailure. Działa idempotentnie: ponowny sukces niczego nie zmienia; porażka po końcowym stanie paid jest odrzucana. Nieudaną płatność ponawia się przez POST /api/v1/admin/orders/:id/payments/retry, co otwiera nową płatność Payment (attemptNo + 1), a wcześniejsze próby pozostają bez zmian.

Payment.status (stan procesu płatności: awaiting_payment → paid | failed, a także deferred dla limitu kredytowego) jest niezależny od przekładania na statusy zamówienia. statusOn* odwołują się do statusów zamówienia wyznaczanych przez port OrderStatusRegistry — dziś opartego na wyliczeniu, a później wymiennego na konfigurowalny rejestr modułu zamówień bez zmian w tym module.

Jak zbudować własny moduł metody płatności​

  1. Utwórz pakiet modułu (packages/modules/<your_module>/) z plikiem src/manifest.ts deklarującym dependencies: ['payment_methods'], a następnie uruchom pnpm --filter backend run composer:generate, aby wygenerowany rejestr manifestów go uwzględnił.

  2. Zaimplementuj PaymentAdapter: ustaw adapterKey, type, trzy funkcje validateUse* (zwracaj true, gdy nie ma ograniczeń), onStorefrontOrderCreated (zwracaj redirect / awaiting_transfer / none) oraz onReceivePayment (przełóż powiadomienie od operatora płatności na success / failure).

  3. Dodaj adapter w hooku startowym modułu, podając moduł jako właściciela:

    import { paymentAdapterRegistry } from '.../payment_methods/services/registry-singleton.js';

    ctx.onBoot(() => {
    paymentAdapterRegistry.register(myAdapter, 'my_module');
    });

    Identyfikator właściciela to nie ozdobnik: rejestr pomija adapter, którego moduł nie jest faktycznie obecny, więc bramka wyłączona przez operatora przestaje być oferowana w checkoucie bez wyrejestrowywania. Hooki startowe wykonują się niezależnie od stanu modułu — na pytanie o obecność odpowiada przeglądanie wpisów, a nie rejestracja.

  4. Wiersze metod dostarcz jako migrację należącą do modułu. Kody, rodzaje i domyślne nazwy są stałe w czasie kompilacji, więc to statyczne dane słownikowe, a nie uzgadnianie przy każdym starcie: insert … on conflict (code) do nothing, z wartością inactive, aby operator świadomie je włączył. Dokładnie tak robią cztery wbudowane bramki (stripe/migrations/…_stripe_seed_payment_methods.ts). PaymentMethodReconciler.ensureMethodForAdapter pozostaje dostępny w installHook dla modułu, który musi utworzyć wiersz w kodzie; jest idempotentny, nigdy nie nadpisuje zmian administratora i nie zmienia przypisań do kanałów sprzedaży.

  5. (Opcjonalnie) zarejestruj szablony dla storefrontu, panelu i e-maili pod kluczami, które deklaruje adapter; w przeciwnym razie użyte zostaną szablony domyślne.

  6. Włącz moduł → na /payment-methods pojawia się konfigurowalna metoda płatności. Zmiany w rdzeniu nie są potrzebne.

paymentAdapterRegistry to singleton procesu (registry-singleton.ts): jedna tabela adapterów na proces, niezależnie od tego, ile razy platforma jest składana, podłączona do sprawdzania dostępności, panelu administracyjnego i składania zamówień. Każdy wpis zapisuje moduł, który go dodał, a każdy odczyt przeznaczony dla kupującego (get, resolve, list) pomija wpis, którego właściciela nie ma. Odczyty dla panelu (entry, ownerOf, isRegistered, listAll) celowo tego nie robią: wyłączenie modułu to nie jego odinstalowanie, więc ekran /payment-methods zachowuje wiersz i pokazuje, dlaczego metoda jest niedostępna.

Kanały sprzedaży​

Każda metoda płatności jest dostępna w tych kanałach sprzedaży, które wybierze dla niej operator. Na ekranie /payment-methods formularz ma pole Kanały sprzedaży, a lista pokazuje kanały każdej metody.

Przypisanie jest ograniczeniem, a metoda bez przypisania jest dostępna w każdym kanale. Metoda przypisana do jednego lub kilku kanałów jest dostępna dokładnie w nich. Metoda nieprzypisana do żadnego kanału — Wszystkie kanały w formularzu — jest dostępna w każdym kanale, także w kanałach utworzonych później. To celowo inna reguła niż dla produktów, gdzie produkt bez kanału nie jest opublikowany nigdzie: metody płatności istnieją bez przypisania w zwykłych sytuacjach, więc potraktowanie „żadnego” jako „nigdzie” odebrałoby istniejącym sklepom metody dostępne przy składaniu zamówienia. Stan metody, której nikt nie przypisał ręcznie:

  • Moduł dostarczający własną metodę tworzy ją podczas instalacji modułu i nie przypisuje jej do żadnego kanału, więc jest dostępna w każdym kanale — niezależnie od tego, kiedy moduł zostanie zainstalowany: w nowej instancji czy w działającej od lat. Wydania sprzed tej reguły działały inaczej: metoda była przypisywana do kanału domyślnego, jeśli ten kanał istniał w chwili instalacji, a istnieje on w każdej instancji uruchomionej przynajmniej raz. Metody utworzone wtedy zachowują to przypisanie.
  • Dane demonstracyjne nie przypisują żadnego kanału.
  • Metoda utworzona przez API bez salesChannelIds zostaje przypisana do kanału domyślnego; metoda utworzona w formularzu panelu bez zaznaczenia kanału nie jest przypisana do żadnego.

Przypisanie jest egzekwowane tam, gdzie spotyka je kupujący:

  • GET /api/v1/payment-methods zwraca tylko metody dostępne w kanale sprzedaży rozpoznanym dla żądania (X-Sales-Channel, ?salesChannel=, mapa hostów, a w ostatniej kolejności kanał domyślny). Sklep musi więc wskazać swój kanał przy tym odczycie: referencyjny sklep przekazuje X-Sales-Channel, a sklep utworzony z wcześniejszego wydania wymaga tej samej zmiany w lib/api/methods.ts — w przeciwnym razie otrzyma metody kanału domyślnego.
  • Złożenie zamówienia i podgląd jego sumy odrzucają metodę, która nie jest dostępna w kanale sprzedaży zamówienia, odpowiedzią 400 ORDER_PAYMENT_METHOD_UNAVAILABLE z details.code = "payment_method_not_in_sales_channel". Dotyczy to zakupu w sklepie, zakupu jednym kliknięciem, zamówienia tworzonego przez administratora w imieniu klienta (kanał wybrany dla zamówienia) oraz zamówienia złożonego kluczem API (kanał klucza). Formularz tworzenia zamówienia w panelu zawęża listy metod do wybranego kanału.

Pole salesChannelIds w PUT /api/v1/admin/payment-methods/:code ma trzy znaczenia:

salesChannelIdsSkutek
pominięteAktualizacja nie zmienia przypisania. Nowa metoda zostaje przypisana tylko do kanału domyślnego.
[]Wszystkie przypisania są usuwane: metoda jest dostępna w każdym kanale.
jeden lub więcej identyfikatorówMetoda jest dostępna dokładnie w tych kanałach.

Formularz w panelu zawsze wysyła to pole, więc metoda utworzona w nim bez zaznaczenia żadnego kanału jest dostępna w każdym kanale. Jeśli formularz nie może wczytać listy kanałów sprzedaży, informuje o tym i nie wysyła pola, a zapis pozostawia przypisanie bez zmian.

Poza tym nadal obowiązuje reguła co najmniej jednego kanału: usunięcie ostatniego kanału metody od strony kanału sprzedaży jest odrzucane, a usunięcie kanału sprzedaży, który jest jedynym kanałem metody, jest odrzucane albo przepina metodę do kanału domyślnego. Przypisanie nie znika więc jako skutek uboczny innej operacji: metoda jest dostępna wszędzie tylko dlatego, że zapisano ją bez wybranego kanału albo utworzono bez przypisania, jak opisano wyżej. Zapis wskazujący kanał sprzedaży, który nie istnieje, jest odrzucany odpowiedzią 400 VALIDATION_FAILED, zanim cokolwiek zostanie zapisane. Jeśli przypisanie kanałów nowej metody mimo to się nie powiedzie, utworzenie jest wycofywane: metoda zostaje usunięta — bez pytania modułu payments, bo do metody utworzonej w tym samym żądaniu nic nie może się odwoływać, więc działa to także przy wyłączonym payments — a żądanie kończy się błędem. Gdyby samo usunięcie się nie powiodło, metoda pozostaje nieaktywna, a nie aktywna bez kanału, więc w najgorszym razie po prostu nie jest oferowana.

Aktualizacja instancji z więcej niż jednym kanałem sprzedaży: przejrzyj każdą metodę. Dotychczas sklep pokazywał każdą aktywną metodę w każdym kanale i pomijał przypisanie. Kolumna Kanały sprzedaży na ekranie /payment-methods pokazuje obecny stan każdej metody:

  • przypisana tylko do kanału domyślnego, a więc niedostępna przy składaniu zamówienia w pozostałych kanałach, dopóki tego nie zmienisz — każda metoda utworzona dotąd w panelu oraz każda metoda utworzona przez moduł we wcześniejszym wydaniu w instancji, która była już uruchomiona. Nic nie poszerza ich automatycznie: takiego wpisu nie da się odróżnić od metody ograniczonej celowo;
  • nieprzypisana do żadnego kanału, a więc dostępna wszędzie — każda metoda tworzona przez moduł od tego wydania, metody utworzone przez moduł we wcześniejszym wydaniu podczas pierwszej konfiguracji instancji oraz metody z danych demonstracyjnych.

Otwórz każdą metodę i wybierz jej kanały albo odznacz wszystkie, aby była dostępna wszędzie. W instancji z jednym kanałem sprzedaży nic się nie zmienia.

Przypisania są przechowywane w tabeli sales_channel_payment_methods i są odczytywane oraz zapisywane wyłącznie przez usługę przypisań kanałów sprzedaży platformy.

Dostępność dla organizacji​

organization_payment_methods to lista dozwolonych: pusta ⇒ oferowane są wszystkie aktywne metody; niepusta ⇒ tylko wymienione. Służy do ograniczania metod, z których może korzystać dana organizacja. Zarządza nią usługa ograniczeń modułu organizacji i odpowiedni ekran w panelu.