Skip to content

Przewodnik integracji

Wykorzystaj nasze API do otrzymywania płatności i stwórz własny formularz płatności, aby uzyskać pełną kontrolę nad wyglądem i doświadczeniem użytkownika na stronie płatności. Postępuj zgodnie z poniższymi instrukcjami, aby rozpocząć przyjmowanie płatności.

Krok 1: Utwórz zamówienie

W tym kroku opisano, jak utworzyć zamówienie, gdy kupujący jest gotowy do zapłaty.

Dostępny docelowy adres URL punktu końcowego (Endpoint):

ŚrodowiskoURLMetoda działania i punkt końcowyOpis operacji
PRODapi.sibsgateway.comPOST api/version-id/paymentsWykonuje żądanie przygotowania wymaganych danych checkout’u i zwraca je wraz z formularzem płatności.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST api/version-id/paymentsWykonuje żądanie przygotowania wymaganych danych checkout’u i zwraca je wraz z formularzem płatności.

Jeśli chodzi o dane wymagane do utworzenia zamówienia, proces jest prosty i wymaga tylko kilku czynności:

Działanie 1: Zdefiniowanie nagłówka i dodanie informacji o sprzedawcy i kliencie
Działanie 2: Dodanie informacji o transakcji do zamówienia
Działanie 3: Wypełnij zamówienie, podając dodatkowe i opcjonalne informacje.
Działanie 1: Zdefiniowanie nagłówka i dodanie informacji o sprzedawcy i kliencie

Sprawdź poniżej pełny opis wymaganych danych, aby rozpocząć tworzenie zamówienia

Parametry nagłówka
Content-type

string

Mandatory

application/json

Show more
Authorization

string

Mandatory

Bearer Token. Based on OAuth2 authentication performed in a pre-step.

Show more
x-ibm-client-id

string

Mandatory

Token that identifies a client organization. It is provided during onboarding process and must be used in every call.

Show more
Parametry żądania
merchant

object

Mandatory

An optional element to query transaction status.

Show more
terminalID

numeric [<= 10 characters]

Mandatory

Merchant Terminal Identification.

Show more
channel

String

Mandatory

Merchant channel, Possible Value “Web”.

Show more
merchantTransactionID

string

Mandatory

Unique Id used by the Merchant.

Show more
transactionDescription

string

Mandatory

Merchant Transaction Short Description.

Show more
shopURL

string

Mandatory

Merchant Shop URL for redirect purposes.

Show more
websiteAddress

string

Mandatory

Merchant’s website identifier for customer redirection.

Show more
customer

object

Mandatory

Object that defines a customer.

Show more
customerInfo

object

Mandatory

Object that defines the predefined customer information.

Show more
customerName

string

Mandatory

Customer Name.

Show more
customerEmail

string

Mandatory

Customer e-mail

Show more
customerLanguage

language code ISO 639-1

Conditional

Customer language

This element is mandatory if intended payment method is one of the following:

„BNCT” – „Bancontact”;
„IDEL” – iDEAL;
„SFRT” – „Sofort”;
“PY24” – “Przelewy24”

Show more
shippingAddress

address

Optional

Customer Address. When applicable used for shipping products.

Show more
street 1

string <= 70 characters

Mandatory

Shipping address street.

Show more
street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

Show more
city

string <= 35 characters

Mandatory

Shipping address city or town.

Show more
postcode

string <= 16 characters

Mandatory

Shipping address Postal Code.

Show more
countrySubDivision

Country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

Show more
billingAddress

Address

Optional

Customer billing address.

Show more
street 1

string <= 70 characters

Mandatory

Shipping address street.

Show more
street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

Show more
city

string <= 35 characters

Mandatory

Shipping address city or town.

Show more
postcode

string <= 60 characters

Mandatory

Shipping address Postal Code.

Show more
countrySubDivision

country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

Show more
billingAddressSameAsShippingAddress

boolean

Optional

Flag to identify if the billing address is the same of shipping address.

Show more
Działanie 2: Dodanie informacji o transakcji do zamówienia

Teraz nadszedł czas, aby dołączyć informacje o transakcjach w oparciu o metody płatności, które chcesz wyświetlać w swoim paywallu.

Parametry żądania: application/json
transaction

object

Mandatory

Object that defines a transaction.

Show more
transactionTimeStamp

ISODateTime

Mandatory

Transaction timestamp.

Show more
description

string <= 70 characters

Mandatory

Transaction short description.

Show more
moto

boolean

Mandatory

