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 tokenization | Recurring payments and subscriptions | |
|---|---|---|
| Use case | Convenient one-time purchases without entering card details | Automated billing for subscriptions, memberships, and recurring plans |
| First payment initiator | The 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 initiator | The buyer during checkout (CIT transaction) | The Merchant from its backend on schedule (MIT transaction) |
| 3-D Secure on subsequent payments | Always required | Not required |
| Obtaining the card token | Retrieved before payment with the payment methods list | Delivered in a notification or fetched via API |
| Deleting card / subscription | Deleting the card token via the API or by the buyer on the Paynow page | Cancelling the subscription via API |
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:
- Card tokenization
- Recurring payments and subscriptions
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.
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.1or higher, - WooCommerce – version
2.5.1or higher, - Magento – version
1.5.0or 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:
| Status | Description |
|---|---|
ACTIVE | Active card that can be used to pay for an order. |
EXPIRED_CARD | Expired 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.
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}}'
Enabling recurring payments
Enabling recurring card payments (paymentMethodId: 2202) requires configuration on the Paynow side. Before starting integration:
- Activate the service – contact the Paynow team at support@paynow.pl to enable recurring card payments for your shop.
- Configure the notification URL in the Merchant Panel – in
Settings > Shops and poses, fill in theNotifications URL for other eventsfield in your shop configuration, where Paynow will send notifications about subscription creation and status updates for subscriptions and saved cards (separate fromTransactions notification URL, which handles payment status notifications).
Core concepts and process flow
- CIT (Customer-Initiated Transaction) – the initial transaction initiated with the buyer's participation. The buyer enters their card details and authorizes the payment (3-D Secure), consenting to future recurring charges.
- MIT (Merchant-Initiated Transaction) – every subsequent transaction initiated by the Merchant without the buyer's participation, executed using the created subscription and saved card token.
- Card token (
token) – unique identifier of the saved payment card generated after a successful CIT payment. - Subscription (
subscriptionId) – association between a saved card token and a buyer (buyer.externalId) that authorizes the Merchant to initiate MIT charges.
Before initiating the first payment (CIT), you must on your shop's side:
- present the recurring payments / subscription terms and conditions to the buyer,
- obtain the buyer's explicit consent to save the card and charge the buyer's account on a recurring basis (specifying the amount or how it is calculated, as well as the billing frequency).
Step-by-step subscription lifecycle
- Buyer consent in the shop – the buyer selects a subscription plan, accepts the recurring payment terms, and proceeds to checkout.
- First payment initiation (CIT) – the Merchant calls
POST /v3/paymentswithpaymentMethodId: 2202and action"REGISTER_TOKEN_AND_CHARGE", passing a permanent buyer identifier inbuyer.externalId. - Card authorization by the buyer – the buyer enters card details on the Paynow paywall (
redirectUrl) or in the embedded widget (widgetUrl) and completes 3-D Secure authentication. - Payment confirmation and subscription creation – once authorized, Paynow sends:
- a standard payment status notification (
CONFIRMED), - a
card.subscription.createdwebhook toNotifications URL for other eventscontainingsubscription.id,ACTIVEstatus, andsavedInstrument.token(if the webhook was missed, fetch these details viaGET /v3/payments/paymentmethods/recurring/card/detailsusingoperationIdset to thepaymentIdof the initial CIT payment).
- a standard payment status notification (
- Saving data on the Merchant's side – the Merchant stores
subscription.idandsavedInstrument.tokenassociated withbuyer.externalId. - Subsequent charges (MIT) – on future billing dates, the Merchant's backend calls
POST /v3/paymentswithpaymentMethodId: 2202, action"NEXT_CHARGE", the savedtoken, andsubscriptionId. - Lifecycle management – status changes are delivered via
card.subscription.status.update. When the buyer cancels, the Merchant deletes the subscription viaDELETE .../subscription/{subscriptionId}.
Retrieving recurring payment methods
By default, GET /v3/payments/paymentmethods returns only one-time payment methods. To retrieve the CARD_RECURRING method (id: 2202), pass the chargeType query parameter:
recurring– returns only recurring payment methods,oneTime,recurring– returns both one-time and recurring payment methods in a single response,oneTime(default when omitted) – returns only one-time payment methods.
Passing an unsupported chargeType value returns a 400 Bad Request validation error.
Remember to include chargeType in parameters when calculating the Signature header.
curl --location --request GET 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods?chargeType=recurring' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}'
Response (200 OK):
[
{
"type": "CARD_RECURRING",
"paymentMethods": [
{
"id": 2202,
"name": "Karta płatnicza",
"description": "Płatność cykliczna kartą",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/2202.png",
"status": "ENABLED",
"authorizationType": "REDIRECT"
}
]
}
]
First payment (CIT – card and subscription registration)
The first payment charges the initial billing period, registers the card token, and creates a new subscription. For request signing rules, see Signature header and Make a payment.
CIT-specific required fields
paymentMethodId– must be set to2202.buyer.email– buyer's email address.buyer.firstNameandbuyer.lastName– buyer's first and last name.buyer.externalId– unique, immutable buyer identifier in the shop. The same identifier will be needed for subsequent MIT charges and subscription management.buyer.ipAddressandbuyer.userAgent– buyer's IP address and browserUser-Agent.buyer.address.billingandbuyer.address.shipping– buyer's billing and shipping addresses.paymentMethodData.card.tokenization.recurring.action–"REGISTER_TOKEN_AND_CHARGE".paymentMethodData.card.cardFormBehaviour– card form presentation mode, defining whether the card form is displayed on the Paynow payment page or in an<iframe>on the shop page.
orderItems field and validityTime limit- For
paymentMethodId: 2202, theorderItemsarray is optional, but we recommend including it in CIT and MIT requests because it facilitates order verification and transaction handling. If the array is non-empty, each item must includename,category,quantity(>= 1),type, andfrequency. Values fortypeandfrequencymust be uppercase enum values, e.g.DIGITAL_SERVICEandMONTHLY. - Optional
validityTimefor2202accepts values from60to7200seconds (default7200s). Higher values return400 Bad Request.
Option 1: Redirect to the Paynow payment page
curl --location --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
--header 'Content-Type: application/json' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--data-raw '{
"amount": 4900,
"currency": "PLN",
"externalId": "order-cit-001",
"description": "Monthly subscription - PRO plan",
"continueUrl": "https://yourshop.com/payment/return",
"paymentMethodId": 2202,
"buyer": {
"email": "jan.kowalski@melements.pl",
"firstName": "Jan",
"lastName": "Kowalski",
"locale": "pl-PL",
"externalId": "9328",
"ipAddress": "192.0.2.10",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
"address": {
"billing": {
"street": "ul. Przykładowa",
"houseNumber": "10",
"apartmentNumber": "4",
"zipcode": "00-001",
"city": "Warszawa",
"country": "PL"
},
"shipping": {
"street": "ul. Przykładowa",
"houseNumber": "10",
"apartmentNumber": "4",
"zipcode": "00-001",
"city": "Warszawa",
"country": "PL"
}
}
},
"orderItems": [
{
"name": "Monthly subscription - PRO plan",
"category": "Subscription",
"quantity": 1,
"price": 4900,
"type": "DIGITAL_SERVICE",
"frequency": "MONTHLY"
}
],
"paymentMethodData": {
"card": {
"cardFormBehaviour": "REDIRECT",
"tokenization": {
"recurring": {
"action": "REGISTER_TOKEN_AND_CHARGE"
}
}
}
}
}'
Response (201 Created) – redirect the buyer to redirectUrl:
{
"redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=******",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "NEW"
}
Option 2: Embedding the widget on the shop page
The initial subscription payment (CIT, paymentMethodId: 2202) can use WIDGET mode.
For the CIT request, set paymentMethodData.card.cardFormBehaviour to "WIDGET" and include the required continueUrl, buyer.ipAddress, and buyer.userAgent fields. In the White Label model, display the current GDPR notice to the buyer; see GDPR notice obligation and service activation for details.
All other CIT fields are the same as in the REDIRECT option. When Card White Label is enabled for the point of sale (POS), the 201 Created response includes widgetUrl:
{
"redirectUrl": null,
"widgetUrl": "<widget-url>",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "PENDING"
}
For instructions on embedding widgetUrl in an <iframe>, handling the redirect to continueUrl, and the fallback to REDIRECT, as well as Sandbox examples, see Card payments and recurring card payments in the White Label model.
Subsequent payments (MIT – recurring charges)
Initiate every subsequent charge under an active subscription via POST /v3/payments, passing the saved card token and subscriptionId with action "NEXT_CHARGE".
Do not include cardFormBehaviour – the transaction runs in the background without the buyer's involvement.
MIT-specific required fields
paymentMethodId–2202.buyer.email– the buyer's email address.buyer.externalId– must match the value used for the initial CIT payment that created the subscription.paymentMethodData.card.tokenization.token– the saved card token received after the CIT payment and associated with this subscription.paymentMethodData.card.tokenization.recurring.action–"NEXT_CHARGE".paymentMethodData.card.tokenization.recurring.subscriptionId– the identifier of the active subscription created after the CIT payment.
curl --location --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
--header 'Content-Type: application/json' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}' \
--data-raw '{
"amount": 4900,
"currency": "PLN",
"externalId": "order-mit-002",
"description": "Monthly subscription - PRO plan (month 2)",
"paymentMethodId": 2202,
"buyer": {
"email": "jan.kowalski@melements.pl",
"externalId": "9328"
},
"orderItems": [
{
"name": "Monthly subscription - PRO plan (month 2)",
"category": "Subscription",
"quantity": 1,
"price": 4900,
"type": "DIGITAL_SERVICE",
"frequency": "MONTHLY"
}
],
"paymentMethodData": {
"card": {
"tokenization": {
"token": "6a70bc18-1b93-4973-bbee-061eafcf4b6a",
"recurring": {
"action": "NEXT_CHARGE",
"subscriptionId": "e4d1c2e2-9e5a-4d3a-8b9f-1a2b3c4d5e6f"
}
}
}
}
}'
Response (201 Created):
{
"redirectUrl": null,
"paymentId": "MITP-9A2-11C-XYZ",
"status": "PENDING"
}
The final MIT payment status is delivered asynchronously via a standard payment status notification or can be checked via GET /v3/payments/{paymentId}/status.
Subscription and card notifications
Subscription and card lifecycle events are sent as HTTP POST requests to Notifications URL for other events. Each webhook is signed with the Signature header (HMAC-SHA256 of body using Signature-Key), and your server should respond with 200 OK or 202 Accepted (retry schedule: 1 min, 2 min, 4 min, 15 min, 30 min, 1 h, 2 h, 4 h, 8 h).
Subscription created
The card.subscription.created notification is sent after a successful initial payment (CIT) once the card is saved and the subscription is ready for MIT charges:
{
"id": "evt_f1a2b3c4-d5e6-5789-8012-3456789abcde",
"object": "event",
"type": "card.subscription.created",
"data": {
"subscription": {
"id": "e4d1c2e2-9e5a-4d3a-8b9f-1a2b3c4d5e6f",
"status": "ACTIVE",
"initialOperation": {
"type": "PAYMENT",
"id": "NOLV-8F9-08K-WGD",
"externalId": "order-cit-001"
},
"externalBuyerId": "9328",
"action": "REGISTER_TOKEN_AND_CHARGE",
"savedInstrument": {
"token": "6a70bc18-1b93-4973-bbee-061eafcf4b6a",
"status": "ACTIVE",
"name": "xxxx xxxx xxxx 1234",
"expirationDate": "08/29",
"brand": "VISA",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/visa.svg"
}
}
},
"createdAt": "2026-07-08T12:15:30Z"
}
data.subscription fields
| Field | Description |
|---|---|
id | Unique Paynow subscription identifier (subscriptionId), required for subsequent MIT charges and cancellation. |
status | Subscription status. Possible values: ACTIVE, SUSPENDED, DELETED. |
initialOperation.type | Type of the initial operation. Possible values: PAYMENT. |
initialOperation.id | Identifier of the initial CIT payment. |
initialOperation.externalId | Merchant's order identifier passed in the initial CIT payment. |
externalBuyerId | Buyer's unique shop identifier passed in the initial CIT payment. |
action | In card.subscription.created: REGISTER_TOKEN_AND_CHARGE; in card.subscription.status.update: UPDATE_STATUS or DELETE. |
savedInstrument.token | Saved card token required for subsequent MIT charges. |
savedInstrument.status | Saved card token status. Possible values: ACTIVE, SUSPENDED, EXPIRED_CARD, EXPIRED_TOKEN, DELETED. |
savedInstrument.name | Masked card number (for example, xxxx xxxx xxxx 1234). |
savedInstrument.expirationDate | Card expiration date in MM/YY format. |
savedInstrument.brand | Card brand (for example, VISA or MASTERCARD). |
savedInstrument.image | URL of the card brand logo. |
Subscription and card status update
The card.subscription.status.update notification is sent whenever an existing subscription changes status:
{
"id": "evt_a9b8c7d6-e5f4-5321-9876-543210fedcba",
"object": "event",
"type": "card.subscription.status.update",
"data": {
"subscription": {
"id": "e4d1c2e2-9e5a-4d3a-8b9f-1a2b3c4d5e6f",
"status": "SUSPENDED",
"initialOperation": {
"type": "PAYMENT",
"id": "NOLV-8F9-08K-WGD",
"externalId": "order-cit-001"
},
"externalBuyerId": "9328",
"action": "UPDATE_STATUS",
"savedInstrument": {
"token": "6a70bc18-1b93-4973-bbee-061eafcf4b6a",
"status": "ACTIVE"
}
}
},
"createdAt": "2026-09-14T09:40:10Z"
}
Retrieving details and cancelling a subscription
Retrieving subscription and card details
GET /v3/payments/paymentmethods/recurring/card/details retrieves subscription and card details once the CIT payment has reached CONFIRMED status – either as a fallback using operationId (the CIT paymentId if the webhook was missed) or by subscriptionId:
| Parameter | Requirement | Description |
|---|---|---|
externalBuyerId | Required | Unique buyer identifier (buyer.externalId). |
operationId | Required if subscriptionId is not provided | Identifier of the initial CIT payment (paymentId). |
subscriptionId | Required if operationId is not provided | Subscription identifier in Paynow. |
Query parameters included in the request must be sorted alphabetically when calculating the Signature header.
curl --location --request GET 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods/recurring/card/details?externalBuyerId=9328&operationId=NOLV-8F9-08K-WGD' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}'
Example response (200 OK):
{
"subscription": {
"id": "e4d1c2e2-9e5a-4d3a-8b9f-1a2b3c4d5e6f",
"status": "ACTIVE",
"initialOperation": {
"type": "PAYMENT",
"id": "NOLV-8F9-08K-WGD",
"externalId": "order-cit-001"
},
"externalBuyerId": "9328",
"action": "REGISTER_TOKEN_AND_CHARGE",
"savedInstrument": {
"token": "6a70bc18-1b93-4973-bbee-061eafcf4b6a",
"status": "ACTIVE",
"name": "xxxx xxxx xxxx 1234",
"expirationDate": "08/29",
"brand": "VISA",
"image": "https://static.sandbox.paynow.pl/payment-method-icons/visa.svg"
}
}
}
Response codes:
200 OK– subscription and saved card details were returned.400 Bad Request(VALIDATION_ERROR) –externalBuyerIdis missing, or neithersubscriptionIdnoroperationIdwas provided.400 Bad Request(PAYMENT_METHOD_NOT_AVAILABLE) – recurring card payments are not enabled for this point of sale.401 Unauthorized/403 Forbidden– authentication failed or theSignatureheader is invalid.404 Not Found(NOT_FOUND) – no subscription or saved card token was found for the parameters; for example, the CIT payment has not yet reachedCONFIRMEDand the subscription is stillNEW.
Cancelling a subscription
When a buyer cancels their subscription, delete it by calling DELETE /v3/payments/paymentmethods/recurring/card/subscription/{subscriptionId} with the externalBuyerId query parameter:
Remember to include the externalBuyerId query parameter (excluding the subscriptionId path parameter) when calculating the Signature header.
curl --location --request DELETE 'https://api.sandbox.paynow.pl/v3/payments/paymentmethods/recurring/card/subscription/e4d1c2e2-9e5a-4d3a-8b9f-1a2b3c4d5e6f?externalBuyerId=9328' \
--header 'Api-Key: {{apiKey}}' \
--header 'Signature: {{signature}}' \
--header 'Idempotency-Key: {{idempotencyKey}}'
Response codes:
200 OK– the subscription was deleted (its status changed toDELETED); ifNotifications URL for other eventsis configured, Paynow sends acard.subscription.status.updatenotification withaction: "DELETE".400 Bad Request(PAYMENT_METHOD_NOT_AVAILABLE) – recurring card payments are not enabled for this point of sale.401 Unauthorized/403 Forbidden– authentication failed or theSignatureheader is invalid.404 Not Found(NOT_FOUND) – the subscription does not exist, does not belong to the specifiedexternalBuyerId, or was already deleted.
Deleting a subscription (DELETED) is irreversible. Resuming the service requires a new initial payment (CIT), which the buyer must authorize using 3-D Secure.
Statuses and error codes
Subscription statuses
| Status | Description and recommended Merchant action |
|---|---|
NEW | Initial CIT payment is still being processed – MIT charges cannot be initiated yet. |
ACTIVE | Subscription is active – you can initiate recurring charges (MIT). |
SUSPENDED | Subscription is temporarily suspended – pause MIT attempts until ACTIVE status is restored. |
DELETED | Subscription is permanently terminated – further MIT charges are not possible (new CIT required). |
Saved card statuses
| Status | Description |
|---|---|
ACTIVE | Card token is active and ready for MIT charges. |
SUSPENDED | Card token is temporarily suspended by the card network or issuing bank. |
EXPIRED_CARD | Card's expirationDate has passed – a new CIT payment is required (creates a new subscription). |
EXPIRED_TOKEN | Card token expired on the provider or card network side – a new CIT payment is required (creates a new subscription). |
DELETED | Card token has been permanently deleted. |
Error codes specific to recurring payments
| HTTP Status | errorType | Cause and handling |
|---|---|---|
400 | INVALID_SUBSCRIPTION_STATUS | Attempted to initiate MIT (NEXT_CHARGE) for a subscription whose status is not ACTIVE (for example, SUSPENDED or DELETED). Check the status with GET /v3/payments/paymentmethods/recurring/card/details. |
400 | INVALID_PAYMENT_TOKEN_STATUS | Attempted to initiate MIT with a card token whose status is not ACTIVE (for example, EXPIRED_CARD, EXPIRED_TOKEN, SUSPENDED, or DELETED). If the token is expired or deleted, a new CIT payment is required (creates a new subscription). |
400 | INCONSISTENT_SUBSCRIPTION_DATA | The token, subscriptionId, and buyer.externalId in the MIT request do not belong to the same subscription. Use the identifiers returned for that buyer when the subscription was created. |
400 | PAYMENT_METHOD_NOT_AVAILABLE | Recurring card payments (2202) are not enabled for this point of sale (POS). |
404 | NOT_FOUND | No subscription or saved card token was found for the provided parameters in GET .../details or DELETE .../subscription/{subscriptionId}. |