Card Tokenization

What is card tokenization?

Card tokenization from Paynow allows you to save your card data into a unique token. It can then be used to process the next card payment without having to enter the card data. The functionality is available to those customers who have an account with the shop.

The saving of the card to the form of a token is available in the payment process after redirecting to the Paynow page, while the payment with the saved card can be made in two models, depending on the way the shop is integrated or the settings in the plugin:

from the shop level (called White Label) - in this scenario, the buyer can select the saved card from the shop checkout, from the Paynow page.

Enable card tokenization

Enabling card tokenization requires it to be configured on the Paynow side, so please contact your advisor at mBank before integration.

Please also read our security recommendations. This will help minimize the risks associated with accepting card payments.

Integration via plug-in

In order to make saved card payments available in your shop, update the Paynow plugin minimum to the version listed below. We recommend installing the latest available version of the plugin:

• Prestashop from version 1.7.1 or higher
• Woocommerce - from version 2.5.1 or higher
• Magento - from version 1.5.0 or higher

You can also update the Paynow plugin to the latest version from the administration panel of your shop.

Description of the process

Saving the card

The card details are saved during the payment process, on the Paynow website. To save the card, the following buyer information must be sent in the buyer field in the payment initiating request:

externalId - unique buyer identifier, deviceFingerprint - fingerprint of buyer’s device,

Example:

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

Device Fingerprint computing

Sending the device's fingerprint to Paynow allows the buyer to display the previously saved cards on the Paynow website. Sharing cards and payment with a saved card is possible only if its finalization is done on the same device and from the same browser on which it was initiated. To do this, you need to call the device fingerprint computing script and send it to Paynow in the relevant field.

An example of a fingerprint computing script:

<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>

Retrieving saved cards

The cards saved by the buyer can be retrieved together with the payment methods. To do so, send externalBuyerId as a query parameter:

Example:

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

Response:

[
  {
    "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"
          }
        ]
      }
    ]
  }
]

Possible statuses of saved cards:

Code	Description
ACTIVE	an active card that can be used to pay for a transaction
EXPIRED_CARD	The buyer is not able to pay for the order with an expired card, but can delete it and enter the details of a new card. We recommend displaying expired cards to the buyer so that they can manage their saved cards themselves.

Payment with saved card

If the buyer has saved cards, the following information must be completed in the buyer field, just as when the card is saved. Saved cards will be visible on the Paynow paywall page.

externalId - unique buyer identifier, deviceFingerprint - fingerprint of buyer’s device.

Example:

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

White Label payment with saved card

The buyer can select a pre-saved card from the shop checkout, without having to go to the Paynow paywall.

Important

Payment with a pre-saved card in the White Label model requires the customer to present the GDPR clause on the store page. The clauses are available for download in Polish and English via a dedicated 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}}'

For enabling the buyer to pay using the White Label method, download the saved cards and display them to the buyer on the store page. Once the card has been selected, its token should be sent to Paynow along with the predefined payment method.

Example:

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

In response, we will receive a redirectUrl to which the buyer should be redirected to complete the transaction using 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"
}

Deleting the card

The buyer should be able to delete a previously saved card. To do this, call up the endpoint below, sending the parameters to paynow: externalId - unique buyer identifier, token - saved card identifier.

Example:

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