The SIBS Payment Gateway exposes REST-based APIs that allow merchant systems to create payments, perform payment operations, and query transaction status.

API interactions use standard HTTP methods and JSON-formatted request and response bodies. Depending on the operation, API requests are used to initiate transactions, execute payment method-specific operations, perform backoffice operations, or retrieve transaction information.

API Interaction Model

Most API calls are synchronous from an HTTP perspective: each request receives an immediate HTTP response.

However, payment execution may involve asynchronous processing depending on the payment method, transaction type, and execution flow. The API response reflects the immediate result of the request, but it may not represent the final transaction outcome.

API responses include structured status and error information. For details on interpreting response codes and error handling strategies, see C. Meta Information, Codes and Transaction States.

Final transaction states must be confirmed using the appropriate status mechanisms.

In most cases, this is done using the Status Inquiry endpoint (GET /payments/{transactionID}/status), which returns the authoritative state of the transaction.

For details on asynchronous processing and finality, see A.2 Core Concepts and Architecture and E. Notifications and Transaction Status.

Base URLs and Environment Aliases

The SIBS Payment Gateway uses environment-specific URLs for both API operations and Form Integration widget loading.

To simplify examples and improve readability throughout this documentation, the following aliases are used:

• <ROOT_URL> – Base URL used for SIBS Payment Gateway API operations
• <WIDGET_URL> – Base URL used to load the SIBS Payment Gateway hosted payment widget

The values depend on the target environment:

The API version is included in the <ROOT_URL> value.

All API examples throughout this documentation use the <ROOT_URL> alias instead of environment-specific URLs.

Form Integration examples use the <WIDGET_URL> alias when referencing the hosted payment widget.

The API environment and widget environment must always match.

Examples throughout this documentation may use placeholders such as:

• POST <ROOT_URL>/payments
• GET <ROOT_URL>/payments/{transactionID}/status
• <script src="<WIDGET_URL>/assets/js/widget.js?id={transactionID}"></script>

These placeholders should be replaced with the environment-specific values shown above.

A checkout created using the Sandbox API environment must use the Sandbox widget URL. Likewise, a checkout created using the Production API environment must use the Production widget URL.

Credentials and environment-specific identifiers are not interchangeable between environments. Sandbox credentials must not be reused in Production, and Production credentials must not be used in Sandbox.

Making API Requests

To make an API request, combine the following elements:

• HTTP method
• API base URL
• Resource URI
• Required HTTP headers
• Request body, when applicable

Resource URIs may include path parameters, such as {transactionID}, which identify the specific resource being accessed. Some endpoints may also support query parameters for filtering or controlling response output.

Resource URIs follow a hierarchical structure that reflects the underlying resource model. For example, /payments/{transactionID}/status represents a specific operation on a payment resource identified by its transaction identifier.

The most commonly used HTTP methods are:

• POST – used to create transactions or execute operations
• GET – used to retrieve transaction information or status

Most POST requests require a JSON request body. GET requests typically do not require a request body and may use path parameters or query parameters depending on the endpoint.

When performing operations that may be retried, implementations should ensure idempotent behavior to avoid unintended duplicate transactions. See F.6 Production Readiness Guidelines for best practices.

HTTP Request Headers

API requests must include the headers required by the specific operation being executed.

The exact combination of headers depends on the endpoint and operation being executed. Some operations require authentication headers, while others may require additional context-specific headers.

The most common headers are:

Accept

Defines the response format expected by the client.

Use:

Accept: application/json

Content-Type

Defines the format of the request body.

For requests that include a JSON body, use:

Content-Type: application/json

X-IBM-Client-ID

Identifies the merchant application making the request.

The Client ID is assigned during onboarding and is specific to each environment:

• In the sandbox environment, the Client ID is assigned after sandbox access is approved
• In the production environment, the Client ID is assigned after technical validation and commercial setup are completed

Client IDs are environment-specific and cannot be reused across environments.

Use:

X-IBM-Client-ID: <ClientId>

Authorization

Authenticates the request and authorizes access to the API operation.

The authorization mechanism depends on the operation being executed:

• Some operations use Bearer authentication with the merchant authorization token
• Some payment method-specific operations use Digest authentication with the transaction signature returned by a previous API response

Always use the authentication mechanism required by the specific endpoint.

Digest authentication is typically used in operations that follow a previous transaction initialization step, where a transaction signature is returned and must be reused for subsequent requests.

Authentication requirements are endpoint-specific. For example, status inquiry operations commonly use Bearer authentication, while certain payment method execution operations use Digest authentication based on the transaction signature returned by the checkout response.

Examples:

Authorization: Bearer <AuthToken>

Authorization: Digest <transactionSignature>

Bearer Tokens are obtained using application credentials created in the SIBS Backoffice under SIBS Payment Gateway → Credentials. For detailed instructions on creating, viewing, and managing application credentials, refer to G.1.7.3 – Credentials.

Some operations may also require or support additional integrity validation through a signature header. See F.4 Security Best Practices for security guidance and F.2 Requests and Responses (Annotated) for examples of request and response structures.

Example Request

The following example retrieves the current status of an existing payment using its transaction identifier.

curl -v -X GET "<ROOT_URL>/payments/{transactionID}/status" \
  --header "X-IBM-Client-ID: <ClientId>" \
  --header "Authorization: Bearer <AuthToken>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json"

The {transactionID} value is the transaction identifier assigned by the platform. It must be used as the primary and authoritative reference for status inquiry and subsequent transaction operations. Merchant-defined identifiers must not be used as substitutes for this value when interacting with the API.

The authorization mechanism used in this example is Bearer authentication. Other operations may require Digest authentication using a transaction signature obtained from a previous API response.

Examples of authorization formats:

Authorization: Bearer <AuthToken>
Authorization: Digest <transactionSignature>

TLS Requirements

Connections to the SIBS Payment Gateway must use TLS version 1.2 or higher.

Requests using lower TLS versions are rejected. This requirement ensures secure communication between merchant systems and the SIBS Payment Gateway.

Related Topics

For additional guidance, see:

• A.2 Core Concepts and Architecture – for the transaction lifecycle and asynchronous processing model
• B. Integration Models – for the available integration approaches
• E. Notifications and Transaction Status – for webhook and status inquiry behavior
• F. Technical Examples and Best Practices – for implementation examples and production readiness guidance
• G.1.7.3 – Credentials – for creating and managing application credentials used for API authentication