Overview
This section provides a detailed, field-level view of API requests and responses, with annotations designed to support accurate, consistent, and production-ready integration with the SIBS Payment Gateway (SPG).
While previous chapters describe transaction flows, states, and behaviors, this section focuses on the exact structure and semantics of the exchanged payloads as they are used in real execution scenarios.
The annotated examples reflect how requests and responses behave in practice, including:
- Validation constraints
- Field dependencies
- Data consistency requirements
- Flow-specific requirements
- Method-specific operational nuances and flow-dependent behaviors
This section enables the transition from conceptual understanding to implementation-ready payload construction and interpretation, reducing ambiguity and minimizing integration errors.
Understanding Annotated Payloads
The examples provided in this chapter are intended to help integrators understand how SIBS Payment Gateway request and response payloads are structured and interpreted in real integration scenarios.
Unlike the reference-oriented chapters focused on field definitions and transaction states, this chapter provides practical annotated examples showing how payload components interact during actual payment flows.
The annotated examples throughout this chapter should be interpreted together with the following chapters:
- C. Meta Information, Codes and Transaction States for field semantics, transaction states, and return codes.
- D. Payment Methods for business payment flows and operation types.
- E. Notifications and Transaction Status for transaction monitoring, status inquiry, webhooks, and asynchronous state transitions.
- F.1 – End-to-End Integration Examples for complete operational payment lifecycle examples.
The examples in this chapter intentionally focus on payload interpretation, field relationships, operational context, and implementation guidance.
Payload Variability and Conditional Fields
The exact structure and content of SIBS Payment Gateway payloads may vary depending on several operational factors, including:
- payment method,
- operation type,
- authentication requirements,
- acquirer behavior,
- tokenization configuration,
- recurring payment context,
- Merchant Initiated Transaction (MIT) configuration,
- omnichannel transaction origin,
- asynchronous processing stages,
- and transaction lifecycle state.
For this reason, integrators should not assume that all fields are always present in all responses.
Implementations should validate and interpret payloads dynamically according to the operational context of each transaction.
Standard Status Inquiry vs Inquiry Details
Some operational flows may require deeper transaction inspection beyond the standard transaction status response.
Standard transaction status responses and Inquiry Details responses may expose different operational metadata depending on the transaction context and lifecycle stage.
For advanced transaction analysis, tokenization details, recurring payment metadata, authentication information, or extended operational attributes, consult F.2.8 – Inquiry Details – Annotated Request and Response together with the corresponding chapters under E. Notifications and Transaction Status.
Relationship Between Integration Flows and Annotated Payloads
This chapter should be read as the payload-level companion to the operational integration flows described in F.1 – End-to-End Integration Examples.
The relationship between the main documentation areas is as follows:
| Documentation Area | Role |
|---|---|
| F.1 – End-to-End Integration Examples | Explains the operational sequence of each payment flow. |
| F.2 – Requests and Responses (Annotated) | Explains the structure, meaning, and interpretation of the corresponding API payloads. |
| C. Meta Information, Codes and Transaction States | Defines transaction states, status codes, return codes, and common semantic rules. |
| E. Notifications and Transaction Status | Explains webhook processing, status inquiry, asynchronous updates, and transaction monitoring. |
The annotated examples in this chapter should therefore be interpreted together with the operational flows, transaction states, status inquiry mechanisms, and webhook processing models described throughout the remaining documentation.
Scope and Positioning
This section complements other chapters as follows:
- Chapter D. Payment Methods defines the functional sequence and behavior of payment operations
- Chapter C. Meta Information, Codes and Transaction States defines the meaning of statuses and codes
- Chapter E.1 – Webhooks (Notifications) defines asynchronous notification structures
In contrast, this section focuses on the payload layer, detailing how data must be structured, validated, and interpreted at each interaction with the API.
For general API request structure, headers, authentication mechanisms, and endpoint conventions, see A.3 – API Requests.
Annotated Example Approach
All examples in this section follow a consistent and structured approach:
- Full request and response payloads are provided
- Relevant fields are annotated with:
- Purpose and business meaning
- Validation constraints and dependencies
- Flow-specific considerations
- Only fields with operational relevance are annotated, ensuring clarity and usability
The examples are based on real execution patterns and reflect the operational behavior of synchronous and asynchronous transaction flows supported by the platform.
How to Use This Section
This section is designed to be used in conjunction with F.1 – End-to-End Integration Examples.
For each integration step:
- Use F.1 – End-to-End Integration Examples to understand the sequence and operational flow of each transaction
- Use this section to construct and interpret the corresponding requests and responses at each step.
The recommended approach is:
- Execute flows using the SIBS Postman Collections
- Use the annotated examples in this section to:
- Validate payload structure
- Confirm field-level correctness
- Troubleshoot integration issues
This combined approach ensures both functional correctness and payload-level accuracy, which are required for production-grade integrations.
Alignment with Postman Collections
All annotated examples in this section are aligned with the Postman collections provided with this documentation.
These collections include:
- Pre-configured requests for supported payment flows
- Environment variables for sandbox and production usage
- End-to-end execution scenarios and alternative paths
The collections should be used as the execution layer, while this section provides the interpretation and implementation guidance required to correctly use them.
Key Principles
- Requests must strictly follow field-level semantics and flow-specific requirements
- Responses must be interpreted based on:
returnStatuspaymentStatus- Method-specific data structures
- Payload correctness directly impacts:
- Operational consistency across transaction flows
- Transaction lifecycle management
- Error handling and recovery
- Reconciliation and audit processes
- Integration resiliency during synchronous and asynchronous processing flows
This section provides the technical foundation required to ensure consistent payload construction, accurate response interpretation, and reliable behavior across all transaction scenarios in production-grade integrations.
Related Chapters
The annotated payload examples provided throughout this chapter complement the following documentation areas: