Skip to content

Szybki przelew

Szybki przelew (PayByLink) to znana w Polsce metoda płatności, która umożliwia klientom płacenie za zakupy w Internecie za pomocą konta bankowego. SIBS Payment Gateway zapewnia interfejs API umożliwiający integrację z usługami szybkiego przelewu poprzez wzorzec Web Redirect.

Interfejs API umożliwia przedstawienie klientowi płatności ze wszystkimi adresowalnymi podmiotami. Gdy klient wybierze podmiot, którego chce użyć, wystarczy wywołać API, które poda Ci odpowiedni adres URL przekierowania.

Opcja płatnościKategoriaKrajeWalutyFunkcjeIntegracje
Szybki przelew (PayByLink)Bankowość onlineCzechy, Francja, Niemcy, Węgry, Portugalia, Polska, Rumunia, Słowacja, SłoweniaCZK, EUR, HUF, PLN, RONAnulowanieAPI Formularz Płatności Wtyczka Prestashop Wtyczka WooCommerce Wtyczka Magento

Jak to działa

Zanim zaczniesz, powinieneś utworzyć żądanie zamówienia z PayByLink (szybki przelew) jako metodą płatności.

Następnie należy wykonać następujące kroki:

Krok 1: Uzyskaj listę podmiotów Szybkiego przelewu i przedstaw je klientowi
Krok 2: Wywołaj API, aby uzyskać ważny link do płatności dla wybranego podmiotu
Krok 3: Uzyskaj status płatności, aby poznać wynik płatności

Krok 1: Uzyskaj listę podmiotów Szybkiego przelewu i przedstaw je klientowi

Możesz sprawdzić listę wszystkich podmiotów PayByLink (szybkiego przelewu) składających żądanie GET.

Należy pamiętać, że żądanie wymaga nagłówka autoryzacji ze znakiem mark, transactionsSignature zwróconym z operacji realizacji transakcji.

Sprawdź poniżej jak uzyskać listę kanałów płatności:

OperacjaTyp operacjiMetoda działania i punkt końcowyOpis operacjiObserwacje
Uzyskaj listę kanałów płatnościPołączenie synchronicznePOST https://{{APIHost}}/api/v1/paymentChannelsWykonaj transakcję i zgłoś Listę kanałów płatności.Content-Type: application/x-www-form-urlencoded
LokalizacjaElement danychTypStanOpis
Nagłówek HTTPAutoryzacjaCiągOpcjonalnyPrzykład: Nośnik *accessToken* Token dostępu użytkownika. Musi to być schemat na okaziciela. Nie dotyczy płatności hybrydowych.
Nagłówek/autoryzacja HTTPIdentyfikator klientaKlucz APIObowiązkowyIdentyfikator klienta projektu. Należy podać w nagłówku każdego żądania.
Nagłówek/autoryzacja HTTPClient-SecretKlucz APIObowiązkowySekret klienta projektu. Należy podać w nagłówku każdego żądania.
Parametr zapytaniacountryCodeCiągOpcjonalnyKod kraju, według którego chcesz uzyskać listę banków (ISO 3166-1 alfa-2). Dostępne kody krajów można uzyskać z punktu końcowego /auth/countries.
Notification

W tym żądaniu token okaziciela zostaje zastąpiony przez odpowiedź z kasy transactionSignature.

 

countryCode(opcjonalne) – Pole wejściowe umożliwiające filtrowanie adresowanych banków według kraju (jeśli nie podano, zwracane są wszystkie banki ze wszystkich krajów).

 

countryCode(opcjonalne) – Pole wyjściowe informujące do jakiego kraju należy dany bank.

Oczekiwana odpowiedź:

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i returnStatus.statusCode=”000″.

W przypadku pomyślnych odpowiedzi otrzymasz następujące dodatkowe dane:

Payment Channels List (Mandatory)

"paymentChannels": [
		{
		"gatewayId": "PBL Gateway ID",
		"gatewayName": "Name to present to customer",
		"gatewayType": "PBL",
		"bankName": "technical bank name",
		"iconURL" : "https://paybylink.bank.pl/grafika/pbl.gif"
		}
]

Regulations (Optional)

Tutaj znajdziesz szczegółowe informacje, takie jak nazwa_nabywcy, logo_nabywcy, logo marki, link do Regulaminu:

"paymentChannels": [
		{
		"gatewayId": "PBL Gateway ID",
		"gatewayName": "Name to present to customer",
		"gatewayType": "PBL",
		"bankName": "technical bank name",
		"iconURL" : "https://paybylink.bank.pl/grafika/pbl.gif"
		}
]

W przypadku otrzymania wykazu regulaminów należy je pokazać Klientowi wraz z hiperłączem do adresu URL.

Krok 2: Wywołaj API, aby uzyskać ważny link do płatności dla wybranego podmiotu