Indicates if is a Mail Order Telephone Order.

Show more
paymentType

allowed values:
“PURS” – Purchase
“AUTH” – Authorization

Mandatory

Define the of payment used by the client.

Show more
paymentMethod

allowed values:
„CARD”
„TOKEN”
„PBLKV”
„BLIK”
„XPAY”
„BNPL”
„SFRT”
„IDEL”
„BNCT”
“PY24”
“CRTB”

Mandatory

Method of payment used by the client.

Show more
amount
Mandatory

Parameter with the value and currency of the transaction.

Show more
value

number: Double

Mandatory

Amount in the transaction.

Show more
currency

currency code:
ISO 4217 Alpha-3 Code

Mandatory

Currency used in the transaction.

Show more
Działanie 3: Wypełnij zamówienie, podając dodatkowe i opcjonalne informacje.

W tym kroku pokazujemy, że istnieje wiele opcjonalnych informacji, które można dodać, aby zakończyć tworzenie zamówienia. Poniżej znajdują się dodatkowe informacje oparte na niektórych przypadkach użycia:

Oto przykład tworzenia zamówienia:

Treść żądania:
{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "Order Id: 9bzraklk4v",
        "transactionDescription": "transaction short description",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "transaction": {
        "transactionTimestamp": "2023-05-15T20:11:11.488Z",
        "description": "transaction statement description",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD",
            "BLIK",
            "PBLKV"
        ]
    }
}

Krok 2: Uzyskanie odpowiedzi

Odpowiedź zawieta statusMsg, transactionID, transactionSignature listę dostępnych paymentMethodList które można wyświetlić.

Przykład odpowiedzi:
{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "string"
    },
    "transactionID": "42f59038f3f14e618d091da8bf3b717e9999",
    "transactionSignature": "42f59038f3f14e618d091da8bf3b717e9999",
    "amount": {
        "value": 50.50,
        "currency": "PLN"
    },
    "merchant": {
        "terminalId": 47215,
        "channel": "web",
        "merchantTransactionId": "5351136",
        "transactionDescription": "string",
        "shopURL": "string",
        "websiteAddress": "string"
    },
    "paymentMethodList": "",
    "tokenList": []
}

Odpowiedź zawiera statusMsg które mogą przyjmować różne wartości:

Kod wynikustatusMsgOpisAkcja
HTTP-200SukcesOdpowiedź sukcesun/a
HTTP-400Zła prośbaŁadunek JSON nie jest zgodny z definicją API lub brakuje niektórych obowiązkowych nagłówków HTTP.Sprawdź w API Market poprawną składnię.
HTTP-401NieautoryzowanyW przypadku Autoryzacji token okaziciela jest nieprawidłowy/wygasł lub nie jest powiązany z używanym terminalem.Sprawdź w SIBS Backoffice w sekcji Poświadczenia, czy token jest ważny i w razie potrzeby utwórz nowy.
HTTP-403ZabronionyIdentyfikator klienta ustawiony w nagłówku HTTP X-IBM-Client-Id jest nieprawidłowy lub nie posiada ważnej subskrypcji interfejsu API.Sprawdź w SIBS Backoffice w SPG APP 2.0, czy ClientID jest poprawny. Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu zresetowania ClientID.
HTTP-405Niedozwolona metodaZastosowana metoda HTTP nie jest zgodna z żadną dostępną definicją API.Sprawdź w API Market poprawną metodę HTTP.
HTTP-429Zbyt dużo zapytańPrzekroczono limit szybkości wywołań API.Informacje na temat limitów stawek mających zastosowanie do API można znaleźć w API Market.
HTTP-500Wewnętrzny błąd serweraWywołanie API nie powiodło się… i najprawdopodobniej jest to po naszej stronie.Powinieneś ponowić operację, a jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną SIBS Gateway w celu uzyskania pomocy.
HTTP-503serwis niedostępnyWywołanie API nie jest obecnie dostępne. Zwykle jesteśmy zawsze aktywni, ale podczas planowej konserwacji mogą wystąpić krótkie problemy z dostępnością.Powinieneś poczekać i spróbować ponownie później.

Krok 3: Dokonaj płatności

Po utworzeniu i przesłaniu zamówienia z danymi płatności kupującego, który zdecyduje się zapłacić za pomocą metody płatności wymagającej przekierowania, należy złożyć wniosek o płatność do SIBS Gateway.

Sprawdź instrukcje dotyczące dokonywania płatności za pomocą każdego rodzaju metody płatności: