Overview

This example illustrates a complete end-to-end flow for a one-off payment using MB WAY.

It demonstrates how the merchant system:

• Creates a checkout session
• Initiates the MB WAY payment request
• Waits for customer approval in the MB WAY mobile application
• Receives asynchronous updates via Webhooks
• Confirms the final transaction state using a final webhook paymentStatus or Status Inquiry when required

This scenario represents a fully asynchronous payment flow, where the transaction outcome depends on user interaction outside the merchant environment and may take several seconds or minutes to complete.

Goal

Process a one-off payment using MB WAY, ensuring:

• Correct initiation of the payment request
• Proper handling of asynchronous user approval
• Reliable transaction state tracking
• Final reconciliation after capture using a final webhook paymentStatus or Status Inquiry when required

Preconditions

Before executing this flow, the following must be in place:

• Valid SPG credentials:
  • terminalId
  • X-IBM-Client-Id
  • Bearer token
• Configured Webhook endpoint
• Backend capable of storing:
  • transactionID
  • merchantTransactionId
• Hosted form integration correctly implemented
• Customer mobile phone number (MB WAY identifier)

In Postman, ensure the following variables are configured:

• terminalId
• ClientID
• Bearer
• host

(See collection root variables in SIBS PAYMENT GATEWAY POSTMAN Collection)

The following diagram illustrates the complete asynchronous lifecycle of an MB WAY payment transaction.

Figure – MB WAY Asynchronous Payment Flow

Step 1 – Create Checkout

The merchant initiates the payment by creating a checkout.

Endpoint

POST <ROOT_URL>/payments

Headers

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

Example Request

{
    "merchant": {
        "terminalId": 11111,
        "channel": "web",
        "merchantTransactionId": "ORDER-MBWAY-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-15T12:00:00.000Z",
        "description": "MB WAY payment",
        "paymentType": "PURS",
        "amount": {
            "value": 25.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "MBWAY"
        ]
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → MB WAY → Checkout MB WAY

Key Outputs

• transactionID → primary identifier
• transactionSignature → required to authorize the MB WAY purchase call.

The transactionID returned in this step must be used as the primary identifier across all subsequent steps, including webhook processing and status validation.

Step 2 – Initiate MB WAY Payment

The merchant initiates the MB WAY payment request.

Endpoint

POST <ROOT_URL>/payments/{transactionID}/mbway-id/purchase

Headers

Authorization: Digest <transactionSignature>
X-IBM-Client-Id: <clientId>
Content-Type: application/json
Accept: application/json

Example Request

{
    "customerPhone": "351#912345678"
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → MB WAY → MB WAY Purchase

Step 3 – Customer Approval (MB WAY App)

After the request is initiated:

• The customer receives a notification in the MB WAY mobile app
• The customer must approve or reject the payment

Important

 

• The payment remains in a pending state until user action
• The typical timeout for user approval is approximately 4 minutes
• If no action is taken, the transaction may result in Timeout
• During this period, the merchant system must treat the transaction as pending and rely on webhook notifications and/or status polling to determine the final outcome.

Depending on processing timing and customer interaction, transactions may temporarily remain in intermediate transaction states such as Pending before reaching a final outcome.

Step 4 – Receive and Process Webhook Notifications

SPG sends a webhook when the transaction state changes.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2ExampleTxMBWAY123",
    "paymentType": "PURS",
    "notificationID": "notif-mbway-001"
}

Processing Requirements

• Receive the notification
• Validate authenticity and integrity (e.g., decryption and header validation)
• Store and process the notification using notificationID as a unique identifier
• Ensure idempotent processing
• Acknowledge correctly

Response to SPG

{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "notif-mbway-001"
}

The notificationID must match the value received in the webhook payload.

Important

 

Webhooks provide event-driven updates.

 

When a webhook contains a final paymentStatus, it may be used for business processing. Status Inquiry should be used when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

The reconciliation and validation mechanisms described in E. Notifications and Transaction Status should be followed where applicable.

Step 5 – Confirm Final State (Status Inquiry)

The merchant may confirm the final transaction state using Status Inquiry when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

Endpoint

GET <ROOT_URL>/payments/{transactionID}/status

Headers

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

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → MB WAY → getStatus

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2ExampleTxMBWAY123",
    "amount": {
        "value": 25.00,
        "currency": "EUR"
    }
}

Final State Rule

The Status Inquiry APIs are the latest transaction state available through the query API, used when required for the final transaction state.

This ensures consistency between:

• Customer action (mobile app)
• Webhook notifications
• Backend reconciliation and processing

This validation step is recommended when timing differences between user interaction, webhook delivery, and backend processing require confirmation or reconciliation.

This ensures consistency between event execution, webhook notifications, and backend processing, particularly in scenarios involving delays, retries, or asynchronous flows.

For scenarios requiring extended operational or financial information, integrations may additionally use the Inquiry Details endpoint documented in E.2 Status Inquiry / Get Status.

Inquiry Details complements operational analysis and troubleshooting workflows, but it must not be used as the source for determining the current or final transaction state.

Expected Final Outcome

• Success → Payment approved by user
• Declined → Payment rejected by user
• Timeout → No user action within allowed time

Timeout scenarios must still be validated using the Status Inquiry APIs to ensure that delayed processing or late user interaction did not result in a completed transaction.

The merchant may finalize the transaction based on a final webhook paymentStatus or on the response returned by the Status Inquiry APIs when required.

Implementation Notes

• MB WAY is a fully asynchronous payment method
• The merchant must handle delayed responses and user inactivity
• Webhook delivery may occur before or after status checks
• The system must be resilient to timing differences between events
• transactionID must be used across all steps
• Polling the Status Inquiry APIs may be required while waiting for user action

Merchant systems must be resilient to out-of-order event delivery and temporary inconsistencies between webhook notifications and status responses.

Operational logs and monitoring systems should correlate transactionID, merchantTransactionId, and notificationID across webhook processing, status validation, and reconciliation stages.

Temporary mobile connectivity issues or delayed customer interaction may prolong transaction completion times and should be considered during operational timeout handling.

Use of Postman Collection

The Postman Collections should be used as the execution layer for this example.

Relevant Requests

• Checkout

SIBS PAYMENT GATEWAY → MB WAY → Checkout MB WAY

• Purchase

SIBS PAYMENT GATEWAY → MB WAY → MB WAY Purchase

• Get Status

SIBS PAYMENT GATEWAY → MB WAY → getStatus

Use the previously referenced requests to execute each step, validate responses, and simulate different transaction outcomes in sandbox environments.

Recommended Usage

• Execute checkout
• Trigger MB WAY payment
• Simulate approval or timeout scenarios
• Validate final status

Final Notes

This example demonstrates a fully asynchronous payment flow dependent on external user interaction.

For production-grade implementations:

• Use API responses for immediate execution flow control
• Use Webhooks for event-driven updates
• Use Status Inquiry APIs when no final webhook is available or when additional confirmation, recovery, or reconciliation is required

This ensures reliable handling of user-driven payments and prevents incorrect transaction finalization.