Polecenie zapłaty SEPA (SEPA DD) to metoda płatności umożliwiająca sprzedawcom pobieranie płatności w euro bezpośrednio z rachunku bankowego klienta w ramach Jednolitego Obszaru Płatności w Euro (SEPA).

Opiera się ona na mandacie, w ramach którego klient (Dłużnik) upoważnia sprzedawcę (Wierzyciela) do inicjowania obciążeń. Zarówno Dłużnik, jak i Wierzyciel muszą posiadać rachunki bankowe w strefie SEPA.

SEPA Direct Debit obsługuje dwa schematy:

• CORE – dla klientów indywidualnych
• B2B – dla transakcji między przedsiębiorstwami

Przegląd metody płatności

Payment Method	Category	Countries	Currencies	Features	Integrations
SEPA DD (via Tink)	Bank Debit	Europe (SEPA)	EUR	Tink – based Open Banking, Recurring payments	Payment Form
SEPA DD (via iDEAL)	Bank Debit	Netherlands	EUR	iDEAL – based authentication	Payment Form, API

Funkcja	SEPA DD przez Tink	SEPA DD przez iDEAL
Zakres geograficzny	Kraje SEPA	Tylko Niderlandy
Typ mandatu	CORE / B2B	Tylko CORE
Kraj klienta	Dowolny	Musi być NL
Adres rozliczeniowy	Zalecany	Obowiązkowy (kontekst holenderski)
Typ integracji	Formularz płatności	Formularz płatności + API

Wybór modelu integracji

Przed rozpoczęciem integracji sprzedawca musi wybrać odpowiedni model integracji.

Wybór ten nie jest częścią specyfikacji SEPA DD i jest opisany w dedykowanej dokumentacji integracyjnej.

Dostępne modele:

• Formularz Płatności – Przewodnik integracji
• API – Przewodnik integracji

Integration Model	Description
Formularz Płatności	SIBS zarządza interfejsem użytkownika oraz przebiegiem płatności
Server-to-Server API	Sprzedawca w pełni kontroluje doświadczenie użytkownika oraz logikę przekierowań

Wybór ten nie jest częścią żądania API – określa sposób wykorzystania odpowiedzi Checkout.

Jak to działa

Integracja zawsze rozpoczyna się od wywołania Checkout API, które tworzy sesję płatności i zwraca dane niezbędne do kontynuacji procesu.

Od tego momentu dalsza realizacja zależy od modelu integracji wybranego podczas onboardingu (Formularz płatności lub API S2S).

Przepływ integracji

1. Utworzenie sesji płatności (Checkout API)
2. Wykonanie płatności
3. Monitorowanie statusu mandatu (Status API)
4. Monitorowanie statusu obciążenia (Opcjonalnie)
5. Webhooki do aktualizacji asynchronicznych

Krok 1 – Utworzenie sesji płatności

Jest to główny punkt wejścia dla transakcji SEPA DD, niezależnie od dostawcy (Tink lub iDEAL).

Na tym etapie tworzona jest sesja płatności oraz definiowane są:

• konfiguracja sprzedawcy
• dane klienta
• szczegóły transakcji
• konfiguracja mandatu

Endpoint

Environment	URL	Method & Endpoint
PROD	api.sibsgateway.com	POST api/version-id/payments
TEST	stargate.qly.site[1|2].sibs.pt	POST api/version-id/payments

Request Headers

Field	Type	Description
Content-Type	String	application/json
Authorization	String	Bearer token
x-ibm-client-id	String	Client identifier (onboarding provided)

Podstawowa struktura żądania

Żądanie Checkout składa się z 4 obowiązkowych blokow:

• merchant
• customer
• transaction
• mandate

1.1 Merchant Object (Mandatory)

Definiuje kontekst akceptanta wykonującego transakcję.

Field	Type	Condition	Description	Example
merchant.terminalId	String (max 10 numeric)	Mandatory	Merchant terminal	47215
merchant.channel	string	Mandatory	Sales channel	WEB
merchant.transactionId	string (max 1000)	Mandatory	Unique reference	987635435
merchant.transactionDescription	String (max 4000)	Optional	Context	order #123

1.2 Transaction Object (Mandatory)

To kluczowy blok konfiguracji realizacji płatności.

Najważniejsze pola:

Field	Type	Condition	Description	Example
transaction.transactionTimestamp	DateTime	Mandatory	Timestamp ISO8601	2026-04-24T13:40:08Z
transaction.description	String	Optional	Transaction short description.	purchase
transaction.moto	Boolean	Optional	Indicates if is a Mail Order Telephone Order.	false
transaction.paymentType	String	Optional	Type of payment used by the client. Possible values are: “PURS” – Purchase, “AUTH” – Authorisation, “CAPT” – Capture, “CAUT” – Authorisation Cancellation, “RFND” – Refund, “RVSL” – Reversal, “STIQ” – Status Inquiry.	AUTH
transaction.amount.value	Number	Mandatory	Transaction amount. For standard SEPA Direct Debit flows, this value must be set to 0. Exception: When using [„SPDD”, „iDEAL”], the amount must be greater than 0, as iDEAL does not support zero-value transactions.	0
transaction.amount.currency	String	Mandatory	Currency used in the transaction.	EUR
transaction.paymentMethod	Array	Mandatory	Determines how the SEPA Direct Debit flow is executed. [„SPDD”] triggers a SEPA DD flow using Tink for bank authentication. [„SPDD”,”IDEL”] adds iDEAL to the authentication journey, enforcing a CORE mandate and NL-based customer data.	[„SPDD”]

Zachowanie metody płatności (KRYTYCZNY PUNKT DECYZYJNY)

Przepływ Tink

Jeśli:

</> JSON
"paymentMethod": ["SPDD"]

Ta konfiguracja włącza przepływ SEPA Direct Debit, w którym autoryzacja bankowa odbywa się za pośrednictwem Tink (Open Banking).

Z perspektywy integracji:

• Klient autoryzuje się w swoim banku podczas checkout
• Dane rachunku bankowego są zbierane w ramach przepływu dostawcy
• Utworzenie mandatu jest wspierane wynikiem autoryzacji

Obowiązki integratora:

• Przekazanie kompletnych danych klienta
• Zapewnienie poprawnego zdefiniowania obiektu mandate
• Kontynuowanie przepływu na podstawie danych z odpowiedzi Checkout

Przepływ iDEAL

Jeśli:

</> JSON 
"paymentMethod": ["SPDD", "IDEL"]

Ta konfiguracja wprowadza iDEAL jako kanał autoryzacji w ramach przepływu SEPA DD.

Z perspektywy integracji:

• Klient przechodzi przez proces autoryzacji u dostawcy
• Weryfikacja tożsamości odbywa się w ramach procesu dostawcy
• Mandat jest wciąż tworzony jako część cyklu życia SEPA DD

Obowiązki integratora:

• Zapewnienie, że mandate.serviceType = CORE
• Przekazanie danych klienta zgodnych z kontekstem holenderskim
• Wymuszenie ograniczeń dotyczących adresu w Holandii

This configuration is intended for Netherlands-based payment flows where iDEAL is part of the checkout experience.

1.3 Customer Object (Mandatory)

Ta konfiguracja jest przeznaczona dla przepływów płatności realizowanych w Holandii, gdzie iDEAL jest częścią procesu checkout.

Key fields:

Field	Type	Condition	Description	Example
customer.customerInfo.customerName	String	Mandatory	Customer name.	Test Name
customer.customerInfo.customerEmail	String	Mandatory	Customer E-mail	email@provider.com
customer.customerInfo.customerLanguage	String	Conditional	Customer language. ISO 639-1 Format. Must be fulfilled if intended Payment Method (Request Body.transaction.paymentMethod) to proceed payment is one of: „IDEL” – „iDEAL”;	NL
customer.customerInfo.customerPhone	String	Conditional	Phone number of the customer formatted in the International E.164 standard, starting with plus (+) symbol. E. 164 numbers can have a maximum of fifteen digits and are usually written as follows: [+][country code][subscriber number including area code] Must be fulfilled if intended Payment Method (Request Body.transaction.paymentMethod) to proceed payment is „BNPL” or „MBWAY”.	+351919191919

Billing Address (Mandatory)

Field	Type	Condition	Description	Example
customer.customerInfo.billingAddress.street1	String (Max70Text)	Mandatory	First line of the billing address (street name and number)	„Damrak 1”
customer.customerInfo.billingAddress.street2	String (Max70Text)	Mandatory	Additional address information (e.g., apartment, floor)	„Floor 2”
customer.customerInfo.billingAddress.city	String (Max35Text)	Mandatory (iDEAL)	City of the billing address	„Amsterdam”
customer.customerInfo.billingAddress.postcode	String (Max16Text)	Optional (Mandatory if available)	Postal code	„1012LG”
customer.customerInfo.billingAddress.country	String (ISO 3166-1 alpha-2)	Mandatory	Country code	„NL”

Shipping Address (Optional)

Używany wyłącznie w przypadku dostaw osobistych.

Fields	Type	Condition	Description	Example
customer.customerInfo.shippingAddress.street1	String (Max70Text)	Mandatory	First line of the shipping address	„Herengracht 10”
customer.customerInfo.shippingAddress.street2	String (Max70Text)	Mandatory	Additional shipping address information	„Unit 5A”
customer.customerInfo.shippingAddress.city	String (Max35Text)	Mandatory (iDEAL)	City of the shipping address	„Amsterdam”
customer.customerInfo.shippingAddress.postcode	String (Max16Text)	Optional (Mandatory if available)	Postal code	„1015BK”
customer.customerInfo.shippingAddress.country	String (ISO 3166-1 alpha-2)	Mandatory	Country code	„NL”

1.4 mandate – Object (Mandatory)

mandate	mandate	Conditional	Mandate details information Remark: only to be filled when Merchant wants to offer SEPA DD as payment method	–
mandate.mandateId	String (Max35Text)	Mandatory	Identification of the Direct Debit mandate resource. It refers to Debit Authorisation Number.	mandateID
mandate.mandateDescription	String (Max256Text)	Mandatory	Description of the Direct Debit mandate resource’s context.	mandateDescription
mandate.frequency	String (Exact4Text)	Mandatory	Regularity with which instructions are to be created and processed. „OOFF” – „One-Off” (Direct debit instruction where the debtor’s authorisation is used to initiate one single direct debit transaction) „RCUR” – „Recurring” (Direct debit instruction where the debtor’s authorisation is used for regular direct debit transactions initiated by the creditor)	‘OOFF’
mandate.serviceType	String (Exact4Text)	Mandatory	Identification of the SEPA Direct Debits service related to the specific Direct Debit Mandate. It can be fulfilled with the following values: „CORE” when it refers to SEPA DD CORE service; „BTOB” when it refers to SEPA DD B2B service.	‘CORE’

Przykład żądania – SEPA DD oparte na Tink

</>JSON
{ 
  "merchant": {
    "terminalId": "1000536",
    "channel": "web",
    "merchantTransactionId": "trx123",
    "transactionDescription": "order 123"
  },
  "transaction": {
    "transactionTimestamp": "2026-04-24T13:41:08Z",
    "paymentType": "AUTH",
    "amount": {
      "value": 0,
      "currency": "EUR"
    },
    "paymentMethod": ["SPDD"]
  },
  "customer": {
    "customerInfo": {
      "customerName": "Test Name",
      "customerEmail": "email@provider.com"
    }
  },
"mandate": {
        "mandateId": "mandateID",
        "mandateDescription": "mandateDescription",
        "frequency": "OOFF",
        "serviceType": "CORE"  }
}

Przykład żądania – SEPA DD oparte na iDEAL

</>JSON
{
  "transaction": {
    "amount": {
      "value": 0.01,
      "currency": "EUR"
    },
    "paymentMethod": ["SPDD","IDEL"]
  }
}

Odpowiedź – API Checkout

Po pomyślnym przetworzeniu żądania Checkout, API zwraca odpowiedź reprezentującą utworzoną sesję płatności.

Ta odpowiedź jest niezbędna do:

• identyfikacji transakcji
• kontynuowania realizacji płatności
• śledzenia cyklu życia płatności

