All data entering the Merchant system from external sources must be treated as untrusted until validated. This includes responses from SPG APIs, asynchronous notifications, and any client-originated input.

Trust boundaries must be clearly defined and enforced to ensure that no external data can influence system state without proper validation and control.

External Input Model

SPG integrations operate across multiple input channels:

• Synchronous responses (API responses returned immediately after a request)
• Asynchronous notifications (webhooks)
• Client-side interactions (e.g., redirects, return URLs, user input)

Each of these channels introduces a separate trust boundary and must be handled independently.

No input source should be considered authoritative on its own without validation.

Validation of External Inputs

All external data must be validated before being accepted or used.

• Input validation must ensure:
  • Structural correctness (expected fields and formats)
  • Logical consistency (matching known transaction context)
  • Integrity and authenticity (must be validated before processing)
• Validation must occur:
  • Before updating any internal state
  • Before triggering any business logic
  • Before persisting any data

External inputs must be processed using a fail-safe approach:

• Invalid or inconsistent data must be rejected
• Partial validation must not be accepted
• Validation failures must not trigger automatic retries without investigation

Asynchronous Notifications and Trust Boundaries

Asynchronous notifications (webhooks) represent a critical external boundary.

• Notifications:
  • Are delivered independently of the original request
  • May arrive delayed, duplicated, or out of order
• The Merchant system must:
  • Treat all notifications as untrusted until validated
  • Ensure that messages are decrypted and validated before use
  • Correlate each notification with a known transaction

A notification must never be used as the sole source of truth for transaction state.

The correct handling of asynchronous notifications, including decryption and validation, is defined in the Security and Validation section (see E.1.5 Security and Validation) and must be strictly followed.

State Reconciliation and Source of Truth

External inputs must be reconciled with the internal system state to ensure consistency.

• The Merchant system must:
  • Maintain its own view of transaction state
  • Validate external updates against known transaction data
  • Confirm the final state using authoritative sources when required, particularly when handling asynchronous updates or delayed transaction flows.

This is particularly important when handling:

• Asynchronous notifications
• Timeouts or delayed responses
• Multiple updates for the same transaction

Relying on a single event or input may lead to inconsistent or incorrect transaction outcomes.

Client-Side Inputs and Redirect Flows

Client-side inputs and redirect-based flows introduce additional risks.

• Data received from:
  • Return URLs
  • Browser interactions must not be trusted or used without validation

The Merchant system must ensure that:

• Client-side data is never used to directly determine transaction outcomes
• All client-provided information is validated against server-side data
• Sensitive operations are always confirmed through secure backend interactions

Client-side interactions should be treated as informational signals, not authoritative sources.

Security Enforcement

Trust boundaries must be enforced consistently across all integration points.

The Merchant system must ensure that:

• All external inputs are validated before being accepted or processed
• No input source is treated as authoritative without verification
• Asynchronous notifications are decrypted, validated, and correlated before use
• Client-side inputs are never trusted without server-side validation
• Internal transaction state is protected from inconsistent, duplicated, or unverified updates

Failure to enforce trust boundaries may result in incorrect transaction states, acceptance of forged inputs, or unintended execution of business logic.