Menu
Back to homepage

PAYMENT GATEWAY

Back to homepage

Integration guide

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. 

Warning

Please note, that in order to use Card payments with Server-To-Server integration method, it’s mandatory being PCI-DSS Compliant, which allows merchants flexible workflows on front-end and back-end processes.

 

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

On this page: