Server-to-Server Integration enables direct communication between the merchant and SIBS.
Throughout this integration, the card holder can finalize the payment without being redirected to SIBS Gateway form.
Server-to-Server integration is based on the following steps:
-
Prepare the checkout: sends payment data, including payment method data.
Display payment method options to customer: displays payment method options to customer and get payment data from the customer including: MB WAY ID, MULTIBANCO, Authorised Payments and Card.
Update payment method data: sends payment method and its required data.
Get the payment status: gets the payment status.
Merchant Notification: Receive payment status.
Create Checkout Server-to-Server
Firstly, perform a Server-to-Server POST request, to prepare the checkout with the required data, where you should include the order type, amount, currency and payment methods allowed.
The JSON of your POST body, can be composed of various Complex Types:
Merchant (Mandatory)
"merchant": {
"terminalId": {{terminalId}},
"channel": "web",
"merchantTransactionId": "{{mti}}"
}
Transaction (Mandatory)
"transaction": {
"transactionTimestamp": "Current Date",
"description": "My transaction -> Order XPTO",
"moto": false,
"paymentType": "PURS",
"amount": {
"value": 5,
"currency": "EUR"
},
"paymentMethod": [
"REFERENCE",
"CARD",
"MBWAY"
],
"paymentReference": {
"initialDatetime": "Current Date",
"finalDatetime": "Expiration Date",
"maxAmount": {
"value": 5,
"currency": "EUR"
},
"minAmount": {
"value": 5,
"currency": "EUR"
},
"entity": "24000"
}
}
Customer Info (Mandatory For Card)
"customer": {
"customerInfo": {
"customerEmail": "client.name@hostname.pt",
"shippingAddress": {
"street1": "Rua 123",
"street2": "",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
},
"billingAddress": {
"street1": "Rua 123",
"street2": "",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
}
}
}
Recurring Transaction (Optional)
"recurringTransaction": {
"validityDate": "2022-09-28T17:37:31.4095147+00:00",
"amountQualifier": "DEFAULT",
"description" : "My transaction -> Order XPTO"
}
Tokenization (Optional)
"tokenisation":{
"tokenisationRequest":{
"tokeniseCard":true
}
}
The response to a successful request is a JSON with a transactionID, which is required on the second step to create a transaction.
With the transactionID, will be present as well a transactionSignature that will be used on the next step.
The available endpoint destination URL is:
POST https://spg.qly.site1.sibs.pt/api/v1/payments
Here's how you can run this locally:
Request URL
https://spg.qly.site1.sibs.pt/api/v1/payments
Request Headers
Authorization: Bearer 0276b80f950fb446c6addaccd121abfbbb.eyJlIjoiMTk4N (...)
X-IBM-Client-Id: 8247e05b-e64d-4948-843d-6e8b30224e39
Content-Type: application/json
Request body
{
"merchant": {
"terminalId": 52221,
"channel": "web",
"merchantTransactionId": "Order ID: r1cm97qqjv"
},
"transaction": {
"transactionTimestamp": "2023-11-09T10:31:44.989Z",
"description": "Your own description",
"moto": false,
"paymentType": "PURS",
"amount": {
"value": 5.5,
"currency": "EUR"
},
"paymentMethod": [
"CARD",
"MBWAY",
"REFERENCE"
],
"paymentReference": {
"initialDatetime": "2023-11-09T10:31:44.989Z",
"finalDatetime": "2023-11-11T10:31:44.989Z",
"maxAmount": {
"value": 5.5,
"currency": "EUR"
},
"minAmount": {
"value": 5.5,
"currency": "EUR"
},
"entity": "24000"
}
}
}
Request checkout
{
"amount": {
"value": 5.5,
"currency": "EUR"
},
"merchant": {
"terminalId": "52221",
"merchantTransactionId": "Order ID: r1cm97qqjv"
},
"transactionID": "s2CB2CH3U91PdGDHsacJ",
"transactionSignature": "eyJ0eElkIjoiczJDQjJDSDNVOTFQZEdESHNhY0oiLCJtYyI6OTk5OTk5OSwidGMiOjUyMjIxfQ==.iouf6xtVLCzwj1tFFJfwpbepumscI6jAfQ50PuMmrpI=.XJIJNOgI3ZrvCFef6yFXl1gT6Wab0WH4Y+bthuRWRtTGux5QVtBqFXpKWV7cXwxG",
"formContext": "eyJQYXltZW50TWV0aG9kIjpbIkNBUkQiLCJNQldBWSIsIlJFRkVSRU5DRSJdLCJUcmFuc2FjdGlvblNpZ25hdHVyZSI6ImV5SjBlRWxrSWpvaWN6SkRRakpEU0ROVk9URlFaRWRFU0hOaFkwb2lMQ0p0WXlJNk9UazVPVGs1T1N3aWRHTWlPalV5TWpJeGZRPT0uaW91ZjZ4dFZMQ3p3ajF0RkZKZndwYmVwdW1zY0k2akFmUTUwUHVNbXJwST0uWEpJSk5PZ0kzWnJ2Q0ZlZjZ5RlhsMWdUNldhYjBXSDRZK2J0aHVSV1J0VEd1eDVRVnRCcUZYcEtXVjdjWHd4RyIsIkFtb3VudCI6eyJBbW91bnQiOjUuNSwiQ3VycmVuY3kiOiJFVVIifSwiTWFuZGF0ZSI6eyJNYW5kYXRlQXZhaWxhYmxlIjpmYWxzZX0sIkFwaVZlcnNpb24iOiJ2MSIsIk1PVE8iOmZhbHNlfQ==",
"expiry": "2023-11-09T10:41:44.989Z",
"tokenList": [],
"paymentMethodList": [
"CARD",
"MBWAY",
"REFERENCE"
],
"execution": {
"startTime": "2023-11-09T15:33:29.460Z",
"endTime": "2023-11-09T15:33:29.611Z"
},
"returnStatus": {
"statusCode": "000",
"statusMsg": "Success",
"statusDescription": "Success"
}
}
Generate transaction
Configuration on Server-to-Server
Note that all the following requests need an Authorisation Header with the “transactionSignature” returned from checkout operation.
On these requests, the Bearer Token is replaced by the checkout response “transactionSignature”.
Example
Authorization: Digest {transactionSignature}
Multibanco
POST https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/service-reference/generate
Request URL
https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/service-reference/generate
Request headers
Authorization: Digest {transactionSignature}
X-IBM-Client-Id: 8247e05b-e64d-4948-843d-6e8b30224e39
Content-Type: application/json
Request body
Ocurred an error sending post to
https://spg.qly.site1.sibs.pt/api/v1/payments//service-reference/generate
Response Body:
undefined
MB WAY
Generate MB WAY payment
Insert the phone number to use:
POST https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}}/mbway-id/purchase
Request URL
https://spg.qly.site1.sibs.pt/api/v1/payments/s2CB2CH3U91PdGDHsacJ/mbway-id/purchase
Request headers
Authorization: Digest {transactionSignature}
X-IBM-Client-Id: 8247e05b-e64d-4948-843d-6e8b30224e39
Content-Type: application/json
Request body
{
"customerPhone": "351#919999999"
}
{
"transactionID": "s2CB2CH3U91PdGDHsacJ",
"execution": {
"startTime": "2023-11-09T16:19:11.924Z",
"endTime": "2023-11-09T16:19:12.052Z"
},
"paymentStatus": "Timeout",
"returnStatus": {
"statusCode": "000",
"statusMsg": "Success",
"statusDescription": "Success"
}
}
Get the payment status
Once the payment has been processed, you must redirect the client to a thank you page and present a message depending on the paymentStatus. You can check the status of your transaction by making a GET request.
GET https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Request URL
https://spg.qly.site1.sibs.pt/api/v1/payments/s2CB2CH3U91PdGDHsacJ/status
Request headers
Authorization: Bearer 0276b80f950fb446c6addaccd121abfbbb.eyJlIjoiMTk4N (...)
X-IBM-Client-Id: 8247e05b-e64d-4948-843d-6e8b30224e39
Content-Type: application/json
Ocurred an error on the GET request to
https://spg.qly.site1.sibs.pt/api/v1/payments/s2CB2CH3U91PdGDHsacJ/status
Response body
{
"merchant": {
"terminalId": "52221",
"merchantTransactionId": "Order ID: r1cm97qqjv"
},
"transactionID": "s2CB2CH3U91PdGDHsacJ",
"amount": {
"currency": "EUR",
"value": "5.50"
},
"paymentType": "PURS",
"paymentStatus": "Timeout",
"paymentMethod": "MBWAY",
"execution": {
"endTime": "2023-11-09T16:44:56.359Z",
"startTime": "2023-11-09T16:44:56.246Z"
},
"returnStatus": {
"statusCode": "999",
"statusMsg": "Validation Request Failed",
"statusDescription": "Please try again."
}
}