PayByLink
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
Pay By Link payment flow relies on the following steps:
Before you start, you should create the order request with PayByLink as payment method.
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 Authorization Header with the “transactionsSignature” returned from checkout operation. Check below how to get the payment channels list:
Operation
Operation Type
Operation Method & Endpoint
Operation Description
Observations
Get Payment Channels List
Synchronous Call
POST https://{{APIHost}}/api/v1/paymentChannels
Perform the transaction and report the Payment Channel List.
Content-Type: application/x-www-form-urlencoded
Location
Data Element
Type
Condition
Description
HTTP Header
Authorization
String
Optional
Example: Bearer *accessToken*
User’s access token. Must be Bearer scheme. Not applicable for hybrid payments.
HTTP Header/
Authorization
Client-Id
API Key
Mandatory
Project’s client id. Must be provided in a header with each request.
HTTP Header/
Authorization
Client-Secret
API Key
Mandatory
Project’s client secret. Must be provided in a header with each request.
Query Parameter
countryCode
String
Optional
Country 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.
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:
Step 2: 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.
In this requests, 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-GB",
"browserColorDepth": "24",
"browserScreenHeight": "900",
"browserScreenWidth": "1440",
"browserTZ": "0",
"browserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:98.0) Gecko/20100101 Firefox/98.0"
},
"customerInfo": [
{
"key": "customerName",
"value": "Test Name"
},
{
"key": "customerEmail",
"value": email@provider.com
}
]
},
"gatewayId": "106",
"userAcceptanceIndicator": true,
"merchant": {
"merchantURL": https://www.pay.sibs.com/eng/documentation/sibs-gateway-3/integration/server-to-server/pbl/
}
}
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.
Operation
Operation Type
Operation Method & Endpoint
Operation Description
Observations
Get Payment Status
Synchronous Call
GET /pis/payment/{paymentId}/status
Obtain the payment status
Body:
Location
Data Element
Type
Condition
Description
Query Parameter
paymentId
String
Mandatory
Payment identification.
Example: 9078fbb0-fced-4606-95c7-4989f06ee253
HTTP Header
Authorization
String
Optional
Example: Bearer *accessToken*
User’s access token. Must be Bearer scheme. Not applicable for hybrid payments.
HTTP Header/
Authorization
Client-Id
API Key
Mandatory
Project’s client id. Must be provided in a header with each request.
HTTP Header/
Authorization
Client-Secret
API Key
Mandatory
Project’s client secret. Must be provided in a header with each request.
Expected response:
Location
Data Element
Type
Condition
Description
Response Body
cardStatus
String
Optional
Enum: “started” “issued” “paid” “payment_success” “payment_failure” “hold” “canceled” “in_progress” “invoice_viewed” “invoice_refunded” “invoice_reversal” “refund_failure” “invoice_refund_reversed” “refund_init_failure” “reversal_init_failure” “reversal_failure” “refund_in_progress” “reversal_in_progress” “received” “rejected” “expired” “chargeback” “representation” “retrieval” “prearbitrationgood_faith” “good_faith” “fraud_advice” “failed” “refund_forbidden” “waiting_for_confirmation” “completed” “partially_refunded” “refunded”
Response Body
bankStatus
String
Optional
Enum: “STRD” “ACCC” “ACCP” “ACSC” “ACSP” “ACTC” “ACWC” “ACWP” “RCVD” “PDNG” “RJCT” “CANC” “ACFC” “PATC”
Response Body
hybridStatus
String
Optional
Enum: “created” “canceled” “expired”
Response Body
statusGroup
String
Optional
Enum: “started” “pending” “completed” “failed”
Response Body
error
Object
Optional
Object
Response Body/
error
code
Numeric
Optional
Number (statusError), only applicable for failed payments
Possible values:
10000: System error.
20017: Insufficient funds.
20022: Creditor account number invalid or missing.
20023: The account number and the name do not coincide.
20024: Transaction currency is invalid or missing.
20029: Remittance information is not valid.
20032: Authorization header is missing or invalid.
