Przejdź do głównej zawartości

Płatność White Label

Utwórz płatność White Label​

White Label oznacza, że kupujący nie jest przekierowywany do strony wyboru metody płatności Paynow — proces płatności rozpoczyna się lub w całości odbywa bezpośrednio na stronie sklepu. Przykładowo dla płatności BLIK kupujący wpisuje kod autoryzacyjny na stronie sklepu, a dla płatności kartą wypełnia formularz kartowy osadzony w ramce <iframe>.

Obecnie integracja w modelu White Label jest dostępna dla płatności BLIK, pay-by-link (PBL), PayPo oraz płatności kartą (jednorazowych i cyklicznych).

Aby skorzystać z modelu White Label:

  1. Przed każdym utworzeniem płatności pobierz aktualną listę metod płatności (GET /v3/payments/paymentmethods — nie zapisuj listy metod płatności w cache).
  2. Utwórz płatność zgodnie z wybraną metodą opisaną poniżej.
  3. Pobierz i wyświetl kupującemu klauzulę informacyjną o administratorze danych osobowych (wymóg prawny — zob. Obowiązek informacyjny RODO i aktywacja usługi).

Płatność BLIK (2007)​

  • Użyj metody płatności, w której wartość pola authorizationType jest równa CODE:
[
{
"type": "BLIK",
"paymentMethods": [
{
"id": 2007,
"name": "BLIK",
"description": "Płacę z BLIKIEM",
"image": "https://static.devel.integrator.emfale.com/payment-method-icons/2007.png",
"status": "ENABLED",
"authorizationType": "CODE"
}
]
}
]
{
"amount": "409272",
"externalId": "c7b55386-ba45-4537-96a5-bb77c6910418",
"paymentMethodId": 2007,
"currency": "PLN",
"description": "Testowa transakcja",
"continueUrl": "https://melements.pl",
"buyer": {
"email": "jan.kowalski@melements.pl",
"firstName": "Jan",
"lastName": "Kowalski",
"locale": "pl-PL",
"phone": {
"prefix": "+48",
"number": "120932212"
}
},
"authorizationCode": "123456"
}

PBL (pay-by-link) oraz PayPo​

Utwórz płatność ze zdefiniowaną metodą płatności (paymentMethodId, np. 3000 dla PayPo) w standardowy sposób opisany w sekcji Tworzenie płatności ze zdefiniowaną metodą płatności.

Płatności kartą (2002) i płatności cykliczne kartą (2202)​

W modelu White Label płatności kartowe mogą być realizowane na dwa sposoby:

  • Płatność kartą w trybie widgetu — formularz płatności jest osadzony bezpośrednio na stronie sklepu w elemencie <iframe>, w którym kupujący wpisuje dane karty. Tryb ten obejmuje:
    • jednorazową płatność kartą (2002) — standardowa płatność za pojedyncze zamówienie (zobacz wymagane pola i przykład żądania poniżej),
    • pierwszą płatność subskrypcyjną (2202, CIT) — opłacenie pierwszego okresu połączone z utworzeniem subskrypcji (przykład żądania i opis cyklu życia znajdziesz w sekcji Zapis karty i subskrypcje).
  • Płatność zapisaną kartą (One-Click, 2002) — płatność wcześniej zapisaną kartą bez ponownego wpisywania jej danych, opisana w sekcji Tokenizacja kart – płatność White Label.

Wymagane pola i wywołanie trybu WIDGET​

Aby zainicjować formularz kartowy w trybie WIDGET, w żądaniu utworzenia płatności (POST /v3/payments) przekaż dodatkowo:

  • paymentMethodData.card.cardFormBehaviour – wartość "WIDGET",
  • continueUrl – adres powrotu po zakończeniu płatności (wywoływany wewnątrz <iframe>),
  • buyer.ipAddress oraz buyer.userAgent – adres IP oraz nagłówek User-Agent przeglądarki kupującego (pominięcie continueUrl, buyer.ipAddress lub buyer.userAgent w trybie WIDGET skutkuje błędem 400 Bad Request).

Przykładowe żądanie dla jednorazowej płatności kartą (2002) w trybie WIDGET:

