Tokenizacja kart

Na czym polega tokenizacja kart?

Tokenizacja kart od Paynow pozwala na zapis danych karty do postaci unikalnego tokenu. Można go następnie użyć do przeprocesowania kolejnej płatności kartą, bez konieczności podawania jej danych. Funkcjonalność jest dostępna dla tych kupujących, którzy posiadają konto w sklepie.

Zapisanie karty w formie tokena jest dostępne w procesie płatności po przekierowaniu na stronę Paynow, podczas gdy płatność zapisaną kartą może być dokonana w dwóch modelach, w zależności od sposobu integracji sklepu lub ustawień wtyczki:

• z poziomu sklepu (tzw. White Label) - w tym scenariuszu kupujący może wybrać zapisaną kartę z poziomu checkoutu sklepu,
• z poziomu strony Paynow.

Włączenie tokenizacji kart

Udostępnienie tokenizacji kart wymaga jej konfiguracji po stronie paynow, dlatego przed integracją skontaktuj się ze swoim doradcą w mBank.

Prosimy również o zapoznanie się z naszymi zaleceniami bezpieczeństwa. Pozwoli to na zminimalizowanie ryzyka związanego z przyjmowaniem płatności kartowych.

Integracja za pomocą wtyczki

Aby płatności zapisaną kartą były dostępne w Twoim sklepie, zaktualizuj wtyczkę paynow minimum do podanej poniżej wersji. Rekomendujemy instalację najnowszej dostępnej wersji wtyczki

• 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 Twojego sklepu.

Opis procesu

Zapis karty

Zapis danych karty odbywa się w procesie płatności, na stronie paynow. Aby opcja zapisu karty była dostępna, w żądaniu inicjującym płatność należy przesłać następującą informację o kupującym w polu buyer:

externalId - unikalny identyfikator kupującego, deviceFingerprint - fingerprint urządzenia kupującego,

Przykład:

curl --location '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"
  }
}'

Obliczanie fingerprint urządzenia

Przesłanie do paynow fingerprintu urządzenia pozwala na wyświetlenie kupującemu zapisanych wcześniej kart na stronie paynow. Udostępnienie kart i płatność zapisaną kartą jest możliwa tylko wtedy, gdy jej finalizacja odbywa się na tym samym urządzeniu i z tej samej przeglądarki, na jakich została zainicjowana. W tym celu należy wywołać skrypt liczący fingerprint urządzenia i przesłać go do paynow w odpowiednim polu.

Przykład skryptu do obliczenia fingerprint:

<script>
    // Initialize the agent at application startup.
    const fpPromise = import('https://static.paynow.pl/scripts/PyG5QjFDUI.min.js')
    .then(FingerprintJS => FingerprintJS.load())

    // Get the visitor identifier when you need it.
    fpPromise
    .then(fp => fp.get())
    .then(result => {
    // This is the visitor identifier:
    const visitorId = result.visitorId
    console.log(visitorId)
})
</script>

Pobieranie zapisanych kart

Zapisane przez kupującego karty można pobrać wraz z metodami płatności. W tym celu należy przesłać externalBuyerId jako parametr żądania:

Przykład:

curl
--location '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}}'

Odpowiedź:

[
  {
    "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/25",
            "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 1234",
            "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:

Kod	Opis
ACTIVE	Aktywna karta, której można użyć do opłacenia transakcji,
EXPIRED_CARD	Karta, której ważność wygasła. Kupujący nie ma możliwości opłacić zamówienia wygasłą kartą, może ją usunąć oraz podać dane nowej karty. Zalecamy wyświetlenie wygasłych kart kupującemu, aby mógł samodzielnie zarządzać swoimi zapisanymi kartami.

Płatność zapisaną kartą

Jeśli kupujący posiada zapisane karty, należy uzupełnić poniższe informacje w polu buyer analogicznie jak przy zapisie karty. Zapisane karty będą widoczne na stronie Paynow.

externalId - unikalny identyfikator kupującego, deviceFingerprint - fingerprint urządzenia kupującego

Przykład:

curl --location '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"
  }
}'

Płatność zapisaną kartą w modelu White Label

Kupujący może wybrać zapisaną wcześniej kartę z poziomu checkoutu sklepu, bez konieczności przechodzenia na paywall Paynow.

Ważne

Płatność zapisaną kartą w modelu white label wymaga przedstawienia klientowi klauzuli RODO na stronie sklepu. Klauzule są dostępne do pobrania w języku polskim i angielskim poprzez dedykowany endpoint:

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

Aby umożliwić kupującemu płatność w modelu whie label, należy pobrać zapisane karty i wyświetlić je kupującemu na stronie sklepu. Po wyborze karty, należy wysłać do paynow jej token wraz z predefiniowaną metodą płatności.

Przykład:

curl --location '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,
  "paymentMethodToken": "670ca483-75cc-4828-a743-2b27dbbe8f33",
  "buyer": {
    "externalId":"4312f0ee-4366-4e53-a1b7-38dda437f7e1",
    "email": "jan.kowalski@melements.pl"
  }
}'

W odpowiedzi otrzymamy redirectUrl, na który należy przekierować kupującego w celu sfinalizowania transakcji za pomocą 3-D Secure:

{
  "redirectUrl": "https://api.sandbox.paynow.pl/payment/initialize_whitelabel/CANL-R6J-XZ7-6RN?token=eyJraWQiOiJhMDAyNjJjYS02NTU3LTRjOTktOGU0NC1kMTFlMTAxYjhhNTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJDQU5MLVI2Si1YWjctNlJOIiwiYXVkIjoicGF5d2FsbC5zYW5kYm94LnBheW5vdy5wbCIsImlzcyI6InNhbmRib3gucGF5bm93LnBsIiwiZXhwIjoxNzAyNjc2MTg3LCJpYXQiOjE3MDE3Njg5ODh9.DSaSg8V_f-hFagwp8q-8DF932M8yiBWXKtfpn0AAtp4",
  "paymentId": "CANL-R6J-XZ7-6RN",
  "status": "PENDING"
}

Usuwanie karty

Kupujący powinien mieć możliwość usunięcia uprzednio zapisanej karty. W tym celu należy wywołać poniższy endpoint, przesyłając do Paynow parametry:

• externalId - identyfikator kupującego,
• token - identyfikator zapisanej karty.

Przykład:

curl --location --request
DELETE 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods/saved?externalBuyerId=4312f0ee-4366-4e53-a1b7-38dda437f7e1&token=51f212a2-9fb7-4cde-8f79-fbbd04212e88' \
--header 'Api-Key: {{apiKey}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--header 'Signature: {{signature}}'