Overview

Form Integration is a payment integration model in which the merchant delegates the collection of sensitive payment data to SIBS-hosted payment components (SPG Form / Widget).

In this model, the merchant system interacts with the SIBS Payment Gateway (SPG) to create and manage transactions, while the customer interacts with a secure payment interface provided and hosted by SIBS.

The merchant is responsible for:

• Initiating the payment (checkout creation)
• Monitoring transaction status
• Managing post-payment operations

SIBS is responsible for:

• Collecting payment method data (e.g., card details)
• Rendering and managing the payment user interface
• Ensuring secure handling of sensitive data

This approach reduces the merchant’s exposure to sensitive data and simplifies compliance requirements.

Form Integration combines server-to-server checkout preparation with a hosted payment form rendered via a SIBS JavaScript widget.

Key Characteristics

• Reduced exposure to sensitive payment data
• Payment UI hosted and managed by SIBS
• Simplified PCI DSS scope
• Lower integration complexity compared to Server-to-Server
• Hybrid model requiring frontend (hosted form) and backend (server-to-server) components
• Limited control over payment user interface and experience
• Standardized payment flows managed by SPG

When to Use

Form Integration is recommended when:

• The merchant wants to minimize PCI DSS scope
• A standard, secure, and SIBS-managed payment interface is acceptable
• Fast implementation and reduced development effort are priorities
• The merchant does not require full control over the checkout UI
• The integration must balance simplicity with backend orchestration capabilities

This model is commonly used for:

• E-commerce websites
• Standard checkout experiences
• Merchants prioritizing speed of integration over customization

Prerequisites

Before implementing Form 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)
• Redirect URL: Merchant endpoint for post-payment redirection

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

High-Level Flow

A typical Form Integration follows these steps:

1. Create Checkout (Server-to-Server)
   The merchant backend creates a transaction in SPG and receives a transaction identifier and the corresponding form context.
2. Render Payment Form (Frontend)
   The merchant frontend loads the SIBS payment widget using the transaction context returned in the previous step.
3. Customer Performs Payment
   The customer interacts with the SIBS-hosted payment form and provides the required payment data.
4. Process Payment
   SPG processes the transaction.
   The result may be:
   • Immediate (synchronous methods)
   • Pending (asynchronous methods)
5. Handle Result
   After payment:
   • The customer is redirected to the merchant’s redirect URL
   • The redirect alone must not be used as a source of truth for payment status.
6. Post-Payment Operations (optional)
   Additional operations may be executed:
   • Capture (for AUTH flows)
   • Refund
   • Merchant Initiated Transactions (MIT)

Synchronous vs Asynchronous Payments

Form Integration supports both execution models:

Synchronous Payments

Immediate final status is available after payment processing.

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 app)
• Multibanco Reference (payment via ATM or home banking)

For asynchronous methods:

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

Payment Methods Support

Form Integration supports all major SPG payment methods, including:

• Credit Card
• MB WAY
• Multibanco Reference
• Authorised Payments (Mandates)
• Token-based payments

Each payment method may have:

• Specific configuration requirements
• Different execution behaviors
• Synchronous or asynchronous processing

Only payment methods configured for the merchant and included in the checkout will be available in the form.

Security and Compliance

PCI DSS Responsibility

In Form Integration:

• Sensitive payment data is handled by SIBS
• The merchant does not process or store card data

This significantly reduces the merchant’s PCI DSS scope.

HMAC Validation (Recommended)

To ensure message integrity:

• Requests and responses may be validated using HMAC
• Requires configuration in the SIBS Backoffice

Benefits:

• Prevents tampering
• Ensures authenticity of communications

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 Form Integration, consider:

Retry mechanisms for transient failures
Idempotency for safe reprocessing of requests
Logging of:

• Backend requests and responses
• Transaction status updates
• Webhook notifications

Proper error handling is critical to ensure transactional consistency.

Advantages and Trade-offs

Advantages

• Reduced PCI DSS scope
• Faster implementation
• Secure, SIBS-managed payment UI
• Lower development and operational complexity

Trade-offs

• Limited control over payment user interface
• Dependency on SIBS-hosted components
• Backend integration still required
• Less flexibility for advanced or highly customized payment flows

Related Topics

• B. Integration Models (overview)
• B.1 Server-to-Server Integration
• B.3 Plugin Integration
• Payment Methods (CARD, MB WAY, REFERENCE, MANDATE)
• API Requests and Authentication

Conclusion

Form Integration provides a streamlined and secure way to integrate with the SIBS Payment Gateway by delegating payment data collection to SIBS-hosted components.

It is best suited for merchants who prioritize simplicity, reduced compliance scope, and faster time-to-market, while still maintaining backend control over transaction lifecycle management.

When properly implemented, it offers a balanced approach between ease of integration and operational capability within the SPG ecosystem.