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 API environment URL (<ROOT_URL>) for the target 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 Two-Step Server-to-Server flow, including authorization initiation, customer approval, authorization validation, capture execution, and final settlement validation.

In a Two-step MB WAY (AUTH → CAPTURE) Server-to-Server Integration, the process is divided into:

1. Checkout creation (server-to-server – AUTH configuration)
2. MB WAY Authorization (customer approval in MB WAY app)
3. Authorization status validation (backend)
4. Capture the authorized transaction (server-to-server)
5. Capture status validation (backend)

MB WAY is an asynchronous payment method. Authorization depends on the customer approving the transaction in the MB WAY mobile application.

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

Goal: Create a checkout session configured for Authorization only (paymentType = AUTH) and obtain the identifiers required for the subsequent server-to-server operations (authorization, status validation and capture).

What you do

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": "unique-order-id"
    },
    "transaction": {
        "transactionTimestamp": "2028-12-31T00:00:00.000Z",
        "description": "Transaction short description",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 5.10,
            "currency": "EUR"
        },
        "paymentMethod": ["MBWAY"]
    }
  }'

Important

• paymentType must be set to “AUTH“
• paymentMethod must include "MBWAY" (i.e., ["MBWAY"])
• merchantTransactionId must be unique per transaction

Headers

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

What you do in this step

• Create a new payment session.
• Define the payment type (AUTH for the first step for the two-step payment).
• Restrict the payment method to "MBWAY".
• Send the total amount and currency.

This call registers the payment and prepares the transaction for the subsequent server-to-server operations.

1.2. Store from the successful response:

From the Checkout response, you must store:

• transactionID : used for authorization tracking, capture operations, status validation, and reconciliation
• transactionSignature: required to authorize the MB WAY authorization request (Authorization: Digest {transactionSignature})
  

Also, the following values will have an important role after the authorization, namely:

• merchantTransactionId : internal reconciliation id
• Authorized amount : amount reserved after successful MB WAY approval

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

Field Notes

merchant

• terminalId : Merchant terminal provided by SIBS
• channel : Integration channel (web, app, etc.)
• merchantTransactionId : Unique merchant-side identifier (use idempotency controls to prevent duplicates)

transaction

• transactionTimestamp : Current timestamp in ISO 8601 format
• description : Free text description
• moto : Mail Order / Telephone Order flag
• paymentType : AUTH (Authorization only for two-step flow)
• amount.value : Decimal value (dot as decimal separator, e.g. 19.20)
• amount.currency : ISO currency code
• paymentMethod : Must include "MBWAY"

Notes

• merchantTransactionId is your internal order identifier (maximum 35 characters, unique per transaction).
• paymentType must be "AUTH" for two-step purchase
• The checkout session expires after 4 minutes. After expiration, you cannot initiate the MB WAY operation and must create a new Checkout.

2) Perform MB WAY Authorization (Server-to-Server)

Goal: Trigger the MB WAY authorization request so that the customer receives a push notification in the MB WAY mobile app.

This step performs the Authorization only. Funds are reserved (authorized) but not captured.

2.1 Collect the customer phone number

The MB WAY alias is the customer mobile phone number.

MBWAY Alias format:

351#900000000

This represents:

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

The merchant backend should validate the MB WAY alias format before initiating the purchase request.

2.2 Initiate the MB WAY purchase (Authorization step)

curl -v -X POST '<ROOT_URL>/payments/{transactionID}/mbway-id/purchase' \
--header "X-IBM-Client-Id: dd43****" \
--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 authorization 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 operation response does not represent the final authorization 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) Validate the Final Transaction Status (Back-End)

Goal: Confirm the final authorization outcome after the customer completes the MB WAY authorization flow.

Even though MB WAY is a near real-time payment method, the final result must be obtained from the Merchant Notification (webhook), when configured, or confirmed via Status Inquiry when no final notification is available.

3.1 When to check status

Confirm the final authorization result using one of the following paths:

• By processing the Merchant Notification (webhook), when configured
• Or, if you don’t use notifications, poll the /status endpoint until the authorization becomes final.

Unlike Multibanco Reference, MB WAY payments do not remain pending for extended periods.

The authorization must only be considered finalized after receiving a final Merchant Notification or a final Status Inquiry response.

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"

Where {transactionID} is the value obtained in the Checkout response (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, typically with values such as:

• Success
• Declined
• Error
• Pending
• Timeout

MB WAY Behaviour

• Success : Authorization approved (funds reserved)
• Declined : Authorization refused or cancelled
• Error : Technical or processing error
• Pending : Temporary state during authentication or processing
• Timeout : Authorization timed out (customer did not approve within allowed time)

The authorization must only be considered successful when:

• paymentStatus = "Success“
• returnStatus.statusCode = "000“

Only then should the transaction be considered Authorized. Funds are now reserved but not captured.

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 maximum polling window)

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

Important Notes

• MB WAY is a near real-time payment method.
• There is no extended waiting period (unlike Multibanco Reference).
• The final payment confirmation must be obtained from the Merchant Notification (webhook), when configured, or confirmed via Status Inquiry when no final notification is available.

4) Capture the Authorized Transaction (Server-to-Server)

Goal: Convert a previously authorized transaction (funds reserved) into a settled payment by executing a Capture operation.

In a Two-step flow, authorization does not transfer funds.
Funds are only settled after this capture call.

What you do

4.1 Decide when to capture

Capture is triggered after your business condition is met, for example:

• Order validated / stock confirmed
• Service delivered or ready to deliver
• Shipment confirmed
• Manual approval completed

Important: Capture must occur within the authorization validity window (scheme rules / issuer policies).

4.2 POST Capture request

curl -v -X POST "<ROOT_URL>/payments/{transactionID}/capture" \
--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": "unique-capture-id"
    },
    "transaction": {
        "transactionTimestamp": "2028-12-31T00:00:00.000Z",
        "description": "Capture operation",
        "amount": {
            "value": 5.00,
            "currency": "EUR"
        }
    }
}'

Where:

• {transactionID} is the original AUTH transactionID (from the Checkout/Authorization flow).

The capture must only be considered successful (capture transaction) when:

• paymentStatus = "Success“
• returnStatus.statusCode = "000“

What happens

• SPG validates that the transaction is in a capturable state (Authorized).
• If valid, SPG captures the amount (full or partial if supported/configured).
• The transaction moves toward a final state where settlement is completed.

What to store from the response

Store at least:

• Capture result status (success/failure)
• The transactionID returned in the capture response (it is different from the original authorization transactionID).
• Your merchantTransactionId for reconciliation/audit
• Captured amount

Important Notes

• The capture amount must not exceed the authorized amount.
• Partial capture depends on merchant configuration / acquiring configuration.
• Capture operations must be implemented idempotently to prevent duplicate settlement in case of retry scenarios or network failures.
• If the authorization expires before capture, the funds are released and capture will fail.

5) Check Payment (Capture) Status (Back-End)

Goal: Confirm the final capture outcome after the capture operation.

5.1 When to check status

The capture transaction must only be considered finalized after a final capture result is received, either in the capture response or Merchant Notification, or, where needed, via Status Inquiry.

5.2 Status endpoints you can use

The following Status Inquiry options are commonly used:

• GET <ROOT_URL>/payments/{transactionID}/status (where {transactionID} is the transactionID returned by the Capture operation)

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"

Where {transactionID} is the value obtained in the Capture response (Step 4).

5.3 Required headers (status call)

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

5.4 What statuses to expect (high level)

The response includes paymentStatus, typically with values such as:

• Success
• Declined
• Error
• Pending
• Timeout

MB WAY Behaviour

• Success : Capture approved and funds settled.
• Declined : Capture refused or cancelled
• Error : Technical or processing error
• Pending : Temporary state while the capture is being processed by SPG.

The capture must only be considered successful when:

• paymentStatus = "Success“
• returnStatus.statusCode = "000“

Only then should the transaction be considered Captured and Settled.

For detailed webhook delivery behaviour and operational considerations, refer to E.1 – Webhooks (Notifications).

For complete Status Inquiry endpoint specifications and response interpretation, refer to E.2 – Status Inquiry / Get Status.

Authorization request examples, capture request examples, and end-to-end MB WAY two-step transaction flows are documented in F. Technical Examples and Best Practices.