Skip to content

Pay By Link

Pay By Link is a well-known payment method in Poland that allows customers paying their online shopping using their Bank accounts. SIBS Payment Gateway provides the API to integrate with Pay By Link services through the Web Redirect pattern.

The API provides the means to present your customer with the payment wall with all addressable entities. Once the customer chooses the entity to use, just call the API that will provide you with the appropriate redirect URL.

Payment optionCategoryCountriesCurrenciesFeaturesIntegrations
PayByLinkOnline BankingCzech Republic, France, Germany,
Hungary, Portugal, Poland, Romania, Slovakia, Slovenia
CZK, EUR, HUF, PLN, RONPartial refund
Refunds
Cancellation
API
Payment Form
Prestashop Plugin
WooCommerce Plugin
Magento Plugin

How it works

Before you start, you should create the order request with PayByLink as payment method.

After that, you should perform the following steps:

Step 1: Get the list of all PayByLink entities and present them to the customer
Step 2: Call the API to get a valid Payment Link for chosen entity
Step 3: Get the Payment Status to know the payment result

Step 1: Get the list of PayByLink entities and present them to the customer

You can check the list of all PayByLink entities making a GET request.

Please note that the request needs an Authorisation Header with the transactionsSignature returned from checkout operation.

Check below how to get the payment channels list:

OperationOperation TypeOperation Method & EndpointOperation DescriptionObservations
Get Payment Channels ListSynchronous CallPOST https://{{APIHost}}/api/v1/paymentChannelsPerform the transaction and report the Payment Channel List.Content-Type: application/x-www-form-urlencoded
LocationData ElementTypeConditionDescription
HTTP HeaderAuthorizationStringOptionalExample: Bearer *accessToken*
User’s access token. Must be Bearer scheme. Not applicable for hybrid payments.
HTTP Header/AuthorizationClient-IdAPI KeyMandatoryProject’s client id. Must be provided in a header with each request. 
HTTP Header/AuthorizationClient-SecretAPI KeyMandatoryProject’s client secret. Must be provided in a header with each request. 
Query ParametercountryCodeStringOptionalCountry code by which you want to get a list of banks (ISO 3166-1 alpha-2).
Available country codes can be obtained from /auth/countries endpoint.
Notification

In this request, the Bearer Token is replaced by the checkout response transactionSignature

 

countryCode(optional) – Input field to filter addressable banks by country (when not provided, all banks from all countries are returned).

 

countryCode(optional) – Output field to inform to which country each bank belongs.

Expected response:

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

For successful responses you will receive the following additional data:

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)

Here you will find details like the acquirer_name, acquirer_logo, brand logos, Terms & Conditions link:

"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"}
]

In case you receive a list of regulations you are required to show them to the customer with an hyperlink to the URL.

Step 2: Call the API to get a valid Payment Link for the chosen entity

Note that the following request needs an Authorization Header with the transactionsSignature returned from checkout operation and you should include these two elements below:

Data ElementTypeConditionDescription
gatewayId StringMandatoryPayment Channel identifier for the channel the Customer is going to use for their payment.
userAcceptanceIndicatorBooleanMandatoryIndicates if the user has accepted the Terms and Conditions, in order to continue with the payment.

In this request, the Bearer Token is replaced by the checkout response “transactionSignature”.

Here’s an example:

Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v2/payments/{transactionID}/pbl/payment-link
Request Headers:
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"
 }
}

Upon completing the operation, you should receive a pending paymentStatus.

The user will be redirected to PBL environment to confirm the payment and then will be redirected back to the merchant URL.

{
 "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"
}

Step 3: Get the Payment Status to know the payment result

Once the payment has been completely processed, you can check the status of your transaction making a GET request.

The Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

OperationOperation TypeOperation Method & EndpointOperation Description
Get Payment StatusSynchronous CallGET
/api/v1/payment/{transactionId}/status
Obtain the payment status
Body:
LocationData ElementTypeConditionDescription
Query ParametertransactionIdStringMandatoryPayment identification.
Example: 9078fbb0-fced-4606-95c7-4989f06ee253
HTTP HeaderAuthorizationStringOptionalExample: Bearer *accessToken*
User’s access token. Must be Bearer scheme. Not applicable for hybrid payments.
HTTP Header/AuthorizationClient-IdAPI KeyMandatoryProject’s client id. Must be provided in a header with each request. 
HTTP Header/AuthorizationClient-SecretAPI KeyMandatoryProject’s client secret. Must be provided in a header with each request. 
Expected response with success:
{
 "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"
 }
}

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.