Overview

This section defines the API-level status model used by the SIBS Payment Gateway (SPG), combining:

• HTTP status codes
• statusCode values returned in the returnStatus object

Together, these elements define the technical outcome of an API request, including:

• request validation results
• processing success or failure
• temporary system conditions

This layer represents the canonical API response contract, independent of payment method or business outcome.

The tables presented in this section provide the complete mapping between HTTP responses and statusCode values for the different SPG API operations.

Dual-Layer Response Model

SPG API responses must be interpreted using two complementary layers:

• HTTP Status Code → transport-level and request-level result
• statusCode → application-level result within SPG

For example:

• HTTP 200 + statusCode = "000" → request accepted and processed
• HTTP 400 + statusCode = "E0101" → invalid request
• HTTP 503 + statusCode = "T9999" → temporary system condition

Both layers must be evaluated together to correctly classify the result of the operation.

HTTP Status Code Semantics

The HTTP status code reflects the technical status of the request at protocol level.

Typical values include:

• 200 OK → request successfully processed
• 206 Partial Content → partial processing (when applicable)
• 400 Bad Request → invalid request structure or parameters
• 401 / 403 → authentication or authorization failure
• 404 Not Found → resource not found
• 409 Conflict → request conflicts with current state
• 500 Internal Server Error → unexpected failure
• 503 Service Unavailable → temporary system unavailability

HTTP status codes provide the first-level classification, but must always be interpreted together with statusCode.

statusCode Semantics

At API level, statusCode represents the application-level outcome of the operation.

Typical categories include:

• Success
  • 000 → operation successfully processed
• Client / Validation Errors
  • e.g., E0101 → invalid request
  • e.g., E0119 → declined operation
• Processing Errors
  • e.g., E0301 → transaction not found or processing issue
• Temporary Errors
  • e.g., T9999 → temporary condition requiring retry

These codes are used consistently across API endpoints, although their exact values and meanings depend on the specific operation.

Interpretation Model

API-level status must be interpreted using the following sequence:

1. Evaluate HTTP status code
2. Evaluate statusCode
3. Interpret paymentStatus (if present)

This ensures correct separation between:

• transport-level issues
• request validation errors
• processing outcomes
• business state

The relationship between these elements is defined in C.5 Status Codes and Error Codes Mapping.

API-Level Status Code Tables

The following tables define the mapping between HTTP status codes and statusCode values for each SPG API domain.

Checkout Request

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
200	OK	000	Success	Success
400	Bad Request	E0001	Error	Invalid merchant or terminal code
400	Bad Request	E0002	Error	Invalid request, data is missing or is invalid
400	Bad Request	E0003	Error	Operation not allowed by the Merchant
400	Bad Request	E0004	Error	Operation not allowed by the Acquirer
400	Bad Request	E0005	Error	Operation not allowed, terms and condition not configured by Merchant
400	Bad Request	E0006	Error	No payment methods available
400	Bad Request	E9999	Error	Operation declined by authorisation system
503	Internal Server Error	T9999	Temporary error	SIBS temporary internal error

Payment Request

<!-- Insert full Payment Request table here -->

Status Inquiry

<!-- Insert full Status table here -->

Backoffice Operations

<!-- Insert full Backoffice table here -->

MB WAY

<!-- Insert full MB WAY table here -->

Multibanco

<!-- Insert full Multibanco table here -->

Card Payments

<!-- Insert full Card table here -->

Security and Authentication

<!-- Insert full Security table here -->

Handling Principles

At API level, responses must be handled as follows:

• HTTP 2xx + statusCode = "000"
  → request accepted; proceed to evaluate paymentStatus
• HTTP 4xx + statusCode = Exxxx
  → request invalid; must be corrected before retry
• HTTP 5xx / 503 + statusCode = Txxxx
  → temporary issue; retry according to strategy
• Temporary conditions (Txxxx)
  → must be handled with retry and backoff mechanisms

Detailed handling rules and responsibility mapping are defined in C.5.2 Error Code Categories and Responsibility Model.

Key Observations

• API-level codes are independent of payment method
• statusCode = "000" does not guarantee a successful payment
• HTTP status alone is insufficient for interpretation
• statusCode must always be evaluated together with paymentStatus
• Temporary errors must be explicitly handled to ensure system resilience

Relationship with Other Code Domains

API-level status codes provide a normalized response model but must be complemented with:

• C.5.2 Error Code Categories and Responsibility Model → responsibility and handling model
• C.5.3 Legacy / Detailed Error Codes (Operational Layer) → detailed operational error codes
• C.5.4 Payment Method-Specific Error Domains → payment method-specific error domains

These layers together provide the full interpretation of SPG responses.

Final Consideration

API-level status codes define the first layer of interpretation in SPG responses.

They establish how requests are accepted, validated, and processed, but do not define the final business outcome.

A correct implementation requires combining:

• HTTP status
• statusCode
• paymentStatus

and applying the interpretation model defined in C.5 Status Codes and Error Codes Mapping.

This ensures consistent, reliable, and production-ready handling of all SPG API interactions.