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 kart | Płatności cykliczne i subskrypcje | |
|---|---|---|
| Zastosowanie | Wygodne zakupy jednorazowe bez podawania danych karty | Automatyczne rozliczenia abonamentów, członkostw i planów cyklicznych |
| Inicjator pierwszej płatności | Kupują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ści | Kupujący podczas zakupów (transakcja CIT) | System sklepu zgodnie z harmonogramem (transakcja MIT) |
| 3-D Secure przy kolejnych płatnościach | Zawsze wymagane | Niewymagane |
| Pozyskanie tokenu karty | Pobierany przed płatnością wraz z listą metod płatności | Przekazywany w powiadomieniu lub pobierany z API |
| Usuwanie karty / subskrypcji | Usunięcie tokenu karty przez API lub przez kupującego na stronie Paynow | Anulowanie subskrypcji przez API |
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ć:
- Tokenizacja kart
- Płatności cykliczne i subskrypcje
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.
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.1lub wyższa, - WooCommerce – wersja
2.5.1lub wyższa, - Magento – wersja
1.5.0lub 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:
| Status | Opis |
|---|---|
ACTIVE | Aktywna karta, której kupujący może użyć do opłacenia zamówienia. |
EXPIRED_CARD | Karta, 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.
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}}'
Włączenie płatności cyklicznych
Udostępnienie płatności cyklicznych kartą (paymentMethodId: 2202) wymaga konfiguracji po stronie Paynow. Przed rozpoczęciem integracji:
- Aktywuj usługę – skontaktuj się z zespołem Paynow pod adresem support@paynow.pl, aby włączyć płatności cykliczne kartą dla Twojego sklepu.
- Skonfiguruj adres powiadomień w Panelu Paynow – w zakładce
Ustawienia > Sklepy i punkty płatnościuzupełnij w konfiguracji sklepu poleAdres powiadomień dot. innych zdarzeń, na który Paynow będzie wysyłać powiadomienia o utworzeniu subskrypcji oraz o zmianach statusu subskrypcji i zapisanej karty (jest to pole niezależne od polaAdres powiadomień dot. transakcji, służącego do powiadomień o statusach płatności).
Podstawowe pojęcia i przebieg procesu
- CIT (Customer-Initiated Transaction) – pierwsza transakcja inicjowana z udziałem kupującego. Kupujący podaje dane karty i autoryzuje płatność (3-D Secure), wyrażając zgodę na przyszłe obciążenia cykliczne.
- MIT (Merchant-Initiated Transaction) – każde kolejne obciążenie inicjowane przez system sklepu bez udziału kupującego, realizowane na podstawie utworzonej subskrypcji i zapisanego tokenu karty.
- Token karty (
token) – unikalny identyfikator zapisanej karty wygenerowany po udanej płatności CIT. - Subskrypcja (
subscriptionId) – powiązanie zapisanego tokenu karty z kupującym (buyer.externalId), z którego system sklepu korzysta przy kolejnych obciążeniach MIT.
Przed zainicjowaniem pierwszej płatności (CIT) musisz po stronie swojego sklepu:
- przedstawić kupującemu regulamin płatności cyklicznych / subskrypcji,
- odebrać od kupującego wyraźną zgodę na zapisanie karty oraz cykliczne obciążanie rachunku kupującego (z określeniem kwoty lub zasad jej wyliczania oraz częstotliwości obciążeń).
Cykl życia subskrypcji krok po kroku
- Zgoda kupującego w sklepie – kupujący wybiera plan subskrypcyjny, akceptuje regulamin płatności cyklicznych i przechodzi do płatności.
- Inicjacja pierwszej płatności (CIT) – system sklepu wywołuje
POST /v3/paymentszpaymentMethodId: 2202oraz akcją"REGISTER_TOKEN_AND_CHARGE", przekazując stały identyfikator kupującego wbuyer.externalId. - Autoryzacja karty przez kupującego – kupujący wprowadza dane karty na bramce Paynow (
redirectUrl) lub w osadzonym widgecie (widgetUrl) i autoryzuje transakcję 3-D Secure. - Potwierdzenie płatności i utworzenie subskrypcji – po pomyślnej autoryzacji Paynow wysyła:
- standardowe powiadomienie o statusie płatności (
CONFIRMED), - Paynow wysyła powiadomienie
card.subscription.createdna adres wskazany w poluAdres powiadomień dot. innych zdarzeń. Powiadomienie zawierasubscription.id, statusACTIVEorazsavedInstrument.token. Jeśli sklep nie otrzyma powiadomienia, te same dane można pobrać żądaniemGET /v3/payments/paymentmethods/recurring/card/detailsz parametremoperationIdustawionym na identyfikator (paymentId) początkowej płatności CIT.
- standardowe powiadomienie o statusie płatności (
- Zapisanie danych po stronie sklepu – sklep zapisuje
subscription.idorazsavedInstrument.tokeni wiąże je z kontem kupującego (buyer.externalId). - Kolejne obciążenia (MIT) – w kolejnych okresach rozliczeniowych system sklepu wywołuje
POST /v3/paymentszpaymentMethodId: 2202, akcją"NEXT_CHARGE", zapisanymtokenorazsubscriptionId. - Zarządzanie cyklem życia – Paynow przekazuje zmiany statusu subskrypcji i karty w powiadomieniu
card.subscription.status.update. Gdy kupujący zrezygnuje z usługi, sklep, wysyłając żądanieDELETE .../subscription/{subscriptionId}, usuwa subskrypcję.
Pobieranie metod płatności cyklicznych
Żądanie GET /v3/payments/paymentmethods domyślnie zwraca wyłącznie metody płatności jednorazowych. Aby na liście pojawiła się metoda typu CARD_RECURRING o identyfikatorze 2202, przekaż parametr chargeType:
recurring– zwraca wyłącznie metody płatności cyklicznych,oneTime,recurring– zwraca w jednej odpowiedzi zarówno metody jednorazowe, jak i cykliczne,oneTime(wartość domyślna, gdy parametr zostanie pominięty) – zwraca wyłącznie metody płatności jednorazowych.
Przekazanie nieobsługiwanej wartości chargeType skutkuje błędem walidacji 400 Bad Request.
Pamiętaj, aby uwzględnić parametr chargeType w sekcji parameters przy obliczaniu nagłówka podpisu (Signature).
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}}'
Odpowiedź (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"
}
]
}
]
Pierwsza płatność (CIT – rejestracja karty i subskrypcji)
Pierwsza płatność pobiera środki za pierwszy okres rozliczeniowy, rejestruje token karty oraz tworzy nową subskrypcję. Zasady podpisywania żądań opisano w sekcjach Nagłówek podpisu oraz Utwórz płatność.
Wymagane pola specyficzne dla CIT
paymentMethodId– musi przyjąć wartość2202.buyer.email– adres e-mail kupującego.buyer.firstNameorazbuyer.lastName– imię i nazwisko kupującego.buyer.externalId– unikalny, niezmienny identyfikator kupującego w sklepie. Ten sam identyfikator będzie potrzebny przy obciążeniach MIT i zarządzaniu subskrypcją.buyer.ipAddressorazbuyer.userAgent– adres IP oraz ciągUser-Agentprzeglądarki kupującego.buyer.address.billingorazbuyer.address.shipping– adres rozliczeniowy i adres dostawy kupującego.paymentMethodData.card.tokenization.recurring.action–"REGISTER_TOKEN_AND_CHARGE".paymentMethodData.card.cardFormBehaviour– sposób prezentacji formularza kartowego, definiujący, czy formularz kartowy zostanie wyświetlony na stronie płatności Paynow, czy w<iframe>na stronie sklepu.
orderItems oraz limit validityTime- Dla
paymentMethodId: 2202tablicaorderItemsnie jest wymagana, ale zalecamy jej przekazywanie w żądaniach CIT i MIT, ponieważ ułatwia to weryfikację zamówienia i obsługę transakcji. Jeśli tablica nie jest pusta, każdy jej element musi zawierać polaname,category,quantity(>= 1),typeifrequency. Wartości póltypeifrequencynależy podawać wielkimi literami, zgodnie ze słownikami, np.DIGITAL_SERVICEiMONTHLY. - Opcjonalne pole
validityTimedla metody2202przyjmuje wartość od60do7200sekund (domyślnie7200s). Wyższa wartość zwróci400 Bad Request.
Wariant 1: Przekierowanie na stronę płatności
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": "Subskrypcja miesięczna - plan PRO",
"continueUrl": "https://twojsklep.pl/platnosc/powrot",
"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": "Subskrypcja miesięczna - plan PRO",
"category": "Subskrypcja",
"quantity": 1,
"price": 4900,
"type": "DIGITAL_SERVICE",
"frequency": "MONTHLY"
}
],
"paymentMethodData": {
"card": {
"cardFormBehaviour": "REDIRECT",
"tokenization": {
"recurring": {
"action": "REGISTER_TOKEN_AND_CHARGE"
}
}
}
}
}'
Odpowiedź (201 Created) – przekieruj kupującego pod adres redirectUrl:
{
"redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=******",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "NEW"
}
Wariant 2: Osadzenie widgetu na stronie sklepu
Pierwszą płatność CIT dla subskrypcji (paymentMethodId: 2202) możesz zainicjować w trybie WIDGET.
W żądaniu CIT ustaw paymentMethodData.card.cardFormBehaviour na "WIDGET" oraz przekaż wymagane w tym trybie pola continueUrl, buyer.ipAddress i buyer.userAgent. W modelu White Label wyświetl kupującemu aktualną klauzulę informacyjną RODO — szczegóły znajdziesz w sekcji Obowiązek informacyjny RODO i aktywacja usługi.
Pozostałe pola wymagane w CIT są takie same jak w wariancie REDIRECT. Gdy usługa White Label dla kart jest aktywna dla punktu sprzedaży (POS), odpowiedź 201 Created zawiera widgetUrl:
{
"redirectUrl": null,
"widgetUrl": "<widget-url>",
"paymentId": "NOLV-8F9-08K-WGD",
"status": "PENDING"
}
Szczegóły osadzenia widgetUrl w <iframe>, obsługi przekierowania na continueUrl i fallbacku do REDIRECT, a także przykłady w środowisku Sandbox, opisano w sekcji Płatności kartą i płatności cykliczne kartą w modelu White Label.
Kolejne płatności (MIT – obciążenia cykliczne)
Każde kolejne obciążenie w ramach aktywnej subskrypcji wywołujesz przez POST /v3/payments, przekazując zapisany token karty oraz subscriptionId z akcją "NEXT_CHARGE".
Nie przekazuj pola cardFormBehaviour – transakcja odbywa się w tle bez udziału kupującego.
Wymagane pola specyficzne dla MIT
paymentMethodId–2202.buyer.email– adres e-mail kupującego.buyer.externalId– musi być taki sam jak w pierwszej płatności CIT, podczas której utworzono subskrypcję.paymentMethodData.card.tokenization.token– token zapisanej karty otrzymany po płatności CIT i powiązany z tą subskrypcją.paymentMethodData.card.tokenization.recurring.action–"NEXT_CHARGE".paymentMethodData.card.tokenization.recurring.subscriptionId– identyfikator aktywnej subskrypcji utworzonej po płatności CIT.
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": "Subskrypcja miesięczna - plan PRO (miesiąc 2)",
"paymentMethodId": 2202,
"buyer": {
"email": "jan.kowalski@melements.pl",
"externalId": "9328"
},
"orderItems": [
{
"name": "Subskrypcja miesięczna - plan PRO (miesiąc 2)",
"category": "Subskrypcja",
"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"
}
}
}
}
}'
Odpowiedź (201 Created):
{
"redirectUrl": null,
"paymentId": "MITP-9A2-11C-XYZ",
"status": "PENDING"
}
Ostateczny status transakcji MIT otrzymasz asynchronicznie w standardowym powiadomieniu o statusie płatności lub sprawdzisz przez GET /v3/payments/{paymentId}/status.
Powiadomienia o subskrypcji i karcie
Powiadomienia o cyklu życia subskrypcji i karty są wysyłane jako żądania HTTP POST na Adres powiadomień dot. innych zdarzeń. Każde powiadomienie jest podpisane nagłówkiem Signature (HMAC-SHA256 z body przy użyciu Signature-Key), a serwer sklepu powinien odpowiedzieć kodem 200 OK lub 202 Accepted (harmonogram ponowień: 1 min, 2 min, 4 min, 15 min, 30 min, 1 h, 2 h, 4 h, 8 h).
Utworzenie subskrypcji
Powiadomienie card.subscription.created jest wysyłane po udanej pierwszej płatności (CIT), gdy karta została zapisana i subskrypcja jest gotowa do obciążeń MIT:
{
"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"
}
Opis pól data.subscription
| Pole | Opis |
|---|---|
id | Unikalny identyfikator subskrypcji w Paynow (subscriptionId), wymagany przy kolejnych obciążeniach MIT i anulowaniu subskrypcji. |
status | Status subskrypcji. Możliwe wartości: ACTIVE, SUSPENDED, DELETED. |
initialOperation.type | Typ operacji inicjującej. Możliwe wartości: PAYMENT. |
initialOperation.id | Identyfikator pierwszej płatności CIT. |
initialOperation.externalId | Identyfikator zamówienia w systemie sklepu przekazany w pierwszej płatności CIT. |
externalBuyerId | Unikalny identyfikator kupującego w sklepie przekazany w pierwszej płatności CIT. |
action | W card.subscription.created: REGISTER_TOKEN_AND_CHARGE; w card.subscription.status.update: UPDATE_STATUS lub DELETE. |
savedInstrument.token | Token zapisanej karty wymagany przy kolejnych obciążeniach MIT. |
savedInstrument.status | Status tokenu zapisanej karty. Możliwe wartości: ACTIVE, SUSPENDED, EXPIRED_CARD, EXPIRED_TOKEN, DELETED. |
savedInstrument.name | Zamaskowany numer karty (np. xxxx xxxx xxxx 1234). |
savedInstrument.expirationDate | Data ważności karty w formacie MM/RR. |
savedInstrument.brand | Organizacja płatnicza karty (np. VISA lub MASTERCARD). |
savedInstrument.image | Adres URL logotypu organizacji płatniczej. |
Zmiana statusu subskrypcji i karty
Powiadomienie card.subscription.status.update jest wysyłane przy każdej zmianie statusu istniejącej subskrypcji:
{
"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"
}
Pobieranie szczegółów i anulowanie subskrypcji
Pobranie szczegółów subskrypcji i karty
Żądanie GET /v3/payments/paymentmethods/recurring/card/details pozwala pobrać szczegóły subskrypcji i karty po potwierdzeniu płatności CIT statusem CONFIRMED. W razie potrzeby możesz użyć operationId (paymentId transakcji CIT, np. gdy sklep nie otrzymał powiadomienia) albo subscriptionId:
| Parametr | Wymagalność | Opis |
|---|---|---|
externalBuyerId | Wymagany | Unikalny identyfikator kupującego w sklepie (buyer.externalId). |
operationId | Wymagany, jeśli nie podano subscriptionId | Identyfikator pierwszej płatności CIT (paymentId). |
subscriptionId | Wymagany, jeśli nie podano operationId | Identyfikator subskrypcji w Paynow. |
Przekazane parametry zapytania należy uwzględnić w kolejności alfabetycznej przy obliczaniu nagłówka podpisu (Signature).
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}}'
Przykładowa odpowiedź (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"
}
}
}
Kody odpowiedzi:
200 OK– zwrócono szczegóły subskrypcji i zapisanej karty.400 Bad Request(VALIDATION_ERROR) – brakuje parametruexternalBuyerIdalbo nie przekazano anisubscriptionId, anioperationId.400 Bad Request(PAYMENT_METHOD_NOT_AVAILABLE) – metoda płatności cyklicznych nie jest włączona dla danego punktu płatności.401 Unauthorized/403 Forbidden– błąd autoryzacji lub nieprawidłowy nagłówekSignature.404 Not Found(NOT_FOUND) – nie znaleziono subskrypcji ani zapisanego tokenu dla podanych parametrów, np. płatność CIT nie ma jeszcze statusuCONFIRMED, a subskrypcja nadal ma statusNEW.
Anulowanie subskrypcji
Gdy kupujący zrezygnuje z subskrypcji, usuń ją wywołując DELETE /v3/payments/paymentmethods/recurring/card/subscription/{subscriptionId} z parametrem zapytania externalBuyerId:
Pamiętaj o uwzględnieniu parametru zapytania externalBuyerId (bez parametru ścieżki subscriptionId) przy obliczaniu nagłówka podpisu (Signature).
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}}'
Kody odpowiedzi:
200 OK– subskrypcja została usunięta (jej status zmienił się naDELETED); jeśli skonfigurowanoAdres powiadomień dot. innych zdarzeń, Paynow wyśle powiadomieniecard.subscription.status.updatezaction: "DELETE".400 Bad Request(PAYMENT_METHOD_NOT_AVAILABLE) – metoda płatności cyklicznych nie jest włączona dla danego punktu płatności.401 Unauthorized/403 Forbidden– błąd autoryzacji lub nieprawidłowy nagłówekSignature.404 Not Found(NOT_FOUND) – subskrypcja nie istnieje, nie należy do wskazanegoexternalBuyerIdalbo została już wcześniej usunięta.
Usunięcie subskrypcji (DELETED) jest operacją nieodwracalną. Wznowienie usługi wymaga wykonania nowej pierwszej płatności (CIT), którą kupujący autoryzuje w 3-D Secure.
Statusy i kody błędów
Statusy subskrypcji
| Status | Opis i zalecane działanie po stronie sklepu |
|---|---|
NEW | Trwa procesowanie pierwszej płatności (CIT) – nie można jeszcze wykonywać obciążeń MIT. |
ACTIVE | Subskrypcja jest aktywna – możesz inicjować obciążenia cykliczne (MIT). |
SUSPENDED | Subskrypcja tymczasowo zawieszona – wstrzymaj próby obciążeń MIT do czasu przywrócenia statusu ACTIVE. |
DELETED | Subskrypcja trwale zakończona – kolejne obciążenia MIT nie są możliwe (wymagana nowa płatność CIT). |
Statusy zapisanej karty
| Status | Opis |
|---|---|
ACTIVE | Token karty jest aktywny i gotowy do realizacji obciążeń MIT. |
SUSPENDED | Token karty został tymczasowo zawieszony w organizacji płatniczej lub przez bank wydawcę. |
EXPIRED_CARD | Upłynęła data ważności karty (expirationDate) – wymagana jest nowa płatność CIT (utworzenie nowej subskrypcji). |
EXPIRED_TOKEN | Token karty wygasł po stronie dostawcy lub organizacji płatniczej – wymagana jest nowa płatność CIT (utworzenie nowej subskrypcji). |
DELETED | Token karty został trwale usunięty. |
Kody błędów specyficzne dla płatności cyklicznych
| Kod HTTP | errorType | Przyczyna i sposób obsługi |
|---|---|---|
400 | INVALID_SUBSCRIPTION_STATUS | Próba wywołania MIT (NEXT_CHARGE) dla subskrypcji o statusie innym niż ACTIVE (np. SUSPENDED lub DELETED). Sprawdź status przez GET /v3/payments/paymentmethods/recurring/card/details. |
400 | INVALID_PAYMENT_TOKEN_STATUS | Próba wywołania MIT dla tokenu karty o statusie innym niż ACTIVE (np. EXPIRED_CARD, EXPIRED_TOKEN, SUSPENDED lub DELETED). W przypadku wygaśnięcia lub usunięcia tokenu wymagana jest nowa płatność CIT (utworzenie nowej subskrypcji). |
400 | INCONSISTENT_SUBSCRIPTION_DATA | Pola token, subscriptionId oraz buyer.externalId w żądaniu MIT nie są ze sobą powiązane. Upewnij się, że przekazujesz identyfikatory zwrócone dla tego kupującego podczas tworzenia subskrypcji. |
400 | PAYMENT_METHOD_NOT_AVAILABLE | Metoda płatności cyklicznych kartą (2202) nie jest włączona dla danego punktu płatności (POS). |
404 | NOT_FOUND | Nie znaleziono subskrypcji lub zapisanego tokenu dla podanych parametrów w żądaniach GET .../details lub DELETE .../subscription/{subscriptionId}. |