Overview

This section provides annotated request and response examples for Multibanco Reference payments, focusing on the payload structures required to generate and manage payment references.

Unlike real-time payment methods (e.g., CARD, MB WAY), Multibanco Reference payments are deferred by design:

• The payment is not executed at checkout time
• A reference is generated and presented to the customer
• The customer completes the payment later via ATM or online banking

The objective of this section is to clarify how Multibanco Reference requests and responses must be constructed and interpreted at payload level, including:

• Checkout creation
• Reference generation
• Reference attributes (entity, reference, expiration)
• Multischeme reference attributes when enabled
• Final state confirmation

Scope and Context

This section focuses strictly on payload construction and response interpretation for Multibanco Reference operations.

For:

• End-to-end flow sequencing → see F.1 – End-to-End Integration Examples
• Payment flow definitions → see D. Payment Methods
• Status and error semantics → see C. Meta Information, Codes and Transaction States
• Webhook structures → see E.1 – Webhooks (Notifications)

1. Checkout Creation (REFERENCE Enabled)

Request

POST <ROOT_URL>/payments

{
    "merchant": {
        "terminalId": "11111",
        "channel": "web",
        "merchantTransactionId": "MBREF-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-16T10:15:30.000Z",
        "description": "Multibanco Reference payment",
        "paymentType": "PURS",
        "paymentMethod": [
            "REFERENCE"
        ],
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        }
    }
}

This operation uses Bearer authentication.

Key Annotations

• paymentMethod = ["REFERENCE"]
→ Restricts the checkout to Multibanco Reference only
• paymentType = "PURS"
  → Indicates a one-off payment request (reference-based)
• merchantTransactionId
  → Must be unique per transaction attempt

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "transactionID": "txMBREF123456789",
    "merchant": {
        "merchantTransactionId": "MBREF-0001"
    },
    "paymentMethodList": [
        "REFERENCE"
    ],
    "execution": {
        "startTime": "2026-04-16T10:15:30.050Z",
        "endTime": "2026-04-16T10:15:30.210Z"
    }
}

Interpretation

• statusCode = "000"
  → Confirms successful request processing only
• transactionID
  → Must be persisted and used as the primary SPG identifier for all subsequent operations, status inquiries, and webhook correlation. Merchant-defined identifiers must not be used as substitutes.

2. Reference Generation

Request

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

Body

(empty)

This request does not require a request body.

No request payload is required for this operation.

Request Headers

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

This operation requires Digest authentication using the transaction signature returned during the checkout step.

The Digest signature is associated with the transaction context created during the checkout initialization process.

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Pending",
    "paymentMethod": "REFERENCE",
    "transactionID": "txMBREF123456789",
    "paymentReference": {
        "entity": "12345",
        "reference": "123 456 789",
        "expireDate": "2026-04-20T23:59:59.000Z"
    }
}

Key Annotations

• paymentStatus = "Pending"
  → Expected state after reference generation
• paymentReference.entity
  → Multibanco entity identifier
• paymentReference.reference
→ Payment reference to be presented to the customer
• paymentReference.expireDate
  → Expiration timestamp for the reference

The paymentStatus value may evolve during the transaction lifecycle as payment execution, expiration, or cancellation events occur.

Interpretation

This response confirms that:

• The reference was successfully generated
• The customer can now perform the payment
• Payment remains possible only while the generated reference is valid and not expired.
• The transaction is awaiting payment

This does not represent payment completion.

3. Multischeme Reference Generation

Multibanco Reference generation may support additional payment schemes beyond the default MB scheme.

Merchants may indicate additional entities or schemes during the Checkout process when generating Multibanco references.

The following additional Checkout fields are supported:

• additionalEntities → Collection of additional entity configurations
• entity → Entity associated with the additional scheme
• scheme → Payment scheme associated with the entity

Supported payment schemes include:

• VISA
• MASTERCARD
• UPI

Actual scheme availability depends on merchant configuration, acquirer capabilities, and enabled SPG features.

Key Annotations

• additionalEntities → Allows the merchant to define additional schemes beyond the default MB reference configuration
• entity → Identifies the entity associated with the additional scheme
• scheme → Defines the payment scheme requested by the merchant

Interpretation

When Multischeme is enabled:

• The default MB reference flow remains supported
• Additional schemes may be configured during Checkout
• The customer may be presented with additional available schemes depending on merchant configuration

Schemes other than MB are returned through the References complex type using the fields reference and scheme.

The default MB reference continues to be returned through the standard paymentReference structure.

For the operational behavior of Multischeme payments within the broader payment lifecycle, refer to D.1.3 – One-Off Payments – Multibanco Reference.

4. Deferred Payment Behavior

Characteristics

Multibanco Reference payments follow a deferred execution model:

• No immediate customer interaction is required at checkout
• Payment may occur:
  • Minutes later
  • Hours later
  • Days later (until expiration)

Important

• The transaction remains in Pending state until:
  • Payment is completed
  • Reference expires
  • Transaction is explicitly cancelled
• The merchant must handle:
  • Delayed confirmations
  • Potential non-payment

5. Final State Confirmation

Webhook-Based Confirmation

A successful payment may trigger a webhook:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "REFERENCE",
    "transactionID": "txMBREF123456789",
    "paymentReference": {
        "entity": "12345",
        "reference": "123 456 789"
    },
    "paymentType": "PURS",
    "notificationID": "notif-987654"
}

Status Inquiry Confirmation

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

Possible status response:

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "transactionID": "txMBREF123456789",
    "amount": {
        "value": 49.90,
        "currency": "EUR"
    }
}

Interpretation

The final transaction state may be determined using:

• Webhooks
• Status Inquiry

Status Inquiry provides the latest transaction state available through the query API.

When discrepancies exist between intermediate responses, webhook notifications, or delayed operational updates, the latest transaction state should be checked using Status Inquiry.

For detailed guidance on status retrieval and response interpretation, see E.2 – Status Inquiry / Get Status.

6. Expired or Unpaid References

Possible Outcomes

• Success → Customer completed payment
• Timeout → Reference expired without payment
• Error → Processing issue

Example (Expired Reference)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Timeout",
    "transactionID": "txMBREF123456789"
}

Interpretation

• The payment was not completed within the allowed time
• The reference is no longer valid
• Expired references cannot be reused or reactivated
• A new transaction must be created if payment is still required

Common Pitfalls

1. Treating reference generation as payment completion

Reference generation only prepares the payment.

2. Not displaying reference details correctly

Customer must receive:

• Entity
• Reference
• Expiration date

3. Not handling expiration

References may expire without payment.

4. Ignoring asynchronous confirmation

Payment completion is not immediate.

5. Not persisting transactionID

Required for:

• Status checks
• Webhook correlation
• Reconciliation

6. Not handling Multischeme reference data

When Multischeme is enabled, merchants must not assume that all reference data is returned only through the standard paymentReference structure. Scheme-specific reference information may be returned through the References complex type.

Key Takeaways

Multibanco Reference is a deferred payment method.

The integration model is:

• Checkout created
• Reference generated
• Customer pays later
• Final state confirmed asynchronously

paymentStatus = "Pending" after generation is expected and correct.

Final confirmation may rely on:

• Webhooks
• Status Inquiry

This section provides the reference foundation for implementing and troubleshooting Multibanco Reference request and response handling in SPG.