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 the appropriate environment URLs. The API base URL (<ROOT_URL>) and hosted widget URL (<WIDGET_URL>) must correspond to the same environment.

Please refer to A.3 – API Requests for the complete list of environment-specific URLs.

API Request Flow

The following diagram summarizes the complete MB WAY Form Integration flow before the detailed implementation steps.

1) Create the Checkout Session (server-to-server)

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

Implementation steps

1.1 POST Checkout Payment to:

curl -v -X POST '<ROOT_URL>/payments' \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "merchant": {
        "terminalId": 58019,
        "channel": "web",
        "merchantTransactionId": "teste 12345"
    },
    "transaction": {
        "transactionTimestamp": "2028-12-31T00:00:00.000Z",
        "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:

The SPG transactionID should be treated as the authoritative identifier for transaction monitoring, webhook correlation, reconciliation, refund operations, and Status Inquiry requests throughout the transaction lifecycle.

From the Checkout response, you must store:

• 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, collect the MB WAY mobile number, and allow the customer to complete the payment authorization flow.

The customer must provide a mobile phone number associated with a valid MB WAY-enabled account.

2.1 Include the SIBS SPG widget script (using transactionID)

Add the script tag to your checkout page:

<script src="<WIDGET_URL>/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 configuration for MB WAY One-Off payments

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 hosted form 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) Validate the final transaction status (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

The following Status Inquiry options are commonly used:

• GET <ROOT_URL>/payments/{transactionID}/status
• GET <ROOT_URL>/payments/status?merchantTransactionId=... (query by your merchant transaction id)

curl -v -X GET "<ROOT_URL>/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

For example, s2iCzUbsAAs5CSjzSFVE represents a transactionID returned by 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 Expected transaction statuses (high level)

Response includes paymentStatus with values such as:

• Success
• Pending
• 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)

• A common implementation approach is to poll GET <ROOT_URL>/payments/{transactionID}/status every 3–5 seconds while awaiting final transaction confirmation.
• Stop when paymentStatus is one of: Success, Declined, Error, Timeout
• If still Pending, continue polling (with a 60-120 second max time cap, after the maximum customer confirmation window allowed for the MB WAY transaction)

Even if polling is implemented, SIBS SPG supports Merchant Notification (webhooks) for asynchronous payments.

Webhook notifications should be treated as the preferred mechanism for asynchronous MB WAY transaction lifecycle monitoring and operational reconciliation.

The Sandbox Payment Simulator may also be used to validate MB WAY Form Integration flows, hosted payment form behaviour, customer confirmation interaction, transaction lifecycle progression, and operational request/response payloads in the sandbox environment.

Example sandbox simulator entry point

For webhook implementation details, refer to E.1 – Webhooks (Notifications).

For transaction lifecycle monitoring, reconciliation, and Status Inquiry operations, refer to E.2 – Status Inquiry / Get Status.