Overview

This section provides annotated payload examples for error scenarios and edge cases, focusing on how responses must be interpreted and handled in production environments.

While previous sections focus on successful execution paths, real-world integrations must correctly handle:

• Validation errors
• Business declines
• Asynchronous timeouts
• Inconsistent or partial states

The objective of this section is to establish a clear interpretation model for non-success scenarios, ensuring robust and predictable integration behavior.

Error code definitions and classification follow the model described in C.5 – Status Codes and Error Codes Mapping and C.6 – Error Payloads and Handling Guidelines.

Scope and Context

This section focuses strictly on response payload interpretation and error handling patterns.

For:

• End-to-end flow sequencing → see F.1 – End-to-End Integration Examples
• Payment flow definitions → see D. Payment Methods
• Status and error semantics → see C. Meta Information, Codes and Transaction States
• Webhook structures → see E.1 – Webhooks (Notifications)

1. Validation Errors (Request Rejected)

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "E0101",
        "statusMsg": "Invalid request"
    }
}

Interpretation

• The request was rejected at validation level
• No transaction was created
• transactionID is not present

Typical Causes

• Missing required fields
• Invalid field formats (e.g., timestamp, currency)
• Unsupported combinations (paymentType vs paymentMethod)

Handling Guidance

• Do not automatically retry validation failures without correcting the underlying request problem.
• Correct the payload before resubmitting
• Log full request/response for diagnostics

2. Technical Success with Business Decline

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Declined",
    "transactionID": "txDECLINE123456"
}

Interpretation

• API call succeeded (returnStatus = 000)
• The payment operation itself was processed correctly at technical level even though the financial authorization or business outcome was unsuccessful.
• Payment was not approved (paymentStatus = Declined)

Typical Causes

• Insufficient funds
• Card issuer rejection
• Risk or fraud rules

Handling Guidance

• Treat as final state
• Do not retry automatically
• Provide clear feedback to the customer
• Allow alternative payment method

3. Pending and Other Non-Final States

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Pending",
    "transactionID": "txPENDING123456"
}

Interpretation

• Request accepted
• Transaction is not yet finalized
• Non-final states are expected operational behavior for asynchronous payment methods and authentication flows.

Typical Scenarios

• 3DS authentication required (CARD)
• Customer confirmation pending (MB WAY)
• Deferred payment (REFERENCE)

Handling Guidance

• Do not assume success or failure
• Wait for webhook notification or use Status Inquiry confirmation when required

When discrepancies exist between intermediate responses, webhook notifications, or delayed operational updates, the latest transaction state should be checked using Status Inquiry.

4. Timeout / Expired Transactions

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Timeout",
    "transactionID": "txPENDING123456"
}

Interpretation

• Transaction was not completed within allowed time
• Considered final non-success state

Typical Scenarios

• MB WAY user did not confirm
• Multibanco reference expired
• 3DS challenge abandoned

Handling Guidance

• Treat as final
• Allow user to retry with a new transaction
• Do not reuse the same transactionID
• A new merchantTransactionId should also be generated when creating a replacement transaction.

5. Inconsistent or Partial States

Scenario

A webhook is received with a final state, but local system is out of sync.

Example Webhook

{
    "returnStatus": {
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "transactionID": "txSYNC123456",
    "notificationID": "notif123"
}

Handling Guidance

• External system indicates success
• Local system may not reflect this state yet
• Confirm when required with:

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

• Use Status Inquiry to check the latest transaction state when required
• Ensure idempotent processing of webhooks

6. Duplicate or Idempotency Conflicts

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "E0119",
        "statusMsg": "Operation not allowed"
    },
    "transactionID": "txNOTALLOWED123456"
}

Interpretation

• Request reused an existing merchantTransactionId
• SPG may:
  • Return the existing transaction context
  • Reject the duplicate request

Handling Guidance

• Ensure uniqueness of merchantTransactionId
• Implement idempotency logic on merchant side
• Avoid retrying with the same identifier

For detailed guidance on idempotency and duplicate protection strategies, see F.6.2 – Idempotency and Duplicate Protection.

7. Temporary Technical Error (Retry Scenario)

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "T9999",
        "statusMsg": "Temporary error"
    },
    "transactionID": "txTEMP123456"
}

Interpretation

• The request failed due to a temporary or transient condition
• No final transaction outcome can be determined

Typical Causes

• Temporary network issues
• Upstream service unavailability
• Transient platform conditions

Handling Guidance

• Retry the request using a retry with backoff strategy
• Retry attempts should be bounded, monitored, and protected by idempotency controls.
• Ensure idempotency when retrying
• Do not treat as final failure

8. Error Handling Model (Recommended)

Decision Model

1. Check returnStatus.statusCode
   • statusCode != "000" → validation or technical error
   • If statusCode starts with “T” → retry with backoff strategy
   • If statusCode starts with “E” → correct request or require user action
2. If "000" → check paymentStatus
   • Success → final success
   • Declined / Timeout → final failure
   • Pending → non-final
3. For non-final states
   • Wait for webhook
   • Confirm with Status Inquiry when required

The HTTP response code reflects the transport-level result of the request and must not be used alone to determine transaction outcome.

 

An HTTP success response (e.g., 200 OK) does not guarantee that the API operation or payment was successful.

9. Misinterpreting Inquiry Details Transaction Status

Scenario

The Inquiry Details response may include a transaction.transactionStatus block containing status-related information.

Interpretation

• This field provides contextual transaction information but is not equivalent to the paymentStatus returned by the Status Inquiry endpoint.
• Incorrect interpretation of this field may lead to inconsistent or incorrect business decisions.

Typical Mistake

• Using transaction.transactionStatus to determine the transaction outcome instead of relying on final webhook paymentStatus or Status Inquiry when required.

Handling Guidance

• Do not use transaction.transactionStatus to determine transaction success or failure
• Treat this field as informational only
• Validate final transaction state using Status Inquiry when no final webhook is available or when confirmation, recovery, or reconciliation is required

See also F.7.9 – Inadequate Error Interpretation and Handling Strategy.

Key Takeaways

• returnStatus, HTTP response codes, and paymentStatus must always be interpreted as separate layers.
• A technically successful API call does not guarantee payment success
• Many payment methods are inherently asynchronous
• Final state may be determined via:
  • Webhooks
  • Status Inquiry

Robust handling of error scenarios and edge cases is essential to ensure:

• Accurate transaction state management
• Reliable reconciliation
• Resilient production integrations

This section provides the reference foundation for implementing defensive and reliable error handling in SPG integrations.