Pamiętaj, że poniższe żądanie wymaga nagłówka autoryzacji z podpisem transakcji zwróconym z operacji realizacji transakcji i powinieneś uwzględnić te dwa elementy poniżej:

Element danychTypStanOpis
gatewayIdCiągObowiązkowyIdentyfikator kanału płatności dla kanału, którego klient zamierza użyć do dokonania płatności.
userAcceptanceIndicatorWartość logicznaObowiązkowyWskazuje, czy użytkownik zaakceptował Regulamin w celu kontynuowania płatności.

W tym żądaniu token okaziciela zostaje zastąpiony odpowiedzią kasy „transactionSignature”.

Oto przykład:

Adres URL żądania:
https://stargate-cer.qly.site1.sibs.pt/api/v2/payments/{transactionID}/pbl/payment-link
Nagłówki żądań:
Authorization: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
{
    "info": {
        "deviceInfo": {
            "browserAcceptHeader": "application/json, text/plain, */*",
            "browserJavaEnabled": "false",
            "browserLanguage": "en",
            "browserColorDepth": "24",
            "browserScreenHeight": "1080",
            "browserScreenWidth": "1920",
            "browserTZ": "-60",
            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
            "systemFamily": "Windows",
            "systemVersion": "Windows",
            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
            "applicationName": "Chrome",
            "applicationVersion": "106"
        },
        "customerInfo": [
            {
                "key": "customerName",
                "value": "DIOGO M"
            },
            {
                "key": "customerEmail",
                "value": "{{CustomerEmail}}"
            }
        ]
    },
    "gatewayId": "PL_TEST",
    "userAcceptanceIndicator": true,
    "merchant": {
        "merchantURL": "https://egadget2.azurewebsites.net/#/returns?id=4qm1q5p6eTgzREWYHRPA"
    }
}

Po zakończeniu operacji powinieneś otrzymać status oczekującej płatności.

Użytkownik zostanie przekierowany do środowiska PBL w celu potwierdzenia płatności, a następnie z powrotem na adres URL sprzedawcy.

{
    "transactionID": "UEBfud1Xg5XZwwfCWWR8",
    "execution": {
        "startTime": "2023-06-20T09:24:25.504Z",
        "endTime": "2023-06-20T09:24:28.415Z"
    },
    "paymentStatus": "Pending",
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    },
    "redirectURL": "https://psd2.kevin.eu/login/1c5c539b-3e48-4971-bed5-4172a58601a9?redirectPreferred=true&bankId=KEVIN_PL_TEST&lang=PL"
}

Krok 3: Uzyskaj status płatności, aby poznać wynik płatności

Po całkowitym przetworzeniu płatności możesz sprawdzić status swojej transakcji, wysyłając żądanie GET.

Nagłówek HTTP autoryzacji jest ustawiony na token okaziciela, tak jak był używany podczas początkowej realizacji transakcji.

OperacjaTyp operacjiMetoda działania i punkt końcowyOpis operacji
Uzyskaj status płatnościPołączenie synchroniczneGET /api/v1/payment/{transactionId}/statusUzyskaj status płatności
Body:
LokalizacjaElement danychTypStanOpis
Parametr zapytaniatransactionIdCiągObowiązkowyIdentyfikacja płatności. Przykład: 9078fbb0-fced-4606-95c7-4989f06ee253
Nagłówek HTTPAutoryzacjaCiągOpcjonalnyPrzykład: Nośnik *accessToken* Token dostępu użytkownika. Musi to być schemat na okaziciela. Nie dotyczy płatności hybrydowych.
Nagłówek/autoryzacja HTTPIdentyfikator klientaKlucz APIObowiązkowyIdentyfikator klienta projektu. Należy podać w nagłówku każdego żądania.
Nagłówek/autoryzacja HTTPClient-SecretKlucz APIObowiązkowySekret klienta projektu. Należy podać w nagłówku każdego żądania.
Oczekiwana odpowiedź pomyślna:
{
    "merchant": {
        "terminalId": "101778",
        "merchantTransactionId": "Order Id: r7cxvi0saj"
    },
    "transactionID": "J120XDzUq2u4UwVDSZBt",
    "amount": {
        "currency": "PLN",
        "value": "50.50"
    },
    "paymentType": "PURS",
    "paymentStatus": "Success",
    "paymentMethod": "PBLKV",
    "execution": {
        "endTime": "2023-06-20T10:07:27.771Z",
        "startTime": "2023-06-20T10:07:27.701Z"
    },
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    }
}

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i wartości returnStatus.statusCode=”000″.

Oto kilka przykładów możliwych kodów wyników:

Kod wynikustatusMsgOpisAkcja
HTTP-200SukcesOdpowiedź powodzeniaNie dotyczy
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 prawidłowej 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.