Skip to main content

Saved cards and subscriptions

Paynow offers two independent models for saving a payment card as a secure token. Choosing the right model depends on who initiates subsequent payments:

  • Card tokenization – an optional feature enabled within the standard card payment method (paymentMethodId: 2002). It allows a buyer with an account in your shop to save their card during checkout on the Paynow payment page, and on subsequent one-time purchases select the saved card directly at checkout (White Label) or on the Paynow paywall without re-entering card details.
  • Recurring card payments (subscriptions) – a dedicated payment method (paymentMethodId: 2202) designed for memberships and subscriptions. The initial transaction (CIT – Customer-Initiated Transaction), during which the subscription is created, requires active authorization from the buyer (3-D Secure), while each subsequent charge (MIT – Merchant-Initiated Transaction) is initiated automatically by the store's system, without the payer's involvement.

Which model should you choose?​

Card tokenizationRecurring payments and subscriptions
Use caseConvenient one-time purchases without entering card detailsAutomated billing for subscriptions, memberships, and recurring plans
First payment initiatorThe buyer on the Paynow payment page – optional card saving during checkout (CIT with 3-D Secure)The buyer on the Paynow payment page or in a widget on the shop page – card saving and subscription creation (CIT with 3-D Secure)
Subsequent payments initiatorThe buyer during checkout (CIT transaction)The Merchant from its backend on schedule (MIT transaction)
3-D Secure on subsequent paymentsAlways requiredNot required
Obtaining the card tokenRetrieved before payment with the payment methods listDelivered in a notification or fetched via API
Deleting card / subscriptionDeleting the card token via the API or by the buyer on the Paynow pageCancelling the subscription via API
Token separation

Card tokens created under Card tokenization (2002) and Recurring card payments (2202) are technically separate and cannot be used interchangeably across these methods. A token saved during one-time purchases cannot be used for MIT subscription charges, and a subscription token is not returned in savedInstruments for one-time payments.


Select the tab matching the model you want to integrate:

Enabling card tokenization​

Payment method paymentMethodId: 2002 (Payment card) handles standard one-time card payments. Enabling card saving within this method requires configuration on the Paynow side – contact your mBank advisor or support@paynow.pl before starting integration.

Please also review our security recommendations to minimize risks associated with accepting card payments.

Payment card (2002) vs Click to Pay (2005)

Saving a card in Paynow applies exclusively to the Payment card (2002) card form and is available to buyers who hold an account in your shop (buyer.externalId). It does not apply to Click to Pay (2005), where cards are stored and managed directly on the card operator and payment scheme side (outside Paynow) and are not returned by the Paynow API.

Integration via plugin​

If you use an official Paynow e-commerce plugin, update it at least to the version listed below (we recommend installing the latest available release):

  • PrestaShop – version 1.7.1 or higher,
  • WooCommerce – version 2.5.1 or higher,
  • Magento – version 1.5.0 or higher.

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

Saving a card during payment​

During payment on the Paynow payment page (Paywall), the buyer can choose to save their card for future purchases. Paynow tokenizes the saved card. To display the save-card option on the card form, pass the following fields inside the buyer object in your POST /v3/payments request:

  • externalId – unique, permanent identifier of the buyer's account in your shop,
  • deviceFingerprint – fingerprint of the buyer's device and browser.
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": "Order payment",
"buyer": {
"externalId": "c0940962-706e-4e23-822a-97810744f1c5",
"deviceFingerprint": "d55f48e43d6384cc0add2229dc67e98f",
"email": "jan.kowalski@melements.pl"
}
}'

Computing deviceFingerprint​

Passing buyer.deviceFingerprint allows Paynow to display previously saved cards on the Paynow payment page. For security reasons, displaying saved cards on the Paywall and paying with them is only possible on the same device and browser from which the card was originally saved.

To compute deviceFingerprint in the buyer's browser, load the script below and pass the resulting visitorId to your backend:

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

Retrieving saved cards​

You can retrieve a buyer's saved cards together with available payment methods via GET /v3/payments/paymentmethods by passing the externalBuyerId query parameter (remember to include it when calculating the Signature header):

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

Saved cards are returned in the savedInstruments array under payment method 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"
}
]
}
]
}
]

Possible statuses in savedInstruments[].status:

StatusDescription
ACTIVEActive card that can be used to pay for an order.
EXPIRED_CARDExpired card. The buyer cannot pay with it, but we recommend displaying expired cards in the buyer's account/checkout so they can remove them.

Paying with a saved card​

Payments with a saved card can be completed in one of two models:

Model 1: Selecting a saved card on the Paynow page (Paywall)​

If you do not pass a preselected card token from your shop, include buyer.externalId and buyer.deviceFingerprint in POST /v3/payments (just as when saving the card). After redirecting to the Paynow page, the buyer will see their saved cards and can choose one or enter a new card:

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": "Order payment",
"buyer": {
"externalId": "4312f0ee-4366-4e53-a1b7-38dda437f7e1",
"deviceFingerprint": "d55f48e43d6384cc0add2229dc67e98f",
"email": "jan.kowalski@melements.pl"
}
}'

Model 2: Selecting a saved card in the shop checkout (White Label)​

The buyer can select a previously saved card directly in your shop's checkout without visiting the Paynow payment method selection page.

GDPR information notice

Paying with a saved card in the White Label model requires presenting the current GDPR data processing notice to the buyer on your shop page, retrieved via GET /v3/payments/dataprocessing/notices:

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

Once the buyer selects a card from savedInstruments, call POST /v3/payments with paymentMethodId: 2002 and pass the selected card token in paymentMethodData.card.tokenization.token (for backward compatibility, top-level paymentMethodToken is also supported):

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": "Order payment",
"paymentMethodId": 2002,
"buyer": {
"externalId": "4312f0ee-4366-4e53-a1b7-38dda437f7e1",
"email": "jan.kowalski@melements.pl"
},
"paymentMethodData": {
"card": {
"tokenization": {
"token": "7bf9d217-bab6-48af-80a8-882097875cd8"
}
}
}
}'

In response, you will receive a redirectUrl to which the buyer should be redirected to complete 3-D Secure authentication:

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

Deleting a saved card​

Allow buyers to delete previously saved cards from their shop account by calling DELETE /v3/payments/paymentmethods/saved with query parameters externalBuyerId and token (sorted alphabetically when calculating the Signature header). This operation is irreversible – the token transitions to DELETED status and is no longer returned in 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}}'