Overview

This section defines the canonical structure of a request to the SIBS Payment Gateway (SPG), focusing on the POST /api/v2/payments operation used to initiate 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>/api/v2/payments

Headers

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

Important:

• The AuthToken must be valid at the time of the request
• 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"
        }
    }
}

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 in ISO 8601 UTC format
• 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.

Common values:

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

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.

Examples:

• CARD
• MBWAY
• REFERENCE

Rules:

• Can include one or multiple methods
• The list determines:
  • What is presented to the customer in Form Integration scenarios
  • 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 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 undefined or non-deterministic behavior

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 Examples)
• The returned transactionID will be required for all subsequent operations

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

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

Key Takeaways

• The POST /api/v2/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.