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:

Środowisko	URL	Metody działania & Endpoint	Opis działania
PROD	api.sibsgateway.com	api/version-id/payments	Wykonuje żądanie przygotowania wymaganych danych kasy i zwraca je wraz z formularzem płatności.
TEST	stargate-cer.qly.site[1\|2].sibs.pt	api/version-id/payments	Wykonuje żą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

Authorization

string

Mandatory

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

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.

Parametry żądania

merchant

object

Mandatory

An optional element to query transaction status.

terminalID

numeric [<= 10 characters]

Mandatory

Merchant Terminal Identification.

channel

String

Mandatory

Merchant channel, Possible Value “Web”.

merchantTransactionID

string

Mandatory

Unique Id used by the Merchant.

transactionDescription

string

Mandatory

Merchant Transaction Short Description.

shopURL

string

Mandatory

Merchant Shop URL for redirect purposes.

websiteAddress

string

Mandatory

Merchant’s website identifier for customer redirection.

customer

object

Mandatory

Object that defines a customer.

customerInfo

object

Mandatory

Object that defines the predefined customer information.

customerName

string

Mandatory

Customer Name.

customerEmail

string

Mandatory

Customer e-mail

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”

shippingAddress

address

Optional

Customer Address. When applicable used for shipping products.

street 1

string <= 70 characters

Mandatory

Shipping address street.

street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

city

string <= 35 characters

Mandatory

Shipping address city or town.

postcode

string <= 16 characters

Mandatory

Shipping address Postal Code.

countrySubDivision

Country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

billingAddress

Address

Optional

Customer billing address.

street 1

string <= 70 characters

Mandatory

Shipping address street.

street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

city

string <= 35 characters

Mandatory

Shipping address city or town.

postcode

string <= 60 characters

Mandatory

Shipping address Postal Code.

countrySubDivision

country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

billingAddressSameAsShippingAddress

boolean

Optional

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

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.

transactionTimeStamp

ISODateTime

Mandatory

Transaction timestamp.

description

string <= 70 characters

Mandatory

Transaction short description.

moto

boolean

Mandatory

Indicates if is a Mail Order Telephone Order.

paymentType

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

Mandatory

Define the of payment used by the client.

paymentMethod

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

Mandatory

Method of payment used by the client.

amount

Mandatory

Parameter with the value and currency of the transaction.

value

number: Double

Mandatory

Amount in the transaction.

currency

currency code:
ISO 4217 Alpha-3 Code

Mandatory

Currency used in the transaction.

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.

Uruchom w Postman

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:

Parametr	Typ	Dostępne wartości	Opis
paymentMethodList	String	‘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.
language	String	‘cs’ ‘de’ ‘en’ ‘fr’ ‘nl’ ‘pl’	Z formatu języka (ISO 639-1).
redirectUrl	String	–	Adres 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

<img data-tf-not-load src="https://www.docs.pay.sibs.com/wp-content/uploads/2023/06/SIBSdocs_logoMobile.svg" width="200" height="1" class="wp-post-image wp-image-9664" title="SIBSdocs_logoMobile" alt="SIBSdocs_logoMobile">

Przewodnik integracji

Krok 1: Utwórz zamówienie

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

Parametry nagłówka

Parametry żądania

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

Parametry żądania: application/json

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

Body:

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

formConfig -> spg-config=”{formConfig}”

Krok 3: Uzyskanie statusu płatności

URL zapytania:

Nagłówki zapytania:

On this page: