Prerequisites (once per merchant/environment)

You need the following credentials and configuration elements before calling the SIBS SPG APIs:

• AuthToken : used as Authorization: Bearer <AuthToken> for REST calls
• TerminalId : the terminal ID assigned to the merchant, by the SIBS OnBoarding team
• X-IBM-Client-Id : merchant application identifier assigned by the SIBS OnBoarding team

Choose the appropriate API environment URL (<ROOT_URL>) for the target environment.

Please refer to A.3 – API Requests for the complete list of environment-specific URLs.

Overview

MB WAY Authorized Payments allow the creation of a mandate (Authorized Payment) that enables subsequent transactions initiated by the merchant.

The process includes:

1. Mandate creation request
2. Customer authorization in the MB WAY application
3. Mandate status monitoring

During authorization, the customer:

• Confirms the mandate
• Defines a maximum amount limit
• Defines an expiration date

The process is asynchronous.

Important

A successful Authorized Payment creation only creates and activates the mandate.

No funds are moved during this step.

Subsequent payments must be performed in a separate operation using the active Authorized Payment.

API Request Flow

The Authorized Payment flow consists of:

1. Create Authorized Payment (mandate)
2. Customer approval in MB WAY application
3. Inquiry of mandate status

1) Create the Authorized Payment (Mandate)

1.1 POST Mandate creation to:

curl -v -X POST '<ROOT_URL>/mbway-mandates/creation' \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "merchant": {
        "terminalId": "58019",
        "channel": "web",
        "merchantTransactionId": "unique-order-id"
    },
    "mandate": {
        "mandateType": "SUBSCRIPTION",
        "aliasMBWAY": "351#900000000",
        "customerName": "Customer Name"
    }
}'

Processing Behavior

• The mandate request is forwarded to MB WAY
• The customer receives a push notification
• The customer authorises the mandate and defines constraints
• The result is returned asynchronously

The mbwayPhoneNumber field should be collected in the Merchant environment. The format of the phone number is <country code>#<phone number>.

Example:

351#900000000

2) Customer Authorization

Goal: Allow the customer to approve the Authorized Payment.

Characteristics

• Performed in the MB WAY mobile application
• Requires explicit user interaction
• Maximum authorization window: ~10 minutes
• Final mandate confirmation is asynchronous and requires Status Inquiry / Monitoring when webhook confirmation is not available or when additional status confirmation is required.

3) Check Mandate Authorization Status until it is finalized (Back-End)

Goal: Confirm the final authorization status after the authorization process is completed.

3.1 When to check status

You must verify the transaction status, right after receiving the authorization creation response, up until 10 minutes after (the user has 10 minutes maximum to accept or reject the operation. After that time, the transaction will timeout)

3.2 Status endpoints you can use

SIBS SPG documents two common options:

• POST <ROOT_URL>/mbway-mandates/{transactionID}/inquiry (where {transactionID} is transactionID from the mandate creation operation)

curl -v -X POST "<ROOT_URL>/mbway-mandates/{transactionID}/inquiry" \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json"
--header "Mbway-ID: <mbwayPhoneNumber>"
--data '{}'

Where {transactionID} is the value obtained in the mandate creation response (Step 1).

3.3 Required headers (status call)

• Authorization: Bearer <AuthToken>
• X-IBM-Client-Id: <clientid>
• Content-Type: application/json
• Accept: application/json
• Mbway-ID: <mbwayPhoneNumber>

3.4 Expected Response

Example response:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    },
    "mandate": {
        "mandateId": "......",
        "mandateType": "SUBSCRIPTION",
        "customerName": "......",
        "mandateStatus": "ACTV",
        "aliasMBWAY": "...",
        "mandateExpirationDate": "...",
        "transactionId": "...",
        "amountLimit": {
            "value": "100.00",
            "currency": "EUR"
        }
    }
}

Note: the mandateId returned by the inquiry operation is required for subsequent payment collection operations.

3.5 Mandate Status and Interpretation

Possible mandateStatus values are:

