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 Multibanco payment form.

What you do

1.1 POST Checkout Payment to:

curl -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/payments" \
  --header "Authorization: Bearer {AuthToken}" \
  --header "X-IBM-Client-Id: {ClientId}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "merchant": {
        "terminalId": "<TerminalId>",
        "channel": "web",
        "merchantTransactionId": "teste 12345"
    },
    "transaction": {
        "transactionTimestamp": "<currentDateISO>", 
        "description": "Test Onboarding",
        "moto": false,
        "paymentType": "PURS", 
        "amount": {
            "value": 100.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "REFERENCE"
        ]
    }
}'

This creates the payment session.

1.2 Store from the successful response

• transactionID (used in the widget script URL)
• transactionSignature (used in the HTML form attribute)
• formContext (used in the HTML form attribute)
• paymentMethodList (should include REFERENCE)

Notes

• In Form Integration, the checkout step sends payment/order data, while payment method data is handled in the hosted SPG form.
• For Multibanco Reference, the widget generates and displays the payment reference; no card or additional payment data is collected from the customer.

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

Goal: Render the SIBS SPG hosted payment form to generate the Multibanco Reference.

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>

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 Multibanco Reference

At minimum, your config should:

• Restrict the form to Multibanco Reference using paymentMethodList
• Set redirectUrl (where the customer returns after the form finishes)
• Set language

Example (conceptual):

const formConfig = JSON.stringify({
  paymentMethodList: ["REFERENCE"],
  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”.

What Happens After Form Submission?

Once the customer confirms:

1. The Multibanco reference is generated.
2. The reference details are displayed:
   • Entity
   • Reference
   • Amount
3. The transaction status becomes Pending until the payment is confirmed or the reference expires.
4. The Customer must complete the payment outside the checkout (ATM or homebanking).

NOTE: Payment is not completed in real time.

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

Goal: Confirm the final payment outcome after the customer completes the Multibanco payment.

3.1 When to check status

Multibanco Reference is an asynchronous payment method.

You should:

• Listen to Merchant Notifications (webhooks) (recommended)
• Optionally poll the transaction status, from time to time

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: {ClientId}" \
--header "Authorization: Bearer {AuthToken}" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

Where s2iCzUbsAAs5CSjzSFVE is the transactionID is the value obtained in the checkout request.

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:

• Pending : Reference generated, awaiting payment
• Success : Payment confirmed
• Expired : Reference expired without payment
• Cancelled
• Error

The transaction remains Pending until:

• The customer completes the payment, or
• The reference validity period expires

3.5 Polling strategy (minimal, practical skeleton)

• Poll GET /api/v2/payments/{transactionID}/status at controlled intervals (e.g., every few minutes or hours)
• Stop when paymentStatus is one of: Success, Expired, Cancelled, Error
• If still Pending, continue polling

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

NOTE: For the Multibanco Reference, polling should be used only as fallback.