Designing Idempotent Payments API Write Endpoints

As an experienced API Designer and Payments Architect, your objective is to define a set of idempotent write endpoints for a payments processing API. The design must prioritize transaction safety, data consistency, and developer experience.

### Context

You_are developing a core payments API that handles sensitive financial transactions such as creating charges, initiating refunds, or processing payouts. In a distributed system, network failures or client retries can lead to duplicate requests. Idempotency is crucial to ensure that these repeated requests do not result in unintended multiple executions or incorrect state changes. The API must clearly define how clients submit idempotent requests and how the server processes and responds to them.

The API should be designed for high availability and resilience, serving a global user base. Assume the underlying payment processing logic can be complex and potentially asynchronous.

### Task

Design the idempotent write endpoints for a payments API. Your design must include the following components:

1.  **API Specification (REST or GraphQL):** Define the specific write endpoints (e.g., `POST /charges`, `POST /refunds`, `POST /payouts`). For each endpoint, specify:
    *   HTTP method and path (for REST) or mutation name (for GraphQL).
    *   Request body structure, including the placement and format of the `Idempotency-Key` (for REST) or equivalent field (for GraphQL).
    *   Response structures for success, idempotent replay, and errors.
    *   Supported headers (e.g., `Idempotency-Key`, `Content-Type`).

2.  **Idempotency Key Strategy:**
    *   Define the format and generation requirements for the `Idempotency-Key`.
    *   Explain how the server uses this key to detect and handle duplicate requests.
    *   Specify the lifecycle of an idempotency key (e.g., how long it's considered valid for replay).

3.  **Replay Semantics and Responses:**
    *   Describe the server's behavior upon receiving a duplicate request with an active idempotency key.
    *   Specify the HTTP status codes (for REST) or error codes (for GraphQL) and response bodies for successful replays (e.g., returning the original successful response).
    *   Address scenarios where the original request failed but the key is replayed.

4.  **Resource Model:**
    *   Define the key resource objects involved (e.g., `Charge`, `Refund`, `Payout`) and their relevant fields, especially those impacted by idempotency (e.g., `status`, `idempotency_key_status`).
    *   Illustrate how the state of these resources changes through the idempotent process.

5.  **Error Schema:**
    *   Define a consistent error response structure for the API.
    *   Include specific error types related to idempotency (e.g., `idempotency_key_mismatch`, `idempotency_key_expired`, `invalid_idempotency_key`).

6.  **Versioning Policy:**
    *   Propose a clear versioning strategy for the API, considering how changes to idempotency mechanisms or endpoint signatures would be handled.

7.  **Examples:**
    *   Provide concrete request and response examples for:
        *   A successful initial request for `{{transaction_type}}` (e.g., a charge).
        *   A successful replay of the same `{{transaction_type}}` request.
        *   A failed initial request for `{{transaction_type}}` followed by a successful replay attempt (if applicable in your design).

### Constraints

*   **API Style:** Choose either RESTful HTTP API or GraphQL. Explicitly state your choice.
*   **Tone:** The design documentation should be principled, versioning-aware, and developer-empathetic.
*   **Clarity:** Ensure all definitions are clear, unambiguous, and practical for implementation by backend engineers.
*   **Security:** Briefly consider the security implications of idempotency keys (e.g., uniqueness, non-predictability).

### Output Format

Present your design in a structured, markdown-formatted document, including:

*   **API Specification:** Detailed endpoint definitions.
*   **Idempotency Key Strategy:** Explanation and guidelines.
*   **Replay Semantics:** Server behavior and response examples.
*   **Resource Model:** Schema definitions for affected resources.
*   **Error Schema:** Standardized error responses with idempotency-specific errors.
*   **Versioning Policy:** Proposed strategy.
*   **Examples:** Illustrated request/response flows.