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 the Status Inquiry endpoint

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
  • mandateId
  • 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)

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
• mandateId (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 polling to determine the final outcome.

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

 

They must not be used to determine the final transaction outcome.

Step 4 – Confirm Mandate (Status Inquiry)

The merchant must confirm that the mandate has been successfully created.

Endpoint

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

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

The mandate must be confirmed as successfully created 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>/api/v2/payments

Headers

Authorization: Digest <transactionSignature>
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 only.

 

They must not be used to determine the final transaction outcome.

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)

The merchant must confirm that the collection transaction has been successfully completed.

Endpoint

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

Authoritative Rule

The Status endpoint is the single source of truth for the final transaction state.

This ensures consistency between:

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

This ensures consistency between event execution, webhook notifications, and backend processing, particularly in scenarios involving delays, retries, or asynchronous 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 is mandatory for both phases
• Mandate lifecycle events (e.g., cancel, renew) must be handled

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 for final validation

This ensures secure, compliant, and reliable handling of mandate-based recurring payments.