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 a final webhook paymentStatus or Status Inquiry when required

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 a final webhook paymentStatus or Status Inquiry when required

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)

Figure – Multibanco Reference Deferred Payment Flow

Step 1 – Create Checkout

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

Endpoint

POST <ROOT_URL>/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>/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 Inquiry APIs 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.

Depending on payment timing and processing state, transactions may temporarily remain in intermediate transaction states such as Pending before reaching a final outcome.

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.

 

For Multibanco Reference generation, a webhook may indicate reference creation while the payment remains Pending. When a webhook contains a final paymentStatus, it may be used for business processing. Status Inquiry should be used when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

The reconciliation and validation mechanisms described in E. Notifications and Transaction Status should be followed where applicable.

Step 5 – Confirm Final State (Status Inquiry APIs)

The merchant may confirm the final transaction state using Status Inquiry when no final webhook is available or when additional confirmation, recovery, or reconciliation is required.

Endpoint

GET <ROOT_URL>/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.

Final State Rule

The Status Inquiry APIs are the latest transaction state available through the query API, used when required for the final transaction state.

For scenarios requiring extended operational or financial information, integrations may additionally use the Inquiry Details endpoint documented in E.2 Status Inquiry / Get Status.

Inquiry Details complements operational analysis and troubleshooting workflows, but it must not be used as the source for determining the current or final transaction state.

This ensures consistency between:

• Customer payment action
• Webhook notifications
• Backend reconciliation and processing

This validation step is recommended when timing differences between customer payment, webhook delivery, and backend processing require confirmation or reconciliation.

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 may finalize the transaction using a final webhook paymentStatus or the response returned by the Status Inquiry APIs when required.

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

Expiration-related scenarios must still be validated using the Status Inquiry APIs to ensure that delayed processing or late payment completion did not result in a successful transaction.

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
• Polling the Status Inquiry APIs 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.

Operational logs and monitoring systems should correlate transactionID, merchantTransactionId, and notificationID across reference generation, webhook processing, status validation, and reconciliation stages.

Merchant systems must be resilient to out-of-order event delivery and temporary inconsistencies between webhook notifications and status responses.

Customer payment completion may occur significantly after reference generation, depending on the payment channel used and customer interaction timing.

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 APIs when no final webhook is available or when additional confirmation, recovery, or reconciliation is required

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