{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Alzaf Pay Public API — Planned Contract",
    "version": "0.1.0",
    "description": "Stage 0 design, not a claim of implemented endpoints or production availability. All amounts are integer minor units, BDT only. Only secret server-side keys authorize these endpoints. Test/live and merchant/project isolation apply to every resource and list. See docs/api/README.md and merchant guides. Browser checkout is a separate capability-scoped surface."
  },
  "servers": [
    {
      "url": "http://localhost:8000/v1",
      "description": "Planned local backend"
    },
    {
      "url": "https://sandbox-api.alzafpay.com/v1",
      "description": "Planned sandbox; test keys only"
    },
    {
      "url": "https://api.alzafpay.com/v1",
      "description": "Planned production; live keys only"
    }
  ],
  "security": [
    {
      "SecretKey": []
    }
  ],
  "tags": [
    {
      "name": "payments",
      "description": "payments operations. Scope requirements are in x-required-scopes."
    },
    {
      "name": "refunds",
      "description": "refunds operations. Scope requirements are in x-required-scopes."
    },
    {
      "name": "transactions",
      "description": "transactions operations. Scope requirements are in x-required-scopes."
    },
    {
      "name": "balance",
      "description": "balance operations. Scope requirements are in x-required-scopes."
    },
    {
      "name": "settlements",
      "description": "settlements operations. Scope requirements are in x-required-scopes."
    },
    {
      "name": "webhooks",
      "description": "webhooks operations. Scope requirements are in x-required-scopes."
    }
  ],
  "paths": {
    "/payment-intents": {
      "post": {
        "operationId": "createPaymentIntent",
        "summary": "Create a payment intent",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:write. Authentication is a project-bound secret bearer key. merchant_reference is unique per project/environment; duplicate business reference returns 409. Merchant and project are derived from the key and cannot be supplied. No charge occurs at creation. checkout_url is issued only here, not on reads or webhooks. Required. Scope is merchant + project + environment + method + normalized path + key (not API credential id, so rotation preserves deduplication). Same key and canonical JSON payload return the original committed status/body for at least 24h. Different payload returns 409 IDEMPOTENCY_CONFLICT. Concurrent owner returns 409 OPERATION_IN_PROGRESS with Retry-After. Client retains keys permanently per business operation; never issue a new key after an uncertain provider result. See README.md for canonicalization and recovery.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:write"
        ],
        "x-idempotency-required": true,
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "201": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                },
                "description": "True when replaying an already committed response."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PaymentCreated"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "pay_01K4XZ1Q0A0000000000000001",
                    "object": "payment_intent",
                    "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                    "project_id": "prj_01K4XZ1Q0A0000000000000001",
                    "environment": "test",
                    "merchant_reference": "ORDER-1001",
                    "amount": 10050,
                    "currency": "BDT",
                    "status": "CREATED",
                    "refunded_amount": 0,
                    "description": "Order 1001",
                    "metadata": {
                      "order_id": "1001"
                    },
                    "customer": null,
                    "success_url": "https://merchant.example/payment/return",
                    "cancel_url": "https://merchant.example/payment/cancel",
                    "checkout_url": "https://sandbox-pay.alzafpay.com/p/pay_01K4XZ1Q0A0000000000000001#token=EXAMPLE_ONLY",
                    "expires_at": "2026-09-12T12:30:00Z",
                    "created_at": "2026-09-12T12:00:00Z",
                    "updated_at": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePayment"
              },
              "example": {
                "merchant_reference": "ORDER-1001",
                "amount": 10050,
                "currency": "BDT",
                "description": "Order 1001",
                "success_url": "https://merchant.example/payment/return",
                "cancel_url": "https://merchant.example/payment/cancel",
                "metadata": {
                  "order_id": "1001"
                }
              }
            }
          }
        }
      }
    },
    "/payment-intents/{id}": {
      "get": {
        "operationId": "getPaymentIntent",
        "summary": "Retrieve a payment intent",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:read. Authentication is a project-bound secret bearer key.  No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "pay_01K4XZ1Q0A0000000000000001",
                    "object": "payment_intent",
                    "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                    "project_id": "prj_01K4XZ1Q0A0000000000000001",
                    "environment": "test",
                    "merchant_reference": "ORDER-1001",
                    "amount": 10050,
                    "currency": "BDT",
                    "status": "CREATED",
                    "refunded_amount": 0,
                    "description": "Order 1001",
                    "metadata": {
                      "order_id": "1001"
                    },
                    "customer": null,
                    "success_url": "https://merchant.example/payment/return",
                    "cancel_url": "https://merchant.example/payment/cancel",
                    "expires_at": "2026-09-12T12:30:00Z",
                    "created_at": "2026-09-12T12:00:00Z",
                    "updated_at": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/payment-intents/{id}/confirm": {
      "post": {
        "operationId": "confirmPaymentIntent",
        "summary": "Begin a payment attempt",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:write. Authentication is a project-bound secret bearer key. Only CREATED/PENDING with no unresolved attempt. Attempt/provider verification occurs server-side. Unknown timeout stays PROCESSING; never automatically fall back to another provider. Required. Scope is merchant + project + environment + method + normalized path + key (not API credential id, so rotation preserves deduplication). Same key and canonical JSON payload return the original committed status/body for at least 24h. Different payload returns 409 IDEMPOTENCY_CONFLICT. Concurrent owner returns 409 OPERATION_IN_PROGRESS with Retry-After. Client retains keys permanently per business operation; never issue a new key after an uncertain provider result. See README.md for canonicalization and recovery.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:write"
        ],
        "x-idempotency-required": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted for processing; fetch current status. Acceptance is not payment/refund success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                },
                "description": "True when replaying an already committed response."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "pay_01K4XZ1Q0A0000000000000001",
                    "object": "payment_intent",
                    "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                    "project_id": "prj_01K4XZ1Q0A0000000000000001",
                    "environment": "test",
                    "merchant_reference": "ORDER-1001",
                    "amount": 10050,
                    "currency": "BDT",
                    "status": "PROCESSING",
                    "refunded_amount": 0,
                    "description": "Order 1001",
                    "metadata": {
                      "order_id": "1001"
                    },
                    "customer": null,
                    "success_url": "https://merchant.example/payment/return",
                    "cancel_url": "https://merchant.example/payment/cancel",
                    "expires_at": "2026-09-12T12:30:00Z",
                    "created_at": "2026-09-12T12:00:00Z",
                    "updated_at": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmPayment"
              },
              "example": {
                "payment_method": "mock",
                "mock_scenario": "SUCCESS"
              }
            }
          }
        }
      }
    },
    "/payment-intents/{id}/cancel": {
      "post": {
        "operationId": "cancelPaymentIntent",
        "summary": "Cancel an unstarted payment",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:write. Authentication is a project-bound secret bearer key. Only CREATED/PENDING with no unresolved provider side effect. Processing or completed payment returns 409. Cancellation never reverses captured money. Required. Scope is merchant + project + environment + method + normalized path + key (not API credential id, so rotation preserves deduplication). Same key and canonical JSON payload return the original committed status/body for at least 24h. Different payload returns 409 IDEMPOTENCY_CONFLICT. Concurrent owner returns 409 OPERATION_IN_PROGRESS with Retry-After. Client retains keys permanently per business operation; never issue a new key after an uncertain provider result. See README.md for canonicalization and recovery.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:write"
        ],
        "x-idempotency-required": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                },
                "description": "True when replaying an already committed response."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "pay_01K4XZ1Q0A0000000000000001",
                    "object": "payment_intent",
                    "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                    "project_id": "prj_01K4XZ1Q0A0000000000000001",
                    "environment": "test",
                    "merchant_reference": "ORDER-1001",
                    "amount": 10050,
                    "currency": "BDT",
                    "status": "CANCELLED",
                    "refunded_amount": 0,
                    "description": "Order 1001",
                    "metadata": {
                      "order_id": "1001"
                    },
                    "customer": null,
                    "success_url": "https://merchant.example/payment/return",
                    "cancel_url": "https://merchant.example/payment/cancel",
                    "expires_at": "2026-09-12T12:30:00Z",
                    "created_at": "2026-09-12T12:00:00Z",
                    "updated_at": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelPayment"
              },
              "example": {
                "reason": "Order abandoned"
              }
            }
          }
        }
      }
    },
    "/payments/{id}": {
      "get": {
        "operationId": "getPayment",
        "summary": "Retrieve canonical payment state",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:read. Authentication is a project-bound secret bearer key. Uses the same pay_ identifier as payment intent; no second payment id is minted. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "pay_01K4XZ1Q0A0000000000000001",
                    "object": "payment_intent",
                    "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                    "project_id": "prj_01K4XZ1Q0A0000000000000001",
                    "environment": "test",
                    "merchant_reference": "ORDER-1001",
                    "amount": 10050,
                    "currency": "BDT",
                    "status": "SUCCEEDED",
                    "refunded_amount": 0,
                    "description": "Order 1001",
                    "metadata": {
                      "order_id": "1001"
                    },
                    "customer": null,
                    "success_url": "https://merchant.example/payment/return",
                    "cancel_url": "https://merchant.example/payment/cancel",
                    "expires_at": "2026-09-12T12:30:00Z",
                    "created_at": "2026-09-12T12:00:00Z",
                    "updated_at": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/refunds": {
      "post": {
        "operationId": "createRefund",
        "summary": "Request a full or partial refund",
        "tags": [
          "refunds"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: refunds:write. Authentication is a project-bound secret bearer key. Amount is always explicit. Captured minus succeeded and pending/processing reserved refunds bounds amount. Provider capability and funds are checked atomically. Timeout preserves reservation until verification. Required. Scope is merchant + project + environment + method + normalized path + key (not API credential id, so rotation preserves deduplication). Same key and canonical JSON payload return the original committed status/body for at least 24h. Different payload returns 409 IDEMPOTENCY_CONFLICT. Concurrent owner returns 409 OPERATION_IN_PROGRESS with Retry-After. Client retains keys permanently per business operation; never issue a new key after an uncertain provider result. See README.md for canonicalization and recovery.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "refunds:write"
        ],
        "x-idempotency-required": true,
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted for processing; fetch current status. Acceptance is not payment/refund success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                },
                "description": "True when replaying an already committed response."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "ref_01K4XZ1Q0A0000000000000001",
                    "object": "refund",
                    "payment_id": "pay_01K4XZ1Q0A0000000000000001",
                    "amount": 1000,
                    "currency": "BDT",
                    "status": "CREATED",
                    "reason": "Customer request",
                    "created_at": "2026-09-12T12:05:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRefund"
              },
              "example": {
                "payment_id": "pay_01K4XZ1Q0A0000000000000001",
                "amount": 1000,
                "reason": "Customer request"
              }
            }
          }
        }
      }
    },
    "/refunds/{id}": {
      "get": {
        "operationId": "getRefund",
        "summary": "Retrieve a refund",
        "tags": [
          "refunds"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: refunds:read. Authentication is a project-bound secret bearer key.  No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "refunds:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "ref_01K4XZ1Q0A0000000000000001",
                    "object": "refund",
                    "payment_id": "pay_01K4XZ1Q0A0000000000000001",
                    "amount": 1000,
                    "currency": "BDT",
                    "status": "CREATED",
                    "reason": "Customer request",
                    "created_at": "2026-09-12T12:05:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/transactions": {
      "get": {
        "operationId": "listTransactions",
        "summary": "List project transactions",
        "tags": [
          "transactions"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: transactions:read. Authentication is a project-bound secret bearer key. Stable descending (created_at,id) keyset ordering. Amount is unsigned; type determines economic meaning. Transactions are read models, not editable ledger entries. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "transactions:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Transaction"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": [
                    {
                      "id": "txn_01K4XZ1Q0A0000000000000001",
                      "payment_id": "pay_01K4XZ1Q0A0000000000000001",
                      "refund_id": null,
                      "settlement_id": null,
                      "type": "PAYMENT",
                      "amount": 10050,
                      "currency": "BDT",
                      "created_at": "2026-09-12T12:00:00Z"
                    }
                  ],
                  "page": {
                    "next_cursor": null,
                    "has_more": false
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/balance": {
      "get": {
        "operationId": "getBalance",
        "summary": "Retrieve the project balance",
        "tags": [
          "balance"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: balance:read. Authentication is a project-bound secret bearer key. Project/environment-scoped projection; do not use as authority to authorize a payout. Aggregate merchant view requires dashboard authorization. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "balance:read"
        ],
        "x-idempotency-required": false,
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Balance"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "currency": "BDT",
                    "pending": 10050,
                    "available": 0,
                    "reserved": 0,
                    "as_of": "2026-09-12T12:00:00Z"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/payment-methods": {
      "get": {
        "operationId": "listPaymentMethods",
        "summary": "List available payment methods",
        "tags": [
          "payments"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: payments:read. Authentication is a project-bound secret bearer key.  No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "payments:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentMethod"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": [
                    {
                      "code": "mock",
                      "display_name": "Mock payment",
                      "available": true,
                      "supports_refund": true,
                      "supports_partial_refund": true
                    }
                  ],
                  "page": {
                    "next_cursor": null,
                    "has_more": false
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/settlements": {
      "get": {
        "operationId": "listSettlements",
        "summary": "List project settlement allocations",
        "tags": [
          "settlements"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: settlements:read. Authentication is a project-bound secret bearer key. Exposes only this project allocation; merchant payout bank details and other project items are excluded. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "settlements:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Settlement"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": [
                    {
                      "id": "set_01K4XZ1Q0A0000000000000001",
                      "amount": 9050,
                      "currency": "BDT",
                      "status": "DRAFT",
                      "item_count": 1,
                      "created_at": "2026-09-12T12:00:00Z",
                      "completed_at": null
                    }
                  ],
                  "page": {
                    "next_cursor": null,
                    "has_more": false
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/settlements/{id}": {
      "get": {
        "operationId": "getSettlement",
        "summary": "Retrieve a project settlement allocation",
        "tags": [
          "settlements"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: settlements:read. Authentication is a project-bound secret bearer key.  No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "settlements:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^set_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Settlement"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "set_01K4XZ1Q0A0000000000000001",
                    "amount": 9050,
                    "currency": "BDT",
                    "status": "DRAFT",
                    "item_count": 1,
                    "created_at": "2026-09-12T12:00:00Z",
                    "completed_at": null
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/webhook-endpoints": {
      "post": {
        "operationId": "createWebhookEndpoint",
        "summary": "Register a merchant webhook",
        "tags": [
          "webhooks"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: webhooks:write. Authentication is a project-bound secret bearer key. No automatic retries: signing_secret is only returned once. On uncertain result list endpoints and reconcile URL, then rotate through dashboard. Duplicate normalized URL within project/environment returns 409 ENDPOINT_ALREADY_EXISTS. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "webhooks:write"
        ],
        "x-idempotency-required": false,
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CreatedWebhookEndpoint"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "whe_01K4XZ1Q0A0000000000000001",
                    "url": "https://merchant.example/webhooks/alzaf-pay",
                    "events": [
                      "payment.succeeded",
                      "refund.succeeded"
                    ],
                    "enabled": true,
                    "created_at": "2026-09-12T12:00:00Z",
                    "signing_secret": "whsec_EXAMPLE_ONLY"
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookEndpoint"
              },
              "example": {
                "url": "https://merchant.example/webhooks/alzaf-pay",
                "events": [
                  "payment.succeeded",
                  "refund.succeeded"
                ]
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints",
        "tags": [
          "webhooks"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: webhooks:read. Authentication is a project-bound secret bearer key.  No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "webhooks:read"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": [
                    {
                      "id": "whe_01K4XZ1Q0A0000000000000001",
                      "url": "https://merchant.example/webhooks/alzaf-pay",
                      "events": [
                        "payment.succeeded",
                        "refund.succeeded"
                      ],
                      "enabled": true,
                      "created_at": "2026-09-12T12:00:00Z"
                    }
                  ],
                  "page": {
                    "next_cursor": null,
                    "has_more": false
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    },
    "/webhook-endpoints/{id}": {
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "summary": "Disable a webhook endpoint",
        "tags": [
          "webhooks"
        ],
        "description": "PLANNED Stage 0 contract; consult implementation status before use. Required scope: webhooks:write. Authentication is a project-bound secret bearer key. Stops new sends and retries. Repeated deletion of an owned tombstone returns 200. Existing in-flight HTTP deliveries may complete. No Idempotency-Key requirement; reads have no side effects.",
        "x-implementation-status": "planned",
        "x-required-scopes": [
          "webhooks:write"
        ],
        "x-idempotency-required": false,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            },
            "description": "Opaque prefixed ULID; ownership always checked."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeletedWebhookEndpoint"
                    },
                    "request_id": {
                      "$ref": "#/components/schemas/RequestId"
                    }
                  },
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "data": {
                    "id": "whe_01K4XZ1Q0A0000000000000001",
                    "deleted": true
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid request headers.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Malformed JSON or invalid request headers.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked, expired or wrong-environment secret key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "AUTHENTICATION_FAILED",
                    "message": "Missing, invalid, revoked, expired or wrong-environment secret key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks the required scope or project is not enabled.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PERMISSION_DENIED",
                    "message": "API key lacks the required scope or project is not enabled.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist in the authenticated merchant/project/environment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RESOURCE_NOT_FOUND",
                    "message": "Resource does not exist in the authenticated merchant/project/environment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "IDEMPOTENCY_CONFLICT",
                    "message": "Idempotency payload mismatch, operation in progress or invalid resource transition. Inspect error.code.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed or operation is not permitted for this payment.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INVALID_REQUEST",
                    "message": "Request validation failed or operation is not permitted for this payment.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Wait Retry-After seconds.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds before retry."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Rate limit exceeded. Wait Retry-After seconds.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Unexpected server failure. Fetch current state before retrying a mutation with its original key.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          },
          "503": {
            "description": "Service or selected provider is temporarily unavailable.",
            "headers": {
              "X-Request-Id": {
                "description": "Server-issued correlation id. Same as body request_id; original id retained on exact idempotent replay.",
                "schema": {
                  "$ref": "#/components/schemas/RequestId"
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "PROVIDER_UNAVAILABLE",
                    "message": "Service or selected provider is temporarily unavailable.",
                    "details": []
                  },
                  "request_id": "req_01K4XZ1Q0A0000000000000001"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SecretKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "alz_{test|live}_sk_{secret}",
        "description": "Server-side only. Publishable pk keys cannot access this API. Scopes bound to merchant/project/environment; use x-required-scopes per operation."
      },
      "WebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "Alzaf-Signature",
        "description": "t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp + dot + exact raw body>; see merchant/webhooks.md."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Required. Scope is merchant + project + environment + method + normalized path + key (not API credential id, so rotation preserves deduplication). Same key and canonical JSON payload return the original committed status/body for at least 24h. Different payload returns 409 IDEMPOTENCY_CONFLICT. Concurrent owner returns 409 OPERATION_IN_PROGRESS with Retry-After. Client retains keys permanently per business operation; never issue a new key after an uncertain provider result. See README.md for canonicalization and recovery.",
        "schema": {
          "type": "string",
          "minLength": 16,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "example": "order-1001-create-v1"
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Opaque signed keyset cursor bound to original query and tenant/environment. Do not decode or edit. Invalid/expired cursor is 422.",
        "schema": {
          "type": "string",
          "maxLength": 2048
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      }
    },
    "schemas": {
      "RequestId": {
        "type": "string",
        "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
      },
      "PaymentId": {
        "type": "string",
        "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
      },
      "Environment": {
        "type": "string",
        "enum": [
          "test",
          "live"
        ]
      },
      "Currency": {
        "type": "string",
        "const": "BDT"
      },
      "Money": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
      },
      "Metadata": {
        "type": "object",
        "maxProperties": 20,
        "propertyNames": {
          "maxLength": 40
        },
        "additionalProperties": {
          "type": "string",
          "maxLength": 500
        },
        "description": "Non-sensitive merchant tags. Never credentials or card data."
      },
      "PaymentStatus": {
        "type": "string",
        "enum": [
          "CREATED",
          "PENDING",
          "PROCESSING",
          "SUCCEEDED",
          "FAILED",
          "CANCELLED",
          "EXPIRED",
          "PARTIALLY_REFUNDED",
          "REFUNDED"
        ]
      },
      "RefundStatus": {
        "type": "string",
        "enum": [
          "CREATED",
          "PROCESSING",
          "UNKNOWN",
          "SUCCEEDED",
          "FAILED"
        ]
      },
      "SettlementStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "RESERVED",
          "PROCESSING",
          "UNKNOWN",
          "COMPLETED",
          "FAILED",
          "CANCELLED"
        ]
      },
      "Customer": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 150
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "phone": {
            "type": "string",
            "maxLength": 30
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "CreatePayment": {
        "type": "object",
        "properties": {
          "merchant_reference": {
            "type": "string",
            "maxLength": 128,
            "minLength": 1
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "description": {
            "type": "string",
            "maxLength": 500
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "success_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Registered HTTPS return URL; loopback HTTP allowed only locally."
          },
          "cancel_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Default 30 minutes, maximum 24 hours from first creation; must be in future. Explicit timezone required. Fractional seconds are truncated to whole seconds before range validation. Checkout expires at this instant; idempotent creation replay does not extend it."
          }
        },
        "required": [
          "merchant_reference",
          "amount",
          "currency",
          "success_url",
          "cancel_url"
        ],
        "additionalProperties": false
      },
      "ConfirmPayment": {
        "type": "object",
        "properties": {
          "payment_method": {
            "type": "string",
            "enum": [
              "mock",
              "bkash",
              "nagad",
              "card",
              "bank"
            ]
          },
          "mock_scenario": {
            "type": "string",
            "enum": [
              "SUCCESS",
              "FAILED",
              "PENDING",
              "TIMEOUT",
              "PROVIDER_ERROR"
            ],
            "description": "Test environment and MockProvider only. Rejected in live mode."
          }
        },
        "required": [
          "payment_method"
        ],
        "additionalProperties": false
      },
      "CancelPayment": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PaymentId"
          },
          "object": {
            "const": "payment_intent",
            "type": "string"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^mer_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "project_id": {
            "type": "string",
            "pattern": "^prj_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "environment": {
            "$ref": "#/components/schemas/Environment"
          },
          "merchant_reference": {
            "type": "string",
            "maxLength": 128
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "refunded_amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "customer": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Customer"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "success_url": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "cancel_url": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "merchant_id",
          "project_id",
          "environment",
          "merchant_reference",
          "amount",
          "currency",
          "status",
          "refunded_amount",
          "customer",
          "description",
          "metadata",
          "success_url",
          "cancel_url",
          "expires_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false,
        "description": "Payment snapshot for retrieval, state transitions and webhook data. Does not disclose a checkout capability."
      },
      "CreateRefund": {
        "type": "object",
        "properties": {
          "payment_id": {
            "$ref": "#/components/schemas/PaymentId"
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [
          "payment_id",
          "amount"
        ],
        "additionalProperties": false
      },
      "Refund": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "object": {
            "type": "string",
            "const": "refund"
          },
          "payment_id": {
            "$ref": "#/components/schemas/PaymentId"
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/RefundStatus"
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "payment_id",
          "amount",
          "currency",
          "status",
          "reason",
          "created_at"
        ],
        "additionalProperties": false
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^txn_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "payment_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PaymentId"
              },
              {
                "type": "null"
              }
            ]
          },
          "refund_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "settlement_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^set_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "PAYMENT",
              "REFUND",
              "FEE",
              "SETTLEMENT",
              "REVERSAL",
              "ADJUSTMENT"
            ]
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "payment_id",
          "refund_id",
          "settlement_id",
          "type",
          "amount",
          "currency",
          "created_at"
        ],
        "additionalProperties": false
      },
      "Balance": {
        "type": "object",
        "properties": {
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "pending": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "available": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "reserved": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "currency",
          "pending",
          "available",
          "reserved",
          "as_of"
        ],
        "additionalProperties": false
      },
      "PaymentMethod": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "mock",
              "bkash",
              "nagad",
              "card",
              "bank"
            ]
          },
          "display_name": {
            "type": "string",
            "maxLength": 100
          },
          "available": {
            "type": "boolean"
          },
          "supports_refund": {
            "type": "boolean"
          },
          "supports_partial_refund": {
            "type": "boolean"
          }
        },
        "required": [
          "code",
          "display_name",
          "available",
          "supports_refund",
          "supports_partial_refund"
        ],
        "additionalProperties": false
      },
      "Settlement": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^set_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/SettlementStatus"
          },
          "item_count": {
            "type": "integer",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "amount",
          "currency",
          "status",
          "item_count",
          "created_at",
          "completed_at"
        ],
        "additionalProperties": false
      },
      "CreateWebhookEndpoint": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "HTTPS public endpoint, no userinfo/fragments. Private IPs blocked after DNS resolution; rechecked on each connection. Local mock receiver is separately allowlisted by development configuration only."
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "payment.created",
                "payment.processing",
                "payment.succeeded",
                "payment.failed",
                "payment.expired",
                "payment.cancelled",
                "refund.succeeded",
                "refund.failed",
                "settlement.created",
                "settlement.completed"
              ]
            }
          }
        },
        "required": [
          "url",
          "events"
        ],
        "additionalProperties": false
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "payment.created",
                "payment.processing",
                "payment.succeeded",
                "payment.failed",
                "payment.expired",
                "payment.cancelled",
                "refund.succeeded",
                "refund.failed",
                "settlement.created",
                "settlement.completed"
              ]
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "enabled",
          "created_at"
        ],
        "additionalProperties": false
      },
      "CreatedWebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "payment.created",
                "payment.processing",
                "payment.succeeded",
                "payment.failed",
                "payment.expired",
                "payment.cancelled",
                "refund.succeeded",
                "refund.failed",
                "settlement.created",
                "settlement.completed"
              ]
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "signing_secret": {
            "type": "string",
            "writeOnly": false,
            "description": "Shown once on creation. Store encrypted server-side; never returned by list."
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "enabled",
          "created_at",
          "signing_secret"
        ],
        "additionalProperties": false
      },
      "DeletedWebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ],
        "additionalProperties": false
      },
      "Page": {
        "type": "object",
        "properties": {
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "required": [
          "next_cursor",
          "has_more"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "maxLength": 80
              },
              "message": {
                "type": "string",
                "maxLength": 500
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string",
                      "maxLength": 100
                    },
                    "message": {
                      "type": "string",
                      "maxLength": 500
                    }
                  },
                  "required": [
                    "field",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "code",
              "message",
              "details"
            ],
            "additionalProperties": false
          },
          "request_id": {
            "$ref": "#/components/schemas/RequestId"
          }
        },
        "required": [
          "error",
          "request_id"
        ],
        "additionalProperties": false
      },
      "WebhookEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "type": {
            "type": "string",
            "enum": [
              "payment.created",
              "payment.processing",
              "payment.succeeded",
              "payment.failed",
              "payment.expired",
                "payment.cancelled",
              "refund.succeeded",
              "refund.failed",
              "settlement.created",
              "settlement.completed"
            ]
          },
          "api_version": {
            "type": "string",
            "const": "v1"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^mer_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "project_id": {
            "type": "string",
            "pattern": "^prj_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "environment": {
            "$ref": "#/components/schemas/Environment"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Payment"
              },
              {
                "$ref": "#/components/schemas/Refund"
              },
              {
                "$ref": "#/components/schemas/Settlement"
              }
            ]
          }
        },
        "required": [
          "id",
          "type",
          "api_version",
          "created_at",
          "merchant_id",
          "project_id",
          "environment",
          "data"
        ],
        "additionalProperties": false
      },
      "PaymentCreated": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PaymentId"
          },
          "object": {
            "const": "payment_intent",
            "type": "string"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^mer_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "project_id": {
            "type": "string",
            "pattern": "^prj_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          "environment": {
            "$ref": "#/components/schemas/Environment"
          },
          "merchant_reference": {
            "type": "string",
            "maxLength": 128
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "refunded_amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float."
          },
          "customer": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Customer"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "success_url": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "cancel_url": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "Short-lived payment-scoped capability URL. Safe to give the payer, confidential in logs. Never contains a merchant secret API key."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "merchant_id",
          "project_id",
          "environment",
          "merchant_reference",
          "amount",
          "currency",
          "status",
          "refunded_amount",
          "customer",
          "description",
          "metadata",
          "success_url",
          "cancel_url",
          "checkout_url",
          "expires_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false,
        "description": "Creation response only. Keep checkout_url confidential; idempotent create replay preserves the original capability."
      }
    }
  },
  "webhooks": {
    "merchantEvent": {
      "post": {
        "operationId": "receiveMerchantEvent",
        "summary": "Receive an at-least-once merchant event",
        "description": "Planned outbound request from Alzaf Pay to registered merchant URL. Event ids stable across retries/replays; delivery ids unique per HTTP attempt. Durable, idempotent acceptance before 2xx within 5 seconds. Signature tolerance 300 seconds. No event ordering guarantee.",
        "security": [
          {
            "WebhookSignature": []
          }
        ],
        "parameters": [
          {
            "name": "Alzaf-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^evt_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            }
          },
          {
            "name": "Alzaf-Delivery-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^del_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              },
              "example": {
                "id": "evt_01K4XZ1Q0A0000000000000001",
                "type": "payment.succeeded",
                "api_version": "v1",
                "created_at": "2026-09-12T12:00:00Z",
                "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                "project_id": "prj_01K4XZ1Q0A0000000000000001",
                "environment": "test",
                "data": {
                  "id": "pay_01K4XZ1Q0A0000000000000001",
                  "object": "payment_intent",
                  "merchant_id": "mer_01K4XZ1Q0A0000000000000001",
                  "project_id": "prj_01K4XZ1Q0A0000000000000001",
                  "environment": "test",
                  "merchant_reference": "ORDER-1001",
                  "amount": 10050,
                  "currency": "BDT",
                  "status": "SUCCEEDED",
                  "refunded_amount": 0,
                  "description": "Order 1001",
                  "metadata": {
                    "order_id": "1001"
                  },
                  "customer": null,
                  "success_url": "https://merchant.example/payment/return",
                  "cancel_url": "https://merchant.example/payment/cancel",
                  "expires_at": "2026-09-12T12:30:00Z",
                  "created_at": "2026-09-12T12:00:00Z",
                  "updated_at": "2026-09-12T12:00:00Z"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Durably accepted (including previously processed duplicate)."
          },
          "204": {
            "description": "Durably accepted with no response body."
          },
          "400": {
            "description": "Malformed payload. Delivery will be retried and eventually dead-lettered."
          },
          "401": {
            "description": "Signature/timestamp invalid. Delivery will be retried; investigate endpoint secret and clock."
          },
          "500": {
            "description": "Temporary receiver failure; retry schedule applies."
          }
        }
      }
    }
  }
}