Skip to content

Przewodnik integracji

Postępuj zgodnie z poniższymi instrukcjami, aby wdrożyć Formularz płatności i rozpocząć płynne 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 Endpoint’u:

ŚrodowiskoURLMetody działania & EndpointOpis działania
PRODapi.sibsgateway.comapi/version-id/paymentsWykonuje żądanie przygotowania wymaganych danych kasy i zwraca je wraz z formularzem płatności.
TESTstargate-cer.qly.site[1|2].sibs.ptapi/version-id/paymentsWykonuje żądanie przygotowania wymaganych danych kasy 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: Uzupełnienie zamówienia o 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
Notification

Dla zalogowanych użytkowników elementy CustomerName iCustomerEmail są obowiązkowe. Dzięki temu użytkownik nie będzie musiał wypełniać ich ponownie w formularzu płatności.

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”
„PBLKY”
„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
Notification

Sprawdź tutaj instrukcje: dokonanie jednorazowego zakupu lub dokonanie wstępnie autoryzowanego przechwycenia.

Działanie 3: Uzupełnienie zamówienia o dodatkowe i opcjonalne informacje.

W tym kroku pokazujemy, że istnieje wiele opcjonalnych informacji, które można dodać, aby zakończyć tworzenie zamówienia. Sprawdź poniżej dodatkowe informacje w oparciu o niektóre przypadki użycia:

Oto przykład tworzenia zamówienia.

Body:
{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "Order Id: 5hraff455o",
        "transactionDescription": "transaction short description",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "transaction": {
        "transactionTimestamp": "2023-05-16T10:33:43.587Z",
        "description": "transaction statement description",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD",
            "BLIK",
            "PBLKV"
        ]
    }
}

Krok 2: Stwórz metodę płatności

Aby utworzyć formularz płatności, wystarczy dodać następujące linie HTML/Javascript do swojej strony i wypełnić następujące zmienne, które otrzymałeś w odpowiedzi z pierwszego kroku:

  • transactionID z checkout’u tktóre otrzymałeś w odpowiedzi z pierwszego kroku:
<script src="https://stargate-cer.qly.site1.sibs.pt/assets/js/widget.js?id={transactionID}"></script>

formContext które otrzymałeś w odpowiedzi z pierwszego kroku i formConfig:

<form class="paymentSPG" spg-context="{formContext}" spg-config="{formConfig}"></form>

formConfig jest niezbędne do prawidłowego utworzenia formularza.

formConfig -> spg-config=”{formConfig}”
{
  "paymentMethodList": [],
  "amount": {
    "value": 50.50,
    "currency": "PLN"
  },
  "language": "en",
  "redirectUrl": ""
}

Atrybut attr.spg-config to JSON w formacie string z następującymi parametrami:

ParametrTypDostępne wartościOpis
paymentMethodListString‘CARD’
‘TOKEN’
‘BLIK’
‘PBLKV’
’XPAY’
Metody płatności wyświetlane w formularzu.
Można korzystać wyłącznie z metod płatności włączonych na koncie.
amount{ value: number, currency: string }Wartość kwoty transakcji.
languageString‘pt’
‘en’
‘pl’
Z formatu języka (ISO 639-1).
redirectUrlStringAdres URL, na który użytkownik powinien zostać przekierowany po zakończeniu płatności.

Masz również możliwość dodania formStyle, aby spersonalizować swój formularz płatności. Więcej szczegółowych informacji można znaleźć na stronie Formularz niestandardowy.

Po przetworzeniu płatności wyświetlana jest strona ze statusem transakcji, a klient zostaje przekierowany na zdefiniowany adres redirectUrl.

Poniżej znajduje się domyślny wygląd formularza płatności, w którym klienci mogą płynnie wprowadzić szczegóły płatności i sfinalizować transakcję:

Krok 3: Uzyskanie statusu płatności

Status transakcji można sprawdzić, wykonując następujące czynności zapytania GET .

GET {transactionID}/status
URL zapytania:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Nagłówki zapytania:
Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>
Content-Type: application/json