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)
• 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>/api/v2/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"
        }
    }
}

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 for reference generation and status tracking

2. Reference Generation

Request

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

Body

(empty)

This request does not require a request body.

An empty body must be sent.

Request Headers

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

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

Interpretation

This response confirms that:

• The reference was successfully generated
• The customer can now perform the payment
• The transaction is awaiting payment

This does not represent payment completion.

3. 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
• The merchant must handle:
  • Delayed confirmations
  • Potential non-payment

4. 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>/api/v2/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 must be determined using:

• Webhooks
• Status inquiry

The status endpoint provides the authoritative confirmation.

5. 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
• 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

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 must always rely on:

• Webhooks
• Status endpoint

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