Overview

Form Integration is a hybrid 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)
• Managing transaction states and transaction-status updates
• Retrieving transaction status using Status Inquiry when explicit verification, reconciliation, or recovery is required
• Processing webhook notifications, including final-state notifications
• Managing post-payment operations (capture, refund, MIT, reconciliation)

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 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 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 must not be used as a source of truth for transaction status
     • The redirect is a user navigation mechanism and does not represent transaction finality
   • Final transaction status must be handled through complementary status mechanisms:
     • Webhook notifications, which normally communicate final transaction states, including when the final outcome is available immediately
     • Status Inquiry, used to retrieve the current transaction state when explicit verification, reconciliation, or recovery is required
     • For Multibanco Reference Generation, a webhook may communicate a Pending state instead of a final outcome.
6. Post-Payment Operations (optional)
   Additional operations may be executed:
   • Capture (for AUTH flows)
   • Refund
   • Merchant Initiated Transactions (MIT)

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

• Merchant backend → SPG checkout creation
• Frontend loading of SIBS hosted payment widget
• Customer interaction with payment form
• SPG payment processing
• Redirect flow to merchant
• Final-state webhook notification flow
• Status Inquiry when explicit inquiry is required
• Post-payment operations (capture, refund, MIT)

Synchronous vs Asynchronous Payments

Form Integration supports both execution models:

Synchronous Payments

Immediate final status is available after payment processing. A final-state webhook may also be sent 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 app)
• Multibanco Reference (payment via ATM or home banking)

For payments whose final outcome is not immediately available:

• Webhook notifications normally communicate the final transaction state once processing is complete
• Status Inquiry should be used to retrieve the current transaction state when explicit verification, reconciliation, or recovery is required
• Implementations must process webhook notifications and Status Inquiry responses as complementary transaction-status mechanisms
• Multibanco Reference Generation is the relevant exception: its webhook may communicate a Pending state

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.

Each payment 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 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.

Although sensitive payment data is handled by SIBS, the merchant remains responsible for securing all backend interactions, transaction processing logic, and data flows within their system.

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.

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 Form Integration

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

API Request Simulator

An API request simulator is available in the documentation portal to support testing and validation of integration parameters and request behaviour.

This tool allows integrators to:

• Test request structures and parameter combinations
• Validate expected responses and behaviour
• Accelerate integration and troubleshooting without requiring full implementation

The simulator should be used during development and validation phases before moving to production.

Related Topics

• B. Integration Models (Overview) for integration model positioning
• B.1 Server-to-Server Integration for full control and backend-driven flows
• B.3 Plugin Integration for platform-based integrations
• 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

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.