Server to Server - 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.
How it Works
Flow - Pay By Link
Pay By Link payment flow relies on the following steps:
- Create the Checkout request with the payment data
- Request a list of all Pay By Link entities and present them to the customer
- Call the API to get a valid Payment Link for the chosen entity
- Redirect the customer to Pay By Link for authentication and authorisation
- Get the Payment Status to know the payment result
For more information regarding the API endpoints please check Payment Wall Sandbox.
If you want to know more about the structures and fields please check API Dev Portal.
Starting by creating the checkout
First, perform a server-to-server POST request, the same as Form Integration, to prepare the checkout with the required data,where you should include the payment type, amount, currency and payment methods allowed.
Only include "PAY_BY_LINK" in the transaction.paymentMethod list.
Additionally you need to provide the transaction.payByLink element, containing two dates:
- expirationDateTime: date when the payment will no longer be accepted, provided as an ISO data with timezone
- linkExpirationDateTime: date when the payment link will no longer be valid, provided as an ISO data with timezone
The payment link can be set to expire a few minutes before the payment, so that it can give the customer enough time to conclude the operation in the Homebanking.
The JSON of your POST body, can be composed of various Complex Types:
"merchant": {
"terminalId": {{terminalId}},
"channel": "web",
"merchantTransactionId": "{{mti}}"
"transactionDescription": "transaction short description"
"shopURL" : "https://mytest.e-shop.pl/"
}
For more info check API Market
"transaction": {
"transactionTimestamp": "Current Date",
"description": "transaction statement description",
"moto": false,
"paymentType": "PURS",
"amount": {
"value": 50.50
"currency": "PLN"
},
"paymentMethod": [
"PAY_BY_LINK"
]
"payByLink": {
"expirationDateTime": "Date the Payment will expire, ISO date with timezone",
"linkExpirationDateTime": "Date the Payment Link will expire, ISO date with timezone",
}
}
For more info check API Market
"customer": {
"customerInfo": {
"customerName": "Client Name",
"customerEmail": "client.name@hostname.pt",
"shippingAddress": {
"street1": "Street address 1",
"street2": "Street address 2",
"city": "Lisbon",
"postcode": "1200-999",
"country": "PT"
},
"billingAddress": {
"street1": "Street address 1",
"street2": "",
"city": "Lisbon",
"postcode": "1200-999",
"country": "PT"
}
}
}
For more info check API Market
The response to a successful request is a JSON with a transactionID, which is required in the second step to create a transaction.
With the transactionID, will be present as well a transactionSignature that will be used on the following step
POST
Expected Response
A success response comprises of an HTTP-200 status, a transactionID and a transactionSignature
Any other HTTP status signals an unsuccessful request. The following statuses may occur:
- HTTP-400 (Bad Request): The 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-401 (Unauthorized): 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-403 (Forbidden): The 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-405 (Method Not Allowed): The HTTP Method used is not matching any of the API definitions available. Please check in API Market for the correct HTTP Method.
- HTTP-429 (Too Many Requests): The API calls rate limit has been exceeded. Please check in API Market for information on the rate limits that apply to the API.
- HTTP-500 (Internal Server Error): The 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-503 (Service Unavailable): The API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.
For more information regarding the responses, please check API Dev Portal.
Now get the list of Pay By Link entities
You can check the list of all Pay By Link entities making a GET request.
Note that the request needs an Authorization Header with the "transactionsSignature" returned from checkout operation.
In this requests, the Bearer Token is replaced by the checkout response "transactionSignature".
Example:
Authorization: Digest {transactionSignature}
/api/v2/paymentsChannels
Authorization: Digest {transactionSignature}
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:
"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": [
{
"regulationId": "identifier of the applicable regulation",
"url": "https://pay-accept.bm.pl/webapi/regulation?ServiceID=903463&MessageID=cbd2034dbf3c9",
"type": "DEFAULT",
"language": "PL",
}
]
In case you receive a list of regulations you are required to show them to the customer with an hyperlink to the URL.
Generate the Pay By Link URL :
Note that the following request needs an Authorization Header with the "transactionsSignature" returned from checkout operation.
In this requests, the Bearer Token is replaced by the checkout response "transactionSignature".
Example:
Authorization: Digest {transactionSignature}
You also need to provide a merchant.merchantURL containing your server's endpoint for redirecting the customer back to you.
/api/v2/payments/{transactionID}/pbl/payment-link
Authorization: Digest {transactionSignature}
For more info check API Market
Expected Response
A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode="000".
For successful responses you will receive the redirectURL you will have to redirect the customer to via POST
Finally you may perform a Get Status
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.