Płatności Unscheduled Card-on-File (UCOF) umożliwiają merchantom 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 UCOF są przeznaczone dla scenariuszy, w których przyszłe obciążenia nie mogą być zaplanowane z góry i są wyzwalane przez zdarzenie biznesowe zdefiniowane przez merchanta. Typowe przykłady obejmują opóźnione obciążenia, dodatkowe opłaty za usługi, opłaty za brak stawienia się (no-show fees), rozliczenia na podstawie zużycia (usage-based billing) lub obciążenia przyrostowe.

Podczas początkowej transakcji CIT merchant ustanawia umowę Merchant-Initiated Transaction (MIT), konfigurując parametry UCOF. Po pomyślnym zakończeniu początkowej płatności kolejne obciążenia mogą być przetwarzane jako transakcje Merchant-Initiated Transactions (MIT), przy użyciu zapisanych danych płatniczych oraz odniesienia do oryginalnej transakcji CIT.

W przeciwieństwie do płatności cyklicznych (Recurring Payments), UCOF nie obsługuje harmonogramów cyklicznych. Merchant jest odpowiedzialny za inicjowanie każdej kolejnej transakcji MIT w momencie wystąpienia prawidłowego zdarzenia biznesowego.

Kiedy stosować UCOF

Stosuj UCOF, gdy merchant obciąża zapisaną kartę bez wcześniej ustalonego harmonogramu, wyzwalanego przez zdarzenia operacyjne, takie jak:

• Opóźnione obciążenia
• Opłaty hotelowe za brak stawienia się (no-show fees)
• Dodatkowe opłaty hotelowe lub za wynajem
• Rozliczenia na podstawie zużycia
• Usługi rozliczane za wykorzystanie (pay-per-use)
• Korekty po zakupie
• Autoryzacje przyrostowe lub dodatkowe opłaty za usługi

Jak to działa

Płatności UCOF 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 dokonuje początkowej płatności.

Podczas tej transakcji merchant ustanawia umowę Merchant-Initiated Transaction (MIT), konfigurując wymagane parametry UCOF.

Po pomyślnym zakończeniu płatności SIBS Gateway generuje original-tx-id, który jednoznacznie identyfikuje zapisaną umowę dotyczącą danych uwierzytelniających i musi być podawany przy każdej kolejnej, przyszłej transakcji Merchant-Initiated typu UCOF.

Ten krok obejmuje następujące czynności:

• Czynność 1 – Utworzenie zamówienia
• Czynność 2 – Przetworzenie płatności
• Czynność 3 – Sprawdzenie statusu transakcji (opcjonalnie)

Czynność 1 – Utworzenie zamówienia

Rozpocznij od utworzenia standardowego zamówienia płatności za pomocą Checkout Payment API.

Pełną strukturę żądania, wymagane nagłówki oraz standardowe pola płatności znajdziesz w sekcji Create Order w dokumentacji API Integration.

Podczas tworzenia początkowej transakcji CIT należy uwzględnić pola konfiguracyjne UCOF opisane poniżej. Pola te ustanawiają umowę dotyczącą zapisanych danych uwierzytelniających, do której będą odnosić się przyszłe transakcje Merchant-Initiated.

Adres URL punktu końcowego

API	Operation
Checkout Payment API	POST /api/{version-id}/payments

Pola konfiguracyjne UCOF

Field	Type	Condition	Description	Example
Request Body.merchantInitiatedTransaction	MITTypeCode	Optional	Defines the Merchant-Initiated Transaction type. For UCOF payments, set this field to UCOF.  Possible values: RCRR, UCOF.	„UCOF”
Request Body.recurringTransaction	RecurringTransaction	Conditional	Object that defines the Merchant-Initiated Transaction agreement. Required when merchantInitiatedTransaction is set to UCOF. For UCOF, only the amountQualifier field must be provided.	{…}
Request Body.recurringTransaction.validityDate	isoDateTime	Optional	Date until which the Merchant-Initiated Transaction agreement remains valid.	„2027-12-31T23:59:59Z”
Request Body.recurringTransaction.amountQualifier	String	Mandatory for UCOF	Qualifies the amount associated with the Merchant-Initiated Transaction. Possible values are ACTUAL, ESTIMATED and DEFAULT. For UCOF payments, this field must always be set to ESTIMATED.	„ESTIMATED”
Request Body.recurringTransaction.amountQualifier	String	Optional	Description of the Merchant-Initiated Transaction agreement.

