Overview

The Status Inquiry endpoint enables merchants to retrieve the current state of a transaction directly from the SIBS Payment Gateway using a synchronous request.

This endpoint provides deterministic and authoritative access to transaction status and must be used to validate the outcome of any payment operation.

Endpoint Definition

GET /api/v2/payments/{transactionID}/status

Path Parameters

Authentication

The Status Inquiry endpoint requires authentication using a Bearer token.

Authorization: Bearer <AuthToken>

This endpoint must be invoked server-to-server and must never be called directly from client-side applications.

Token Characteristics

• The token is generated and managed via the SIBS Backoffice
• The token is static and does not expire under normal operation
• The token must be securely stored and treated as a credential
• Invalid or missing tokens will result in authentication errors

The Bearer token must be configured prior to performing any API operations.

The token must be treated as a sensitive credential and must never be exposed in client-side code, browser traffic, or unsecured logs.

Headers

Request Characteristics

• Method: GET
• Request Body: Not applicable
• Idempotency: The operation is idempotent and can be safely repeated without side effects
• Operational Use: Suitable for real-time polling scenarios, subject to normal network and platform conditions

Example Request

GET https://<ROOT_URL>/api/v2/payments/{transactionID}/status
Authorization: Bearer <AuthToken>
X-IBM-Client-Id: <clientid>
Content-Type: application/json
Accept: application/json

Response Overview

The response contains the current representation of the transaction state, including:

• paymentStatus – current state of the transaction
• returnStatus – operation result codes and messages
• Transaction metadata (timestamps, identifiers)
• paymentMethod – Payment method information
• Optional extension blocks depending on the payment method and transaction context

The complete response structure is defined in E.2.3 – Response Payload Structure

Operational Considerations

Use of transactionID

• The transactionID is the only supported identifier for status retrieval
• Merchants must persist this value at transaction creation time
• The merchantTransactionID must not be used for status queries

Authoritative State Retrieval

• The endpoint returns the most up-to-date transaction state known to SIBS at query time
• It must be used to validate final outcomes, particularly after receiving webhook notifications

For more details, refer to:

• E.2.6 – Consistency Model: Query vs Webhook
• C.3 – Transaction States and Operational Meaning

Polling Usage

• This endpoint can be used in polling strategies for real-time status tracking
• Aggressive polling patterns must be avoided
• Retry and backoff mechanisms should be implemented

Detailed recommendations are provided in E.2.5 – Polling Strategy and Best Practices

Error Handling

• Always evaluate both:
  • HTTP status code
  • returnStatus.statusCode
• A 200 OK response does not necessarily indicate a successful payment
• The paymentStatus field must be interpreted according to transaction semantics

Refer to:

• C.5 – Status Codes and Error Codes Catalogue
• E.2.8 – Error Handling and Edge Cases

Key Integration Principles

• Always validate the final transaction state using this endpoint
• Do not rely solely on webhook notifications
• Implement retries and fallback mechanisms
• Ensure secure handling of authentication credentials

Summary

The Status Inquiry endpoint is the core mechanism for deterministic transaction state retrieval within the SIBS Payment Gateway.

It ensures:

• Accurate validation of transaction outcomes
• Resilience against asynchronous notification issues
• Consistent transaction lifecycle management

It must be systematically used in conjunction with webhook notifications to guarantee correct, auditable, and reliable payment processing.