Przejdź do głównej zawartości

Zapis karty i subskrypcje

Paynow udostępnia dwa niezależne modele zapisu karty płatniczej w postaci bezpiecznego tokenu. Wybór odpowiedniego modelu zależy od tego, kto inicjuje kolejne płatności:

  • Tokenizacja kart – opcjonalna funkcja uruchamiana w ramach standardowej metody płatności kartą (paymentMethodId: 2002). Pozwala kupującemu posiadającemu konto w sklepie zapisać kartę podczas płatności na stronie Paynow, a przy kolejnych jednorazowych zakupach wybrać zapisaną kartę bezpośrednio w koszyku sklepu (model White Label) lub na stronie płatności Paynow.
  • Płatności cykliczne kartą (subskrypcje) – dedykowana metoda płatności (paymentMethodId: 2202) przeznaczona do abonamentów i subskrypcji. Pierwsza transakcja (CIT – Customer-Initiated Transaction), podczas której zakładana jest subskrypcja, wymaga aktywnej autoryzacji kupującego (3-D Secure), natomiast każde kolejne obciążenie (MIT – Merchant-Initiated Transaction) inicjuje automatycznie system sklepu – bez udziału płatnika.

Który wariant wybrać?​

Tokenizacja kartPłatności cykliczne i subskrypcje
ZastosowanieWygodne zakupy jednorazowe bez podawania danych kartyAutomatyczne rozliczenia abonamentów, członkostw i planów cyklicznych
Inicjator pierwszej płatnościKupujący na stronie płatności Paynow – opcjonalny zapis karty podczas płatności (CIT z 3-D Secure)Kupujący na stronie płatności Paynow lub w widgecie na stronie sklepu – zapis karty i utworzenie subskrypcji (CIT z 3-D Secure)
Inicjator kolejnych płatnościKupujący podczas zakupów (transakcja CIT)System sklepu zgodnie z harmonogramem (transakcja MIT)
3-D Secure przy kolejnych płatnościachZawsze wymaganeNiewymagane
Pozyskanie tokenu kartyPobierany przed płatnością wraz z listą metod płatnościPrzekazywany w powiadomieniu lub pobierany z API
Usuwanie karty / subskrypcjiUsunięcie tokenu karty przez API lub przez kupującego na stronie PaynowAnulowanie subskrypcji przez API
Rozdzielność tokenów

Tokeny kart utworzone w ramach Tokenizacji kart (2002) oraz Płatności cyklicznych (2202) są technicznie rozdzielne i nie mogą być używane zamiennie pomiędzy tymi metodami. Token zapisany podczas zakupów jednorazowych nie może posłużyć do obciążeń subskrypcyjnych MIT, a token subskrypcyjny nie jest zwracany na liście savedInstruments dla płatności jednorazowych.


Wybierz zakładkę odpowiadającą modelowi, który chcesz wdrożyć:

Włączenie tokenizacji kart​

Metoda paymentMethodId: 2002 (Karta płatnicza) służy standardowo do obsługi jednorazowych płatności kartowych. Udostępnienie w jej ramach funkcji zapisu kart wymaga aktywacji usługi po stronie Paynow – przed rozpoczęciem integracji skontaktuj się ze swoim doradcą w mBanku lub zespołem support@paynow.pl.

Zapoznaj się również z naszymi zaleceniami bezpieczeństwa, które pomogą zminimalizować ryzyko związane z przyjmowaniem płatności kartowych.

Karta płatnicza (2002) a Click to Pay (2005)

Zapis karty w systemie Paynow działa wyłącznie dla formularza kartowego metody Karta płatnicza (2002) i jest dostępny dla kupujących posiadających konto w sklepie (buyer.externalId). Funkcja ta nie dotyczy metody Click to Pay (2005), w której karty są zapisywane i zarządzane bezpośrednio po stronie operatora kartowego oraz organizacji płatniczych (poza systemem Paynow) i nie są zwracane przez API Paynow.

Integracja za pomocą wtyczki​

Jeśli korzystasz z gotowej wtyczki e-commerce Paynow, zaktualizuj ją minimum do poniższej wersji (rekomendujemy instalację najnowszej dostępnej wersji):

  • PrestaShop – wersja 1.7.1 lub wyższa,
  • WooCommerce – wersja 2.5.1 lub wyższa,
  • Magento – wersja 1.5.0 lub wyższa.

Możesz również zaktualizować wtyczkę Paynow do najnowszej wersji z poziomu panelu administracyjnego sklepu.

Zapis karty podczas płatności​

Podczas płatności na stronie Paynow (Paywall) kupujący może wybrać opcję zapisania karty na przyszłe zakupy. Paynow tokenizuje zapisaną kartę. Aby opcja zapisu była widoczna na formularzu kartowym, w żądaniu POST /v3/payments przekaż w obiekcie buyer:

  • externalId – unikalny, stały identyfikator konta kupującego w sklepie,
  • deviceFingerprint – odcisk urządzenia i przeglądarki kupującego.
curl --location --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 10000,
"externalId": "2aacccb4-a780-4ac4-ad7b-d80490219259",
"description": "Płatność za zamówienie",
"buyer": {
"externalId": "c0940962-706e-4e23-822a-97810744f1c5",
"deviceFingerprint": "d55f48e43d6384cc0add2229dc67e98f",
"email": "jan.kowalski@melements.pl"
}
}'

Wyliczanie odcisku urządzenia (deviceFingerprint)​

Przekazanie parametru buyer.deviceFingerprint pozwala wyświetlić kupującemu jego wcześniej zapisane karty na stronie Paynow. Ze względów bezpieczeństwa udostępnienie zapisanych kart na stronie płatności Paynow i opłacenie nimi transakcji jest możliwe wyłącznie na tym samym urządzeniu i w tej samej przeglądarce, z których karta została zapisana.

Aby wyliczyć wartość deviceFingerprint po stronie przeglądarki kupującego, wywołaj poniższy skrypt i przekaż uzyskany visitorId do systemu sklepu:

<script>
const fpPromise = import('https://static.paynow.pl/scripts/PyG5QjFDUI.min.js')
.then(FingerprintJS => FingerprintJS.load());

fpPromise
.then(fp => fp.get())
.then(result => {
const visitorId = result.visitorId;
console.log(visitorId);
});
</script>

Pobieranie zapisanych kart​

Listę kart zapisanych przez danego kupującego pobierzesz razem z dostępnymi metodami płatności, wysyłając żądanie GET /v3/payments/paymentmethods z parametrem externalBuyerId. Pamiętaj, aby uwzględnić ten parametr przy obliczaniu nagłówka podpisu (Signature):

