Overview

This example illustrates a complete end-to-end flow for a one-off payment using Multibanco Reference.

It demonstrates how the merchant system:

• Creates a checkout session configured for Multibanco Reference
• Generates the payment reference
• Presents the payment details to the customer
• Receives asynchronous updates via Webhooks
• Confirms the final transaction state using the Status Inquiry endpoint

This scenario represents a deferred / offline payment flow, where the transaction is not completed at the moment the reference is generated. Instead, the customer uses the generated payment details to complete the payment through a Multibanco-supported channel, and the merchant system must reconcile the final result asynchronously. The Postman collections include both the execution flow and sandbox scenarios for unpaid and paid references.

Goal

Process a one-off payment using Multibanco Reference, ensuring:

• Correct checkout creation for reference-based payment
• Correct generation and presentation of reference details
• Reliable handling of deferred payment completion
• Final reconciliation using the Status API

Preconditions

Before executing this flow, the following must be in place:

• Valid SPG credentials:
  • terminalId
  • X-IBM-Client-Id
  • Bearer token
• Configured Webhook endpoint
• Backend capable of storing:
  • transactionID
  • merchantTransactionId
• Valid Multibanco test entity, when applicable
• Ability to present and persist reference details for customer access

In Postman, ensure the following variables are configured:

• terminalId
• ClientID
• Bearer
• host
• entity

(See collection root variables in SIBS PAYMENT GATEWAY POSTMAN Collection)

Step 1 – Create Checkout

The merchant initiates the payment by creating a checkout configured for Multibanco Reference.

Endpoint

POST <ROOT_URL>/api/v2/payments

Headers

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

Example Request

{
    "merchant": {
        "terminalId": 11111,
        "channel": "web",
        "merchantTransactionId": "ORDER-REF-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-15T13:00:00.000Z",
        "description": "Multibanco Reference payment",
        "moto": false,
        "paymentType": "PURS",
        "amount": {
            "value": 20.00,
            "currency": "EUR"
        },
        "paymentMethod": [
            "REFERENCE"
        ],
        "paymentReference": {
            "initialDatetime": "2026-04-15T13:00:00.000Z",
            "finalDatetime": "2026-04-20T23:59:59.000Z",
            "maxAmount": {
                "value": 20.00,
                "currency": "EUR"
            },
            "minAmount": {
                "value": 20.00,
                "currency": "EUR"
            },
            "entity": "40200"
        }
    }
}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Multibanco → Checkout REFERENCE

Key Outputs

• transactionID → primary identifier
• transactionSignature → required for reference generation

The transactionID must be used as the primary correlation identifier across all subsequent steps, including reference generation, webhook processing, and status validation.

Step 2 – Generate Reference

After checkout creation, the merchant generates the Multibanco reference.

Endpoint

POST <ROOT_URL>/api/v2/payments/{transactionID}/service-reference/generate

Headers

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

Example Request

{}

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Multibanco → Generate Reference

Expected Behavior

This step generates the payment reference details associated with the transaction. The payment itself is still not completed at this point.

Typical Output Data

The generated reference details are later available through the Status API under paymentReference, including:

• entity
• reference
• amount
• expireDate
• status

Step 3 – Present Reference Details to the Customer

After the reference is generated, the merchant must present the payment details to the customer.

The customer must be able to access at least:

• Entity
• Reference
• Amount
• Expiration date

Important

 

The transaction is not completed when the reference is generated.

At this point, the transaction should be treated as pending until the customer performs the payment through a supported Multibanco channel and the final status is confirmed.

During this period, the merchant system must rely on webhook notifications and/or status polling to detect when the payment is completed or expired.

The SIBS Postman collection explicitly describes this as a deferred flow in which the payment remains pending until the customer completes it, and the sandbox collection includes both unpaid and paid scenarios.

Step 4 – Receive and Process Webhook Notifications

SPG sends a webhook when the transaction state changes, including when the reference payment is completed.

