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 the full payment lifecycle
• Collecting and transmitting payment data (when applicable)
• Managing transaction states and post-payment operations

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

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

Key Characteristics

• Full control over the payment lifecycle
• 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:

• AuthToken: Used for API authentication (Authorization: Bearer <AuthToken>)
• X-IBM-Client-Id: Application identifier provided by SIBS
• TerminalId: Assigned by SIBS during onboarding
• Environment Base URL: (Test / Production endpoints)
• HMAC Configuration (optional but recommended): For request and response integrity validation

Refer to the API Requests section for detailed authentication and header specifications.

High-Level Flow

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

1. Create Checkout
   • Merchant calls POST /api/v2/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 request to SPG
4. Process Payment
   • SPG processes the transaction
   • Response may be:
     • Immediate (synchronous methods)
     • Pending (asynchronous methods)
5. Handle Result
   • Merchant processes response
   • Receives final status via:
     • API response (synchronous)
     • Webhook notification (asynchronous)
6. Post-Payment Operations (optional)
   • Capture (for AUTH flows)
   • Refund
   • MIT (recurring or delayed charges)

Synchronous vs Asynchronous Payments

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

Synchronous Payments

• Immediate final status returned in 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:

• Webhooks are the primary notification mechanism
• Status polling should be used as fallback

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 may have:

• Specific request payloads
• Different execution flows
• Synchronous or asynchronous behavior

Refer to the dedicated sections for each payment method.

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

HMAC Validation (Recommended)

To ensure message integrity:

• Requests and responses can be signed using HMAC
• Requires 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

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.

Advantages and Trade-offs

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)
• B.2 Form Integration
• B.3 Plugin Integration
• Payment Methods (CARD, MB WAY, REFERENCE, MANDATE)
• API Requests and Authentication

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 seamless integration into complex business systems.