Overview

This section provides annotated request and response examples for MB WAY payments, focusing on the payload structures used in the most common MB WAY scenarios.

MB WAY payments are asynchronous by design in most scenarios, as customer confirmation is performed outside the merchant system in the MB WAY application.

The objective of this section is to clarify how MB WAY requests and responses must be constructed and interpreted at payload level, including:

• Checkout creation
• MB WAY payment execution
• Initial pending responses
• Final state confirmation through Webhooks and Status Inquiry

Scope and Context

This section focuses strictly on payload construction and response interpretation for MB WAY operations.

For:

• End-to-end flow sequencing → see F.1 – End-to-End Integration Examples
• Payment flow definitions → see D. Payment Methods
• Status and error semantics → see C. Meta Information, Codes and Transaction States
• Webhook structures → see E.1 – Webhooks (Notifications)

1. Checkout Creation (MB WAY Enabled)

Request

POST <ROOT_URL>/payments

{
    "merchant": {
        "terminalId": "11111",
        "channel": "web",
        "merchantTransactionId": "MBWAY-PURS-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-16T10:15:30.000Z",
        "description": "MB WAY payment",
        "paymentType": "PURS",
        "paymentMethod": [
            "MBWAY"
        ],
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        }
    }
}

This operation uses Bearer authentication.

Key Annotations

• paymentMethod = ["MBWAY"]
→ Restricts the checkout to MB WAY only
• paymentType = "PURS"
  → Indicates a one-off MB WAY payment request
• merchantTransactionId
  → Must be unique per transaction attempt

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "transactionID": "txMBWAY123456789",
    "merchant": {
        "merchantTransactionId": "MBWAY-PURS-0001"
    },
    "paymentMethodList": [
        "MBWAY"
    ],
    "execution": {
        "startTime": "2026-04-16T10:15:30.050Z",
        "endTime": "2026-04-16T10:15:30.210Z"
    }
}

Interpretation

• statusCode = "000"
  → Confirms successful request processing only
• transactionID
  → Must be persisted and used as the primary SPG identifier for all subsequent operations, status inquiries, and webhook correlation. Merchant-defined identifiers must not be used as substitutes.

2. MB WAY Payment Execution

Request

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

{
    "customerPhone": "351#912345678"
}

Request Headers

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

This operation requires Digest authentication using the transaction signature returned during the checkout step.

The Digest signature is associated with the transaction context created during the checkout initialization process.

Key Annotations

• customerPhone
  → MB WAY alias in international format

Expected structure:
<countryCode>#<mobileNumber>

Example:
351#912345678

This value identifies the mobile number to which the MB WAY authorization request will be sent.

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Pending",
    "paymentMethod": "MBWAY",
    "transactionID": "txMBWAY123456789",
    "execution": {
        "startTime": "2026-04-16T10:15:31.020Z",
        "endTime": "2026-04-16T10:15:31.310Z"
    }
}

Interpretation

• paymentStatus = "Pending"
  → This is the expected initial outcome for a standard MB WAY payment request

The paymentStatus value may evolve during the transaction lifecycle as customer interaction and payment validation progress.

The initial response only confirms that:

• the request was accepted
• the MB WAY authorization request was initiated
• customer confirmation is still pending

This does not represent the final payment result.

3. Asynchronous Nature of MB WAY

Behavior

MB WAY payments normally require customer interaction in the MB WAY application.

After the purchase request is submitted:

• the customer receives a push notification in the MB WAY app
• the customer accepts or declines the payment
• the final result is communicated later through Webhooks and/or confirmed via Status Inquiry
• the customer may also ignore or abandon the authorization request, resulting in timeout or incomplete transaction scenarios

Typical Initial Indicators

Common initial response patterns include:

• returnStatus.statusCode = "000"
• paymentStatus = "Pending"

In practice, this means:

• the API call was successful
• the transaction has not yet reached its final state

Important

The initial MB WAY response must never be treated as final payment confirmation.

Final state may be established through:

• Webhook notification
• Status Inquiry

When discrepancies exist between intermediate responses and asynchronous updates, the latest transaction state should be checked using Status Inquiry.

See also F.7.1 – Misinterpreting Payment Finality (Synchronous vs Asynchronous).

4. Final State Confirmation

Webhook-Based Confirmation

A later webhook may indicate, for example:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "txMBWAY123456789",
    "paymentType": "PURS",
    "notificationID": "notif-123456"
}

Status Inquiry Confirmation

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

This request does not require a request body.

Possible status response:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "transactionID": "txMBWAY123456789",
    "amount": {
        "value": 49.90,
        "currency": "EUR"
    }
}

Interpretation

The status response provides the latest transaction state available through the query API and should be used when confirmation, recovery, or reconciliation is required.

When a final webhook is received, the merchant-side decision may be based on the final webhook paymentStatus; Status Inquiry should be used when confirmation, recovery, or reconciliation is required.

For a detailed explanation of status retrieval, polling strategies, and response interpretation, see E.2 – Status Inquiry / Get Status.

5. Declined or Expired Scenarios

MB WAY payments may also end in:

• Declined
• Timeout
• Error

Example:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Declined",
    "transactionID": "txMBWAY123456789"
}

Interpretation

A technically successful API interaction may still produce a business-level decline.

This is why:

• returnStatus
• paymentStatus

must always be interpreted separately.

6. Optional In-App Variant

Some MB WAY integrations may use the optional inApp flag.

Request Example

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

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

Meaning

inApp = true
→ Indicates that the merchant is requesting the in-app MB WAY flow where applicable

Availability and behavior may depend on the integration environment, device context, and MB WAY application capabilities.

This affects user experience and redirection behavior, but does not change the core interpretation model:

• initial response may still be pending
• final state may be determined from Webhooks or Status Inquiry when required

Common Pitfalls

1. Treating the initial response as final

A Pending response does not mean payment success.

2. Misinterpreting returnStatus

"000" confirms technical success of the API call, not business success of the payment.

3. Using an invalid phone format

customerPhone must follow the expected alias format.

4. Not persisting transactionID

Without it, the merchant cannot:

• query status
• correlate webhooks
• complete reconciliation

5. Not handling timeout or customer inaction

MB WAY depends on customer confirmation and may not complete immediately.

Key Takeaways

MB WAY integrations are fundamentally asynchronous in most payment scenarios.

The core interpretation model is:

• initial request accepted → usually Pending
• customer confirms in MB WAY app
• final state established later
• merchant determines final state through Webhooks or Status Inquiry when required

transactionID must always be persisted and used as the primary SPG correlation key for all operations, status inquiries, and webhook processing.

This section provides the reference foundation for implementing and troubleshooting MB WAY request and response handling in SPG.