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 session in SIBS SPG and obtain the identifiers required to initiate the MB WAY payment.

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

Headers:

• Authorization: Bearer {AuthToken}
• X-IBM-Client-Id: {clientId}
• Content-Type: application/json
• Accept: application/json

This creates the payment session.

1.2. Store from the successful response:

• transactionID : used in subsequent calls
• transactionSignature: required to authorize the MB WAY purchase call. The transactionSignature is generated during Checkout and must not be altered.

Notes:

• In Server-to-Server integration, the merchant backend is fully responsible for securely collecting and validating the customer’s MB WAY mobile number (alias).
• No hosted payment form is used in this flow.

2) REQUEST MB WAY PAYMENT (BACKEND)

Goal: Send the customer phone number to SIBS SPG and trigger the MB WAY authorization request in the MB WAY APP.

2.1 Collect the customer phone number

The MB WAY alias is the customer mobile phone number.

MBWAY Alias format:

351#910000000

This represents:

• Country code (e.g., 351 for Portugal)
• Separator #
• MBWAY Account Mobile number

2.2 Initiate the MB WAY purchase

curl --location 'https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/mbway-id/purchase' \
--header "X-IBM-Client-Id: b824198a-321c-4f53-9bcb-832281d95735" \
--header "Authorization: Digest {transactionSignature}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
    "customerPhone": "351#910000000" 
}'

Headers

• Authorization: Digest {transactionSignature}
• X-IBM-Client-Id: {clientId}
• Content-Type: application/json
• Accept: application/json

2.3 Request body

{
  "customerPhone": "351#910000000",
  "inApp": true
}

Where:

• customerPhone: MB WAY alias (required)
• inApp: optional boolean to optimize mobile experiences

2.4 Immediate response behaviour

After the purchase request:

• MB WAY is an asynchronous payment method. After the purchase request, the transaction typically moves to Pending while the customer authorizes the payment in the MB WAY app.
• The customer receives a push notification in the MB WAY app
• The final result is asynchronous
• The purchase response does not represent the final payment result.

Optional inApp behaviour:

• If inApp = true, the customer can be redirected back to the merchant mobile app after accepting or declining the payment.
• If inApp is absent from the request payload, the default is false

3) CHECK PAYMENT STATUS UNTIL IT IS PAID (BACK-END)

Goal: Confirm the final payment outcome after the customer authorizes the MB WAY request.

Important: Do not consider the payment successful based solely on the MB WAY purchase response. Always confirm the final payment outcome via the /status endpoint or Merchant Notification.

3.1 When to check status

You should:

• Listen to Merchant Notifications (recommended)
• Optionally poll the transaction status

3.2 Status endpoints you can use

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:

• {transactionID} is the value obtained in the checkout request (Step 1).

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)

The response includes paymentStatus with values such as:

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

MB WAY is an asynchronous payment method. The transaction may remain in Pending until the 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.