Example Payload

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "REFERENCE",
    "transactionID": "s2ExampleTxREF123",
    "paymentType": "PURS",
    "notificationID": "notif-reference-001"
}

Processing Requirements

• Receive the notification
• Validate authenticity and integrity according to the configured webhook security model (e.g., decryption and header validation)
• Store and process the notification using notificationID as a unique identifier
• Ensure idempotent processing
• Acknowledge correctly

Response to SPG

{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "notif-reference-001"
}

The notificationID must match the value received in the webhook payload.

Important

 

Webhooks provide event-driven updates only.

 

They must not be used to determine the final transaction outcome.

Step 5 – Confirm Final State (Status Inquiry)

The merchant must confirm the final transaction state using the Status API.

Endpoint

GET <ROOT_URL>/api/v2/payments/{transactionID}/status

Headers

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

Execute this step in Postman using:

Collection Path:

SIBS PAYMENT GATEWAY → Multibanco → getStatus

Example Response

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Pending",
    "transactionID": "s2ExampleTxREF123",
    "amount": {
        "value": 20.00,
        "currency": "EUR"
    },
    "paymentReference": {
        "entity": "40200",
        "reference": "123 456 789",
        "amount": {
            "value": 20.00,
            "currency": "EUR"
        },
        "expireDate": "2026-04-20T23:59:59.000Z",
        "status": "UNPAID"
    }
}

The SPG manual defines paymentReference in the status response for reference-based payments, including entity, reference, amount, expireDate, and status, with possible values such as UNPAID, PAID, PARTPAIDCLS, PARTPAIDOPN, CANC, and UNKN.

Authoritative Rule

The Status endpoint is the single source of truth for the final transaction state.

This ensures consistency between:

• Customer payment action
• Webhook notifications
• Backend processing

This validation step is mandatory to resolve potential timing differences between customer payment, webhook delivery, and backend processing.

This ensures consistency between event execution, webhook notifications, and backend processing, particularly in scenarios involving delays, retries, or asynchronous flows.

Step 6 – Reconcile Final Outcome

The merchant system must finalize the transaction using the Status API response.

Typical Outcome Patterns

• paymentStatus = Pending and paymentReference.status = UNPAID
  → The reference was generated, but payment has not yet been completed
• paymentStatus = Success and paymentReference.status = PAID
  → The reference payment has been completed successfully
• Expiration reached with no successful payment
  → The merchant must treat the transaction as expired / not paid according to internal business rules, confirmed via status validation

The sandbox Postman collection includes explicit Multibanco scenarios for unpaid and paid references, using:

• MULTIBANCO → Multibanco - UNPAID
• MULTIBANCO → Multibanco - PAID

Implementation Notes

• Multibanco Reference is a deferred / offline payment method
• Reference generation does not mean payment completion
• The merchant must persist and expose the reference details to the customer
• Webhook delivery may occur before or after a status query
• The system must be resilient to timing differences between events
• transactionID must be used across all steps
• Status polling may be required, especially around the expiration moment or when no webhook is received

The SIBS collection guidance also recommends using getStatus after generation and again after expiration if no webhook is received.

Use of Postman Collection

The Postman Collections should be used as the execution layer for this example.

Relevant Requests

• Checkout

SIBS PAYMENT GATEWAY → Multibanco → Checkout REFERENCE

• Generate Reference

SIBS PAYMENT GATEWAY → Multibanco → Generate Reference

• Get Status

SIBS PAYMENT GATEWAY → Multibanco → getStatus

Use the previously referenced requests to execute each step, validate responses, and simulate different transaction outcomes in sandbox environments.

Recommended Usage

• Execute checkout
• Generate reference
• Validate reference details through status
• Simulate unpaid and paid outcomes
• Validate final status

Final Notes

This example demonstrates a deferred payment flow in which payment completion is decoupled from reference generation.

For production-grade implementations:

• Use API responses for immediate execution flow control
• Use Webhooks for event-driven updates
• Use Status Inquiry for final validation

This ensures reliable handling of deferred payments and prevents incorrect transaction finalization.