Overview

This example illustrates a complete end-to-end flow for MB WAY recurring payments using mandates, based on:

• Mandate Creation (Customer Authorization) → customer grants permission for future payments
• Mandate-Based Collection (Merchant Initiated) → merchant performs subsequent charges

It demonstrates how the merchant system:

• Creates a mandate request
• Handles customer approval in the MB WAY mobile application
• Stores mandate identifiers for future use
• Executes recurring collections based on the mandate
• Processes asynchronous updates via Webhooks
• Confirms final transaction states using final webhook paymentStatus values, Mandate Inquiry, or Status Inquiry when required

This scenario represents a two-phase lifecycle, where customer authorization is decoupled from payment execution.

Goal

Enable recurring MB WAY payments using mandates, ensuring:

• Proper mandate creation and customer consent
• Secure storage of mandate identifiers
• Correct execution of mandate-based collections
• Reliable transaction validation and reconciliation

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
  • mandateIdentification
  • mandateStatus
• Customer mobile phone number (MB WAY identifier)
• Defined business rules for recurring collections

In Postman, ensure the following variables are configured:

• • terminalId
  • ClientID
  • Bearer
  • host

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

Figure – MB WAY Mandate and Collection Lifecycle

Phase 1 – Mandate Creation (Customer Authorization)

Step 1 – Create Mandate Request

The merchant initiates the mandate creation.

Endpoint

POST <ROOT_URL>/mbway-mandates/creation

Headers

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

Example Request

{
    "merchant": {
        "terminalId": 11111,
        "merchantTransactionId": "MANDATE-0001"
    },
    "transaction": {
        "amount": {
            "value": 0.00,
            "currency": "EUR"
        },
        "description": "MB WAY Mandate Creation"
    },
    "customer": {
        "phoneNumber": "351#912345678"
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → MB WAY → Create Mandate

Key Outputs

• transactionID
• mandateIdentification (after approval)

The transactionID must be used as the primary correlation identifier across all subsequent steps, including mandate validation, webhook processing, and collection execution.

Step 2 – Customer Approval (MB WAY App)

After the request:

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

Important

 

• The payment remains in a pending state until user action
• The typical timeout for user approval is approximately 10 minutes
• No payment is executed at this stage
• 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 Inquiry APIs polling to determine the final outcome.

Temporary mobile connectivity issues or delayed customer interaction may prolong mandate approval timing and affect asynchronous transaction completion behavior.

Step 3 – Receive and Process Webhook (Mandate Creation)

SPG sends a notification with the mandate result.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentMethod": "MANDATE",
    "paymentStatus": "Success",
    "transactionID": "s2ExampleMandate123",
    "notificationID": "notif-mandate-001",
    "mbwayMandate": {
        "mandateIdentification": "MANDATE123",
        "mandateAction": "CRTN",
        "mandateActionStatus": "SCCS"
    }
}

Processing Requirements

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

Response to SPG

{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "notif-mandate-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 or final mandate action status, it may be used for business processing. Mandate Inquiry or 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 4 – Confirm Mandate (Status Inquiry APIs)

At this point, the mandate transaction may still temporarily remain in intermediate transaction states such as Pending before reaching a final outcome.

The merchant may confirm that the mandate has been successfully created using Mandate Inquiry when no final mandate webhook is available or when additional confirmation, recovery, or reconciliation is required.

Endpoint

POST <ROOT_URL>/mbway-mandates/{transactionID}/inquiry

This inquiry operation is specific to MB WAY mandate lifecycle validation and complements the standard Status Inquiry APIs used for payment transaction reconciliation.

Headers

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

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "mbwayMandate": {
        "mandateIdentification": "MANDATE123",
        "mandateAction": "CRTN",
        "mandateActionStatus": "SCCS"
    }
}

A valid approved mandate must exist before performing any collection.

The mandate identifier obtained in this step must be stored and reused for all subsequent collection operations.

Phase 2 – Mandate-Based Collection (MIT Equivalent)

Step 5 – Execute Collection

The merchant initiates a payment using the approved mandate.

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": "MBWAY-COLLECTION-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-15T15:00:00.000Z",
        "paymentType": "MIT",
        "amount": {
            "value": 15.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "MBWAY"
        ]
    },
    "mbwayMandate": {
        "mandateIdentification": "MANDATE123"
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → MB WAY → Mandate Collection

Step 6 – Receive Webhook (Collection)

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

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.

Response to SPG

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

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

Step 7 – Confirm Collection (Status Inquiry APIs)

At this point, the transaction may still temporarily remain in intermediate transaction states such as Pending before reaching a final outcome.

The merchant may confirm that the collection transaction has been successfully completed using Status Inquiry when no final collection 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

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "paymentType": "MIT",
    "transactionID": "s2ExampleTxMBWAYCOL123"
}

Final State Rule

Final transaction state may be determined from a final webhook paymentStatus or via Status Inquiry when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

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.

This ensures consistency between:

• Merchant-initiated collection (no customer interaction)
• Webhook notifications
• Backend reconciliation and processing

This ensures consistency between event execution, webhook notifications, and backend reconciliation and processing, particularly in scenarios involving delayed customer approval, retries, mobile interaction latency, or asynchronous processing flows.

Expected Final Outcome

• Mandate Creation → Success
• Collection → Success

Recurring cycle continues according to business rules.

Implementation Notes

• Mandate creation and payment collection are separate operations
• No payment occurs during mandate creation
• Customer interaction occurs only during mandate creation
• Collections are fully merchant-initiated
• mandateIdentification must be stored and reused
• Webhooks may arrive before or after status validation
• Status validation should be used in each phase when no final webhook is available or when additional confirmation, recovery, or reconciliation is required
• Mandate lifecycle events (e.g., cancellation, expiration, revocation, renewal, or status changes) must be continuously monitored and handled before executing new collections.

Operational logs and monitoring systems should correlate transactionID, mandateIdentification, merchantTransactionId, and notificationID across mandate creation, collection execution, webhook processing, and reconciliation stages.

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

Mandate status changes, expiration events, customer revocations, and renewal scenarios must be continuously validated before executing new collections.

Use of Postman Collection

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

Relevant Requests

• Create Mandate

SIBS PAYMENT GATEWAY → MB WAY → Create Mandate

• Mandate Inquiry

SIBS PAYMENT GATEWAY → MB WAY → Mandate Inquiry

• Mandate Collection

SIBS PAYMENT GATEWAY → MB WAY → Mandate Collection

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

Recommended Usage

• Execute mandate creation
• Validate mandate status
• Execute collection
• Validate collection status
• Simulate success and failure scenarios

Final Notes

This example demonstrates a complete mandate-based recurring payment flow for MB WAY.

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 secure, compliant, and reliable handling of mandate-based recurring payments.