Skip to content

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.

mssg_bell

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.