---

SIBS - Multibanco Reference Generation

Overview

QLY Environment:

---

Endpoint

---

Authentication

Headers

---

Request Body

Schema: MultibancoReferenceRequest

1. 🔄 Automatic Checkout Mode: Provide all required fields to create transaction and generate reference in one call
2. 📋 Existing Transaction Mode: Provide only transactionId for an already created transaction

---

Required Fields (All Modes)

---

Required for Automatic Checkout Mode

---

Optional Fields

---

Nested Objects

Payment Object

---

Customer Object

---

Shipping Object (⚠️ CRITICAL FORMAT)

---

Request Example

Automatic Checkout (Complete)

---

Response

Schema: MultibancoReferenceResponse

Success Response (200 OK)

---

Response Fields

---

Transaction Status Values

---

Customer Payment Flow

What Happens After API Call

---

Payment Methods Available

1. 🏧 ATM (Multibanco Terminal)

2. 💻 Online Banking

3. 📱 Mobile Banking App

---

Error Responses

400 Bad Request - Invalid JSON Structure

• ❌ shipping.address as nested object instead of string
• ❌ Malformed JSON syntax
• ❌ Type mismatch (string instead of number)

---

400 Bad Request - Missing Required Fields

---

400 Bad Request - Duplicate Transaction

---

400 Bad Request - Invalid Credential Header

---

400 Bad Request - Validation Error

---

404 Not Found - Transaction Not Found

---

500 Internal Server Error

---

Business Rules

1. Two Operational Modes:
   • ✅ Automatic Checkout: Provide all required fields (payment, customer, shipping, dates, notificationUrl)
   • ✅ Existing Transaction: Provide only transactionId (transaction must exist)
2. Transaction ID Uniqueness:
   • Each transactionId must be unique
   • ❌ Cannot reuse existing IDs
   • ✅ Use timestamp or UUID in ID generation
3. Entity Code:
   • Automatically obtained from SIBS terminal credentials
   • Typically "11604" for SIBS
   • ❌ Do NOT send entity in request
4. Date Validation:
   • initialDatetime should be current or future
   • finalDatetime must be after initialDatetime
   • Typical expiration: 1-30 days
   • Maximum expiration: Usually 365 days
5. Amount Ranges:
   • If not specified, maxAmount and minAmount default to payment.amount.total
   • SIBS validates paid amount is within range
   • Useful for partial payments or overpayments
6. Country Code Format:
   • Must use ISO-3166 alpha-2 (2 uppercase letters)
   • ✅ "PT", "ES", "FR"
   • ❌ "PRT", "Portugal", "pt"
7. Currency:
   • Multibanco primarily supports EUR (Euro)
   • Required for Portugal-based transactions
8. Webhook Notifications:
   • SIBS sends webhook after customer payment
   • Typically within 1-5 seconds of payment
   • Implement webhook handler for notificationUrl

---

Best Practices

1. Transaction ID Generation

• Use unique identifiers with timestamp: mb-ref-20251107-{unique-id}
• Include date for easier tracking
• Store mapping between your order ID and transaction ID

• Reuse transaction IDs
• Use sequential numbers (security risk)
• Use customer-provided IDs without validation

---

2. Shipping Structure

---

3. Date Management

• Use ISO 8601 format: 2025-11-07T12:00:00Z
• Set reasonable expiration periods (7-30 days)
• Consider business hours and holidays

• Use past dates for finalDatetime
• Set expiration too short (< 1 day)
• Exceed SIBS maximum (typically 365 days)

---

4. Error Handling

• Validate shipping structure before API call
• Check country code format (2 letters)
• Implement retry logic for network errors
• Store reference details for customer support

• Skip JSON structure validation
• Retry on 400 errors without fixing data
• Ignore validation errors
• Assume immediate success

---

5. Webhook Implementation

• Return 200 OK immediately
• Process webhook asynchronously
• Validate webhook signature (if provided)
• Log all webhook attempts
• Handle duplicate webhooks idempotently

