Prepare the checkout

Firstly, perform a server-to-server POST request to prepare the checkout with the required data, where you should include the payment type, amount, currency and payment methods allowed.

The JSON of your POST, can be composed of various complex types:

Merchant (Mandatory)

"merchant": {
  "terminalId": {{terminalId}},
  "channel": "web",
  "merchantTransactionId": "gp9253eg4o"
}

Transaction (Mandatory)

"transaction": {
  "transactionTimestamp": "Current Date",
  "description": "My transaction -> Order Order Id: gp9253eg4o",
  "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": "porta 2",
      "city": "Lisboa",
      "postcode": "1200-999",
      "country": "PT"
},
  "billingAddress": {
      "street1": "Rua 123",
      "street2": "porta 2",
      "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 the payment form.

With the transactionID, will be present as well a formContext that will be used on the following step.

POST https://spg.qly.site1.sibs.pt/api/v1/payments

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

Create the payment form

To create the payment form you just need to add the following lines of HTML/Javascript to your page and populate the following variables:

• The checkout’s transactionID that you got as a response from the first step:

<script src="https://spg.qly.site1.sibs.pt/assets/js/widget.js?id={transactionID}"></script>

• The {formContext} that you get as response from the first step, a {formConfig} and optionally {formStyle}

<form class="paymentSPG" spg-context="{formContext}" spg-config="{formConfig}" spg-style="{formStyle}"><form>

Your transactionID, and formContext from step 1:

TransactionID:

s2RuXZaeEt9z9CUM5GS7

form-context:

eyJQYXltZW50TWV0aG9kIjpbIkNBUkQiLCJNQldBWSIsIlJFRkVSRU5DRSJdLCJUcmFuc2FjdGlvblNpZ25hdHVyZSI6ImV5SjBlRWxrSWpvaWN6SlNkVmhhWVdWRmREbDZPVU5WVFRWSFV6Y2lMQ0p0WXlJNk9UazVPVGs1T1N3aWRHTWlPalV5TWpJeGZRPT0uMzNybHpIOTRRM0lZcVRubEQwWGRnSHo3eW9COXlvMC9ZN1ZCVDU3ZlUxbz0uWEpJSk5PZ0kzWnJ2Q0ZlZjZ5RlhsMWdUNldhYjBXSDRZK2J0aHVSV1J0VEd1eDVRVnRCcUZYcEtXVjdjWHd4RyIsIkFtb3VudCI6eyJBbW91bnQiOjUuNSwiQ3VycmVuY3kiOiJFVVIifSwiTWFuZGF0ZSI6eyJNYW5kYXRlQXZhaWxhYmxlIjpmYWxzZX0sIkFwaVZlcnNpb24iOiJ2MSIsIk1PVE8iOmZhbHNlfQ==

• The {formConfig} and optionally {formStyle} are important to be able to create the from correctly. You can find an example of each below:
• formConfig -> spg-config=”{formConfig}”

{
    "paymentMethodList": [],
    "amount": {
        "value": 5,
        "currency": "EUR" 
    },
    "language": "en",
    "redirectUrl": "https://www.pay.sibs.com/documentacao/sibs-gateway",
    "customerData": null 
}

• formStyle -> spg-style=”{formStyle}”

{
    "transaction": {
        "layout": 'default',
        "theme": 'default',

        "color": {
            "primary": "",
            "secondary": "",
            "border": "",
            "surface": "",
            "header": {
                "text": "",
                "background": ""
            },

            "body": {
                "text": "",
                "background": ""
            }
        }
    },

    "font": ""
}

Get the payment status

Once the payment has been processed, the customer is redirected to your redirectURL (defined in “spg-config”), you can check the status of your transanction 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/s2RuXZaeEt9z9CUM5GS7/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/s2RuXZaeEt9z9CUM5GS7/status

Response body

{
    "merchant": {
        "terminalId": "52221",
        "merchantTransactionId": "Order ID: r1cm97qqjv"
    },
    "transactionID": "s2RuXZaeEt9z9CUM5GS7",
    "amount": {
        "currency": "EUR",
        "value": "5.50"
    },
    "paymentType": "PURS",
    "paymentStatus": "Timeout",
    "execution": {
        "endTime": "2023-11-09T11:50:30.007Z",
        "startTime": "2023-11-09T11:50:29.890Z"
    },
    "returnStatus": {
        "statusCode": "999",
        "statusMsg": "Validation Request Failed",
        "statusDescription": "Please try again."
    }
}

For more info check SIBS API Market