1. Przegląd

Ta sekcja opisuje, w jaki sposób SIBS Gateway przekazuje wyniki transakcji dla wszystkich metod płatności.

Każda odpowiedź zawiera:

• Identyfikator metody płatności
• Kod powodu odrzucenia
• Kod statusu HTTP
• Zewnętrzny kod statusu
• Zewnętrzny opis statusu

Te wartości pozwalają zrozumieć, dlaczego transakcja nie została pomyślnie zakończona oraz jak odpowiednio obsłużyć odpowiedź.

2. Model interpretacji odpowiedzi

Odpowiedzi SIBS Gateway mają strukturę warstwową:

Warstwa 1 — Kod statusu HTTP
Wskazuje wynik żądania na poziomie transportowym.

Warstwa 2 — Status biznesowy (returnStatus.statusCode)
Wskazuje wynik decyzji transakcyjnej (akceptacja, odrzucenie, błąd).

Warstwa 3 — Opis statusu
Komunikat zrozumiały dla człowieka, używany wyłącznie do logowania i debugowania.

3. Kody statusu HTTP

API SIBS Stargate używa standardowych kodów statusu HTTP do wskazania wyniku żądań API.

Kody statusu HTTP odzwierciedlają sukces lub niepowodzenie na poziomie transportowym. Szczegóły na poziomie biznesowym są zwracane w treści odpowiedzi.

Grupy kodów statusu HTTP

Kategoria	Opis
1xx	Informacyjne – komunikacja na poziomie protokołu
2xx	Sukces – żądanie zostało poprawnie przetworzone
3xx	Przekierowanie – wymagane dalsze działanie
4xx	Błąd klienta – nieprawidłowe żądanie lub problem z uprawnieniami
5xx	Błąd serwera – niepowodzenie przetwarzania po stronie SIBS

Kod statusu HTTP	Komunikat statusu HTTP	Opis
200	Ok	Żądanie zostało poprawnie przetworzone, a odpowiedź zawiera żądany wynik.
201	Created	Żądanie zostało poprawnie przetworzone i utworzono nowy zasób.
202	Accepted	Żądanie zostało przyjęte do przetworzenia, ale nie zostało jeszcze zrealizowane.
204	No Content	Żądanie zostało poprawnie przetworzone i nie zwrócono treści odpowiedzi.
300	Multiple Choices	Żądany zasób ma wiele możliwych reprezentacji, a klient może wybrać jedną z nich.
301	Moved Permanently	Żądany zasób został trwale przeniesiony do nowej lokalizacji. Kolejne żądania powinny korzystać z nowego URI.
302	Found	Żądany zasób jest tymczasowo dostępny w innej lokalizacji.
303	See Other	Odpowiedź można uzyskać za pomocą żądania GET na URI podanym w odpowiedzi.
307	Temporary Redirect	Żądanie powinno zostać powtórzone tą samą metodą HTTP na URI podanym w odpowiedzi.
400	Bad Request	Żądanie nie mogło zostać przetworzone z powodu nieprawidłowych lub brakujących informacji. Żądanie nie powinno być powtarzane bez zmian.
401	Unauthorized	Niepowodzenie uwierzytelnienia lub brak ważnych danych uwierzytelniających.
403	Forbidden	Żądanie zostało zrozumiane, ale nie mogło zostać przetworzone z powodu niewystarczających uprawnień lub ograniczeń biznesowych.
404	Not Found	Żądany zasób lub transakcja nie została znaleziona.
405	Method Not Allowed	Metoda HTTP użyta w żądaniu nie jest obsługiwana dla docelowego zasobu.
408	Request Timeout	Serwer przekroczył czas oczekiwania na żądanie. Można spróbować ponownie później.
500	Internal Server Error	Wystąpił nieoczekiwany błąd podczas przetwarzania żądania. Ponowne wysłanie może się powieść.
503	Service Unavailable	Usługa jest tymczasowo niedostępna z powodu konserwacji lub przeciążenia. Spróbuj ponownie później.

4. Przykład odpowiedzi błędu

API SIBS Stargate używa standardowych kodów statusu HTTP do wskazania ogólnego wyniku żądania.

Dodatkowe szczegóły transakcji są zwracane w ciele odpowiedzi w polach statusCode i statusDescription.

{
  "returnStatus": {
    "statusCode": "E0112",
    "statusMsg": "DECLINED",
    "statusDescription": "Transaction failed due to insufficient funds or exceed limits"
  },
  "transactionID": "42f59038f3f14e618d091da8bf3b717e9999",
  "paymentMethodList": [
    "BLIK"
  ],
  "amount": {
    "value": 50.50,
    "currency": "EUR"
  }
}

5. Użycie pól

Pola te powinny być wykorzystywane do prawidłowej interpretacji nieudanych transakcji i implementacji logiki integracyjnej.

Pole	Opis	Zastosowanie
statusCode	Główne pole decyzyjne dla logiki integracji	Routing / ponowne próby / obsługa błędów
statusMsg	Wysokopoziomowa klasyfikacja statusu (SUCCESS / DECLINED / ERROR)	Logowanie / monitorowanie
statusDescription	Komunikat zrozumiały dla człowieka	Debugowanie / logi

6. Referencje kodów błędów

Poniższe sekcje przedstawiają kody błędów zwracane dla obsługiwanych metod płatności i usług platformy SIBS.

6.1. BLIK – Kody błędów

HTTP CODE	ERROR CODE	ERROR DESCRIPTION
400	E0104	Amount limit exceeded
400	E0110	Transaction rejected by financial institution
400	E0111	Transaction has expired
400	E0112	Transaction failed due to insufficient funds or exceed limits
400	E0201	Declined operation
400	E0547	Refund time limit reached
400	E0910	Incorrect or Expired BLIK Code
404	E0305	Transaction not found
404	E0548	Alias not found or inactive
500	E0923	Issuer Bank not available
500	E9999	SIBS internal error

6.2. Bizum / iDEAL / Bancontact – Error Codes

HTTP CODE	ERROR CODE	ERROR DESCRIPTION
400	E0101	Invalid request, data is missing or is invalid
400	E0201	Declined operation
403	E0201	Declined operation
500	E9999	SIBS internal error
500	T9999	SIBS temporary internal error

6.3. Card / Token / XPay – Error Codes

HTTP CODE	ERROR CODE	ERROR DESCRIPTION
400	E0109	Invalid request, requires authentication
400	E0702	Specific issue, please require further verification by the bank
400	E0703	The merchant is not authorized to process the transaction
400	E0704	The card has been flagged for pickup
400	E0706	A general processing error occurred.
400	E0707	The card is flagged for pickup due to a specific issue.
400	E0713	The transaction amount is invalid.
400	E0714	The card number entered does not match any valid accounts
400	E0715	The card-issuing bank does not exist or cannot be identified
400	E0719	The transaction should be reattempted due to an issue.
400	E0725	The transaction or account details could not be found in the bank’s system.
400	E0730	The transaction request format is incorrect
400	E0731	The issuing bank does not support this type of transaction or card
400	E0738	The cardholder has entered an incorrect PIN too many times, the card is flagged for pickup
400	E0741	The card has been reported lost.
400	E0743	The card has been reported stolen.
400	E0745	The cardholder’s account has been closed and cannot process transactions.
400	E0746	Additional verification is needed before the transaction can proceed.
400	E0751	Not sufficient funds.
400	E0754	The card has expired and is no longer valid for transactions.
400	E0761	The transaction amount exceeds the cardholder’s allowed withdrawal limit.
400	E0763	A security rule was triggered, preventing the transaction.
400	E0764	The amount entered does not match the original transaction details.
400	E0901	Invalid acceptor, creditor, account or mandate details
401	E0758	The terminal is not authorized to process this type of transaction
403	E0701	The transaction was declined, cardholder must contact issuing bank for more details
403	E0705	The issuing bank declined the transaction without specifying a reason
403	E0712	The transaction is not allowed under the card’s terms or settings
403	E0755	The cardholder entered an incorrect PIN
403	E0757	The cardholder is not authorized to perform this transaction.
403	E0759	The transaction has been declined due to suspected fraudulent activity.
403	E0762	The card is restricted and cannot be used for this transaction.
403	E0770	The issuing bank has blocked the transaction.
403	E0775	The cardholder has entered an incorrect PIN too many times.
500	E9999	SIBS internal error
503	E0791	The issuing bank or network switch is temporarily unavailable.
503	E0792Invalid request, data is missing or is invalid	The transaction could not be properly routed to the correct financial institution.

6.4. SEPA Direct Debit / SEPA Credit Transfer – Error Codes

HTTP CODE	ERROR CODE	ERROR STATUS DESCRIPTION
400	AG02	Invalid operation type
400	FF01	Invalid operation type
400	AM04	Not sufficient funds.
400	MD01	Invalid acceptor, creditor, account or mandate details
400	AC01	Account identifier incorrect
400	AC06	Account blocked for direct debit by the debtor
400	AG01	Regulatory reason
400	RR01	Regulatory reason
400	RR02	Regulatory reason
400	RR03	Regulatory reason
400	RR04	Regulatory reason
400	AM05	Duplicate collection
400	BE05	Identifier of the Creditor incorrect
400	FF05	Direct debit type incorrect
400	MD06	Disputed authorized transaction
400	MD07	Debtor deceased
400	MS02	Refusal by the debtor
400	RC01	Reason not specified
400	SL01	Specific Service offered by the debtor ban
400	MS03	SIBS internal error
403	AC04	Account closed

6.5. MB Way – Error Codes

HTTP CODE	ERROR CODE	ERROR DESCRIPTION
400	E0502	Not possible to associate MB WAY to the provided alias
400	E0508	Invalid MB WAY authorised payment amount
400	E0509	MB WAY Authorised Payment monthly amount limit reached
400	E0511	MB WAY Authorized Payment merchant limits reached
400	E0512	Ineligible MB WAY Authorized Payment for the MB WAY alias
400	E0513	MB WAY Authorized Payment invalid expiration date
400	E0514	MB WAY Authorized Payment creation timeout
400	E0516	MB WAY Authorized Payment not created. Cardholder did not accept the operation.
400	E0519	MB WAY Authorized Payment Cancelation timeout
400	E0520	MB WAY Authorized Payment already cancelled
400	E0522	MB WAY Authorized payment disabled
400	E0533	MB WAY purchase with an invalid card
400	E0534	MB WAY purchase with an invalid card data
400	E0536	MB WAY Authorized Payment creation error
400	E0538	MB WAY Authorized Payment is suspended
400	E0539	MB WAY Authorized Payment – Invalid Payment method
400	E0540	MB WAY Authorized Payment Data is missing
400	E0541	MB WAY Authorized Payment Service is inactive
400	E0542	MB WAY Authorized Payment Already Exists.
400	E0543	MB WAY Authorized Payment is Cancelled
400	E0544	MBWAY Authorized Payment Data does not match operation data
400	E0545	MB WAY Authorized Payment Unavailable
400	E0546	MB WAY Authorized Payment invalid status
403	E0526	Declined operation
404	E0507	Unknown MB WAY Authorized Payment
500	E9999	SIBS internal error
500	T9999	SIBS temporary internal error

6.6. Cartes Bancaires / Token for Cartes Bancaire – Error Codes

HTTP CODE	ERROR CODE	ERROR DESCRIPTION
400	E0101	Invalid request, data is missing or is invalid
400	E0302	No agreement found
403	E0201	Declined operation
500	E9999	SIBS internal error
500	T9999	SIBS temporary internal error

6.8. SIBS Gateway — General Error Codes

