Płatności Cykliczne (Recurring Payments) umożliwiają akceptantom przetwarzanie przyszłych płatności przy użyciu danych płatniczych wcześniej autoryzowanych przez klienta podczas początkowej transakcji Cardholder-Initiated Transaction (CIT).
Płatności Cykliczne są zazwyczaj wykorzystywane w modelach subskrypcyjnych lub w scenariuszach cyklicznego rozliczania, w których obciążenia są przetwarzane w z góry określonych odstępach czasu.
Podczas początkowej transakcji CIT ustanawiana jest umowa cykliczna poprzez zdefiniowanie konfiguracji płatności cyklicznej, w tym harmonogramu rozliczeń. Po pomyślnym zakończeniu początkowej płatności wszystkie kolejne obciążenia cykliczne są automatycznie przetwarzane przez SIBS Gateway jako transakcje Merchant-Initiated Transaction (MIT), z wykorzystaniem zapisanych danych płatniczych oraz odniesienia do pierwotnej transakcji CIT.
Akceptant jest zobowiązany skonfigurować umowę cykliczną wyłącznie podczas początkowej płatności. Po ustanowieniu umowy, SIBS Gateway zarządza wykonaniem wszystkich kolejnych płatności cyklicznych zgodnie ze skonfigurowanym harmonogramem.
Kiedy stosować
Ten model należy stosować, gdy akceptant obciąża klienta zgodnie ze stałym i przewidywalnym harmonogramem, na przykład w przypadku:
- Subskrypcji miesięcznych lub rocznych
- Cykli rozliczeniowych SaaS
- Opłat członkowskich
- Płatności okresowych (stałych lub zmiennych) o znanym interwale rozliczeniowym
Jak to działa
Płatności Cykliczne są realizowane w trzech krokach:
- Krok 1 – Początkowa transakcja Cardholder-Initiated Transaction (CIT)
- Krok 2 – Kolejne transakcje Merchant-Initiated Transaction (MIT)
- Krok 3 – Odbieranie powiadomień o płatnościach (opcjonalnie)
Krok 1 – Początkowa transakcja Cardholder-Initiated Transaction (CIT)
Klient realizuje płatność początkową.
Podczas tej transakcji akceptant ustanawia umowę cykliczną, konfigurując parametry transakcji Merchant-Initiated Transaction (MIT).
Po pomyślnym zakończeniu transakcji początkowej, SIBS Gateway generuje wartość original-tx-id, która jednoznacznie identyfikuje umowę cykliczną i musi być podawana we wszystkich przyszłych transakcjach Merchant-Initiated Transaction.
Ten krok obejmuje następujące działania:
- Działanie 1 – Utworzenie zamówienia
- Działanie 2 – Przetworzenie płatności
- Działanie 3 – Sprawdzenie statusu transakcji (opcjonalnie)
Działanie 1 – Utworzenie zamówienia
Rozpocznij od utworzenia standardowego zamówienia płatności przy użyciu Checkout Payment API.
Pełną strukturę żądania, wymagane nagłówki oraz standardowe pola płatności znajdziesz w sekcji Utwórz Zamówienie dokumentacji API Integration.
Podczas tworzenia początkowej transakcji CIT należy uwzględnić pola konfiguracji MIT opisane w poniższej tabeli. Pola te określają, że transakcja ustanawia umowę cykliczną, oraz definiują sposób przetwarzania przyszłych płatności cyklicznych.
Endpoint URL:
| API | Operacja |
|---|---|
| Checkout Payment API | POST /api/{version-id}/payments |
Pola konfiguracji MIT
| Field | Type | Condition | Description | Example |
|---|---|---|---|---|
Request Body .merchantInitiatedTransaction | MITTypeCode | Optional | Definiuje typ transakcji Merchant-Initiated Transaction. W przypadku płatności cyklicznych ustaw to pole na RCRR. Możliwe wartości: RCRR, UCOF. | „RCRR” |
Request Body .recurringTransaction | RecurringTransaction | Conditional | Obiekt definiujący umowę cykliczną. Wymagany, gdy merchantInitiatedTransaction jest ustawione na RCRR. | {…} |
Request Body .recurringTransaction.validityDate | isoDateTime | Optional | Data, do której umowa cykliczna pozostaje ważna. | „2027-12-31T23:59:59Z” |
Request Body .recurringTransaction.amountQualifier | String | Optional | Określa kwalifikator kwoty płatności cyklicznej. Możliwe wartości: ACTUAL, ESTIMATED oraz DEFAULT. Jeśli pole zostanie pominięte, przyjmowana jest wartość DEFAULT. | „DEFAULT” |
Request Body .recurringTransaction.description | String | Optional | Opis umowy cyklicznej. | „Monthly Subscription” |
Request Body .recurringTransaction.schedule | Schedule | Optional | Definiuje harmonogram płatności cyklicznych. Jeśli pole zostanie pominięte, przyszłe płatności cykliczne muszą być inicjowane przez akceptanta za pomocą MIT API. | |
Request Body .recurringTransaction.schedule.initialDate | isoDateTime | Conditional | Data rozpoczęcia harmonogramu cyklicznego. Wymagane przy konfigurowaniu zaplanowanych płatności cyklicznych. | „2026-08-01T00:00:00Z” |
Request Body .recurringTransaction.schedule.finalDate | isoDateTime | Conditional | Data zakończenia harmonogramu cyklicznego. Wymagane przy konfigurowaniu zaplanowanych płatności cyklicznych. | „2027-08-01T00:00:00Z” |
Request Body .recurringTransaction.schedule.interval | IntervalType | Conditional | Określa częstotliwość płatności cyklicznych. Możliwe wartości: DAILY, WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL oraz ANNUAL. Wymagane przy konfigurowaniu harmonogramu cyklicznego. | „MONTHLY” |
Request Body .recurringTransaction.hideNonRecurring | Boolean | Optional | Wskazuje, czy metody płatności niecykliczne powinny być ukryte podczas procesu checkout. Jeśli pole zostanie pominięte, domyślną wartością jest false. | true |
Ważne
Podczas konfigurowania Płatności Cyklicznych pole transaction.paymentMethod musi zawierać wyłącznie wartość „CARD”.
Przykładowe żądanie
Poniższy przykład przedstawia kompletne żądanie Checkout Payment skonfigurowane w celu utworzenia umowy cyklicznej. Podczas tej początkowej transakcji Cardholder-Initiated Transaction (CIT) akceptant definiuje konfigurację cykliczną, która zostanie wykorzystana w kolejnych transakcjach Merchant-Initiated Transaction (MIT).
</> JSON
{
"merchant": {
"terminalId": {{TerminalID}},
"channel": "web",
"merchantTransactionId": "{{merchantTrxID}}",
"websiteAddress": "https://website.com"
},
"customer": {
"customerInfo": {
"customerLanguage": "pl"
}
},
"transaction": {
"transactionTimestamp": "{{trxDatetime}}",
"description": "Transaction for order number {{trxOrderNum}} terminalId {{TerminalID}}",
"moto": false,
"paymentType": "AUTH",
"amount": {
"value": 50.50,
"currency": "PLN"
},
"paymentMethod": [
"CARD"
]
},
"tokenisation": {
"tokenisationRequest": {
"tokeniseCard": false
},
"paymentTokens": []
},
"merchantInitiatedTransaction": "RCRR",
"recurringTransaction": {
"validityDate": "{{trxRecurrValidityDatetime}}",
"amountQualifier": "DEFAULT",
"description" : "Recurring transaction -> Order {{trxOrderNum}}",
"schedule" : {
"initialDate": "{{trxRecurrInitialDatetime}}",
"finalDate": "{{trxRecurrFinalDatetime}}",
"interval": "MONTHLY"
}
}
} Działanie 2 – Przetworzenie płatności
Po utworzeniu zamówienia, dokończ płatność klienta przy użyciu Card Purchase API.
W odróżnieniu od żądania Checkout, ta operacja nie wykorzystuje Bearer Token w nagłówku Authorization. Zamiast tego żądanie musi zawierać wartość transactionSignature zwróconą w odpowiedzi Checkout.
Wartość transactionSignature autoryzuje wykonanie płatności dla transakcji utworzonej wcześniej za pomocą Checkout API.
| API | Operacja |
|---|---|
| Card Purchase API | POST /api/{version-id}/payments/{transactionID}/card/purchase |
Header Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
Content-Type | string | Mandatory | Określa typ zawartości żądania. | application/json |
Authorization | string | Mandatory | Użyj wartości transactionSignature zwróconej przez Checkout API. To żądanie musi wykorzystywać schemat uwierzytelniania Digest. | Digest {transactionSignature} |
x-ibm-client-id | string | Mandatory | Token identyfikujący organizację klienta, przekazany podczas onboardingu. | 123456789 |
Przykładowe żądanie Purchase:
</> JSON
{
"cardInfo": {
"PAN": "5204740000001002",
"secureCode": "100",
"validationDate": "2025-12-31T00:00:00.000Z",
"cardholderName": "Jane Smith",
"createToken": false
}
} Odpowiedź
Pomyślna odpowiedź techniczna zwraca:
- HTTP Status 200
- returnStatus.statusCode = „000”
Pole paymentStatus wskazuje wynik autoryzacji płatności.
| Payment Status | Description |
|---|---|
| Success | Płatność została pomyślnie autoryzowana, a umowa cykliczna została ustanowiona. |
| Declined | Płatność została odrzucona. Umowa cykliczna nie zostaje utworzona. |
| Pending | Ostateczny wynik płatności nie jest jeszcze dostępny. Korzystaj ze Status API do momentu uzyskania statusu ostatecznego. |
| Partial | Wymagana jest dodatkowa interakcja z klientem (na przykład uwierzytelnienie 3DS). Element actionResponse zawiera instrukcje dotyczące dalszego postępowania. |
Odpowiedź API zawiera również pole recurringTransaction.status. Pole to potwierdza, czy umowa cykliczna została pomyślnie utworzona i czy kwalifikuje się do przyszłych automatycznych wykonań cyklicznych. Tylko wtedy, gdy ten status wskazuje powodzenie, transakcja może zostać wykorzystana jako odniesienie dla przyszłych transakcji Recurring Merchant-Initiated Transaction (MIT).
Działanie 3 – Sprawdzenie statusu transakcji (opcjonalnie)
Po przesłaniu płatności możesz zweryfikować jej status przetwarzania przy użyciu Status API.
W odróżnieniu od żądania Card Purchase, Status API wykorzystuje tę samą metodę uwierzytelniania co początkowe żądanie Checkout. Nagłówek Authorization musi zawierać Bearer Token.
Endpoint URL
| API | Operation |
|---|---|
| Payment Status API | GET /api/{version-id}/payments/{transactionID}/status |
Header Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
Content-Type | string | Mandatory | Określa typ zawartości żądania. | application/json |
Authorization | string | Mandatory | Bearer Token uzyskany w procesie uwierzytelniania. | Bearer xxxxxxxx |
x-ibm-client-id | string | Mandatory | Token identyfikujący organizację klienta, przekazany podczas onboardingu. | 123456789 |
Example Request
Checkout Status Response
Pomyślna odpowiedź techniczna zwraca HTTP 200 z returnStatus.statusCode = „000”.
Korzystaj z tej operacji zawsze, gdy potrzebujesz pobrać aktualny status przetwarzania transakcji.
Pełną listę kodów statusu transakcji, kodów błędów oraz przyczyn odrzucenia znajdziesz w dokumentacji Obsługa Błędów i Kody Odrzucenia.
Krok 2 – Przetwarzanie kolejnych płatności cyklicznych
Po pomyślnym zakończeniu początkowej transakcji Cardholder-Initiated Transaction (CIT) i ustanowieniu umowy cyklicznej, SIBS Gateway automatycznie przetwarza wszystkie kolejne transakcje Merchant-Initiated Transaction (MIT) zgodnie z harmonogramem cyklicznym skonfigurowanym podczas początkowej płatności.
Ten krok obejmuje następujące działania:
- Działanie 1 – Automatyczne wykonywanie płatności cyklicznych
- Działanie 2 – Sprawdzenie statusu transakcji (zalecane)
Działanie 1 – Automatyczne wykonywanie płatności cyklicznych
Ze strony akceptanta nie są wymagane żadne dodatkowe żądania płatności.
Korzystając z konfiguracji cyklicznej zdefiniowanej podczas początkowej transakcji CIT, SIBS Gateway automatycznie wykonuje każdą cykliczną transakcję Merchant-Initiated Transaction (MIT) zgodnie ze skonfigurowanymi parametrami:
- Data rozpoczęcia (schedule.initialDate)
- Data zakończenia (schedule.finalDate)
- Interwał rozliczeniowy (schedule.interval)
- Konfiguracja kwoty (amountQualifier)
Akceptant nie musi przesyłać dodatkowych żądań API dla każdej płatności cyklicznej, ponieważ SIBS Gateway zarządza wykonaniem cyklicznym automatycznie przez cały okres obowiązywania umowy cyklicznej.
Działanie 2 – Sprawdzenie statusu transakcji (opcjonalne, ale zalecane)
Po przetworzeniu płatności cyklicznej możesz zweryfikować jej status przetwarzania przy użyciu Status API.
Zdecydowanie zaleca się korzystanie ze Status API, ponieważ umożliwia to Twojemu systemowi pobranie aktualnego statusu przetwarzania oraz potwierdzenie ostatecznego wyniku każdej płatności cyklicznej.
W odróżnieniu od żądania Card Purchase realizowanego podczas początkowej transakcji CIT, Status API wykorzystuje Bearer Token w nagłówku Authorization.
Example Request
Krok 3 – Odbieranie powiadomień o płatnościach cyklicznych (opcjonalnie)
Aby jeszcze bardziej zautomatyzować swoją integrację, możesz skonfigurować Webhooks w celu odbierania asynchronicznych powiadomień za każdym razem, gdy przetwarzana jest płatność cykliczna.
Gdy Webhooks są włączone, SIBS Gateway automatycznie wysyła powiadomienia o zdarzeniach do skonfigurowanego punktu końcowego akceptanta po każdej cyklicznej transakcji Merchant-Initiated Transaction (MIT), umożliwiając Twojemu systemowi reagowanie na zdarzenia płatnicze w czasie rzeczywistym.
Typowe powiadomienia obejmują:
- Płatność cykliczna przetworzona pomyślnie
- Płatność cykliczna odrzucona
- Płatność cykliczna oczekująca
- Przetwarzanie płatności cyklicznej zakończone
Webhooks uzupełniają integrację płatności cyklicznych, zapewniając mechanizm oparty na zdarzeniach do odbierania aktualizacji transakcji, co ułatwia utrzymanie systemów subskrypcyjnych lub rozliczeniowych w zgodności z najbardziej aktualnym statusem płatności.
Informacje na temat konfigurowania Webhooks, obsługiwanych zdarzeń oraz szczegółów implementacji znajdziesz w dokumentacji Webhooks Integration.
Dowiedz się więcej o Webhooks tutaj.