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:
- 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). - Utwórz płatność zgodnie z wybraną metodą opisaną poniżej.
- 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
authorizationTypejest równaCODE:
[
{
"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"
}
]
}
]
- Wyślij żądanie utworzenia płatności (
POST /v3/payments) z uzupełnionym kodem autoryzacyjnymauthorizationCode:
{
"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).
- jednorazową płatność kartą (
- 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.ipAddressorazbuyer.userAgent– adres IP oraz nagłówekUser-Agentprzeglądarki kupującego (pominięciecontinueUrl,buyer.ipAddresslubbuyer.userAgentw trybieWIDGETskutkuje błędem400 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.
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
widgetUrljest niepuste — osadź widget w<iframe>, - gdy zwrócono
redirectUrl(widgetUrljestnull) — przekieruj kupującego pod adresredirectUrl.
- Jednorazowa płatność kartą (
2002): Osadzenie na stronie sklepu (iframe-flow) | Osadzenie w oknie modalnym (modal-flow) - Płatność cykliczna kartą (
2202): Osadzenie na stronie sklepu (iframe-flow) | Osadzenie w oknie modalnym (modal-flow)
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 autoryzacyjnegoauthorizationCodew treści żądania płatności zakończy się błędem400 Bad Request(BAD_REQUEST), - dla płatności kartą (
2002) oraz płatności cyklicznych kartą (2202) zcardFormBehaviour: "WIDGET"błąd nie wystąpi — żądanie zostanie automatycznie przełączone na tryb przekierowania (REDIRECT), a w odpowiedzi otrzymaszredirectUrl(widgetUrl: null,status: "NEW").