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

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
206	Partial Content	000	Success	Partial
200	OK	000	Success	Sucess
400	Unauthorized	E0100	Error	Invalid merchant or terminal code
400	Bad Request	E0101	Error	Invalid request, data is missing or is invalid
400	Bad Request	E0102	Error	Checkout expired
409	Conflict	E0103	Error	Wrong parameterization for the payment method
400	Bad Request	E0104	Error	Acceptor not active
400	Bad Request	E0105	Error	Invalid terminal
400	Bad Request	E0106	Error	Terminal code differs from checkout terminal code
400	Bad Request	E0107	Error	Invalid terminal status
400	Bad Request	E0108	Error	Terminal is not authorized
400	Bad Request	E0109	Error	Invalid Amount
400	Bad Request	E0110	Error	Amount not supported
400	Bad Request	E0111	Error	Amount limit exceeded
400	Bad Request	E0112	Error	Wrong Currency
400	Bad Request	E0113	Error	Insufficient funds
400	Bad Request	E0114	Error	Transaction amount exceeds the authorized amount
400	Bad Request	E0115	Error	Transaction amount is lower than the comission
400	Bad Request	E0116	Error	Invalid transaction value
400	Bad Request	E0117	Error	Daily amount limit exceeded
400	Bad Request	E0118	Error	Possible risk of fraud
400	Bad Request	E0119	Error	Declined operation
400	Bad Request	E0120	Error	Card issuer temporarily unavailable
400	Bad Request	E0121	Error	Invalid payment request, terms and conditions were not accepted
400	Bad Request	E0122	Error	Transaction not allowed
400	Bad Request	E0123	Error	Transaction not authorized
403	Bad Request	E0124	Error	Invalid operation, transaction already processed
400	Bad Request	E0125	Error	Invalid original transaction
400	Bad Request	E0126	Error	No match between transactions
400	Bad Request	E0127	Error	Transaction already made
400	Bad Request	E0128	Error	Exceeded the number of operations allowed
400	Bad Request	E0129	Error	Declined, recurring payment is deactivated
400	Bad Request	E0130	Error	Authorisation expired
400	Bad Request	E0131	Error	Authorisation is cancelled
400	Bad Request	E0132	Error	Authorization was already used
400	Bad Request	E0133	Error	Refund amount exceeds purchase amount
400	Bad Request	E0134	Error	Refund amount exceeds available daily funds
400	Bad Request	E0135	Error	Refund amount is invalid
400	Bad Request	E0136	Error	Purchase already refunded
400	Bad Request	E0137	Error	Invalid refund amount
400	Bad Request	E0138	Error	Cancellation amount exceeds the authorized amount
400	Bad Request	E0139	Error	Invalid Cancellation
400	Bad Request	E0140	Error	No agreement found
400	Bad Request	E0141	Error	Payment type differs from checkout payment type
400	Bad Request	E0142	Error	Transaction Unknown
400	Bad Request	E0143	Error	Issuer’s Acceptor Configuration is not valid
400	Bad Request	E0144	Error	Declined by the issuer due to invalid account
400	Bad Request	E0145	Error	Operation not supported by the issuer
400	Bad Request	E0146	Error	Offline operation not allowed by the issuer
400	Bad Request	E0147	Error	Operation declined by the issuer
400	Bad Request	E0148	Error	Communication error with the issuer
400	Bad Request	E0149	Error	Issuer’s acquirer configuration is not valid
400	Bad Request	E0150	Error	Unknown issuer
400	Bad Request	E0151	Error	Invalid operation
400	Bad Request	E0152	Error	Invalid original amount
400	Bad Request	E0153	Error	Invalid transaction
400	Bad Request	E0154	Error	Transaction not allowed by the issuer for the given terminal
400	Bad Request	E0155	Error	Cash Service not available
400	Bad Request	E0156	Error	Additional customer authentication required
400	Bad Request	E0157	Error	Acquirer not registered on SP
400	Bad Request	E0158	Error	Unavailable agreement data
400	Bad Request	E0159	Error	Invalid fee
400	Bad Request	E9999	Error	Operation declined by authorisation system
503	Service unavailable	T9999	Temporary error	SIBS temporary internal error

Status Inquiry

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
200	OK	000	Success	Success
200	OK	000	Success	Pending
200	OK	000	Success	In Processing
200	OK	000	Success	Partial
200	OK	000	Success	Timeout
400	Bad Request	E0300	Error	Invalid request, data is missing or is invalid
400	Bad Request	E0301	Error	Transaction not found
400	Bad Request	E0302	Error	Invalid merchant or terminal code
400	Bad Request	E0303	Error	Invalid transaction ID or merchant transaction ID
400	Bad Request	E9999	Error	Operation declined by authorisation system
503	Service unavailable	T9999	Temporary error	SIBS temporary internal error

Backoffice Operations

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
200	OK	000	Success	Success
400	Bad Request	E0200	Error	Invalid request, data is missing or is invalid
400	Bad Request	E0201	Error	Operation not allowed by the Merchant
400	Bad Request	E0202	Error	Operation not supported
400	Bad Request	E9999	Error	Operation declined by authorisation system
503	Service unavailable	T9999	Temporary error	SIBS temporary internal error