• ACTV : Active
• SSPN : Suspended
• EXPR : Expired
• CNCL : Cancelled

Mandate Status Interpretation

The Authorized Payment creation should only be considered successful when:

• returnStatus.statusCode = "000"
• mandate.mandateStatus = "ACTV"

3.6 Polling strategy (minimal, practical skeleton)

• Poll POST <ROOT_URL>/mbway-mandates/{transactionID}/inquiry every few seconds
• Stop polling when:
  • mandate.mandateStatus is in a final state (ACTV, SSPN, EXPR, CNCL), or
  • the maximum polling window is reached.
• If still Pending continue polling with a timeout safeguard

If the status is Pending, the merchant should:

1. Wait a few seconds
2. Poll the Status endpoint again
3. Stop polling when a final state is reached

Recommended polling strategy:

• Interval: 3–5 seconds
• Maximum duration: up to 10 minutes (authorization window)
• Always implement idempotent processing logic

Merchants may implement a shorter timeout based on business requirements.

Even if polling is implemented, SIBS SPG supports Merchant Notification (webhooks) for asynchronous payments.

Webhook behavior

SIBS SPG may send a Merchant Notification (webhook) after the Authorized Payment is created, containing mandate details such as limits and expiration date.

Webhook notifications and, where needed, Status Inquiry should be used for mandate lifecycle monitoring and operational reconciliation.

3.7 Recommended monitoring strategy

For MBWAY Mandates Server-to-Server Integration:

• If Pending, retry status after a short delay (few seconds).
• Stop when a final mandate state is reached (ACTV, SSPN, EXPR, CNCL).

Decision Logic

The inquiry response should be interpreted as follows:

• If returnStatus.statusCode is not “000“, the operation must not be considered valid.
• If mandate.mandateStatus = "ACTV", the Authorized Payment is active and can be used for future collection.
• If mandate.mandateStatus is “SSPN“, “EXPR“ or “CNCL“, the Authorized Payment must not be used.
• If the status is Pending, the merchant should continue polling until a final state is reached or the timeout is exceeded.

3.8 Persistence Requirements

After mandate creation, the merchant should persist the transactionID returned in the creation response.

The SPG transactionID should be treated as the primary and authoritative identifier for mandate monitoring, webhook correlation, reconciliation, inquiry monitoring, and recurring collection lifecycle operations.

Once the Authorized Payment is available via the inquiry operation, the merchant should persist:

• transactionID (from mandate creation)
• mandateId (required for payment collection)
• mandateStatus
• aliasMBWAY
• mandateExpirationDate
• amountLimit

This information is required to support future operations using the Authorized Payment.

Important Notes

• The final Authorized Payment Status confirmation must always be validated server-to-server.
• Mandate creation does not perform any payment collection.
• The initial creation response must not be used as final confirmation of the mandate status.
• The final state must always be validated using the inquiry endpoint.
• The authorization process may take up to 10 minutes depending on customer interaction.

The Sandbox Payment Simulator may be used to validate mandate creation requests, customer authorization behavior, inquiry operations, mandate status transitions, timeout scenarios, and recurring payment preparation flows in the sandbox environment.

Next Step

After the Authorized Payment is successfully created and the mandate is in state “ACTV“, the merchant can perform payment collection using the mandate.

See D.2.1.3 – Recurring Payments – MBWAY Authorized Payments Collection for details on executing payments using an active Authorized Payment.

The Sandbox Payment Simulator may also be used to validate MB WAY Authorized Payment mandate creation flows, customer authorization interaction, mandate lifecycle progression, mandate inquiry operations, recurring collection scenarios, and operational request/response payloads in the sandbox environment.

Example sandbox simulator entry point

For webhook delivery behavior, retry semantics, payload interpretation, and notification security considerations, refer to E.1 – Webhooks (Notifications).

For complete Status Inquiry endpoint specifications and response interpretation, refer to E.2 – Status Inquiry / Get Status.

Practical MB WAY mandate creation examples, inquiry workflows, recurring payment collections, Postman collections, and operational testing scenarios are documented in F. Technical Examples and Best Practices.