• Perform long operations in webhook handler
• Return errors for processing issues
• Skip webhook validation
• Process same webhook multiple times

---

Troubleshooting

Issue: "Failed to read HTTP message"

1. Shipping structure wrong (Most common)
   json

   // ❌ Wrong "shipping": { "address": { "street": "Rua X", "city": "Lisboa" } } // ✅ Correct "shipping": { "address": "Rua X", "city": "Lisboa", "country": "PT", "postalCode": "1000-001", "phone": "351912345678" }

   json

   // ❌ Wrong "shipping": { "address": { "street": "Rua X", "city": "Lisboa" } } // ✅ Correct "shipping": { "address": "Rua X", "city": "Lisboa", "country": "PT", "postalCode": "1000-001", "phone": "351912345678" }
2. JSON syntax errors
   • Missing commas
   • Missing quotes
   • Unclosed brackets
3. Type mismatches
   • String where number expected
   • Number where string expected

---

Issue: "Country must be an ISO-3166 alpha-2 code"

---

Issue: "Transaction does not exist and no checkout data provided"

---

Issue: "The transaction ID already exists"

---

Issue: Reference not working at ATM

1. Reference not yet active
   • Check initialDatetime hasn't been reached
2. Reference expired
   • Check finalDatetime hasn't passed
3. Wrong entity entered
   • Verify customer entered correct entity (11604)
4. SIBS system delay
   • Wait 1-2 minutes after generation

• Verify API response was successful
• Confirm dates are valid
• Provide customer with correct entity and reference
• Wait a few minutes and retry

---

Issue: Webhook not received

1. Incorrect notificationUrl
   • URL not publicly accessible
   • HTTPS required (not HTTP)
   • Firewall blocking SIBS IPs
2. Server not responding
   • Server down or timeout
   • SSL certificate issues
   • Response not 200 OK
3. Webhook processing error
   • Server returns error status
   • Processing takes too long

• Verify URL is publicly accessible
• Test webhook endpoint manually
• Check server logs
• Implement status polling as fallback

---

Checking Payment Status

Method 1: Webhooks (Recommended)

---

Method 2: Status Polling

Poll the status endpoint:

• First check: After 1 minute
• Subsequent checks: Every 5-10 minutes
• Continue until: Payment received or reference expires

---

Testing

Test Scenarios

1. ✅ Successful Automatic Checkout
   • Provide all required fields
   • Expected: Reference generated with 9 digits
2. ✅ Successful Existing Transaction
   • Create transaction via checkout first
   • Generate reference with transaction ID only
   • Expected: Reference linked to existing transaction
3. ❌ Missing Required Fields (Automatic Mode)
   • Omit shipping.phone
   • Expected: 400 validation error
4. ❌ Invalid Shipping Structure
   • Send shipping.address as object
   • Expected: 400 "Failed to read HTTP message"
5. ❌ Invalid Country Code
   • Use "PRT" instead of "PT"
   • Expected: 400 validation error
6. ❌ Duplicate Transaction ID
   • Create reference with ID "test-001"
   • Attempt to create another with same ID
   • Expected: 409 conflict error
7. ❌ Nonexistent Transaction (Existing Mode)
   • Use transaction ID that doesn't exist
   • Expected: 404 transaction not found
8. ✅ Payment Flow End-to-End
   • Generate reference
   • Simulate ATM payment (sandbox)
   • Verify webhook received
   • Confirm status updated

---

Related Endpoints

• MBWAY - Alternative Portuguese mobile payment
• Checkout - Create SIBS transaction
• Status - Query transaction status
• Refund - Refund Multibanco payment

---

Common Questions

• Multibanco: Generates reference for payment at ATMs/online banking. Asynchronous, customer pays anytime within expiration.
• MB WAY: Direct mobile payment with phone number. Synchronous, customer must approve within 5 minutes.

---

Support

For technical support or questions:

• Email: matias.nunez@conexa.ai
• SIBS Documentation: Contact SIBS support

---

Changelog

---