HTTP CODE	ERROR CODE	ERROR STATUS DESCRIPTION
400	E0101	Invalid request, data is missing or is invalid
400	E0102	Invalid or missing data for the payment type
400	E0103	3D Secure Authentication failed
400	E0104	Amount limit exceeded
400	E0105	Authorized Payment – Invalid Payment method
400	E0106	Invalid terminal
400	E0107	Authorized Payment Unknown
400	E0108	Invalid webhook configuration
400	E0110	Transaction rejected by financial institution
400	E0201	Declined, recurring payment is deactivated
400	E0201	Declined operation
400	E0202	Declined operation
400	E0302	No agreement found
400	E0303	Operation not supported
400	E0304	Transaction already finalized
400	E0305	Transaction not found
400	E0306	Wrong parameterization for the payment method
400	E0307	Wrong parameterization for the payment type
400	E0500	Operation was not accepted by the card holder
400	E0501	Invalid request, data is missing or is invalid
400	E0503	The provided alias is not correct
400	E0504	The provided alias has an invalid format
400	E0505	The provided alias is duplicated
400	E0506	The provided alias does not exists
400	E0515	Operation Rejected due to fraud suspicion
400	E0521	Invalid operation type
400	E0524	Invalid terminal
400	E0525	Invalid Amount
400	E0526	Declined operation
400	E0527	Invalid original transaction
400	E0528	Authorization is cancelled.
400	E0529	Authorization was already used
400	E0530	Refund amount exceeds purchase amount
400	E0531	Invalid refund amount
400	E0532	Cancellation amount exceeds the authorized amount
400	E0535	Transaction already refunded
400	E0537	Invalid Service Provider
400	E0547	Refund time limit reached
400	E0900	Invalid authentication or authorization Data
400	E0901	Invalid acceptor, creditor, account or mandate details
400	E0902	Invalid Amount
400	E0903	Invalid Currency
400	E0904	Invalid link to pay
400	E0905	Invalid Mandate date
400	E0906	Invalid merchant or terminal code
400	E0908	Invalid settlement points
400	E9999	SIBS internal error
401	E0301	Merchant credentials error
403	E0201	Declined operation
403	E0202	Declined operation
404	E0101	Invalid request, data is missing or is invalid
404	E0106	Invalid terminal
404	E0302	No agreement found
404	E0305	Transaction not found
404	E0904	Invalid link to pay
404	E0901	Invalid acceptor, creditor, account or mandate details
404	E0906	Invalid merchant or terminal code
404	E0908	Invalid settlement points
405	E0201	Declined operation
408	E9999	SIBS Internal error
408	T9999	SIBS Temporary internal error
408	T999	SIBS temporary error
500	E9999	SIBS Internal error
500	T9999	SIBS temporary internal error
500	T999	SIBS temporary internal error
503	E9999	SIBS Internal error
503	T9999	SIBS temporary internal error
503	E999	SIBS Internal Error

7. Wytyczne integracji

Podczas przetwarzania nieudanych transakcji:

• Używaj kodu statusu HTTP do identyfikacji błędów transportu
• Używaj pola statusCode do logiki decyzji biznesowych
• Używaj opisu błędu do logowania i rozwiązywania problemów
• Nie powtarzaj walidacji ani operacji odrzuconych przez użytkownika
• Ponawiaj błędy tymczasowe lub związane z timeoutem stosując wykładniczy backoff
• Sprawdź status transakcji przed ponownym wysłaniem w przypadku timeoutu

8. Najlepsze praktyki obsługi błędów

Poniższe zalecenia stanowią ogólne wytyczne dotyczące obsługi nieudanych transakcji oraz wdrażania spójnych strategii ponawiania i walidacji dla różnych metod płatności.

SCENARIO TYPE	RECOMMENDED ACTION
Błędy walidacji	Sprawdź dane żądania przed ponownym wysłaniem
Błędy uwierzytelnienia	Zweryfikuj dane uwierzytelniające i nagłówki autoryzacji
Operacje odrzucone przez użytkownika	Nie powtarzaj automatycznie
Błędy timeout	Sprawdź status transakcji przed ponownym wysłaniem
Błędy wewnętrzne	Ponów z wykładniczym backoff lub skontaktuj się z pomocą techniczną