Field	Type	Condition	Description	Example
transactionID	String (Max36Text)	Always	Unique identifier of the transaction. Must be stored for tracking and status queries	TECByGFuB7yaFta19hua
transactionSignature	String	Always	Security signature associated with the transaction	eyJ0eElkIjoiVEVD…
amount.value	Number (double)	Always	Transaction amount. ⚠️ Represents the transaction amount. For SEPA Direct Debit, this value corresponds to the actual transaction amount.	0.01
amount.currency	String (Currency Code – ISO 4217 Alpha-3 Code).	Always	Currency of the transaction	EUR
paymentMethodList	Array	Always	List of payment methods available for execution	[„IDEL”,”SPDD”]
formContext	String	Conditional (Payment Form)	Encoded data required to initialise the hosted payment execution experience	eyJQYXltZW50TWV0aG9kIj…
mandate.mandateId	String (Max35Text)	Conditional (SEPA DD)	Unique identifier of the generated SEPA mandate	v8t58W2RpGDaDbESMrnMhYGZdixsHUDZUkC
mandate.mandateDescription	String (Max254Text)	Mandatory	Description of the Direct Debit mandate resource’s context.	“short information”
mandate.frequency	String (Exact4Text)	Conditional (SEPA DD)	Mandate frequency (OOFF or RCUR)	OOFF
mandate.serviceType	String (Exact4Text)	Conditional (SEPA DD)	SEPA scheme used (CORE or B2B)	CORE
returnStatus.statusCode	String	Always	Operation status code („000” means success)	000
returnStatus.statusMsg	String	Always	Short status message	Success
serviceType	String	Always	Detailed status description	Success

Przykładowa odpowiedź

</> JSON
{
  "transactionID": "TECByGFuB7yaFta19hua",
  "transactionSignature": "eyJ0eElkIjoiVEVD...",
  "amount": {
    "value": 0.01,
    "currency": "EUR"
  },
  "paymentMethodList": ["IDEL", "SPDD"],
  "returnStatus": {
    "statusCode": "000",
    "statusMsg": "Success",
    "statusDescription": "Success"
  }
}

Jak wykorzystać odpowiedź

Po otrzymaniu pomyślnej odpowiedzi:

• Zapisz transactionID jako główny identyfikator referencyjny
• Wykorzystaj zwrócone dane do kontynuowania realizacji płatności
• Przygotuj system na obsługę aktualizacji asynchronicznych (status lub webhooki)

Jeśli korzystasz z hostowanego modelu integracji, odpowiedź zawiera dane niezbędne do zainicjowania kroku realizacji płatności

Krok 2 – Realizacja płatności

Co się dzieje w praktyce

• Wcześniej utworzona sesja płatności jest wykorzystywana do kontynuowania procesu checkout
• Klient przechodzi przez proces autoryzacji u dostawcy (Tink lub iDEAL)
• Autoryzacja mandatu oraz zbieranie wymaganych danych bankowych odbywają się w ramach procesu dostawcy

Perspektywa integracji

Z perspektywy integracji:

• Na tym etapie nie jest wymagane dodatkowe wywołanie API
• Nie oczekuje się żadnej ręcznej interwencji ani przetwarzania ze strony integratora
• Cały proces realizacji jest obsługiwany w ramach kontekstu sesji płatności zwróconego w Kroku 1

Krok 3 – Status płatności

Po zakończeniu procesu realizacji płatności (Krok 2) mandat SEPA Direct Debit kontynuuje swój cykl asynchronicznie, aż do osiągnięcia ostatecznego statusu w cyklu życia.

Akceptant może monitorować cykl życia mandatu za pomocą API Checkout Status.

Jak sprawdzić status

Endpoint

Environment	URL	Method & Endpoint
PROD	api.sibsgateway.com	GET /version-id/payments/{transactionId}/status
TEST	stargate.qly.site[1|2].sibs.pt	GET version-id/payments/status

Parametry żądania

Type	Field	Format	Condition	Description
PATH	transactionId	String	Conditional	Unikalny identyfikator transakcji
QUERY	merchantTransactionId	String (Max1000)	Conditional	Referencja akceptanta używana do pobrania statusu

