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 query-driven transaction-state validation and should be used when no final webhook is available or when additional confirmation, recovery, reconciliation, or inconsistency resolution is required.

Endpoint Definition

GET <ROOT_URL>/payments/{transactionID}/status

Path Parameters

Authentication

The Status Inquiry APIs require authentication using a Bearer token.

Authorization: Bearer <AuthToken>

The Status Inquiry APIs 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 controlled real-time polling scenarios, subject to normal network and platform conditions

Example Request

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

Response Overview

The response contains the latest transaction state available through the query API, 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 extended Inquiry Details endpoint specification is provided in E.2.11 – Inquiry Details Endpoint Specification.

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

Transaction State Retrieval

• The endpoint returns the most up-to-date transaction state known to SIBS at query time
• Depending on the payment method and transaction lifecycle stage, the returned state may continue to evolve asynchronously until final operational resolution is reached
• It should be used to validate final outcomes when no final webhook is available or when additional confirmation is required
• The Status Inquiry APIs are the supported mechanism for retrieving the latest transaction state available through the query API

For more details, refer to:

• E.2.6 – Consistency Model: Query vs Webhook
• C.3 – Transaction States and Operational Meaning
• E.1.8 – Webhooks vs Status Inquiry (Consistency Model)

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 Mapping
• E.2.8 – Error Handling and Edge Cases

Key Integration Principles

• Validate the final transaction state using the Status Inquiry APIs when no final webhook is available or when additional confirmation is required
• Do not rely solely on webhook notifications unless they contain a final paymentStatus suitable for business processing
• Implement retries and fallback mechanisms
• Ensure secure handling of authentication credentials

Summary

The Status Inquiry APIs are the core mechanism for retrieval of the latest transaction state available through the query API within the SIBS Payment Gateway.

They ensure:

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

They should be used in conjunction with webhook notifications when explicit validation, fallback, reconciliation, or additional confirmation is required to guarantee correct, auditable, and reliable payment processing.