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

Additionally, you must have a previously active Authorized Payment (mandate):

• mandateId obtained from the Authorized Payment creation flow (see D.2.1.2 – Recurring Payments – MBWAY Authorized Payments [Server-to-Server Integration])
• mandate.mandateStatus = "ACTV"

The mandateId used in this operation must be obtained from the Authorized Payment creation flow and validated as ACTV via the inquiry operation.

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 Collection allows the merchant to charge a customer using an existing Authorized Payment (mandate).

The process consists of:

1. Create a payment (checkout) referencing the mandate
2. Execute the purchase using the mandate
3. Validate the transaction status

This process is server-to-server and does not require customer interaction, provided that:

• The Authorized Payment is active
• The transaction respects the mandate constraints (amount limit and validity period)

• A valid and active mandate is required before performing any collection
• No customer approval is required during collection
• The transaction must comply with:
  • Mandate expiration date
  • Mandate amount limit

Although the collection is initiated using the MB WAY channel, transactions executed using an Authorized Payment are identified with paymentMethod = "MANDATE" in API responses.

API Request Flow

The Authorized Payment Collection flow consists of:

1. Create payment (checkout) using mandate
2. Execute purchase using mandate
3. Check transaction status

1) Create payment (checkout) using mandate (Server-to-Server)

Goal: Create a payment transaction referencing an existing Authorized Payment.

1.1 POST Payment creation to:

curl -v -X POST '<ROOT_URL>/payments' \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "mandate": {
        "mandateId": "{{mbwayMandateId}}"
    },
    "merchant": {
        "terminalId": "58019",
        "channel": "web",
        "merchantTransactionId": "unique-order-id"
    },
    "transaction": {
        "transactionTimestamp": "2028-12-31T00:00:00.000Z",
        "description": "MBWAY Collection operation",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": 5.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "MANDATE"
        ]
    },
    "customer": {
        "customerInfo": {
            "customerName": "{{customerName}}",
            "customerEmail": "{{customerEmail}}",
            "shippingAddress": {
                "street1": "{{shippingAddressStreet1}}",
                "street2": "{{shippingAddressStreet2}}",
                "city": "{{shippingAddressCity}}",
                "postcode": "{{shippingAddressPostalCode}}",
                "country": "PT"
            },
            "billingAddress": {
                "street1": "{{billingAddressStreet1}}",
                "street2": "{{billingAddressStreet2}}",
                "city": "{{billingAddressCity}}",
                "postcode": "{{billingAddressPostalCode}}",
                "country": "PT"
            }
        }
    }
}'

Headers

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

Processing Behavior

• A payment transaction is created referencing the mandate
• A transactionID is returned
• No funds are captured at this stage

The SPG transactionID should be treated as the primary and authoritative identifier for collection monitoring, webhook correlation, reconciliation, transaction monitoring, and operational lifecycle tracking.

2) Execute purchase using mandate

Goal: Trigger the payment using the existing Authorized Payment.

2.1 POST Purchase using Authorized Payment (mandate) to:

curl -v -X POST '<ROOT_URL>/payments/{transactionID}/mbway-id/purchase' \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Digest <transactionsignature>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "mandate": {
        "mandateCreation": false,
        "useMBWAYMandate": true
    }
}'

Headers

• Authorization: Digest <transactionSignature>
• X-IBM-Client-Id: <ClientId>
• Content-Type: application/json
• Accept: application/json

Processing Behavior

• The transaction is executed using the Authorized Payment
• No customer interaction or customer approval is required during collection
• The payment is processed asynchronously

2.2 Example Response

{
    "transactionID": "s2si95ESKukZ25VZs2bc",
    "paymentStatus": "Success",
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    }
}

3) Check Transaction Status (Back-End)

Goal: Validate the final status of the transaction.

3.1 GET Transaction status to:

The following Status Inquiry options are commonly used:

• GET <ROOT_URL>/payments/{transactionID}/status (where {transactionID} is the transactionID returned by the Purchase operation)

curl -v -X GET "<ROOT_URL>/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

Headers

3.2 Example Response

{
    "merchant": {
        "terminalId": "58019",
        "merchantTransactionId": "4b218123df5a481fb2f84bbb50caf507"
    },
    "transactionID": "s2si95ESKukZ25VZs2bc",
    "amount": {
        "currency": "EUR",
        "value": "5.20"
    },
    "paymentType": "PURS",
    "paymentStatus": "Success",
    "token": {
        "tokenType": "MobilePhone"
    },
    "paymentMethod": "MANDATE",
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    },
    "transactionStatusCode": "000",
    "transactionStatusDescription": "Success"
}

3.3 Status Interpretation

3.4 Success Criteria

The payment should be considered successful when:

• returnStatus.statusCode = "000"
• paymentStatus = "Success"

3.5 Polling Strategy

• Poll GET <ROOT_URL>/payments/{transactionID}/status every few seconds
• Recommended interval: 3–5 seconds
• Continue until:
  • Final status is reached, or
  • Timeout is exceeded

3.6 Webhook Behavior

SIBS SPG may send a Merchant Notification (webhook) containing the transaction result.

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

3.7 Decision Logic

The transaction response should be interpreted as follows:

• If returnStatus.statusCode is not "000", the operation must not be considered valid
• If paymentStatus = "Success", the payment is confirmed
• If paymentStatus = "Declined" or "Error", the payment failed
• If the status is Pending, continue polling

3.8 Persistence Requirements

The merchant should persist:

• transactionID
• paymentStatus
• amount
• paymentMethod

Important Notes

• The Authorized Payment must be active (mandateStatus = "ACTV") before performing collection
• The mandate must be validated as “ACTV“ at the time of collection. Expired, suspended or cancelled mandates must not be used.
• Collections must not be attempted against mandates in SSPN, EXPR, or CNCL states.
• The transaction must respect:
  • Mandate amount limit
  • Mandate expiration date
• No customer interaction occurs during collection
• The final payment confirmation must always be validated server-to-server
• The initial payment creation response must not be used as final confirmation

The Sandbox Payment Simulator may also be used to validate MB WAY Authorized Payment collection flows, mandate-based purchase execution, transaction status progression, collection success and failure 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 Authorized Payment collection examples, Postman collections, recurring payment workflows, and operational testing scenarios are documented in F. Technical Examples and Best Practices.