Przejdź do głównej zawartości

Filtrowanie metod płatności na bramce Paymentic

Jeśli nie chcesz pomijać bramki Paymentic, ale zależy Ci na tym, by na ekranie wyboru pojawiły się tylko wybrane metody/kanały (albo wręcz odwrotnie — żeby pewne metody były ukryte), możesz sterować tym z poziomu requestu tworzącego transakcję przez dwa pola:

  • allowedPaymentMethods — whitelist. Pokaż klientowi tylko to, co jest na liście.
  • hiddenPaymentMethods — blacklist. Pokaż wszystko, z wyjątkiem tego, co jest na liście.

Tymi polami możesz wpływać na ekran wyboru Paymentic per pojedyncza transakcja, bez zmian w konfiguracji punktu płatności.

Kiedy warto tego użyć?​

  • Masz jedną integrację i jeden pointId, ale dla różnych klientów chcesz pokazywać różne zestawy metod (np. B2B — bez BNPL, B2C — z BNPL).
  • Chcesz tymczasowo ukryć metodę, która ma problemy po stronie operatora, bez kontaktu z Paymentic.
  • W checkoucie premium chcesz ograniczyć się wyłącznie do kart i BLIKa, a w standardowym pokazać wszystko.
  • Chcesz wykluczyć konkretny bank PBL (np. w okresie jego prac serwisowych), ale zostawić resztę.

Jak to działa w skrócie​

Struktura pola​

Oba pola są tablicą obiektów. Każdy obiekt to jeden wpis filtra i ma dwie właściwości:

PoleWymaganeTypOpis
paymentMethodtakstringMetoda, której dotyczy wpis. Dopuszczalne wartości: BLIK, PBL, BNPL, CARD, MW, PAYSAFE.
paymentChannelniestringKonkretny kanał w obrębie metody (np. mbank, blik-level0). Jeśli pominiesz (null), filtr dotyczy wszystkich kanałów tej metody.
wskazówka

Listę dostępnych paymentMethod i paymentChannel pobierzesz z endpointu GET /v1_2/payment/points/{pointId}/channels — to ta sama lista, której używasz przy płatności z pominięciem bramki.

Przykład 1. Whitelist — pokaż tylko BLIK i wybrane banki PBL​

Pokazujemy klientowi tylko BLIK oraz dwa banki przez PBL — mBank i ING.

POST https://api.sandbox.paymentic.com/v1_2/payment/points/{pointId}/transactions
{
  "amount": "149.00",
  "currency": "PLN",
  "title": "Zamówienie #12345",
  "allowedPaymentMethods": [
    { "paymentMethod": "BLIK" },
    { "paymentMethod": "PBL", "paymentChannel": "mbank" },
    { "paymentMethod": "PBL", "paymentChannel": "ing" }
  ]
}

Wpis { "paymentMethod": "BLIK" } bez paymentChannel oznacza "wszystkie kanały BLIK". Dwa kolejne zawężają PBL do konkretnych banków — pozostałe banki PBL nie pojawią się na ekranie wyboru.

Przykład 2. Blacklist — ukryj BNPL i konkretny bank PBL​

Pokazujemy wszystko, ale ukrywamy BNPL w całości i dodatkowo jeden bank PBL, który ma serwis.

POST https://api.sandbox.paymentic.com/v1_2/payment/points/{pointId}/transactions
{
  "amount": "149.00",
  "currency": "PLN",
  "title": "Zamówienie #12345",
  "hiddenPaymentMethods": [
    { "paymentMethod": "BNPL" },
    { "paymentMethod": "PBL", "paymentChannel": "pko" }
  ]
}

Wpis { "paymentMethod": "BNPL" } ukrywa wszystkie kanały BNPL. Drugi wpis ukrywa wyłącznie kanał pko w metodzie PBL — pozostałe banki PBL nadal będą widoczne.

Odpowiedź i dalszy przebieg​

W odpowiedzi dostajesz standardowy obiekt z redirectUrl — tak jak w scenariuszu domyślnym. Przekierowanie prowadzi na ekran wyboru Paymentic, ale ekran ten zawiera wyłącznie metody, które przeszły przez filtr.

{
  "data": {
    "id": "ABCD-123-XYZ-9876",
    "redirectUrl": "https://pay.sandbox.paymentic.com/ABCD-123-XYZ-9876?token=...",
    "whitelabel": null
  }
}

Zmiany statusu transakcji przychodzą webhookiem — identycznie jak w standardowym scenariuszu.

Ważne uwagi​

  • allowedPaymentMethods i hiddenPaymentMethods wzajemnie się wykluczają. W jednym requescie możesz podać tylko jedno z dwóch — nie oba na raz.
  • Nie łącz z paymentMethod / paymentChannel. Pola filtrujące nie mogą współistnieć z polami "direct payment" (które wybierają jedną konkretną metodę i kanał — zob. Płatność z pominięciem bramki). Te dwa mechanizmy odpowiadają na dwa różne pytania: "pokaż ograniczony ekran wyboru" vs. "pomiń ekran wyboru w ogóle".
  • paymentChannel jest opcjonalny. Gdy go pominiesz (albo ustawisz null), filtr dotyczy wszystkich kanałów danej metody. Dzięki temu wpis { "paymentMethod": "BLIK" } działa jako "cała metoda BLIK".
  • paymentChannel musi pasować do paymentMethod. Jeśli podasz kanał mbank z metodą BLIK, wpis będzie niepoprawny — kanał zawsze jest podrzędny wobec metody i nazwy muszą być zgodne z odpowiedzią endpointu channels.
  • Filtr nie włącza niedostępnych metod. Jeśli dana metoda nie jest podpięta do Twojego punktu płatności albo nie obsługuje waluty transakcji, dodanie jej do allowedPaymentMethods nic nie zmieni — nadal się nie pojawi.
  • Pusty filtr = brak dostępnych metod. allowedPaymentMethods: [] oznacza, że nie ma ani jednej dozwolonej metody — zamiast tego pomiń pole.

Co dalej?​