curl --location --request GET 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods?externalBuyerId=7795474a-4f58-4a41-88b2-d5106b4cd718' \
--header 'Api-Key: {{apiKey}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Signature: {{signature}}'

Zapisane karty zostaną zwrócone w tablicy savedInstruments wewnątrz metody 2002:

[
{
"type": "CARD",
"paymentMethods": [
{
"id": 2002,
"name": "Karta płatnicza",
"description": "Płatność kartą",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/2002.png",
"status": "ENABLED",
"authorizationType": "REDIRECT",
"savedInstruments": [
{
"name": "xxxx xxxx xxxx 1234",
"expirationDate": "10/28",
"brand": "VISA",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/visa.svg",
"token": "7bf9d217-bab6-48af-80a8-882097875cd8",
"status": "ACTIVE"
},
{
"name": "xxxx xxxx xxxx 5678",
"expirationDate": "10/25",
"brand": "MASTERCARD",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/mastercard.svg",
"token": "fdfdeac9-fad3-4f2a-bee7-97fc003c4764",
"status": "EXPIRED_CARD"
}
]
}
]
}
]

Możliwe statusy zapisanych kart w polu savedInstruments[].status:

StatusOpis
ACTIVEAktywna karta, której kupujący może użyć do opłacenia zamówienia.
EXPIRED_CARDKarta, której data ważności upłynęła. Kupujący nie może nią zapłacić, ale zalecamy wyświetlanie wygasłych kart na koncie/w koszyku z opcją ich samodzielnego usunięcia.

Płatność zapisaną kartą​

Płatność zapisaną kartą może zostać zrealizowana w jednym z dwóch modeli:

Model 1: Wybór zapisanej karty na stronie płatności Paynow​

Jeśli nie przekazujesz predefiniowanego tokenu karty ze sklepu, prześlij w POST /v3/payments pola buyer.externalId oraz buyer.deviceFingerprint (analogicznie jak przy zapisie karty). Po przekierowaniu na stronę Paynow kupujący zobaczy swoje zapisane karty i wybierze jedną z nich lub poda dane nowej karty:

curl --location --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 45671,
"externalId": "433a1a19-885f-47c5-92ef-2ad9d338f674",
"description": "Płatność za zamówienie",
"buyer": {
"externalId": "4312f0ee-4366-4e53-a1b7-38dda437f7e1",
"deviceFingerprint": "d55f48e43d6384cc0add2229dc67e98f",
"email": "jan.kowalski@melements.pl"
}
}'

Model 2: Wybór zapisanej karty w koszyku sklepu (White Label)​

Kupujący może wybrać wcześniej zapisaną kartę bezpośrednio na stronie Twojego sklepu, z pominięciem strony wyboru metod płatności Paynow.

Obowiązek informacyjny RODO

W modelu White Label kupującemu należy wyświetlić na stronie sklepu aktualną klauzulę informacyjną RODO. Pobierz ją żądaniem GET /v3/payments/dataprocessing/notices:

curl --location --request GET 'https://api.sandbox.paynow.pl/v3/payments/dataprocessing/notices?locale=pl-PL' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}'

Po wybraniu przez kupującego konkretnej karty z listy savedInstruments, wyślij żądanie POST /v3/payments z paymentMethodId: 2002 oraz wybranym tokenem karty w polu paymentMethodData.card.tokenization.token (dla zachowania kompatybilności wstecznej obsługiwane jest również pole głównego poziomu paymentMethodToken):

curl --location --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 45671,
"externalId": "17c944cf-e2ac-4bd2-9192-05e01204ba1f",
"description": "Płatność za zamówienie",
"paymentMethodId": 2002,
"buyer": {
"externalId": "4312f0ee-4366-4e53-a1b7-38dda437f7e1",
"email": "jan.kowalski@melements.pl"
},
"paymentMethodData": {
"card": {
"tokenization": {
"token": "7bf9d217-bab6-48af-80a8-882097875cd8"
}
}
}
}'

W odpowiedzi otrzymasz redirectUrl, pod który należy przekierować kupującego w celu autoryzacji 3-D Secure:

{
"redirectUrl": "https://api.sandbox.paynow.pl/payment/initialize_whitelabel/CANL-R6J-XZ7-6RN?token=******",
"paymentId": "CANL-R6J-XZ7-6RN",
"status": "PENDING"
}

Usuwanie zapisanej karty​

Kupujący powinien mieć możliwość usunięcia zapisanej karty ze swojego konta w sklepie. W tym celu wyślij żądanie DELETE /v3/payments/paymentmethods/saved z parametrami externalBuyerId oraz token. Uwzględnij je w kolejności alfabetycznej przy obliczaniu nagłówka podpisu (Signature). Operacja jest nieodwracalna – token otrzymuje status DELETED i przestaje być zwracany na liście savedInstruments:

curl --location --request DELETE 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods/saved?externalBuyerId=4312f0ee-4366-4e53-a1b7-38dda437f7e1&token=7bf9d217-bab6-48af-80a8-882097875cd8' \
--header 'Api-Key: {{apiKey}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Signature: {{signature}}'