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.

API Request Flow

1) Prepare the checkout (server-to-server)

Goal: Create a checkout session in SIBS SPG and obtain the identifiers required to initiate the Multibanco Reference.

What you do

1.1 POST Checkout Payment 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 '{
    "merchant": {
        "terminalId": 58019,
        "channel": "web",
        "merchantTransactionId": "teste 12345" 
    },
    "transaction": {
        "transactionTimestamp": "2026-02-12T19:08:08.354Z", 
        "description": "Test Onboarding",
        "moto": false,
        "paymentType": "PURS", 
        "amount": {
            "value": 5.10,
            "currency": "EUR"
        },
        "paymentMethod": [
            "REFERENCE"
        ]
    }
}'

NOTE: For Multibanco Reference, paymentType = PURS creates the transaction container. The actual payment instrument is generated in Step 2.

Headers:

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

This creates the payment session.

1.2. Store from the successful response:

• transactionID : used in subsequent calls
• transactionSignature: required to authorize the Multibanco Reference generation call

At this stage, the transaction is created but no reference exists yet.

2) GENERATE MULTIBANCO REFERENCE (BACKEND)

Goal: Request the generation of the Multibanco Reference for the created transaction.

2.1 Generate Reference

curl --location 'https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/service-reference/generate' \
--header "X-IBM-Client-Id: {ClientId}" \
--header "Authorization: Digest {transactionSignature}" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
  "expiration_date": "2024-08-30T15:47:23.000Z",
  "amount": 5.10,
  "currency": "EUR"
}'

Headers

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

2.2 Request body

{
    "expiration_date": "2024-08-30T15:47:23.000Z",
    "amount": 5.10,
    "currency": "EUR"
}

Where:

• expiration_date : Date and time until which the reference is valid (ISO format)
• amount : Payment amount (decimal format)
• currency : Currency code (e.g., EUR)

Important:

• The amount must match the intended payment amount.
• If the reference expires without payment, the transaction will move to an expired state.

2.3 Successful Response

The response will contain the Multibanco payment details:

{
  "entity": "12345",
  "reference": "123 456 789",
  "amount": 5.10,
  "currency": "EUR",
  "expiration_date": "2024-08-30T15:47:23.000Z"
}

The merchant must present to the customer:

• Entity
• Reference
• Amount
• Expiration date

The customer completes the payment externally via:

• ATM
• Online banking
• Mobile banking application

2.4 Immediate Response Behaviour

After reference generation:

• The transaction moves to Pending
• No real-time authorization occurs
• Payment confirmation is asynchronous
• Final status depends on the customer completing the reference payment within the validity period

The merchant system must wait for confirmation via:

• Merchant Notifications (recommended)
• Or status polling

3) CHECK PAYMENT STATUS UNTIL IT IS PAID (BACK-END)

Goal: Confirm the final payment outcome after the customer executes the Multibanco Reference payment.

3.1 When to check status

Multibanco Reference is an asynchronous payment method.

You should:

• Listen to Merchant Notifications (recommended)
• Optionally poll the transaction status

Unlike MB WAY (where customer authorization must occur within a short timeframe — typically within minutes), Multibanco Reference payments may take hours or several days to be completed, depending on the configured expiration date.

The final payment result is not immediate and depends on the customer executing the payment before the reference expires.

3.2 Status endpoints you can use

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

Where:

• {transactionID} is the value obtained in the checkout request (Step 1).

3.3 Required headers (status call)

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

3.4 What statuses to expect (high level)

The response includes paymentStatus, with values such as:

• Success
• Pending
• Expired
• Declined
• Error
• Timeout
• InProcessing

Multibanco Reference behaviour

• After reference generation, the transaction moves to Pending.
• It may remain in Pending state for an extended period (hours or days).
• When the customer completes the payment via ATM or home banking, the status changes to Success.
• If the expiration date is reached without payment, the status becomes Expired.

The transaction must only be considered completed when the status is Success.

3.5 Polling strategy (minimal, practical skeleton)

Because Multibanco Reference payments can take significantly longer than MB WAY:

• Do not poll every few seconds.
• Avoid aggressive short-interval polling strategies.

Recommended approach

• Rely primarily on Merchant Notification (webhooks).
• Optionally implement low-frequency polling.

Suggested polling pattern

• Poll once immediately after reference generation (optional).
• Then poll at longer intervals (e.g., every 30–60 minutes).
• Stop polling when:
  • paymentStatus = Success
  • paymentStatus = Expired
  • paymentStatus = Declined
  • paymentStatus = Error
• Implement a maximum polling duration aligned with the reference expiration date.

Important Notes

• There is no capture step in Multibanco Reference.
• The transaction is automatically settled after confirmed payment.
• Expiration handling must be aligned with the configured expiration_date.
• Webhooks are strongly recommended to avoid unnecessary system load.