{
  "openapi": "3.1.0",
  "info": {
    "title": "Vestonix Public API",
    "version": "1.0.0",
    "summary": "Cross-border payments API for businesses.",
    "description": "Vestonix Public API v1. Sandbox credentials use vsk_test_. This document is the integration contract.",
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://sandbox-api.vestonix.io",
      "description": "Sandbox. Mock rails. vsk_test_ only. Hostname does not enable live money."
    },
    {
      "url": "https://api.vestonix.io",
      "description": "Production. vsk_live_ only."
    }
  ],
  "security": [
    {
      "sessionCookie": []
    },
    {
      "bearerApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Payments",
      "description": "Create, authorize, capture, cancel and retrieve payments."
    },
    {
      "name": "Payment Links",
      "description": "Create shareable payment links that resolve to Vestonix payments."
    },
    {
      "name": "Customers",
      "description": "Merchant-owned customers (`vcus_`). Not Vestonix accounts."
    },
    {
      "name": "Payment Requests",
      "description": "Commercial requests for money (`vreq_`). Distinct from payment links and payments."
    },
    {
      "name": "Refunds",
      "description": "Return captured funds to the payer."
    },
    {
      "name": "Checkout",
      "description": "Scoped, short-lived credentials for the hosted checkout."
    },
    {
      "name": "Embedded Checkout",
      "description": "Merchant-owned customer apps. Create a `vcsess_` with `vsk_`; the app holds only `vcs_`. Same `vpay_` as the Public API."
    },
    {
      "name": "API Keys",
      "description": "Create, list and revoke merchant API keys. Management requires a dashboard session; Bearer API keys cannot manage keys."
    },
    {
      "name": "Webhooks",
      "description": "Register endpoints to receive Vestonix event notifications, and inspect delivery history."
    },
    {
      "name": "Balances",
      "description": "Authoritative merchant fiat balances from the Vestonix ledger. Never summed from payment rows."
    },
    {
      "name": "Settlements",
      "description": "Merchant settlement requests from available balance. Distinct from transfers."
    },
    {
      "name": "Settlement Destinations",
      "description": "Merchant-owned crypto wallet and bank settlement destinations (`vdst_`)."
    },
    {
      "name": "Settlement Quotes",
      "description": "Server-issued settlement quotes (`vqte_`). Sandbox rates are test-only."
    },
    {
      "name": "Transactions",
      "description": "Merchant financial history: payments, refunds, and settlements."
    },
    {
      "name": "Quotes",
      "description": "Public alias of Settlement Quotes. Same `vqte_` resources. Scopes `quotes:*` or `settlements:*`."
    },
    {
      "name": "Beneficiaries",
      "description": "Public alias of Settlement Destinations. Same `vdst_` resources. Scopes `beneficiaries:*` or `destinations:*`."
    },
    {
      "name": "Onboarding",
      "description": "One-time sandbox credential retrieval for invited developers. Not merchant API-key management."
    }
  ],
  "paths": {
    "/v1/sandbox-access-requests": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "operationId": "submitSandboxAccessRequest",
        "summary": "Request sandbox access",
        "description": "Creates a technical evaluation request. Does not create a merchant, issue an API credential, or grant production access.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "company_name",
                  "work_email",
                  "contact_name",
                  "country",
                  "use_case",
                  "expected_volume",
                  "technical_contact_email"
                ],
                "properties": {
                  "company_name": {
                    "type": "string"
                  },
                  "work_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "contact_name": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "use_case": {
                    "type": "string"
                  },
                  "expected_volume": {
                    "type": "string"
                  },
                  "technical_contact_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Request recorded. No credential is returned."
          }
        }
      }
    },
    "/auth/forgot-access": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "operationId": "requestMerchantSignInLink",
        "summary": "Request a merchant sign-in link",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "surface": {
                    "type": "string",
                    "enum": [
                      "dashboard",
                      "business_app"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A generic response that does not disclose whether the account exists."
          }
        }
      }
    },
    "/v1/commercial-proposals/{token}": {
      "get": {
        "tags": [
          "Commercial proposals"
        ],
        "operationId": "openCommercialProposal",
        "summary": "Open a commercial proposal",
        "description": "Opens one immutable proposal version using its expiring customer link. The token is the authority. Acceptance is not a legal signature and does not activate a live account.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The proposal version bound to this link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommercialProposalView"
                }
              }
            }
          }
        }
      }
    },
    "/v1/commercial-proposals/{token}/decision": {
      "post": {
        "tags": [
          "Commercial proposals"
        ],
        "operationId": "decideCommercialProposal",
        "summary": "Accept, decline, or request changes",
        "description": "Records a customer decision against the exact proposal version in the link. An expired or superseded version is rejected.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommercialProposalDecisionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision recorded for this version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommercialProposalDecision"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "createPayment",
        "summary": "Create a payment",
        "description": "Creates a payment and returns a `vpay_` identifier. When `capture_method` is `manual`, funds are authorized but not captured; the payment settles at `requires_capture` until you call the capture endpoint.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentRequest"
              },
              "examples": {
                "automatic": {
                  "summary": "Immediate capture",
                  "value": {
                    "amount": "250.00",
                    "currency": "EUR",
                    "reference": "INV-1042"
                  }
                },
                "manual": {
                  "summary": "Authorize now, capture later",
                  "value": {
                    "amount": "250.00",
                    "currency": "EUR",
                    "reference": "INV-1042",
                    "capture_method": "manual"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment created.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "listPayments",
        "summary": "List payments",
        "description": "Returns payments belonging to the authenticated merchant, newest first.",
        "responses": {
          "200": {
            "description": "A list of payments.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/payments/{payment_id}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "operationId": "retrievePayment",
        "summary": "Retrieve a payment",
        "description": "Returns the current state of a payment. Vestonix synchronizes with the underlying processor on read, so this is always authoritative.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "description": "The payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payments/{payment_id}/capture": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "capturePayment",
        "summary": "Capture an authorized payment",
        "description": "Captures a payment in `requires_capture`. Omit `amount` to capture the full authorized amount. Supplying a smaller `amount` performs a partial capture and releases the remaining authorization; the payment then moves to `succeeded` with `captured_amount` set to the captured figure. Only payments created with `capture_method: \"manual\"` can be captured.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CapturePaymentRequest"
              },
              "examples": {
                "full": {
                  "summary": "Capture everything",
                  "value": {}
                },
                "partial": {
                  "summary": "Capture part of the authorization",
                  "value": {
                    "amount": "120.00"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The captured payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/payments/{payment_id}/cancel": {
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "cancelPayment",
        "summary": "Cancel a payment",
        "description": "Cancels (voids) a payment before funds are captured, releasing any authorization hold. Cancelling an already-cancelled payment is a no-op and returns `200`. Once a payment has `succeeded`, use a refund instead.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelPaymentRequest"
              },
              "examples": {
                "withReason": {
                  "value": {
                    "reason": "requested_by_customer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancelled payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/payments/{payment_id}/refunds": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "operationId": "listPaymentRefunds",
        "summary": "List refunds for a payment",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of refunds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefundList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payments/{payment_id}/checkout-session": {
      "post": {
        "tags": [
          "Checkout"
        ],
        "operationId": "createCheckoutSession",
        "summary": "Create a checkout session",
        "description": "Returns short-lived, scoped credentials that the Vestonix hosted checkout page uses to collect payment details in the browser. The session is intentionally separate from the payment resource because it expires and must never be persisted.\n\nCard data is collected directly by the checkout front end and never traverses your servers or the Vestonix API.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "surface": {
                    "type": "string",
                    "enum": [
                      "hosted",
                      "embed"
                    ],
                    "description": "Hosted full-page checkout or iframe embed. Defaults to hosted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A checkout session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSession"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payments/{payment_id}/client-sessions": {
      "post": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "createClientCheckoutSession",
        "summary": "Create a client checkout session",
        "description": "Merchant-authenticated. Returns a short-lived opaque `vcs_` credential for the merchant's customer application. Never put `vsk_` in an app. Creating a session does not create a new payment. A later create for the same `vpay_` revokes the previous `vcs_`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "web",
                      "react_native",
                      "ios",
                      "android",
                      "flutter"
                    ]
                  },
                  "return_url": {
                    "type": "string",
                    "description": "Merchant app return URL or custom scheme. javascript: and data: are rejected."
                  },
                  "origin": {
                    "type": "string",
                    "description": "Optional browser origin binding for the Web SDK."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Client checkout session. `client_secret` is shown once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientCheckoutSessionCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/client-checkout/session": {
      "get": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "retrieveClientCheckoutSession",
        "summary": "Retrieve the client checkout session for a `vcs_` credential",
        "description": "Authorize with `Authorization: Bearer vcs_test_…` or `vcs_live_…`. This is not a merchant API key. SDK callbacks are not payment finality — retrieve the payment or wait for a webhook.",
        "security": [],
        "responses": {
          "200": {
            "description": "Session context for the Vestonix SDK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientCheckoutSessionContext"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "options": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "preflightClientCheckoutSession",
        "summary": "CORS preflight for the Web SDK",
        "security": [],
        "responses": {
          "204": {
            "description": "No content."
          }
        }
      }
    },
    "/v1/client-checkout/methods": {
      "get": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "listClientCheckoutMethods",
        "summary": "List server-driven methods for the client session",
        "description": "Fail-closed. Apple Pay, Google Pay, and saved cards stay hidden until a certified provider capability says otherwise. Authorize with `vcs_`.",
        "security": [],
        "responses": {
          "200": {
            "description": "Available methods.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethodList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "options": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "preflightClientCheckoutMethods",
        "summary": "CORS preflight for the Web SDK",
        "security": [],
        "responses": {
          "204": {
            "description": "No content."
          }
        }
      }
    },
    "/v1/client-checkout/payment": {
      "get": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "retrieveClientCheckoutPayment",
        "summary": "Retrieve the `vpay_` bound to this client session",
        "description": "Authoritative payment view for the SDK. Cannot mark the payment succeeded.",
        "security": [],
        "responses": {
          "200": {
            "description": "Checkout payment view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutPaymentView"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "options": {
        "tags": [
          "Embedded Checkout"
        ],
        "operationId": "preflightClientCheckoutPayment",
        "summary": "CORS preflight for the Web SDK",
        "security": [],
        "responses": {
          "204": {
            "description": "No content."
          }
        }
      }
    },
    "/v1/checkout/payments/{payment_id}": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "retrieveCheckoutPayment",
        "summary": "Retrieve a payment from the checkout page",
        "description": "A deliberately reduced view of a payment for use by the hosted checkout and the payer's return page. It is unauthenticated — the unguessable `vpay_` identifier is the capability — and therefore exposes only what the payer already knows: amount, currency, reference and status.\n\nDo not use this from your backend; use the authenticated retrieve endpoint instead.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "description": "A reduced payment view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutPaymentView"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/checkout/payments/{payment_id}/methods": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "listCheckoutPaymentMethods",
        "summary": "List payment methods available for a checkout payment",
        "description": "Server-authoritative methods for this `vpay_`. Does not name underlying processors.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Available payment methods.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethodList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Checkout"
        ],
        "operationId": "selectCheckoutPaymentMethod",
        "summary": "Select a payment method on a checkout payment",
        "description": "`card`, `apple_pay`, and `google_pay` bind the processor collection path. `mobile_money` starts an asynchronous local collection. `crypto` creates a stablecoin payment instruction. Provider identifiers are never returned.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SelectCheckoutPaymentMethodRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated checkout payment view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutPaymentView"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/checkout/payment-links/{payment_link_id}/methods": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "listCheckoutPaymentLinkMethods",
        "summary": "List payment methods available for a payment link",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "Available payment methods.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethodList"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/checkout-settings": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "getCheckoutSettings",
        "summary": "Retrieve merchant checkout method settings",
        "description": "Server-authoritative method switches for Apple Pay, Google Pay, and crypto. Does not expose processor secrets.",
        "responses": {
          "200": {
            "description": "Checkout settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantCheckoutSettings"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Checkout"
        ],
        "operationId": "updateCheckoutSettings",
        "summary": "Update merchant checkout method settings",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMerchantCheckoutSettingsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated checkout settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantCheckoutSettings"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          }
        }
      }
    },
    "/v1/payment-links": {
      "post": {
        "tags": [
          "Payment Links"
        ],
        "operationId": "createPaymentLink",
        "summary": "Create a payment link",
        "description": "Creates a shareable Vestonix payment link (`vplink_`). The public URL is hosted by Vestonix. Paying the link creates or reuses a Vestonix payment — callers never talk to a processor directly.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentLinkRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment link created.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "get": {
        "tags": [
          "Payment Links"
        ],
        "operationId": "listPaymentLinks",
        "summary": "List payment links",
        "description": "Returns payment links belonging to the authenticated merchant, newest first.",
        "responses": {
          "200": {
            "description": "A list of payment links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/payment-links/{payment_link_id}": {
      "get": {
        "tags": [
          "Payment Links"
        ],
        "operationId": "retrievePaymentLink",
        "summary": "Retrieve a payment link",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "The payment link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payment-links/{payment_link_id}/cancel": {
      "post": {
        "tags": [
          "Payment Links"
        ],
        "operationId": "cancelPaymentLink",
        "summary": "Cancel a payment link",
        "description": "Disables an unpaid payment link. Paid links cannot be cancelled.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "The cancelled payment link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/collection-capabilities": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "listCollectionCapabilities",
        "summary": "List effective collection methods",
        "description": "Server-authoritative methods available to this merchant. The client must not infer Cards, Apple Pay, Google Pay, Mobile Money, or crypto locally.",
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Currency"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available collection methods.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethodList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/customers": {
      "post": {
        "tags": [
          "Customers"
        ],
        "operationId": "createCustomer",
        "summary": "Create a customer",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCustomerRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Customer created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "listCustomers",
        "summary": "List customers",
        "responses": {
          "200": {
            "description": "A list of customers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/customers/{customer_id}": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "retrieveCustomer",
        "summary": "Retrieve a customer",
        "parameters": [
          {
            "$ref": "#/components/parameters/CustomerId"
          }
        ],
        "responses": {
          "200": {
            "description": "The customer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Customers"
        ],
        "operationId": "updateCustomer",
        "summary": "Update a customer",
        "parameters": [
          {
            "$ref": "#/components/parameters/CustomerId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCustomerRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated customer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/customers/{customer_id}/payments": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "listCustomerPayments",
        "summary": "List payments for a customer",
        "parameters": [
          {
            "$ref": "#/components/parameters/CustomerId"
          }
        ],
        "responses": {
          "200": {
            "description": "Payments linked to this customer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/customers/{customer_id}/payment-requests": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "listCustomerPaymentRequests",
        "summary": "List payment requests for a customer",
        "parameters": [
          {
            "$ref": "#/components/parameters/CustomerId"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment requests for this customer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payment-requests": {
      "post": {
        "tags": [
          "Payment Requests"
        ],
        "operationId": "createPaymentRequest",
        "summary": "Create a payment request",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentRequestResource"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment request created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "get": {
        "tags": [
          "Payment Requests"
        ],
        "operationId": "listPaymentRequests",
        "summary": "List payment requests",
        "responses": {
          "200": {
            "description": "A list of payment requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/payment-requests/{payment_request_id}": {
      "get": {
        "tags": [
          "Payment Requests"
        ],
        "operationId": "retrievePaymentRequest",
        "summary": "Retrieve a payment request",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentRequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "The payment request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/payment-requests/{payment_request_id}/cancel": {
      "post": {
        "tags": [
          "Payment Requests"
        ],
        "operationId": "cancelPaymentRequest",
        "summary": "Cancel a payment request",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentRequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "The cancelled payment request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/checkout/payment-links/{payment_link_id}": {
      "get": {
        "tags": [
          "Checkout"
        ],
        "operationId": "retrieveCheckoutPaymentLink",
        "summary": "Retrieve a payment link from the public pay page",
        "description": "A reduced, unauthenticated view of a payment link for the payer landing page. The unguessable `vplink_` identifier is the capability.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "A reduced payment-link view.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkPublicView"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/checkout/payment-links/{payment_link_id}/start": {
      "post": {
        "tags": [
          "Checkout"
        ],
        "operationId": "startCheckoutPaymentLink",
        "summary": "Start checkout from a payment link",
        "description": "Creates or reuses a Vestonix payment for the link and returns the hosted checkout URL. Card details are never collected here.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkId"
          }
        ],
        "responses": {
          "200": {
            "description": "Checkout session for the payment link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkStartResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/refunds": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "operationId": "listRefunds",
        "summary": "List refunds",
        "description": "Returns refunds belonging to the authenticated merchant, newest first.",
        "responses": {
          "200": {
            "description": "A list of refunds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefundList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Refunds"
        ],
        "operationId": "createRefund",
        "summary": "Create a refund",
        "description": "Refunds part or all of a captured payment. Multiple partial refunds are allowed while their total stays within the captured amount.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRefundRequest"
              },
              "examples": {
                "partial": {
                  "value": {
                    "payment_id": "vpay_01JX2M0Q7T",
                    "amount": "25.00",
                    "reason": "damaged_item"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Refund created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefundObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/refunds/{refund_id}": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "operationId": "retrieveRefund",
        "summary": "Retrieve a refund",
        "parameters": [
          {
            "name": "refund_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vrfd_"
            },
            "example": "vrfd_01JX2M4B8Z"
          }
        ],
        "responses": {
          "200": {
            "description": "The refund.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefundObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "createApiKey",
        "summary": "Create an API key",
        "description": "Creates a Vestonix secret API key for the authenticated merchant. The raw secret is returned once in the response and cannot be retrieved again — store it immediately.\n\nRequires a dashboard session. Bearer API keys cannot create keys.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApiKeyRequest"
              },
              "examples": {
                "scoped": {
                  "summary": "Collect and money scopes",
                  "value": {
                    "name": "Backend integration",
                    "scopes": [
                      "customers:read",
                      "customers:write",
                      "payment_requests:read",
                      "payment_requests:write",
                      "payments:read",
                      "balances:read",
                      "settlements:read",
                      "webhooks:read",
                      "webhooks:write"
                    ]
                  }
                },
                "payments_only": {
                  "summary": "Payments-only key",
                  "value": {
                    "name": "Payments reader",
                    "scopes": [
                      "payments:read"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created. Includes the raw `secret` once.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreatedObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "tags": [
          "API Keys"
        ],
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "description": "Returns API keys for the authenticated merchant. Secrets are never included — only `secret_hint`.\n\nRequires a dashboard session. Bearer API keys cannot list keys.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "A list of API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}": {
      "get": {
        "tags": [
          "API Keys"
        ],
        "operationId": "retrieveApiKey",
        "summary": "Retrieve an API key",
        "description": "Returns metadata for a single API key. The raw secret is never returned.\n\nRequires a dashboard session. Bearer API keys cannot retrieve keys.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}/revoke": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "revokeApiKey",
        "summary": "Revoke an API key",
        "description": "Revokes an API key so it can no longer authenticate. Revoking an already-revoked key is idempotent.\n\nRequires a dashboard session. Bearer API keys cannot revoke keys.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "The revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhookEndpoint",
        "summary": "Create a webhook endpoint",
        "description": "Registers a URL that Vestonix will POST signed event payloads to. The signing secret is returned once in the create response — store it immediately.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookEndpointRequest"
              },
              "examples": {
                "allEvents": {
                  "summary": "Receive all events",
                  "value": {
                    "url": "https://example.com/webhooks/vestonix"
                  }
                },
                "paymentsOnly": {
                  "summary": "Payments lifecycle only",
                  "value": {
                    "url": "https://example.com/webhooks/vestonix",
                    "description": "Payments",
                    "enabled_events": [
                      "payment.created",
                      "payment.succeeded",
                      "payment.failed"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook endpoint created. Includes the raw signing `secret` once.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointCreatedObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints",
        "description": "Returns webhook endpoints for the authenticated merchant. Signing secrets are never included — only `secret_hint`.",
        "responses": {
          "200": {
            "description": "A list of webhook endpoints.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{webhook_endpoint_id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "retrieveWebhookEndpoint",
        "summary": "Retrieve a webhook endpoint",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "The webhook endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "updateWebhookEndpoint",
        "summary": "Update a webhook endpoint",
        "description": "Updates URL, description, enabled flag, or subscribed event types. Does not rotate the signing secret.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookEndpointRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated webhook endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhookEndpoint",
        "summary": "Disable a webhook endpoint",
        "description": "Disables the endpoint so Vestonix stops delivering events to it. The resource remains retrievable with `enabled: false`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "The disabled webhook endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{webhook_endpoint_id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhookEndpoint",
        "summary": "Send a test webhook event",
        "description": "Queues a `webhook.test` event for delivery to the endpoint. Returns immediately with the event and delivery identifiers; inspect deliveries for the outcome.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "responses": {
          "202": {
            "description": "Test event queued for delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookTestQueued"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{webhook_endpoint_id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookDeliveries",
        "summary": "List webhook deliveries",
        "description": "Returns recent delivery attempts for the endpoint, newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of deliveries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/balances": {
      "get": {
        "tags": [
          "Balances"
        ],
        "operationId": "listMerchantBalances",
        "summary": "List merchant balances",
        "description": "Authoritative fiat balances from the Vestonix ledger, per currency. Amounts are decimal strings: available, pending, reserved, and settlement_pending.",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Merchant balances from the Vestonix ledger.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantBalanceList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/balances/{currency}": {
      "get": {
        "tags": [
          "Balances"
        ],
        "operationId": "getMerchantBalance",
        "summary": "Retrieve a merchant balance",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "currency",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Merchant balance for one currency.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantBalanceObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/settlements": {
      "get": {
        "tags": [
          "Settlements"
        ],
        "operationId": "listSettlements",
        "summary": "List settlements",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Settlements"
        ],
        "operationId": "createSettlement",
        "summary": "Create a settlement request",
        "description": "Reserves available balance. With `quote_id`, starts cross-border settlement orchestration. Legacy amount/currency requests remain reserve-only.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSettlementRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Settlement request created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/settlements/{id}": {
      "get": {
        "tags": [
          "Settlements"
        ],
        "operationId": "getSettlement",
        "summary": "Retrieve a settlement",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vset_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/settlement-destinations": {
      "get": {
        "tags": [
          "Settlement Destinations"
        ],
        "operationId": "listSettlementDestinations",
        "summary": "List settlement destinations",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement destinations for the authenticated merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Settlement Destinations"
        ],
        "operationId": "createSettlementDestination",
        "summary": "Create a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSettlementDestinationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Destination created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/settlement-destinations/{id}": {
      "get": {
        "tags": [
          "Settlement Destinations"
        ],
        "operationId": "getSettlementDestination",
        "summary": "Retrieve a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Destination details with masked sensitive fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Settlement Destinations"
        ],
        "operationId": "updateSettlementDestination",
        "summary": "Update a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSettlementDestinationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated destination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Settlement Destinations"
        ],
        "operationId": "disableSettlementDestination",
        "summary": "Disable a settlement destination",
        "description": "Sets status to inactive. Does not delete historical settlements.",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Destination disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/settlement-quotes": {
      "post": {
        "tags": [
          "Settlement Quotes"
        ],
        "operationId": "createSettlementQuote",
        "summary": "Create a settlement quote",
        "description": "Server-calculated, immutable quote. Does not reserve ledger funds. Sandbox rates are test-only.",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSettlementQuoteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "get": {
        "tags": [
          "Settlement Quotes"
        ],
        "operationId": "listSettlementQuotes",
        "summary": "List settlement quotes",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Quotes for the authenticated merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/settlement-quotes/{id}": {
      "get": {
        "tags": [
          "Settlement Quotes"
        ],
        "operationId": "getSettlementQuote",
        "summary": "Retrieve a settlement quote",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vqte_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quote details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}/rotate": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "rotateApiKey",
        "summary": "Rotate an API client secret",
        "description": "Issues a new secret. The previous secret continues to authenticate until you call revoke-previous or rotate again. The new secret is shown once.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "Rotated API client with the new secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreatedObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}/revoke-previous": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "revokePreviousApiKeySecret",
        "summary": "Revoke the previous rotated secret",
        "description": "Ends overlap after a rotation. The current secret continues to work.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "API client metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}/suspend": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "suspendApiKey",
        "summary": "Suspend an API client",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "Suspended API client.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/api-keys/{api_key_id}/activate": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "activateApiKey",
        "summary": "Reactivate a suspended API client",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyId"
          }
        ],
        "responses": {
          "200": {
            "description": "Active API client.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "rotateWebhookEndpointSecret",
        "summary": "Rotate a webhook signing secret",
        "description": "Issues a new `vwhsec_` secret, shown once. Immediate cutover — no overlap.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint with the new secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/webhook-endpoints/{webhook_endpoint_id}/deliveries/{delivery_id}/resend": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "resendWebhookDelivery",
        "summary": "Resend a webhook event",
        "description": "Queues a new delivery attempt for the same historical event. Does not re-run a financial operation.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookEndpointId"
          },
          {
            "name": "delivery_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdlv_"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "New delivery queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": [
          "Transactions"
        ],
        "operationId": "listTransactions",
        "summary": "List merchant transactions",
        "description": "Payments, refunds, and settlements for the authenticated merchant. Not raw ledger postings.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/CreatedAfter"
          },
          {
            "$ref": "#/components/parameters/CreatedBefore"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "payment",
                "refund",
                "settlement",
                "adjustment"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of transactions.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/quotes": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "createQuote",
        "summary": "Create a settlement quote",
        "description": "Server-calculated, immutable quote. Does not reserve ledger funds. Sandbox rates are test-only.",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSettlementQuoteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "get": {
        "tags": [
          "Quotes"
        ],
        "operationId": "listQuotes",
        "summary": "List settlement quotes",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Quotes for the authenticated merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/quotes/{id}": {
      "get": {
        "tags": [
          "Quotes"
        ],
        "operationId": "getQuote",
        "summary": "Retrieve a settlement quote",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vqte_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quote details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementQuoteObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/beneficiaries": {
      "get": {
        "tags": [
          "Beneficiaries"
        ],
        "operationId": "listBeneficiaries",
        "summary": "List settlement destinations",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement destinations for the authenticated merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Beneficiaries"
        ],
        "operationId": "createBeneficiary",
        "summary": "Create a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSettlementDestinationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Destination created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/beneficiaries/{id}": {
      "get": {
        "tags": [
          "Beneficiaries"
        ],
        "operationId": "getBeneficiary",
        "summary": "Retrieve a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Destination details with masked sensitive fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Beneficiaries"
        ],
        "operationId": "updateBeneficiary",
        "summary": "Update a settlement destination",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSettlementDestinationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated destination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Beneficiaries"
        ],
        "operationId": "disableBeneficiary",
        "summary": "Disable a settlement destination",
        "description": "Sets status to inactive. Does not delete historical settlements.",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^vdst_"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Destination disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementDestinationObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/onboarding/credentials/retrieve": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "operationId": "retrieveSandboxCredential",
        "summary": "Retrieve a sandbox credential once",
        "description": "Exchanges a one-time retrieval token for a sandbox API secret. Call this only after an explicit human action such as clicking **Reveal Sandbox Credential**.\n\nGET, page load, refresh, and link previews must not call this endpoint and do not retrieve the credential. A successful POST returns the secret once. Repeating the same token, or using an invalid, expired, or revoked token, returns a generic 404 that does not distinguish those cases.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrieveSandboxCredentialRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sandbox credential returned once. Store the secret immediately; it is not shown again.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxCredentialObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/kyb/invitations/{token}": {
      "get": {
        "tags": [
          "Compliance"
        ],
        "operationId": "openKybTestInvitation",
        "summary": "Open a KYB test invitation",
        "description": "Opens a Vestonix TEST business-verification invitation. The journey is not valid for live KYB and does not submit a case to an identity provider.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test invitation opened. live eligibility stays false.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/kyb/journeys/{journeyId}/sections": {
      "post": {
        "tags": [
          "Compliance"
        ],
        "operationId": "advanceKybTestJourney",
        "summary": "Record a KYB test section",
        "description": "Records progress on a TEST journey. This does not approve live KYB.",
        "security": [],
        "parameters": [
          {
            "name": "journeyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Section recorded. live_eligible remains false."
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          }
        }
      }
    },
    "/v1/kyb/journeys/{journeyId}/signatures": {
      "post": {
        "tags": [
          "Compliance"
        ],
        "operationId": "signKybTestDeclaration",
        "summary": "Sign a KYB test declaration",
        "description": "Stores an electronic signature for the TEST declaration text. It is not a live KYB approval.",
        "security": [],
        "parameters": [
          {
            "name": "journeyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signature stored."
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          }
        }
      }
    },
    "/v1/kyb/journeys/{journeyId}/submit": {
      "post": {
        "tags": [
          "Compliance"
        ],
        "operationId": "submitKybTestJourney",
        "summary": "Submit a KYB test journey",
        "description": "Submits a TEST journey. The response keeps live_eligible false and does not call an external identity provider.",
        "security": [],
        "parameters": [
          {
            "name": "journeyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test evidence recorded. Not valid for live KYB."
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "vestonix_session",
        "description": "Dashboard browser session cookie. Prefer Bearer API keys (`vsk_…`) for server-to-server calls. API key management endpoints require a session and reject Bearer authentication."
      },
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "vsk_…",
        "description": "Vestonix secret API key. Create keys in the dashboard. Format: vsk_test_… or vsk_live_…. The raw secret is shown once at creation."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "A unique key that makes the request safe to retry. Replaying the same key with the same body returns the original resource; replaying it with a different body returns `409 idempotency_key_reuse`.",
        "schema": {
          "type": "string",
          "maxLength": 255
        },
        "example": "order-1042-attempt-1"
      },
      "PaymentId": {
        "name": "payment_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vpay_"
        },
        "example": "vpay_01JX2M0Q7T"
      },
      "PaymentLinkId": {
        "name": "payment_link_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vplink_"
        },
        "example": "vplink_01JX2M0Q7T"
      },
      "CustomerId": {
        "name": "customer_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vcus_"
        },
        "example": "vcus_01JX2M0Q7T"
      },
      "PaymentRequestId": {
        "name": "payment_request_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vreq_"
        },
        "example": "vreq_01JX2M0Q7T"
      },
      "ApiKeyId": {
        "name": "api_key_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vkey_"
        },
        "example": "vkey_01JX2M0Q7T"
      },
      "WebhookEndpointId": {
        "name": "webhook_endpoint_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^vwh_"
        },
        "example": "vwh_01JX2M0Q7T"
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Resource id from `next_cursor`.",
        "schema": {
          "type": "string"
        }
      },
      "CreatedAfter": {
        "name": "created_after",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "CreatedBefore": {
        "name": "created_before",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "headers": {
      "XRequestId": {
        "description": "Request correlation id. Also returned as X-Vestonix-Request-Id.",
        "schema": {
          "type": "string"
        }
      },
      "XVestonixRequestId": {
        "description": "Vestonix request correlation id. Same value as X-Request-Id.",
        "schema": {
          "type": "string",
          "pattern": "^vreq_"
        }
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "The request was malformed or not valid for the current resource state.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated, but not allowed to perform this operation (for example, using a Bearer API key against API key management endpoints).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource does not exist, or does not belong to the authenticated merchant. Vestonix returns `404` rather than `403` so that resource existence is not leaked across merchants.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with the current state of the resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "CommercialProposalView": {
        "type": "object",
        "required": [
          "object",
          "company_name",
          "proposal_id",
          "version_id",
          "version_number",
          "status",
          "currency",
          "modules"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "commercial_proposal"
            ]
          },
          "company_name": {
            "type": "string"
          },
          "proposal_id": {
            "type": "string"
          },
          "version_id": {
            "type": "string"
          },
          "version_number": {
            "type": "integer"
          },
          "content_hash": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "modules": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "special_terms": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CommercialProposalDecisionRequest": {
        "type": "object",
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "ACCEPT",
              "REQUEST_CHANGES",
              "DECLINE"
            ]
          },
          "reason_category": {
            "type": "string"
          },
          "comment": {
            "type": "string"
          }
        }
      },
      "CommercialProposalDecision": {
        "type": "object",
        "required": [
          "object",
          "id",
          "proposal_id",
          "version_id",
          "action"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "commercial_proposal_decision"
            ]
          },
          "id": {
            "type": "string"
          },
          "proposal_id": {
            "type": "string"
          },
          "version_id": {
            "type": "string"
          },
          "content_hash": {
            "type": "string"
          },
          "action": {
            "type": "string"
          }
        }
      },
      "Amount": {
        "type": "string",
        "pattern": "^\\d+(\\.\\d{1,18})?$",
        "description": "A positive decimal string. Never a float. Requests may carry any scale (`\"250.00\"`); responses echo the canonical form with trailing fractional zeros removed (`\"250\"`, `\"19.9\"`). Compare amounts numerically, not as strings.",
        "example": "250.00"
      },
      "Currency": {
        "type": "string",
        "pattern": "^[A-Z]{3}$",
        "description": "ISO 4217 alpha-3 currency code.",
        "example": "EUR"
      },
      "PaymentStatus": {
        "type": "string",
        "description": "The Vestonix payment lifecycle.\n\n- `created` — accepted, not yet handed to a processor\n- `requires_action` — the payer must complete checkout or authentication\n- `processing` — in flight at the processor\n- `requires_capture` — authorized; funds are held pending capture\n- `succeeded` — funds captured\n- `failed` — declined or errored; terminal\n- `cancelled` — voided before capture; terminal",
        "enum": [
          "created",
          "requires_action",
          "processing",
          "requires_capture",
          "succeeded",
          "failed",
          "cancelled"
        ]
      },
      "CaptureMethod": {
        "type": "string",
        "enum": [
          "automatic",
          "manual"
        ],
        "default": "automatic",
        "description": "`automatic` captures funds as soon as authorization succeeds. `manual` holds the authorization until you call the capture endpoint."
      },
      "CreatePaymentRequest": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "additionalProperties": false,
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "reference": {
            "type": "string",
            "description": "Your own identifier for this payment, echoed back on every response and webhook.",
            "example": "INV-1042"
          },
          "description": {
            "type": "string",
            "description": "Merchant-facing description shown on the dashboard and payment link."
          },
          "customer_email": {
            "type": "string",
            "format": "email",
            "description": "Optional customer email. Not a full customer resource."
          },
          "capture_method": {
            "$ref": "#/components/schemas/CaptureMethod"
          }
        }
      },
      "CapturePaymentRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Amount"
              }
            ],
            "description": "Amount to capture. Must not exceed the authorized amount. Omit to capture in full."
          }
        }
      },
      "CancelPaymentRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reason": {
            "type": "string",
            "description": "Free-text reason stored on the payment and shown in the dashboard.",
            "example": "requested_by_customer"
          }
        }
      },
      "PaymentObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "amount",
          "currency",
          "status",
          "capture_method",
          "captured_amount",
          "reference",
          "description",
          "customer_email",
          "cancellation_reason",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "payment"
          },
          "id": {
            "type": "string",
            "pattern": "^vpay_",
            "example": "vpay_01JX2M0Q7T"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_",
            "example": "vmrc_demo"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "capture_method": {
            "$ref": "#/components/schemas/CaptureMethod"
          },
          "captured_amount": {
            "type": [
              "string",
              "null"
            ],
            "description": "Amount captured so far, or `null` before any capture. After a partial capture this is less than `amount` and becomes the ceiling for refunds.",
            "example": "120.00"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "payment_request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "payment_method": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "card",
              "apple_pay",
              "google_pay",
              "mobile_money",
              "crypto",
              null
            ],
            "description": "Normalized payment method. Never a processor or operator name."
          },
          "crypto": {
            "type": [
              "object",
              "null"
            ],
            "description": "Normalized crypto collection summary. Present only for crypto payments. Never includes provider IDs.",
            "properties": {
              "asset": {
                "type": "string",
                "enum": [
                  "USDC"
                ]
              },
              "network": {
                "type": "string",
                "enum": [
                  "ethereum",
                  "base"
                ]
              }
            }
          },
          "cancellation_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_action": {
            "$ref": "#/components/schemas/PaymentNextAction"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaymentNextAction": {
        "type": "object",
        "description": "Present when the payer must complete an action. Currently always a hosted checkout redirect.",
        "properties": {
          "type": {
            "const": "hosted_checkout"
          },
          "hosted_checkout": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "PaymentList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PaymentLinkStatus": {
        "type": "string",
        "enum": [
          "active",
          "paid",
          "expired",
          "cancelled"
        ]
      },
      "CreatePaymentLinkRequest": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "additionalProperties": false,
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "description": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "customer_email": {
            "type": "string",
            "format": "email"
          },
          "capture_method": {
            "$ref": "#/components/schemas/CaptureMethod"
          }
        }
      },
      "PaymentLinkObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "amount",
          "currency",
          "description",
          "reference",
          "customer_email",
          "capture_method",
          "status",
          "url",
          "payment_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "payment_link"
          },
          "id": {
            "type": "string",
            "pattern": "^vplink_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "capture_method": {
            "$ref": "#/components/schemas/CaptureMethod"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentLinkStatus"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "payment_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^vpay_"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaymentLinkList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentLinkObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PaymentLinkPublicView": {
        "type": "object",
        "required": [
          "object",
          "id",
          "amount",
          "currency",
          "description",
          "reference",
          "merchant_name",
          "status",
          "payment_status"
        ],
        "properties": {
          "object": {
            "const": "payment_link"
          },
          "id": {
            "type": "string",
            "pattern": "^vplink_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "merchant_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/PaymentLinkStatus"
          },
          "payment_status": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PaymentStatus"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "PaymentLinkStartResponse": {
        "type": "object",
        "required": [
          "object",
          "payment_link_id",
          "payment_id",
          "checkout_url",
          "status"
        ],
        "properties": {
          "object": {
            "const": "payment_link_session"
          },
          "payment_link_id": {
            "type": "string",
            "pattern": "^vplink_"
          },
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentLinkStatus"
          }
        }
      },
      "CreateCustomerRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "preferred_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "external_reference": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "UpdateCustomerRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "preferred_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "CustomerObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "name",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "customer"
          },
          "id": {
            "type": "string",
            "pattern": "^vcus_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "preferred_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CustomerList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomerObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreatePaymentRequestResource": {
        "type": "object",
        "required": [
          "customer_id",
          "amount",
          "currency"
        ],
        "properties": {
          "customer_id": {
            "type": "string",
            "pattern": "^vcus_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "reference": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "PaymentRequestObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "customer_id",
          "amount",
          "currency",
          "status"
        ],
        "properties": {
          "object": {
            "const": "payment_request"
          },
          "id": {
            "type": "string",
            "pattern": "^vreq_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "customer_id": {
            "type": "string",
            "pattern": "^vcus_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "paid",
              "cancelled"
            ]
          },
          "payment_link_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "payment_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "paid_payment_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "paid_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaymentRequestList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentRequestObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "RefundStatus": {
        "type": "string",
        "enum": [
          "created",
          "processing",
          "succeeded",
          "failed",
          "cancelled"
        ]
      },
      "CreateRefundRequest": {
        "type": "object",
        "required": [
          "payment_id",
          "amount"
        ],
        "additionalProperties": false,
        "properties": {
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "RefundObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "payment_id",
          "merchant_id",
          "amount",
          "currency",
          "status",
          "reason",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "refund"
          },
          "id": {
            "type": "string",
            "pattern": "^vrfd_",
            "example": "vrfd_01JX2M4B8Z"
          },
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/RefundStatus"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RefundList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RefundObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CheckoutSession": {
        "type": "object",
        "required": [
          "object",
          "payment_id",
          "amount",
          "currency",
          "status",
          "expires_at",
          "checkout"
        ],
        "properties": {
          "object": {
            "const": "checkout_session"
          },
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "payment_method": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "card",
              "apple_pay",
              "google_pay",
              "mobile_money",
              "crypto",
              null
            ]
          },
          "checkout": {
            "type": "object",
            "description": "Front-end bootstrap data. Its shape depends on the checkout mode and is not a stable contract for server-side code.",
            "additionalProperties": true
          }
        }
      },
      "ClientCheckoutSessionCreated": {
        "type": "object",
        "required": [
          "object",
          "id",
          "payment_id",
          "client_secret",
          "expires_at",
          "livemode",
          "allowed_operations"
        ],
        "properties": {
          "object": {
            "const": "client_checkout_session"
          },
          "id": {
            "type": "string",
            "pattern": "^vcsess_"
          },
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "client_secret": {
            "type": "string",
            "description": "Opaque `vcs_test_` or `vcs_live_` credential. Shown once. Never a `vsk_`."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean"
          },
          "allowed_operations": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "present_checkout",
                "read_payment",
                "list_methods"
              ]
            }
          },
          "return_url": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ClientCheckoutSessionContext": {
        "type": "object",
        "required": [
          "object",
          "id",
          "payment_id",
          "amount",
          "currency",
          "status",
          "expires_at",
          "hosted_checkout_url",
          "methods",
          "capabilities",
          "presentation"
        ],
        "properties": {
          "object": {
            "const": "client_checkout_session"
          },
          "id": {
            "type": "string",
            "pattern": "^vcsess_"
          },
          "payment_id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "return_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "hosted_checkout_url": {
            "type": "string"
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "appearance": {
            "type": "object",
            "additionalProperties": true
          },
          "payment": {
            "$ref": "#/components/schemas/CheckoutPaymentView"
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "card": {
                "type": "boolean"
              },
              "apple_pay": {
                "type": "boolean"
              },
              "google_pay": {
                "type": "boolean"
              },
              "saved_card": {
                "type": "boolean"
              },
              "mobile_money": {
                "type": "boolean"
              },
              "crypto": {
                "type": "boolean"
              }
            }
          },
          "presentation": {
            "type": "object",
            "description": "Brokered SDK presentation. Not a second payment resource.",
            "additionalProperties": true
          }
        }
      },
      "CheckoutPaymentView": {
        "type": "object",
        "required": [
          "object",
          "id",
          "amount",
          "currency",
          "status",
          "reference",
          "description",
          "customer_email",
          "merchant_name"
        ],
        "properties": {
          "object": {
            "const": "payment"
          },
          "id": {
            "type": "string",
            "pattern": "^vpay_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "merchant_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "payment_method": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "card",
              "apple_pay",
              "google_pay",
              "mobile_money",
              "crypto",
              null
            ]
          },
          "collection_instruction": {
            "type": [
              "string",
              "null"
            ]
          },
          "crypto": {
            "$ref": "#/components/schemas/CryptoCheckoutDetails"
          }
        }
      },
      "PaymentMethodList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type",
                "label",
                "phone_required"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "card",
                    "apple_pay",
                    "google_pay",
                    "mobile_money",
                    "crypto"
                  ]
                },
                "label": {
                  "type": "string"
                },
                "phone_required": {
                  "type": "boolean"
                }
              }
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SelectCheckoutPaymentMethodRequest": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "card",
              "apple_pay",
              "google_pay",
              "mobile_money",
              "crypto"
            ]
          },
          "phone": {
            "type": "string",
            "description": "International phone number for mobile money. Ignored otherwise."
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          }
        }
      },
      "CryptoCheckoutDetails": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "expected_amount": {
            "type": "string"
          },
          "destination_address": {
            "type": "string"
          },
          "payment_uri": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "amount_basis": {
            "const": "test_usd_1_to_1"
          }
        }
      },
      "MerchantCheckoutSettings": {
        "type": "object",
        "properties": {
          "object": {
            "const": "checkout_settings"
          },
          "merchant_id": {
            "type": "string"
          },
          "apple_pay": {
            "type": "boolean"
          },
          "google_pay": {
            "type": "boolean"
          },
          "crypto": {
            "type": "boolean"
          },
          "crypto_asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "crypto_network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "apple_pay_domain_verification_configured": {
            "type": "boolean"
          }
        }
      },
      "UpdateMerchantCheckoutSettingsRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apple_pay": {
            "type": "boolean"
          },
          "google_pay": {
            "type": "boolean"
          },
          "crypto": {
            "type": "boolean"
          },
          "crypto_asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "crypto_network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "apple_pay_domain_association": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ApiKeyScope": {
        "type": "string",
        "description": "Permission granted to an external API client. `quotes:*` and `beneficiaries:*` are public aliases of `settlements:*` and `destinations:*` respectively and grant the same permission. Crypto rail scopes are not part of the public developer contract.",
        "enum": [
          "customers:read",
          "customers:write",
          "payment_requests:read",
          "payment_requests:write",
          "payment_links:read",
          "payment_links:write",
          "payments:read",
          "payments:write",
          "refunds:read",
          "refunds:write",
          "webhooks:read",
          "webhooks:write",
          "balances:read",
          "transactions:read",
          "settlements:read",
          "settlements:write",
          "destinations:read",
          "destinations:write",
          "quotes:read",
          "quotes:write",
          "beneficiaries:read",
          "beneficiaries:write"
        ]
      },
      "ApiKeyEnvironment": {
        "type": "string",
        "enum": [
          "test",
          "live"
        ],
        "default": "test",
        "description": "Key environment. Assigned from the merchant account. A test credential cannot access Live."
      },
      "ApiKeyStatus": {
        "type": "string",
        "enum": [
          "active",
          "suspended",
          "revoked"
        ]
      },
      "CreateApiKeyRequest": {
        "type": "object",
        "required": [
          "name",
          "scopes"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable label shown in the dashboard.",
            "example": "Backend integration"
          },
          "scopes": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            },
            "description": "Permissions granted to the key. At least one scope is required. There is no wildcard super-key."
          },
          "environment": {
            "$ref": "#/components/schemas/ApiKeyEnvironment"
          }
        }
      },
      "ApiKeyObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "name",
          "secret_hint",
          "environment",
          "scopes",
          "status",
          "last_used_at",
          "created_at",
          "revoked_at"
        ],
        "properties": {
          "object": {
            "const": "api_key"
          },
          "id": {
            "type": "string",
            "pattern": "^vkey_",
            "example": "vkey_01JX2M0Q7T"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_",
            "example": "vmrc_demo"
          },
          "name": {
            "type": "string"
          },
          "secret_hint": {
            "type": "string",
            "description": "Masked secret for display, e.g. `vsk_test_…abcd`. Never the raw secret.",
            "example": "vsk_test_…abcd"
          },
          "environment": {
            "$ref": "#/components/schemas/ApiKeyEnvironment"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            }
          },
          "status": {
            "$ref": "#/components/schemas/ApiKeyStatus",
            "enum": [
              "active",
              "suspended",
              "revoked"
            ]
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "suspended_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "rotated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ApiKeyCreatedObject": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiKeyObject"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "description": "Raw secret. Shown once — store it immediately.",
                "example": "vsk_test_<sandbox-key>"
              }
            }
          }
        ]
      },
      "RetrieveSandboxCredentialRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "minLength": 16,
            "description": "One-time retrieval token from the credential email. Do not send this on GET or page load."
          }
        }
      },
      "SandboxCredentialObject": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "object",
          "secret",
          "api_client_id",
          "warning"
        ],
        "properties": {
          "object": {
            "const": "sandbox_credential"
          },
          "secret": {
            "type": "string",
            "pattern": "^vsk_test_",
            "description": "Sandbox API secret. Returned only on this successful one-time POST. Store it immediately."
          },
          "api_client_id": {
            "type": "string",
            "pattern": "^vkey_",
            "description": "Public identifier of the sandbox API client. This is not the secret."
          },
          "warning": {
            "type": "string",
            "description": "Reminder that the secret is shown once."
          }
        }
      },
      "ApiKeyList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "VestonixEventType": {
        "type": "string",
        "description": "Vestonix webhook event type delivered to merchant endpoints.",
        "enum": [
          "payment.created",
          "payment.requires_action",
          "payment.requires_capture",
          "payment.processing",
          "payment.succeeded",
          "payment.failed",
          "payment.cancelled",
          "refund.created",
          "refund.processing",
          "refund.succeeded",
          "refund.failed",
          "crypto.deposit.detected",
          "crypto.deposit.confirmed",
          "balance.updated",
          "settlement.created",
          "settlement.processing",
          "settlement.action_required",
          "settlement.completed",
          "settlement.failed",
          "settlement.cancelled",
          "transfer.completed",
          "transfer.failed",
          "customer.created",
          "payment_request.created",
          "payment_request.paid",
          "payment_request.cancelled",
          "webhook.test"
        ]
      },
      "WebhookTestObject": {
        "type": "object",
        "required": [
          "object",
          "message"
        ],
        "properties": {
          "object": {
            "const": "webhook_test"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "VestonixEventObject": {
        "type": "object",
        "description": "Public event envelope delivered to merchant webhook endpoints.",
        "required": [
          "object",
          "id",
          "type",
          "created_at",
          "merchant_id",
          "data"
        ],
        "properties": {
          "object": {
            "const": "event"
          },
          "id": {
            "type": "string",
            "pattern": "^vevt_",
            "example": "vevt_01JX2M0Q7T"
          },
          "type": {
            "$ref": "#/components/schemas/VestonixEventType"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "data": {
            "type": "object",
            "required": [
              "object"
            ],
            "properties": {
              "object": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PaymentObject"
                  },
                  {
                    "$ref": "#/components/schemas/RefundObject"
                  },
                  {
                    "$ref": "#/components/schemas/WebhookTestObject"
                  }
                ]
              }
            }
          }
        }
      },
      "CreateWebhookEndpointRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS URL that will receive Vestonix event POSTs.",
            "example": "https://example.com/webhooks/vestonix"
          },
          "description": {
            "type": "string",
            "description": "Optional human-readable label."
          },
          "enabled_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VestonixEventType"
            },
            "description": "Event types to deliver. Defaults to all non-test event types when omitted."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the endpoint accepts deliveries. Defaults to true."
          }
        }
      },
      "UpdateWebhookEndpointRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass `null` to clear the description."
          },
          "enabled_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VestonixEventType"
            }
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookEndpointObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "url",
          "description",
          "enabled",
          "enabled_events",
          "secret_hint",
          "created_at",
          "updated_at",
          "disabled_at"
        ],
        "properties": {
          "object": {
            "const": "webhook_endpoint"
          },
          "id": {
            "type": "string",
            "pattern": "^vwh_",
            "example": "vwh_01JX2M0Q7T"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_",
            "example": "vmrc_demo"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "enabled_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VestonixEventType"
            }
          },
          "secret_hint": {
            "type": "string",
            "description": "Masked signing secret, e.g. `vwhsec_…xyz`. Never the raw secret after create.",
            "example": "vwhsec_…xyz"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "disabled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "WebhookEndpointCreatedObject": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpointObject"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "description": "Raw signing secret. Shown once — store it immediately.",
                "example": "vwhsec_abcdefghijklmnopqrstuvwxyz012345"
              }
            }
          }
        ]
      },
      "WebhookEndpointList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEndpointObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "WebhookDeliveryStatus": {
        "type": "string",
        "enum": [
          "pending",
          "succeeded",
          "failed",
          "retrying",
          "abandoned"
        ]
      },
      "WebhookDeliveryObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "event_id",
          "webhook_endpoint_id",
          "event_type",
          "status",
          "attempt_count",
          "http_status",
          "next_attempt_at",
          "last_attempt_at",
          "error_summary",
          "created_at"
        ],
        "properties": {
          "object": {
            "const": "webhook_delivery"
          },
          "id": {
            "type": "string",
            "pattern": "^vdlv_",
            "example": "vdlv_01JX2M0Q7T"
          },
          "event_id": {
            "type": "string",
            "pattern": "^vevt_"
          },
          "webhook_endpoint_id": {
            "type": "string",
            "pattern": "^vwh_"
          },
          "event_type": {
            "$ref": "#/components/schemas/VestonixEventType"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookDeliveryStatus"
          },
          "attempt_count": {
            "type": "integer",
            "minimum": 0
          },
          "http_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "next_attempt_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_attempt_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "error_summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookDeliveryList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDeliveryObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "WebhookTestQueued": {
        "type": "object",
        "required": [
          "object",
          "event_id",
          "delivery_id"
        ],
        "properties": {
          "object": {
            "const": "webhook_test_queued"
          },
          "event_id": {
            "type": "string",
            "pattern": "^vevt_"
          },
          "delivery_id": {
            "type": "string",
            "pattern": "^vdlv_"
          }
        }
      },
      "BalanceObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "asset",
          "network",
          "available",
          "pending",
          "reserved",
          "in_transit",
          "total"
        ],
        "properties": {
          "object": {
            "const": "balance"
          },
          "id": {
            "type": "string",
            "pattern": "^vbal_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "available": {
            "type": "string"
          },
          "pending": {
            "type": "string"
          },
          "reserved": {
            "type": "string"
          },
          "in_transit": {
            "type": "string"
          },
          "total": {
            "type": "string"
          }
        }
      },
      "BalanceList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalanceObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "MerchantBalanceObject": {
        "type": "object",
        "required": [
          "object",
          "merchant_id",
          "currency",
          "pending",
          "available",
          "reserved",
          "settlement_pending"
        ],
        "properties": {
          "object": {
            "const": "merchant_balance"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "pending": {
            "type": "string"
          },
          "available": {
            "type": "string"
          },
          "reserved": {
            "type": "string"
          },
          "settlement_pending": {
            "type": "string"
          }
        }
      },
      "MerchantBalanceList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MerchantBalanceObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SettlementStatus": {
        "type": "string",
        "enum": [
          "pending",
          "processing",
          "action_required",
          "completed",
          "failed",
          "cancelled"
        ]
      },
      "CreateSettlementRequest": {
        "type": "object",
        "properties": {
          "quote_id": {
            "type": "string",
            "pattern": "^vqte_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "destination": {
            "type": "string"
          }
        }
      },
      "SettlementObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "amount",
          "currency",
          "status",
          "source_balance",
          "destination",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "settlement"
          },
          "id": {
            "type": "string",
            "pattern": "^vset_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "$ref": "#/components/schemas/SettlementStatus"
          },
          "source_balance": {
            "const": "available"
          },
          "destination": {
            "type": "string"
          },
          "quote_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "crypto_wallet",
              "bank_account",
              "legacy",
              null
            ]
          },
          "estimated_receive_amount": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "fx_rate": {
            "type": [
              "string",
              "null"
            ]
          },
          "fee": {
            "type": [
              "string",
              "null"
            ]
          },
          "network_cost": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimated_arrival": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination_transaction_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SettlementList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreateSettlementDestinationRequest": {
        "type": "object",
        "required": [
          "type",
          "label"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "crypto_wallet",
              "bank_account"
            ]
          },
          "label": {
            "type": "string"
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "address": {
            "type": "string"
          },
          "memo": {
            "type": "string"
          },
          "account_holder_name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "bank_name": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "iban": {
            "type": "string"
          },
          "swift_bic": {
            "type": "string"
          },
          "routing_code": {
            "type": "string"
          },
          "beneficiary_address": {
            "type": "string"
          }
        }
      },
      "UpdateSettlementDestinationRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "bank_name": {
            "type": "string"
          },
          "beneficiary_address": {
            "type": "string"
          }
        }
      },
      "SettlementDestinationObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "type",
          "label",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "settlement_destination"
          },
          "id": {
            "type": "string",
            "pattern": "^vdst_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "type": {
            "type": "string",
            "enum": [
              "crypto_wallet",
              "bank_account"
            ]
          },
          "label": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "asset": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "memo": {
            "type": [
              "string",
              "null"
            ]
          },
          "account_holder_name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "bank_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "account_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "iban": {
            "type": [
              "string",
              "null"
            ]
          },
          "swift_bic": {
            "type": [
              "string",
              "null"
            ]
          },
          "routing_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "beneficiary_address": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SettlementDestinationList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementDestinationObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreateSettlementQuoteRequest": {
        "type": "object",
        "required": [
          "source_amount",
          "source_currency"
        ],
        "properties": {
          "source_amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "source_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "destination_id": {
            "type": "string",
            "pattern": "^vdst_"
          },
          "beneficiary_id": {
            "type": "string",
            "pattern": "^vdst_",
            "description": "Alias of destination_id."
          }
        }
      },
      "SettlementQuoteObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "source_amount",
          "source_currency",
          "destination_id",
          "destination_type",
          "destination_currency",
          "estimated_receive_amount",
          "fx_rate",
          "vestonix_fee",
          "vestonix_fee_currency",
          "network_cost",
          "total_deductions",
          "estimated_arrival",
          "expires_at",
          "status",
          "rate_basis",
          "created_at"
        ],
        "properties": {
          "object": {
            "const": "settlement_quote"
          },
          "id": {
            "type": "string",
            "pattern": "^vqte_"
          },
          "merchant_id": {
            "type": "string",
            "pattern": "^vmrc_"
          },
          "source_amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "source_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "destination_id": {
            "type": "string",
            "pattern": "^vdst_"
          },
          "destination_type": {
            "type": "string",
            "enum": [
              "crypto_wallet",
              "bank_account"
            ]
          },
          "destination_currency": {
            "type": "string"
          },
          "estimated_receive_amount": {
            "type": "string"
          },
          "fx_rate": {
            "type": "string"
          },
          "vestonix_fee": {
            "type": "string"
          },
          "vestonix_fee_currency": {
            "type": "string"
          },
          "network_cost": {
            "type": "string"
          },
          "total_deductions": {
            "type": "string"
          },
          "estimated_arrival": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "consumed",
              "expired"
            ]
          },
          "rate_basis": {
            "const": "sandbox_test"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WalletObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "asset",
          "network",
          "status",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "object": {
            "const": "wallet"
          },
          "id": {
            "type": "string",
            "pattern": "^vwlt_"
          },
          "merchant_id": {
            "type": "string"
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WalletList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WalletObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreateWalletRequest": {
        "type": "object",
        "required": [
          "asset",
          "network"
        ],
        "properties": {
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          }
        }
      },
      "AddressObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "wallet_id",
          "merchant_id",
          "asset",
          "network",
          "address",
          "status",
          "created_at"
        ],
        "properties": {
          "object": {
            "const": "address"
          },
          "id": {
            "type": "string",
            "pattern": "^vaddr_"
          },
          "wallet_id": {
            "type": "string",
            "pattern": "^vwlt_"
          },
          "merchant_id": {
            "type": "string"
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "address": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AddressList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddressObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "TransferObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "merchant_id",
          "type",
          "asset",
          "network",
          "amount",
          "status",
          "destination",
          "transaction_hash",
          "wallet_id",
          "address_id",
          "failure_code",
          "failure_message",
          "created_at",
          "updated_at",
          "completed_at"
        ],
        "properties": {
          "object": {
            "const": "transfer"
          },
          "id": {
            "type": "string",
            "pattern": "^vtr_"
          },
          "merchant_id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "crypto_receive",
              "crypto_send"
            ]
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "amount": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "destination": {
            "type": [
              "object",
              "null"
            ]
          },
          "transaction_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "wallet_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "address_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "TransferList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransferObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CreateTransferRequest": {
        "type": "object",
        "required": [
          "type",
          "asset",
          "network",
          "amount"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "crypto_send"
            ]
          },
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "network": {
            "type": "string",
            "enum": [
              "ethereum",
              "base"
            ]
          },
          "amount": {
            "type": "string"
          },
          "destination": {
            "type": "object",
            "required": [
              "type",
              "address"
            ],
            "properties": {
              "type": {
                "const": "wallet_address"
              },
              "address": {
                "type": "string"
              }
            }
          },
          "reference": {
            "type": "string"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          }
        }
      },
      "ErrorBody": {
        "type": "object",
        "required": [
          "type",
          "code",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Error family. Not-found and conflict conditions are `invalid_request_error` with a specific `code` (for example `payment_not_found`); idempotency-key reuse with a different body is `idempotency_error`; missing scopes are `authorization_error`; provider outages are `api_error` with code `provider_temporarily_unavailable`.",
            "enum": [
              "invalid_request_error",
              "authentication_error",
              "authorization_error",
              "rate_limit_error",
              "idempotency_error",
              "api_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "A stable, machine-readable Vestonix error code. Never a processor error code.",
            "example": "payment_not_capturable"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "The request field that caused the error, when applicable."
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "TransactionObject": {
        "type": "object",
        "required": [
          "object",
          "id",
          "kind",
          "amount",
          "currency",
          "status",
          "created_at"
        ],
        "properties": {
          "object": {
            "const": "transaction"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "payment",
              "refund",
              "settlement",
              "adjustment"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "status": {
            "type": "string"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TransactionList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SettlementQuoteList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more"
        ],
        "properties": {
          "object": {
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementQuoteObject"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