MB WAY

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
200	OK	000	Success	Success
201	OK	000	Success	Success
400	Bad Request	E0500	Error	Operation was not accepted by the card holder
400	Bad Request	E0501	Error	Invalid request, data is missing or is invalid
400	Bad Request	E0502	Error	Not possible to associate MB WAY to the provided alias
400	Bad Request	E0503	Error	The provided alias is not correct
400	Bad Request	E0504	Error	The provided alias has an invalid format
400	Bad Request	E0505	Error	The provided alias is duplicated
400	Bad Request	E0506	Error	The provided alias does not exist
400	Not found	E0507	Error	Unknown MB WAY authorized payment
400	Bad Request	E0508	Error	Invalid MB WAY authorized payment amount
400	Bad Request	E0509	Error	MB WAY authorized payment’s monthly amount limit reached
400	Bad Request	E0510	Error	MB WAY authorized payment’s merchant limits reached
400	Bad Request	E0511	Error	Ineligible MB WAY authorized payment for the MB WAY alias
400	Bad Request	E0512	Error	MB WAY authorized payment invalid expiration date
400	Bad Request	E0513	Error	MB WAY authorized payment creation timeout
400	Bad Request	E0514	Error	Operation Rejected due to fraud suspicion
400	Bad Request	E0515	Error	MB WAY Authorized Payment not created. Cardholder did not accept the operation.
400	Bad Request	E0516	Error	MB WAY authorized payment is expired
400	Bad Request	E0517	Error	MB WAY authorized payment Cancellation timeout
400	Bad Request	E0518	Error	MB WAY authorized payment already cancelled
400	Bad Request	E0519	Error	Invalid operation type
400	Bad Request	E0520	Error	MB WAY Authorized payment disabled
400	Bad Request	E0521	Error	Operation declined. MB WAY alias is already associated
400	Bad Request	E0522	Error	Invalid terminal
400	Bad Request	E0523	Error	Invalid amount
400	Bad Request	E0524	Error	Declined operation
400	Bad Request	E0525	Error	Invalid original transaction
400	Bad Request	E0526	Error	Authorisation is cancelled
400	Bad Request	E0527	Error	Authorisation was already used
400	Bad Request	E0528	Error	Refund amount exceeds purchase amount
400	Bad Request	E0529	Error	Invalid refund amount
400	Bad Request	E0530	Error	Cancellation amount exceeds the authorized amount
400	Bad Request	E0531	Error	MB WAY purchase with an invalid card
400	Bad Request	E0532	Error	MB WAY purchase with an invalid card data
400	Bad Request	E0533	Error	Transaction already refunded
400	Bad Request	E0534	Error	MB WAY Authorized Payment creation error
400	Bad Request	E0535	Error	Invalid Service Provider
400	Bad Request	E0536	Error	MB WAY Authorized Payment is suspended
400	Bad Request	E0537	Error	MB WAY Authorized Payment – Invalid Payment method
400	Bad Request	E0538	Error	MB WAY Authorized Payment Data is missing
400	Bad Request	E0539	Error	MB WAY Authorized Payment Service is inactive
400	Bad Request	E0540	Error	MB WAY Authorized Payment Already Exists
400	Bad Request	E0541	Error	MB WAY Authorized Payment is Cancelled
400	Bad Request	E0542	Error	MB WAY Authorized Payment Data does not match operation data
400	Bad Request	E0543	Error	MB WAY Authorized Payment Unavailable
400	Bad Request	E0544	Error	MB WAY Authorized Payment invalid status
400	Bad Request	E9999	Error	Operation declined by authorisation system
408	Request Timeout	T9999	Temporary error	SIBS temporary internal error
503	Service Unavailable	T9999	Temporary error	SIBS temporary internal error

Multibanco

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
400	Bad Request	E0600	Error	Invalid payment entity
400	Bad Request	E0601	Error	Invalid payment reference minimum amount
400	Bad Request	E0602	Error	Invalid payment reference maximum amount
400	Bad Request	E0603	Error	Invalid currency
400	Bad Request	E0604	Error	Invalid NIB or IBAN
400	Bad Request	E0605	Error	Invalid payment reference initial date time
400	Bad Request	E0606	Error	Invalid payment reference limit date time
400	Bad Request	E0607	Error	Invalid Email
400	Bad Request	E0608	Error	Payment entity is not active
400	Bad Request	E0609	Error	Missing data required to perform the payment reference generation
400	Bad Request	E0610	Error	Payment reference generation not allowed for the payment entity
400	Bad Request	E0611	Error	Unknown payment reference
400	Bad Request	E0612	Error	Payment reference is cancelled
400	Bad Request	E0613	Error	Payment reference already paid
400	Bad Request	E0614	Error	Invalid operation
400	Bad Request	E0615	Error	Transaction with error or not found
400	Bad Request	E0616	Error	Invalid refund amount
400	Bad Request	E0617	Error	Refund amount exceeds payment amount
400	Bad Request	E0618	Error	Service Payment already refunded
400	Bad Request	E0619	Error	Service Payment refund not allowed
400	Bad Request	E9999	Error	Operation declined by authorisation system

Card Payments

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
400	Bad Request	E0700	Error	Invalid card data. Card number, CVV or expiration date is invalid
400	Bad Request	E0701	Error	Invalid card
400	Bad Request	E0702	Error	Card brand not supported
400	Bad Request	E0703	Error	Invalid payment modality
400	Bad Request	E0704	Error	DCC not allowed
400	Bad Request	E0705	Error	Card holder not authenticated
400	Bad Request	E0706	Error	Authentication method not allowed
400	Bad Request	E9999	Error	Operation declined by authorisation system
503	Bad Request	T9999	Temporary error	SIBS temporary error

Security and Authentication

HTTP Code	HTTP Message	Status Code	Status Message	Status Description
401	Unauthorized	E0900	Error	Invalid authentication or authorisation Data
401	Bad Request	E9999	Error	Operation declined by authorisation system

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.