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 environment root URLs (you will use them in the API base URL and in the widget URL).

Please refer to the API Requests documentation page for more information.

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 validation

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) PREPARE THE MANDATE CREATION (SERVER-TO-SERVER)

1.1 POST Mandate creation to:

curl -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/mbway-mandates/creation" \
  --header "Authorization: Bearer <AuthToken>" \
  --header "X-IBM-Client-Id: <ClientId>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "merchant": {
        "terminalId": {{terminalId}},
        "channel": "web",
        "merchantTransactionId": "9ad9799c0cd248719d3868cb78d46338"
    },
    "mandate": {
        "mandateType": "SUBSCRIPTION",
        "aliasMBWAY": "{{mbwayPhoneNumber}}",
        "customerName": "{{customerName}}"
    }
}'

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

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
• No synchronous confirmation

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 /api/v2/mbway-mandates/{{transactionID}}/inquiry (where {transactionID} is transactionID from the mandate creation operation)

curl -v -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/mbway-mandates/{{transactionID}}/inquiry" \
--header "X-IBM-Client-Id: <ClientId>" \
--header "Authorization: Bearer <AuthToken>" \
--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 /api/v2/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 or InProcessing continue polling with a timeout safeguard

If the status is Pending or InProcessing, 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 complement the polling mechanism but do not replace server-to-server validation using the inquiry endpoint.

3.7 Recommended validation 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 or InProcessing, 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.

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.

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 Recurring Payments – MBWAY Authorized Payments Collection for details on executing payments using an active Authorized Payment.