Overview

Plugin Integration is a payment integration model based on pre-built plugins provided for supported e-commerce platforms and content management systems.

In this model, the integration logic between the merchant platform and the SIBS Payment Gateway (SPG) is encapsulated within a plugin, allowing merchants to enable payments with minimal development effort.

The merchant system interacts with SPG indirectly through the plugin abstraction layer, while the customer interacts with the payment interface exposed by the platform and/or SIBS components, depending on the plugin implementation.

The merchant is responsible for:

• Configuring the plugin according to business and operational requirements
• Managing platform-level payment settings and behavior
• Monitoring transaction states and ensuring correct order lifecycle updates
• Verifying transaction outcomes through platform or backend mechanisms when required
• Managing reconciliation and operational processes

Although the plugin abstracts most integration logic, the merchant remains responsible for ensuring that transaction outcomes are correctly reflected in business systems and that reconciliation processes are properly implemented.

This approach significantly reduces implementation effort and accelerates time-to-market. However, this abstraction also limits direct control over payment behavior and integration logic.

Depending on the plugin implementation, Plugin Integration typically relies internally on Form Integration or Server-to-Server interactions, without exposing this complexity to the merchant.

Key Characteristics

• Very low integration complexity
• Minimal or no custom development required
• Fast time-to-market
• Integration managed through platform plugins
• Limited control over payment flow and behavior
• Standardized integration patterns defined by the platform
• Dependency on plugin capabilities and updates

When to Use

Plugin Integration is recommended when:

• The merchant operates on a supported e-commerce platform
• Rapid deployment is a priority
• Internal development resources are limited
• Standard payment flows are sufficient
• Customization requirements are minimal

This model is commonly used for:

• WooCommerce-based websites
• Magento stores
• PrestaShop installations
• Shopify environments

SIBS currently provides plugins for the following platforms:

• WooCommerce
• Magento
• Shopify
• PrestaShop

Each plugin integrates natively with the platform’s checkout and order lifecycle.

Prerequisites

Before implementing Plugin Integration, ensure the following are available:

• Access to a supported e-commerce platform
• Availability of the official SIBS plugin for that platform

• Authentication credentials:
  • Authorization: Bearer <AuthToken> (for most API operations)

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

• TerminalId assigned during onboarding
• Configured environment (Test and Production)
• Basic understanding of the platform’s plugin installation and configuration process

Refer to A.3 – API Requests for authentication and request structure details.

High-Level Flow

A typical Plugin Integration follows these steps:

1. Install and Configure Plugin
   The merchant installs the SIBS plugin and configures it with the required credentials and payment settings.
   
2. Customer Initiates Payment
   The customer selects a payment method during checkout on the merchant platform.
   
3. Payment Processing
   The plugin handles the interaction with SPG and executes the payment flow on behalf of the merchant.
   Depending on the implementation, this may involve:
   • Hosted payment forms (Form Integration)
   • Direct API interactions (Server-to-Server)
     
4. Process Payment Result
   SPG processes the transaction and returns the result via the plugin.
   
5. Handle Result
   The platform updates the order status based on the transaction outcome.
   Final transaction status may be handled through:
   
   • Plugin-handled mechanisms, including webhooks or internal callbacks
   • Platform-level processing of transaction-status notifications
   • Status Inquiry or backend status retrieval mechanisms where applicable
   Final-state webhooks normally communicate the definitive transaction outcome. Multibanco Reference Generation is the relevant exception, as a webhook may communicate a Pending state.
   Final state handling must not rely solely on initial payment responses when the final outcome is not immediately available.
   
6. Post-Payment Operations (optional)
   Depending on plugin capabilities, operations such as:
   • Capture
   • Refund
   may be available through the platform interface or backend processes.

This sequence diagram illustrates a typical Plugin integration flow, including:

• Customer interaction with platform checkout
• Plugin handling of payment request
• Communication between plugin and SPG
• SPG payment processing
• Platform order update flow
• Transaction-status notification handling (webhooks or equivalent)
• Optional backend status retrieval or reconciliation step

Synchronous vs Asynchronous Payments

Plugin Integration supports both execution models:

Synchronous Payments

Immediate final status is returned after payment processing. A final-state webhook or equivalent plugin-handled notification may also be processed for synchronous outcomes.

Example:

• Credit Card (depending on flow)

Asynchronous Payments

Require external user action or delayed processing.
Final status is not immediately available.

Examples:

• MB WAY (user approval in mobile application)
• Multibanco Reference (payment via ATM or home banking)

