Overview

Server-to-Server (S2S) Integration is a direct API-based integration model where the merchant system communicates with the SIBS Payment Gateway (SPG) without relying on hosted payment pages.

In this model, the merchant is responsible for:

• Orchestrating payment execution and transaction lifecycle management
• Collecting and transmitting payment data (when applicable)
• Managing transaction states, asynchronous status updates, and all post-payment operations (capture, refund, cancellation, MIT, reconciliation)

This approach provides maximum flexibility and control, making it suitable for advanced use cases and fully customized checkout experiences.

All operations are performed via SIBS Payment Gateway APIs, without relying on SIBS-hosted user interfaces.

This integration model follows an API-first approach, where all payment operations are executed through direct interaction with SIBS Payment Gateway APIs using well-defined request and response structures.

Key Characteristics

• Full control over payment execution and transaction lifecycle management, including post-payment operations
• Direct communication with SPG APIs
• Support for advanced payment flows:
  • Two-step payments (AUTH → CAPTURE)
  • Merchant Initiated Transactions (MIT)
  • Tokenization and recurring payments
• Custom checkout UI and user experience
• Increased responsibility for security and compliance

When to Use

Server-to-Server integration is recommended when:

• The merchant has the capability to manage PCI DSS requirements
• A fully customized checkout experience is required
• The merchant needs to implement advanced payment logic
• Integration is part of a broader backend orchestration platform (e.g., payment orchestration layer)
• Recurring payments, tokenization, or split operations are required

Prerequisites

Before implementing Server-to-Server integration, ensure the following are available and correctly configured:

• Authentication credentials:
  • Authorization: Bearer <AuthToken> (for most API operations)
  • Additional authentication mechanisms may apply depending on the operation context

• Application identification:
  • ClientId provided by SIBS (used as X-IBM-Client-ID in API requests)

• TerminalId assigned during onboarding

• Environment base URLs (Test and Production)

• Optional integrity mechanisms:
  • HMAC configuration for request and response validation

Refer to A.3 – API Requests for detailed authentication models, header requirements, and request structure.

High-Level Flow

A typical Server-to-Server integration follows these steps:

1. Create Checkout
   • Merchant calls POST <ROOT_URL>/payments
   • Defines payment configuration (amount, method, options)
2. Receive Transaction Context
   • SPG returns:
     • transactionID
     • transactionSignature
3. Execute Payment
   • Merchant collects required payment data (e.g., card details, MB WAY phone number)
   • Sends payment execution request to SPG
4. Process Payment
   • SPG processes the transaction based on the selected payment method and flow
   • Response may indicate:
     • Immediate completion (synchronous payment methods)
     • Pending state requiring further action or asynchronous confirmation
5. Handle Result
   • Merchant processes the initial response and determines the next step.
   • The final transaction outcome may be communicated through:
     • The initial API response
     • A final-state webhook notification, including when the final outcome is already available in the initial API response
   • The Status Inquiry API may be used to retrieve the current transaction state explicitly, including for validation, reconciliation, or recovery when webhook delivery or processing is uncertain.
   • For Multibanco Reference Generation, a webhook may communicate a Pending state rather than a final outcome.
6. Post-Payment Operations (optional)
   • Capture (for AUTH flows)
   • Refund
   • MIT (recurring or delayed charges)

This sequence diagram illustrates a typical Server-to-Server integration flow, including:

• Checkout creation and transaction context retrieval
• Payment execution and SPG processing
• Synchronous vs asynchronous execution paths
• Webhook notification flow for final transaction outcomes, including synchronous payments
• Status Inquiry when explicit status retrieval or reconciliation is required
• Post-payment operations such as capture, refund, and Merchant Initiated Transactions (MIT)

It highlights the distinction between synchronous and asynchronous payment methods, the role of webhooks in communicating final-state updates for both synchronous and asynchronous flows, the Pending webhook exception applicable to Multibanco Reference Generation, and the use of Status Inquiry for explicit verification and recovery when required.

Synchronous vs Asynchronous Payments

Server-to-Server integration supports both payment execution models:

Synchronous Payments

• Immediate final status returned in the API response
• A final-state webhook notification is also sent after the final outcome is determined, even when that outcome is already available in the initial API response
• Example: Credit Card (depending on flow)

Asynchronous Payments

• Require external user action
• Final status delivered later

Examples:

• MB WAY (user approval in mobile app)
• Multibanco Reference (payment at ATM / app)

For asynchronous methods:

• A final-state webhook is the primary mechanism for communicating the final transaction outcome
• The Status Inquiry API may be used to retrieve the current transaction state explicitly, including for validation, reconciliation, or recovery when webhook delivery or processing is uncertain
• Implementations must process webhook notifications idempotently and maintain consistency between the notified transaction outcome and the corresponding merchant-side state
• Multibanco Reference Generation is the relevant exception: its generation webhook may communicate a Pending state rather than a final outcome

Payment Methods Support

Server-to-Server integration supports all SPG payment methods, including:

• Credit Card
• MB WAY
• Multibanco Reference
• Authorised Payments (Mandates)

Each payment method introduces specific request structures, execution flows, and synchronous or asynchronous behavior, which must be handled accordingly.

These differences directly impact integration design, transaction handling logic, and user experience.

Refer to the dedicated payment method sections for detailed implementation.

Each method must be integrated with full awareness of its execution model, including synchronous or asynchronous behavior, required user interaction, and transaction finality mechanisms.

Security and Compliance

PCI DSS Responsibility

In Server-to-Server integration:

• The merchant may handle sensitive payment data (e.g., card details)
• PCI DSS compliance is required for applicable flows

The choice of Server-to-Server integration directly impacts the merchant’s compliance scope and must be evaluated in the context of the overall system architecture.

HMAC Validation (Recommended)

To ensure message integrity:

• Requests and responses can be signed using HMAC
• Requires a shared secret configured in SIBS Backoffice

Benefits:

• Prevents tampering
• Ensures authenticity of messages

Transport Security

• All communication must use HTTPS
• TLS configuration must be properly implemented, and certificate chains must be validated

Data Handling

When processing sensitive payment data (such as card details), the merchant must ensure:

• No storage of sensitive authentication data (e.g., CVV)
• Secure handling and transmission of payment data
• Proper segregation of sensitive data flows

Refer to F.4 – Security Best Practices for detailed guidelines.

Error Handling and Idempotency

When implementing Server-to-Server integration, consider:

• Retry mechanisms for transient failures
• Idempotency for safe reprocessing of requests
• Logging of:
  • Request payloads
  • Response payloads
  • Headers and status codes

Proper error handling is critical to ensure transactional consistency.

Error handling must distinguish between conditions that may be retried using controlled backoff strategies and errors that require analysis, correction, or user action.

Retry behavior must be determined from the specific error code and its documented handling guidance. An EXXXX response must not trigger a generic automatic retry policy based solely on its prefix; some EXXXX errors may be retryable after merchant analysis.

Refer to C.6 – Error Code Interpretation Strategy for classification and handling guidelines.

Advantages and Trade-offs of Server-to-Server

Advantages

• Maximum flexibility and control
• Advanced payment capabilities
• Full ownership of user experience
• Suitable for complex business logic

Trade-offs

• Higher implementation complexity
• Increased security and compliance responsibility
• Requires robust backend architecture
• Longer time-to-market

Related Topics

• B. Integration Models (Overview) for integration model positioning
• E.1 – Webhooks (Notifications) for webhook notification handling
• E.2 – Status Inquiry / Get Status for transaction status retrieval and reconciliation
• F.4 – Security Best Practices for data protection and compliance requirements
• F.6 – Production Readiness Guidelines for operational readiness and reliability
• C.6 – Error Code Interpretation Strategy for error handling and retry classification
• F.7 – Common Integration Pitfalls for typical implementation errors and anti-patterns in Server-to-Server integrations

Conclusion

Server-to-Server integration is the most powerful and flexible integration model available in SIBS SPG.

It is designed for merchants who require full control over their payment flows and are capable of handling the associated complexity and security requirements.

When properly implemented, it enables advanced payment orchestration and provides full control over transaction lifecycle management within complex business systems.