Przykładowe żądanie

</> 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”: „UCOF”,
„recurringTransaction”: {
„validityDate”: „{{trxRecurrValidityDatetime}}”,
„amountQualifier”: „ESTIMATED”,
„description”: „UCOF transaction -> Order {{trxOrderNum}}”
}
}

Czynność 2 – Przetworzenie płatności

Po utworzeniu zamówienia dokończ płatność klienta za pomocą Card Purchase API.

W przeciwieństwie do żądania Checkout, ta operacja nie wykorzystuje tokenu Bearer w nagłówku Authorization. Zamiast tego żądanie musi zawierać transactionSignature zwrócony w odpowiedzi Checkout.

transactionSignature autoryzuje wykonanie płatności dla transakcji utworzonej wcześniej za pomocą Checkout API.

Adres URL punktu końcowego

API	Operation
Card Purchase API	POST /api/{version-id}/payments/{transactionID}/card/purchase

Parametry nagłówka

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Use transactionSignature returned by the Checkout API. This request must use the Digest authentication scheme.	Digest {transactionSignature}
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	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:

• Status HTTP 200
• returnStatus.statusCode = "000"

Pole paymentStatus wskazuje wynik autoryzacji płatności.

Status płatności	Opis
Success	Płatność została pomyślnie autoryzowana, a umowa cykliczna (recurring agreement) 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 otrzymania ostatecznego statusu.
Partial	Wymagana jest dodatkowa interakcja z klientem (np. uwierzytelnienie 3DS). Element actionResponse zawiera instrukcje dotyczące dalszego postępowania.

Odpowiedź API zawiera również pole recurringTransaction.status, które wskazuje, czy konfiguracja cykliczna została pomyślnie ustanowiona podczas początkowej płatności. Tylko wtedy, gdy ten status jest pozytywny, transakcja może zostać użyta jako odniesienie dla przyszłych transakcji Merchant-Initiated (MIT) typu UCOF.

Czynność 3 – Sprawdzenie statusu transakcji (opcjonalnie)

Po przesłaniu płatności możesz zweryfikować jej status przetwarzania za pomocą Status API.

W przeciwieństwie do żądania Card Purchase, Status API wykorzystuje tę samą metodę uwierzytelniania co początkowe żądanie Checkout. Nagłówek Authorization musi zawierać token Bearer.

Adres URL punktu końcowego

API	Operation
Payment Status API	GET /api/{version-id}/payments/{transactionID}/status

Parametry nagłówka

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Przykładowe żądanie

Odpowiedź statusu Checkout

Pomyślna odpowiedź techniczna zwraca status HTTP 200 z returnStatus.statusCode = "000".

Korzystaj z tej operacji za każdym razem, gdy musisz pobrać najnowszy status przetwarzania transakcji.

Pełną listę kodów statusu transakcji, kodów błędów i przyczyn odrzuceń znajdziesz w dokumentacji Obsługa Błędów i Kody Odrzucenia.

Krok 2 – Przetwarzanie kolejnych płatności UCOF (MIT)

Po pomyślnym zakończeniu początkowej płatności merchant może inicjować transakcje Merchant-Initiated Transaction (MIT) za każdym razem, gdy wystąpi prawidłowe zdarzenie biznesowe.

Każda kolejna płatność UCOF odnosi się do original-tx-id wygenerowanego podczas początkowej transakcji CIT i wykorzystuje dane płatnicze wcześniej autoryzowane przez klienta.

W przeciwieństwie do płatności cyklicznych (Recurring Payments), transakcje UCOF nie są zaplanowane w harmonogramie. Każde żądanie MIT musi zostać jawnie przesłane przez merchanta.

Ten krok obejmuje następujące czynności:

• Czynność 1 – Przesłanie żądania MIT
• Czynność 2 – Sprawdzenie statusu transakcji (opcjonalnie)

Czynność 1 – Przesłanie żądania MIT