Nagłówki żądania

Field	Type	Condition	Description
Content-Type	String	Mandatory	application/json
Authorization	String	Mandatory	Bearer token
x-ibm-client-id	String	Mandatory	Client identifier provided during onboarding

Co należy monitorować

Pole: mandate.mandateStatus

To pole reprezentuje cykl życia mandatu SEPA Direct Debit.

Wartości statusu

Status	Znaczenie
INTT	Zainicjowany
PDNG	Oczekujący
ACTV*	Aktywny
RJCT	Odrzucony
RFSD	Odmówiony
CNCL	Anulowany

*ACTV oznacza pomyślnie aktywowany mandat.

Rekomendacja integracyjna

Należy:

• Zapisać transactionId zwrócony w Kroku 1
• Okresowo wywoływać API Checkout Status
• Opcjonalnie zaimplementować webhooki dla powiadomień asynchronicznych

Krok 4 – Informacje dodatkowe: status pobrania (Collection Status)

Monitorowanie statusu pobrania ma zastosowanie tylko wtedy, gdy pobrania środków są inicjowane w oparciu o istniejący mandat SEPA.

Po aktywacji mandatu SEPA Direct Debit, pobrania środków mogą być inicjowane zgodnie z modelem biznesowym akceptanta.

Realizacja pobrania jest asynchroniczna i może udostępniać dodatkowe informacje o statusie za pomocą API Checkout Status.

Monitorowanie cyklu życia pobrania

Odpowiedź Checkout Status udostępnia dwa uzupełniające się pola statusu dla pobrań SEPA Direct Debit.

Pole	Cel
paymentStatus	Końcowy wynik transakcji
mandate.mandateCollection.status	Szczegółowy cykl życia pobrania SEPA Direct Debit

4.1. paymentStatus

Pole: paymentStatus

To pole reprezentuje skonsolidowany wynik transakcji z perspektywy akceptanta.

Możliwe wartości obejmują:

Status	Meaning
PENDING	Transakcja wciąż w trakcie przetwarzania
INPROCESSING	Realizacja pobrania w toku
SUCCESS	Pobranie zrealizowane pomyślnie
DECLINED	Pobranie nie powiodło się lub zostało odrzucone
ERROR	Błąd techniczny

To pole podstawowe, które należy wykorzystać do określenia ostatecznego wyniku transakcji.

4.2. mandate.mandateCollction.status

Pole: mandate.mandateCollction.status

To pole zawiera dodatkowe szczegóły operacyjne dotyczące cyklu życia pobrania SEPA Direct Debit.

Wartości statusu pobrania

Status	Meaning
CRTD	Pobranie utworzone
PDNG	Oczekujące na przetworzenie
ACSP*	Zaakceptowane, rozliczenie w toku (STATUS KOŃCOWY)
RJCT	Odrzucone
RVSL	Wycofane (Reversed)

*ACSP oznacza pomyślne zakończenie procesu pobrania SEPA Direct Debit i powinno być traktowane jako ostateczny status sukcesu.

Rekomendacja integracyjna

Z perspektywy integracji:

• Zapisz transactionId zwrócony podczas tworzenia sesji Checkout
• Monitoruj aktualizacje transakcji za pomocą API Checkout Status
• Traktuj przepływy SEPA Direct Debit jako asynchroniczne
• Opcjonalnie zaimplementuj webhooki dla automatycznych powiadomień o statusie

Krok 5 – Webhooki

Transakcje SEPA Direct Debit są z natury asynchroniczne.

Zamiast okresowo wywoływać API Checkout Status, akceptanci mogą opcjonalnie zaimplementować webhooki, aby otrzymywać automatyczne aktualizacje transakcji.

Powiadomienia webhook mogą być wykorzystywane do:

• monitorowania zmian w cyklu życia transakcji
• otrzymywania aktualizacji statusu płatności
• śledzenia przebiegu pobrania SEPA Direct Debit

Szczegóły integracji webhooków, struktura payloadu oraz konfiguracja zdarzeń znajdują się w dokumentacji integracji webhooków.