Prerequisites (once per merchant/environment)

You need the following credentials and configuration elements before calling the SIBS SPG APIs:

• AuthToken : (used as Authorization: Bearer <AuthToken> for REST calls),
• TerminalId : the terminal ID assigned to the merchant, by the SIBS OnBoarding team
• X-IBM-Client-Id : merchant application identifier assigned by the SIBS OnBoarding team

Choose environment root URLs (you will use them in the API base URL and in the widget URL).

Please refer to the API Requests documentation page for more information.

API Request Flow

1) Prepare the checkout (server-to-server)

Goal: Create a checkout payment session in SIBS SPG and obtain the identifiers required to render the payment form.

What you do

1.1 POST Checkout Payment to:

curl -v -X POST 'https://api.qly.sibspayments.com/sibs/spg/v2/payments' \
--header "X-IBM-Client-Id: b824198a-321c-4f53-9bcb-832281d95735" \
--header "Authorization: ••••••" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "merchant": {
        "terminalId": 58019,
        "channel": "web",
        "merchantTransactionId": "teste 12345"
    },
    "transaction": {
        "transactionTimestamp": "2026-02-12T19:08:08.354Z", 
        "description": "Test Onboarding",
        "moto": false,
        "paymentType": "PURS", 
        "amount": {
            "value": 2,
            "currency": "EUR"
        },
        "paymentMethod": [
            "MBWAY"
        ]
    }
}'

Notes:

• merchantTransactionId must be unique per transaction
• MB WAY one-off payments use paymentType = PURS (Purchase)

1.2. Store from the successful response:

• transactionID : (you’ll inject it in the widget script URL)
• transactionSignature : (you’ll inject it into the HTML form attribute)
• formContext : secure configuration context generated during Checkout (must not be altered)
• paymentMethodList : (SIBS SPG may also return available methods)

Notes:

• In Form Integration, the checkout step sends payment/order data, while payment-method data is collected later in the hosted form.

2) Create the payment form link (Widget) + customization (front-end)

Goal: Render the SIBS SPG payment form and allow the customer to select MB WAY and complete the payment flow.

2.1 Include the SIBS SPG widget script (using transactionID)

Add the script tag to your checkout page:

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

This is the standard Form Integration approach and the script URL includes the transactionID.

2.2 Add the <form> element and inject formContext + transactionSignature + config/style

You must have a form with class paymentSPG and the SIBS SPG attributes:

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

SIBS SPG explicitly defines:

• spg-context : the formContext you received from Checkout
• spg-signature : the transactionSignature you received from Checkout
• spg-config : merchant configuration (JSON string),
• spg-style : optional styling configuration (JSON string).

2.3 formConfig – minimal config for MB WAY one-time

At minimum, your config should:

• Restrict the form to MB WAY using paymentMethodList
• Set redirectUrl (where the customer returns after the form finishes)
• The amount is defined in the Checkout request and does not need to be redefined in formConfig.
• Set language

Example (conceptual):

const formConfig = JSON.stringify({
  paymentMethodList: ["MBWAY"],
  redirectUrl: "https://merchant.example.com/payment-return",
  language: "en"
});

Supported values for paymentMethodList include MBWAY, REFERENCE, CARD (display depends on merchant permissions).

2.4 formStyle – optional UI customization

If you want to align the SIBS SPG form with your brand, SIBS SPG supports a style object with parameters like layout/theme/colors/font.
Example (conceptual):

const formStyle = JSON.stringify({
  layout: "default",
  theme: "light",
  color: { 
      primary: "#0033A1" 
  }
});

Optional: react to “Pay” click events in real time

SIBS SPG supports event monitoring via window.postMessage from the iframe so you can show a spinner / tracking / UX actions when the user clicks “Pay”.

3) Check payment status until it is paid (back-end)

Goal: Confirm the final payment outcome after the customer completes the SIBS SPG form (or while the payment is still processing).

3.1 When to check status

• After the customer returns to your redirectUrl, you should query the transaction status (“Transaction Status Inquiry”).

Important: The redirectUrl does NOT guarantee that the payment was successful. Always confirm the final payment outcome server-side.

3.2 Status endpoints you can use

SIBS SPG documents two common options:

• GET /api/v2/payments/{id}/status (where {id} is transactionID)
• GET /api/v2/payments/status?merchantTransactionId=... (query by your merchant transaction id)

curl -v -X GET "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: b824198a-321c-4f53-9bcb-832281d95735" \
--header "Authorization: ••••••" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

Where s2iCzUbsAAs5CSjzSFVE represents the transactionID obtained in the Checkout response.

3.3 Required headers (status call)

• Authorization: Bearer <AuthToken>
• X-IBM-Client-Id: <ClientId>
• Content-Type: application/json
• Accept: application/json

3.4 What statuses to expect (high level)

Response includes paymentStatus with values such as:

• Success
• Pending
• InProcessing
• Declined
• Error
• Timeout

MB WAY is an asynchronous payment method. The transaction typically moves to “Pending” while the customer authorizes in the MB WAY app; your system must wait for the final result (commonly via notification). The final state is only determined once the MB WAY authorization result is processed by SPG.

3.5 Polling strategy (minimal, practical skeleton)

• Poll GET /api/v2/payments/{transactionID}/status every 3-5 seconds (recommended)
• Stop when paymentStatus is one of: Success, Declined, Error, Timeout
• If still Pending / InProcessing, continue polling (with a 60–120 second max time cap, after the maximum allowed confirmation window for MB WAY)

Even if polling is implemented, SIBS SPG supports Merchant Notification (webhooks) for asynchronous payments. This is the recommended approach for MB WAY.