For payments whose final outcome is not immediately available:

• The plugin and platform typically handle transaction-state updates internally
• Webhooks or equivalent mechanisms normally communicate final transaction states once processing is complete
• Status Inquiry or backend status retrieval may be used depending on plugin capabilities

Merchants must ensure that transaction states are consistent between platform order status and actual payment status.

Multibanco Reference Generation is the relevant exception: its webhook may communicate a Pending state.

Payment Methods Support

Plugin Integration supports SPG payment methods depending on:

• Plugin capabilities
• Platform limitations
• Merchant configuration

Typical supported payment methods include:

• Credit Card
• MB WAY
• Multibanco Reference

Available methods are configured through the plugin settings and depend on merchant enablement.

Security and Compliance

PCI DSS Responsibility

In Plugin Integration, sensitive payment data is typically handled by SIBS-hosted components or secure mechanisms embedded within the plugin.

This significantly reduces the merchant’s PCI DSS scope.

However:

• The exact scope depends on the plugin implementation and configuration
• Merchants remain responsible for ensuring their platform and environment are secure
• Compliance obligations are reduced but not eliminated

Although most security mechanisms are handled by the plugin, the merchant remains responsible for securing the hosting environment, platform configuration, and access control mechanisms.

Security Responsibilities (Plugin-Managed)

Most security-related mechanisms are handled internally by the plugin, including:

• Secure communication with SPG
• Authentication and request handling
• Validation of transaction responses

These responsibilities are abstracted from the merchant and implemented according to SIBS integration standards.

HMAC Validation (When Applicable)

HMAC-based message validation may be supported and handled internally by the plugin.

When available:

• It ensures message integrity and authenticity
• It is configured through the plugin or platform settings

No direct implementation is typically required by the merchant.

Transport Security

All communication between the platform, plugin, and SPG must use HTTPS.

Transport security is generally enforced by:

• The plugin implementation
• The underlying platform infrastructure

Merchants must ensure their hosting environment maintains proper TLS configuration and certificate validity.

Error Handling and Idempotency

Error handling and retry mechanisms are typically managed by:

• The plugin
• The e-commerce platform

However, merchants should:

• Monitor transaction outcomes through the platform
• Ensure proper order state reconciliation
• Validate that retry or duplicate processing does not impact business logic

Error handling must distinguish between transient errors (Txxxx) and functional or validation errors (Exxxx). Txxxx errors may be retryable according to the documented handling guidance. Exxxx errors require inspection of the specific error code and must not trigger an automatic generic retry policy solely based on the prefix.
Refer to C.6 – Error Code Interpretation Strategy for detailed classification and handling guidelines.

Advantages and Trade-offs of Plugin Integration

Advantages

• Very fast implementation
• Minimal development effort
• Simplified integration process
• Reduced PCI DSS scope
• Tight integration with platform ecosystem

Trade-offs

• Limited control over payment flows
• Dependency on plugin capabilities and updates
• Reduced flexibility for advanced use cases
• Potential limitations in customization and extensibility
• Reliance on platform-specific behavior

Limitations of Plugin Integration

Plugin-based integrations provide a simplified implementation model but introduce certain limitations that must be considered when selecting this approach:

• Reduced control over payment execution and flow customization
• Dependency on e-commerce platform capabilities and plugin updates
• Limited ability to implement advanced or custom payment scenarios
• Indirect access to SIBS Payment Gateway APIs, reducing flexibility for orchestration and fine-grained control

For use cases requiring full control over payment flows, orchestration, or advanced features, the Server-to-Server integration model should be considered.

Related Topics

• B. Integration Models (Overview) for integration model positioning
• B.1 – Server-to-Server Integration for full control and backend-driven flows
• B.2 – Form Integration for hybrid integration using hosted payment forms
• E.1 – Webhooks (Notifications) for transaction-status 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
• F.7 – Common Integration Pitfalls for typical implementation errors and anti-patterns across integration models

Conclusion

Plugin Integration provides the fastest and simplest way to integrate with the SIBS Payment Gateway, leveraging pre-built components tailored for popular e-commerce platforms.

It is best suited for merchants who prioritize rapid deployment and minimal development effort, while accepting reduced flexibility and control.

Although abstracted from the merchant, plugin-based integrations still rely on the same SPG infrastructure and may internally use Form Integration or Server-to-Server interactions to execute payment operations.

Understanding these underlying mechanisms is important to ensure correct expectations regarding capabilities, limitations, and extensibility.