Gdy płatności UCOF są inicjowane przez merchanta, prześlij transakcję Merchant-Initiated Transaction, wykorzystując original-tx-id wygenerowany podczas początkowej transakcji CIT.

original-tx-id identyfikuje umowę cykliczną (recurring agreement) i łączy każdą transakcję MIT z oryginalną transakcją autoryzowaną przez klienta.

Punkt końcowy

API	Operation
MIT API	POST /api/{version-id}/payments/{original-tx-id}/mit

Parametry nagłówka

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Pola żądania MIT

Field	Type	Condition	Description
original-tx-id (Path)	String (Max36Text)	Mandatory	Original transaction identifier generated during the initial CIT. This value identifies the stored credential agreement used to process the Merchant-Initiated Transaction.
transaction.transactionType	String (Transaction Type Code)	Mandatory	Defines the Merchant-Initiated Transaction(MIT) type. Possible values: RCRR or UCOF.
transaction.amount.value	Number (double)	Mandatory	Amount to be charged.
transaction.amount.currency	String (Currency Code – ISO Alpha-3)	Mandatory	Currency used in the transaction.
transaction.description	String	Optional	Short description of the Merchant-Initiated Transaction.

Przykładowe żądanie

</> JSON

{
„merchant”: {
„terminalId”: „{{TerminalID}}”,
„channel”: „web”,
„merchantTransactionId”: „{{merchantTrxID}}”
},
„transaction”: {
„transactionTimestamp”: „{{trxDatetime}}”,
„transactionType”: „UCOF”,
„description”: „Transaction for order {{trxOrderNum}}”,
„amount”: {
„value”: 50.50,
„currency”: „PLN”
},
„originalTransaction”: {
„id”: „{{ originalTxId}}”,
„datetime”: „{{trxOriginalDatetime}}”
}
}
}

Czynność 2 – Sprawdzenie statusu transakcji (opcjonalnie, ale zalecane)

Po przesłaniu transakcji Merchant-Initiated Transaction (MIT) możesz zweryfikować jej status przetwarzania za pomocą Status API.

Status API umożliwia pobranie najnowszego statusu przetwarzania transakcji, gdy natychmiastowe potwierdzenie nie jest dostępne lub gdy potrzebujesz potwierdzić ostateczny wynik płatności.

W przeciwieństwie do Purchase API, to żądanie wykorzystuje tę samą metodę uwierzytelniania co początkowe żądanie Checkout. Nagłówek Authorization musi zawierać token Bearer.

Adres URL punktu końcowego

API	Operation
Payment Status API	GET /api/{version-id}/payments/{transactionID}/status

Parametry nagłówka

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Przykładowe żądanie

Odpowiedź

Pomyślna odpowiedź techniczna zwraca:

• Status HTTP 200
• returnStatus.statusCode = "000"

Korzystaj z tej operacji za każdym razem, gdy musisz pobrać najnowszy status przetwarzania transakcji Merchant-Initiated.

Pełną listę kodów statusu transakcji, kodów błędów i przyczyn odrzuceń znajdziesz w dokumentacji Obsługa Błędów i Kody Odrzucenia.

Krok 3 – Odbieranie powiadomień o płatnościach (opcjonalnie)

Aby dodatkowo zautomatyzować integrację, możesz skonfigurować Webhooks w celu otrzymywania asynchronicznych powiadomień za każdym razem, gdy zmienia się status transakcji Merchant-Initiated Transaction.

Gdy Webhooks są włączone, SIBS Gateway automatycznie wysyła powiadomienia o zdarzeniach do skonfigurowanego punktu końcowego merchanta po przetworzeniu każdej płatności UCOF. Umożliwia to systemowi merchanta reagowanie na zdarzenia płatnicze w czasie rzeczywistym.

Typowe powiadomienia obejmują:

• Płatność przetworzona pomyślnie
• Płatność odrzucona
• Płatność w toku (pending)
• Przetwarzanie płatności zakończone

Webhooks uzupełniają integrację płatności, zapewniając mechanizm oparty na zdarzeniach do otrzymywania aktualizacji statusu transakcji, co ułatwia synchronizację systemów merchanta 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.