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.

Unlike Credit Card flows, MB WAY payments are typically asynchronous by design, because customer confirmation is usually performed in the MB WAY application after the payment request has been initiated.

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>/api/v2/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"
        }
    }
}

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 for the MB WAY payment request and all subsequent validation steps

2. MB WAY Payment Execution

Request

POST <ROOT_URL>/api/v2/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

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 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

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 must always be established through:

• Webhook notification
• Status endpoint

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>/api/v2/payments/{transactionID}/status

Possible status response:

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

Interpretation

The status response is the authoritative confirmation step.

Even when a webhook is received, the final merchant-side decision should be based on the confirmed transaction state.

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>/api/v2/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

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

• initial response may still be pending
• final confirmation still depends on Webhooks and Status Inquiry

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 confirms final state through Webhooks and Status Inquiry

transactionID must always be persisted and used as the primary correlation key.

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