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 Recurring Payments – MBWAY Authorized Payments)
• 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 environment root URLs (you will use them in the API base URL).

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

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 -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/payments" \
  --header "Authorization: Bearer <AuthToken>" \
  --header "X-IBM-Client-Id: <ClientId>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "mandate": {
        "mandateId": "{{mbwayMandateId}}"
    },
    "merchant": {
        "terminalId": {{terminalId}},
        "channel": "web",
        "merchantTransactionId": "{{merchantUniqueTransactionId}}"
    },
    "transaction": {
        "transactionTimestamp": "2026-03-21T19:14:11.711Z",
        "description": "{{transactionDescription}}",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": {{amount}},
            "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

2) Execute purchase using mandate

Goal: Trigger the payment using the existing Authorized Payment.

2.1 POST Purchase using Authorized Payment (mandate) to:

curl -X POST "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{{transactionID}}/mbway-id/purchase" \
  --header "Authorization: Digest <transactionSignature>" \
  --header "X-IBM-Client-Id: <ClientId>" \
  --header "Content-Type: application/json" \
  --header "Accept: 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 is required
• 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:

curl -X GET "https://api.qly.sibspayments.com/sibs/spg/v2/payments/{{transactionID}}/status" \
  --header "Authorization: Bearer <AuthToken>" \
  --header "X-IBM-Client-Id: <ClientId>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  

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 /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 complement polling but do not replace server-to-server validation.

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 or InProcessing, 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.
• 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