Overview

This section defines the canonical structure of a request to the SIBS Payment Gateway (SPG), focusing on the POST <ROOT_URL>/payments operation used to create a checkout and initialize a transaction.

The objective is to provide a clear, implementation-ready understanding of how requests must be constructed, including field-level semantics, validation rules, and dependencies that apply across payment methods.

This structure is common to all flows and payment methods, with method-specific extensions introduced in subsequent steps or additional API operations.

Canonical Request Structure

This request creates a checkout and initializes a transaction in SPG.

Endpoint

POST <ROOT_URL>/payments

Headers

Authorization: Bearer <AuthToken>
X-IBM-Client-ID: <ClientId>
Content-Type: application/json
Accept: application/json

This operation uses Bearer authentication. Other operations may require Digest authentication using a transaction signature returned by a previous API response.

For general API transport conventions, authentication models, and HTTP request structure guidelines, see A.3 – API Requests.

Important:

• The AuthToken must correspond to a valid credential configured for the target SPG environment.
• The X-IBM-Client-ID is provided during onboarding
• Missing or invalid headers will result in request rejection before payload validation

The following example illustrates the generic request structure used to create a checkout.

{
    "merchant": {
        "terminalId": "11111",                  // Provided by SIBS onboarding
        "channel": "web",                       // Integration channel (e.g., web, mobile)
        "merchantTransactionId": "ORDER-001"    // Unique identifier defined by the merchant
    },
    "transaction": {
        "transactionTimestamp": "2026-04-16T10:15:30.000Z",  // ISO 8601 UTC timestamp
        "description": "Order payment",                      // Optional but recommended
        "paymentType": "PURS",                              // Defines the transaction type
        "paymentMethod": [
            "CARD",
            "MBWAY"
        ],
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        }
    }
}

This operation uses the POST method and requires a JSON request body. Other operations, such as status inquiries, use the GET method and do not require a request body.

Top-Level Structure

A valid request is composed of two main blocks:

• merchant → Identifies the merchant and the transaction in the merchant system
• transaction → Defines how the payment should be processed

Both blocks are mandatory.

Merchant Block

terminalId

• Assigned during onboarding
• Identifies the merchant configuration in SPG
• Must match the environment (sandbox vs production)

channel

• Indicates the origin of the transaction
• Typical values:
  • web
  • mobile
• Must be consistent with merchant configuration

merchantTransactionId

• Unique identifier generated by the merchant
• Used for:
  • Idempotency control
  • Internal reconciliation
• Must be unique per transaction attempt

Important:

• Reusing the same value may lead to:
  • Request rejection
  • Retrieval of an existing transaction instead of creating a new one
  • Ambiguous or inconsistent transaction handling

Transaction Block

transactionTimestamp

• Must be provided in ISO 8601 UTC format including milliseconds (for example: 2026-04-16T10:15:30.000Z)
• Represents the moment the transaction is created
• Should be generated server-side

Constraint:

• Significant clock drift may lead to validation issues

description

• Free-text field describing the transaction
• Optional but recommended for:
  • Backoffice visibility
  • Operational support

paymentType

Defines the processing behavior of the transaction.

This initial request creates the transaction context and checkout configuration. Depending on the selected flow and payment method, the actual financial operation may occur immediately, during customer interaction, or in subsequent API operations.

Common values:

• PURS → One-off payment (immediate execution)
• AUTH → Authorization (for two-step flows)
• MIT → Merchant-initiated transaction (recurring or subsequent payments)

MIT operations typically depend on a previously established transaction relationship or stored payment credential context.

Important:

• Must be consistent with:
  • The intended flow (see Chapter D. Payment Methods)
  • The subsequent operations (e.g., CAPTURE after AUTH)

paymentMethod

Defines the allowed payment methods for the transaction.

This field configures which payment methods are made available for the transaction within the checkout experience and subsequent processing flow.

Examples:

• CARD
• MBWAY
• REFERENCE

Rules:

• Can include one or multiple methods
• The list determines:
  • What is presented to the customer in Form Integration scenarios, including the payment method selection experience presented by the SPG checkout interface
  • What is allowed to be executed in Server-to-Server integrations

The actual execution of a payment method occurs in subsequent API calls or user interaction steps.

Important:

• Not all combinations may be enabled for a given merchant
• Must match SIBS configuration

amount

value

• Decimal number
• Must respect currency precision (e.g., 2 decimal places for EUR)

currency

• ISO currency code (e.g., EUR)
• Must match the merchant configuration

Field Dependencies and Constraints

The request is not purely declarative – several fields are interdependent:

• paymentType ↔ determines:
  • Allowed subsequent operations
  • Required additional fields in later steps
• paymentMethod ↔ impacts:
  • Required fields in method-specific requests
  • Behavior of the transaction lifecycle
• amount ↔ may be:
  • Mandatory or constrained depending on flow (e.g., zero-amount AUTH for tokenization)

Additional method-specific request structures are detailed in the corresponding F.2.x payment method chapters.

Additional Constraints:

• The combination of terminalId, merchantTransactionId, and transactionTimestamp must be consistent and unique per transaction attempt within the same integration context
• Inconsistent reuse across requests may result in ambiguous transaction interpretation, duplicate detection conflicts, or inconsistent operational outcomes.

Additional semantic and validation guidance is available in C.2 – Field Semantics and Validation Rules.

Idempotency and Uniqueness

The platform does not rely solely on HTTP idempotency.

Instead:

• merchantTransactionId acts as the primary idempotency key
• Each logical transaction must have a unique value

Best Practice:

• Use a structured format:
  • ORDER-{timestamp}-{sequence}
• Persist the value before sending the request

Common Pitfalls

1. Reusing merchantTransactionId

• Leads to:
  • Duplicate transaction ambiguity
  • Potential request rejection

2. Mismatch between paymentType and flow

• Example:
  • Using PURS when a two-step flow requires AUTH
• Impact:
  • Inability to perform subsequent operations (e.g., CAPTURE)

3. Invalid or inconsistent paymentMethod

• Using methods not enabled for the merchant
• Combining incompatible methods

4. Incorrect timestamp format

• Not using UTC
• Invalid ISO format

5. Currency mismatches

• Currency not aligned with terminal configuration

Execution Context

This request corresponds to:

• Step 1 – Create Checkout (see F.1 – End-to-End Integration Examples)
• The returned transactionID will be required for all subsequent operations and status inquiries

This identifier must be used as the primary SPG reference for all interactions with the platform. Merchant-defined identifiers must not be used as substitutes.

This request should be executed using the SIBS Payment Gateway Postman Collection, which provides:

• Pre-configured headers
• Environment variables
• Ready-to-run examples

The exact subsequent operations depend on the selected paymentType and paymentMethod combination.

Key Takeaways

• The POST <ROOT_URL>/payments request is the foundation of all SPG integrations
• Correct construction of this request determines:
  • Available payment methods
  • Allowed transaction flows
  • Downstream processing behavior
• Strict adherence to:
  • Field semantics
  • Validation rules
  • Idempotency practices

is required to ensure predictable and robust integration behavior in production environments.