{
"amount": 45671,
"currency": "PLN",
"externalId": "order-card-wl-001",
"description": "Opłata za zamówienie nr 1024",
"continueUrl": "https://twojsklep.pl/platnosc/powrot",
"paymentMethodId": 2002,
"buyer": {
"email": "jan.kowalski@example.com",
"firstName": "Jan",
"lastName": "Kowalski",
"locale": "pl-PL",
"ipAddress": "203.0.113.42",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
},
"paymentMethodData": {
"card": {
"cardFormBehaviour": "WIDGET"
}
}
}

Gdy usługa White Label dla płatności kartą jest aktywna na koncie sklepu (POS), w odpowiedzi 201 Created otrzymasz adres widgetUrl (redirectUrl przyjmuje wartość null, a początkowy status płatności to PENDING):

{
"redirectUrl": null,
"widgetUrl": "<widget-url>",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "PENDING"
}

Umieść wartość widgetUrl w atrybucie src elementu <iframe> na stronie sklepu i dodaj atrybut allow="payment". Ustaw width: 100% w responsywnym kontenerze o szerokości co najmniej 320px (zalecane 400px–520px) oraz wysokość co najmniej 480px. Ponieważ widget jest ładowany z innej domeny, wysokość <iframe> nie dopasowuje się automatycznie; obramowanie można ukryć za pomocą border: none:

<iframe
id="paymentIframe"
src="<widget-url>"
allow="payment"
title="Formularz płatności kartą">
</iframe>

Po zakończeniu procesu płatności przekierowanie na continueUrl odbywa się wewnątrz elementu <iframe>. Strona powrotu powinna obsługiwać pomyślną, przerwaną i nieudaną płatność oraz mieć kompaktowy układ bez pełnego nagłówka i stopki sklepu.

Opcjonalny tryb WIDGET – automatyczny fallback do REDIRECT

Dla płatności kartowych (2002 oraz 2202) tryb WIDGET ma charakter opcjonalny. Jeśli usługa White Label dla kart nie jest włączona dla danego punktu sprzedaży (POS), przekazanie cardFormBehaviour: "WIDGET" nie powoduje błędu — Paynow automatycznie przełącza płatność na tryb przekierowania (REDIRECT) i zwraca 201 Created ze standardowym adresem redirectUrl do strony płatności Paynow (widgetUrl: null, status: "NEW").

Po stronie sklepu należy sprawdzać zawartość odpowiedzi POST /v3/payments:

  • gdy pole widgetUrl jest niepuste — osadź widget w <iframe>,
  • gdy zwrócono redirectUrl (widgetUrl jest null) — przekieruj kupującego pod adres redirectUrl.
Przykłady osadzenia widgetu w środowisku Sandbox

Obowiązek informacyjny RODO i aktywacja usługi​

Obowiązek informacyjny wynika z rozporządzenia RODO o ochronie danych osobowych. W przypadku płatności innych niż White Label informacje są wyświetlane na stronie płatności Paynow. W przypadku płatności White Label musisz dodatkowo:

  • pobrać i wyświetlić klauzulę RODO z endpointu pobrania klauzul (GET /v3/payments/dataprocessing/notices — odpowiedź można przechowywać w cache, ale nie należy jej zapisywać na stałe w kodzie).

  • przesłać na adres support@paynow.pl link do sklepu oraz zrzut ekranu pokazujący, jak klauzula RODO jest wyświetlana, aby zespół Paynow mógł zweryfikować wdrożenie i aktywować usługę White Label.

Po pozytywnej weryfikacji usługa White Label zostanie skonfigurowana dla sklepu w Paynow. Jeśli White Label nie jest jeszcze aktywny na danym punkcie sprzedaży (POS):

  • dla płatności BLIK (2007) przekazanie kodu autoryzacyjnego authorizationCode w treści żądania płatności zakończy się błędem 400 Bad Request (BAD_REQUEST),
  • dla płatności kartą (2002) oraz płatności cyklicznych kartą (2202) z cardFormBehaviour: "WIDGET" błąd nie wystąpi — żądanie zostanie automatycznie przełączone na tryb przekierowania (REDIRECT), a w odpowiedzi otrzymasz redirectUrl (widgetUrl: null, status: "NEW").