{"openapi":"3.1.0","info":{"title":"Stablevoy API","version":"1.0.0","description":"Stablevoy accepts USDC and USDT payments that go straight to your own wallet. This reference lists every endpoint; the guides (payment flow, webhooks, WooCommerce, recovery) are at https://stablevoy.com/docs/.\n\n## Authentication\n\n- **API key** for your server and plugins: `Authorization: Bearer sk_live_...`. Create keys in the dashboard, one store per key. Never put a key in a browser or an app.\n- **Merchant session** for the dashboard and apps: Sign-In with Ethereum (`/v1/auth/siwe/*`). Browsers get httpOnly cookies, apps get a bearer token.\n\n## Amounts\n\nInvoice amounts are integers in US cents (`1999` is $19.99). Token amounts are strings in the token's smallest units (USDC and USDT have 6 decimals on most networks), so large values never lose precision.\n\n## Idempotency\n\nSend an `Idempotency-Key` header when creating an invoice (your order id is a good key). Retrying with the same key and body returns the first invoice with `replayed: true` instead of a duplicate.\n\n## Pagination\n\nList endpoints take `limit` (1 to 100) and return `nextCursor`; pass it as `cursor` until it is `null`.\n\n## Errors\n\nErrors are RFC 7807 problem documents (`application/problem+json`) with a stable `code`, a readable `detail` and a `type` link to the code's entry in the error catalog: https://stablevoy.com/docs/api/errors/.\n\n## Webhooks\n\nStablevoy POSTs invoice events to the store's webhook URL, signed with HMAC-SHA256. How to verify them: https://stablevoy.com/docs/#webhooks."},"servers":[{"url":"https://api.stablevoy.com"}],"tags":[{"name":"Invoices","description":"Create invoices and read their status and payments. The main thing a shop integration does."},{"name":"Checkout","description":"Public data behind the hosted payment page."},{"name":"Stores","description":"Stores with their networks, limits, website and webhook."},{"name":"API keys","description":"Keys for server-to-server calls, one store each."},{"name":"Webhooks","description":"Signing secret, test events, delivery history and redelivery."},{"name":"Account","description":"The signed-in merchant, setup progress and the payout wallet."},{"name":"Auth","description":"Sign-In with Ethereum and sessions for the dashboard and apps."},{"name":"System","description":"Health, limits, pricing, networks, this document and the contact form."}],"paths":{"/v1/health":{"get":{"operationId":"getV1Health","summary":"Service health","description":"State of every network watcher and background component. Answers HTTP 503 with the same body when anything is degraded, so uptime monitors alert.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"degraded also answers HTTP 503, so uptime monitors alert."},"networks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"healthy":{"type":"boolean"},"lagBlocks":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How far the watcher is behind the chain head."}},"required":["key","healthy","lagBlocks"],"additionalProperties":false}},"components":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"ok":{"type":"boolean"}},"required":["component","ok"],"additionalProperties":false}},"failedSweeps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"belowThresholdSweeps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deposit addresses holding less than the automatic sweep minimum. Informational, never degrades health."},"pendingWebhooks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["status","networks","components","failedSweeps","belowThresholdSweeps","pendingWebhooks"],"additionalProperties":false},"example":{"status":"ok","networks":[{"key":"base","healthy":true,"lagBlocks":2}],"components":[{"component":"relayer:base","ok":true}],"failedSweeps":0,"belowThresholdSweeps":0,"pendingWebhooks":0}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/limits":{"get":{"operationId":"getV1Limits","summary":"Platform invoice limits","description":"The platform minimum and cap per invoice. Store limits must fit inside them.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"minInvoiceUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform minimum per invoice, in cents."},"maxInvoiceUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform cap per invoice, in cents."}},"required":["minInvoiceUsdCents","maxInvoiceUsdCents"],"additionalProperties":false},"example":{"minInvoiceUsdCents":500,"maxInvoiceUsdCents":100000}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/pricing":{"get":{"operationId":"getV1Pricing","summary":"Pricing","description":"The one-time free volume per payout wallet, the fee above it in basis points and the cap the contract enforces.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"freeVolumeUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"One-time free volume per payout wallet, in cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Fee above the free volume, in basis points (50 is 0.5%)."},"maxFeeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hard cap on the fee enforced by the contract."}},"required":["freeVolumeUsdCents","feeBps","maxFeeBps"],"additionalProperties":false},"example":{"freeVolumeUsdCents":100000,"feeBps":50,"maxFeeBps":200}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/networks":{"get":{"operationId":"getV1Networks","summary":"Networks and tokens","description":"Networks and stablecoins Stablevoy accepts, with the contract addresses on each, so you can verify them on the block explorer.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"displayName":{"type":"string"},"chainId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"confirmations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Blocks to wait before a payment counts as confirmed."},"factoryAddress":{"type":"string","description":"ForwarderFactory contract that deploys deposit addresses and sweeps funds."},"forwarderImplementation":{"type":"string"},"explorerUrl":{"type":["string","null"]},"rpcUrl":{"type":"string","description":"Public RPC endpoint of the network, for wallets and browser reads. Not the one Stablevoy watches the chain with."},"tokens":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string"},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["symbol","address","decimals"],"additionalProperties":false}}},"required":["key","displayName","chainId","confirmations","factoryAddress","forwarderImplementation","explorerUrl","rpcUrl","tokens"],"additionalProperties":false}},"example":[{"key":"base","displayName":"Base","chainId":8453,"confirmations":12,"factoryAddress":"0xf0E1D2c3b4a5968778695A4b3c2d1e0f9A8b7C6d","forwarderImplementation":"0xa1B2c3d4E5f60718293a4B5C6d7E8F9012345678","explorerUrl":"https://basescan.org","rpcUrl":"https://mainnet.base.org","tokens":[{"symbol":"USDC","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6}]}]}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/errors":{"get":{"operationId":"getV1Errors","summary":"Error catalog","description":"Every error code the API can answer, grouped, with its HTTP status, what it means and what to do. The same text is on https://stablevoy.com/docs/api/errors/.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["authentication","validation","invoices","stores","payout","networks","contact","general","internal"]},"title":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["authentication_failed","unsupported_chain","validation_failed","bad_request","payload_too_large","unsupported_media_type","invalid_address","invalid_amount","amount_below_minimum","amount_above_store_limit","amount_above_platform_cap","invalid_external_reference","invalid_return_url","conflict","store_disabled","invalid_store_name","store_limit_reached","no_networks","invalid_limits","invalid_website_url","invalid_webhook_url","webhook_not_configured","invalid_key_name","payout_address_not_set","address_not_checksummed","unsupported_network","unsupported_token","networks_unavailable","invalid_contact_topic","invalid_contact_name","invalid_contact_email","invalid_contact_message","human_check_failed","human_check_unavailable","not_found","rate_limited","internal_error","invalid_fee","invalid_fee_config","invalid_retry_policy","invalid_store_quota","invalid_ttl","no_networks_configured","no_tokens_configured","no_public_rpc","duplicate_network","invalid_state_transition","screening_unavailable","invalid_bytes32"]},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"meaning":{"type":"string","description":"What happened."},"action":{"type":"string","description":"What to do about it."}},"required":["code","status","meaning","action"],"additionalProperties":false}}},"required":["key","title","errors"],"additionalProperties":false}}},"required":["groups"],"additionalProperties":false},"example":{"groups":[{"key":"invoices","title":"Invoices and amounts","errors":[{"code":"amount_below_minimum","status":422,"meaning":"The amount is below the store minimum or the platform minimum.","action":"Raise the amount to at least limitUsdCents."}]}]}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getV1OpenapiJson","summary":"OpenAPI document","description":"This API description in OpenAPI 3.1. Import the URL into Postman, Insomnia, Bruno or Swagger UI.","tags":["System"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"This OpenAPI 3.1 document."}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/contact":{"post":{"operationId":"postV1Contact","summary":"Contact the team","description":"Used by the contact form on the site. Needs a Cloudflare Turnstile token from the page, so it is not meant for scripts. Limited to 5 messages per hour per IP.","tags":["System"],"security":[],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"received":{"type":"boolean","const":true}},"required":["received"],"additionalProperties":false},"example":{"received":true}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_contact_topic`: The topic is not one of the offered ones.\n\n`invalid_contact_name`: The name is empty or longer than 100 characters.\n\n`invalid_contact_email`: The email address is not valid, so we could not reply.\n\n`invalid_contact_message`: The message is shorter than 20 or longer than 5,000 characters.\n\n`human_check_failed`: The Cloudflare Turnstile check did not confirm a person, or its token was already used.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_contact_topic":{"summary":"invalid_contact_topic","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_contact_topic","title":"invalid contact topic","status":422,"code":"invalid_contact_topic","detail":"The topic is not one of the offered ones."}},"invalid_contact_name":{"summary":"invalid_contact_name","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_contact_name","title":"invalid contact name","status":422,"code":"invalid_contact_name","detail":"The name is empty or longer than 100 characters."}},"invalid_contact_email":{"summary":"invalid_contact_email","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_contact_email","title":"invalid contact email","status":422,"code":"invalid_contact_email","detail":"The email address is not valid, so we could not reply."}},"invalid_contact_message":{"summary":"invalid_contact_message","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_contact_message","title":"invalid contact message","status":422,"code":"invalid_contact_message","detail":"The message is shorter than 20 or longer than 5,000 characters."}},"human_check_failed":{"summary":"human_check_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-human_check_failed","title":"human check failed","status":422,"code":"human_check_failed","detail":"The Cloudflare Turnstile check did not confirm a person, or its token was already used."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}},"503":{"description":"`human_check_unavailable`: The human check could not be verified right now, so the message was not accepted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"human_check_unavailable":{"summary":"human_check_unavailable","value":{"type":"https://stablevoy.com/docs/api/errors/#error-human_check_unavailable","title":"human check unavailable","status":503,"code":"human_check_unavailable","detail":"The human check could not be verified right now, so the message was not accepted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","maxLength":200,"description":"1 to 100 characters after trimming."},"email":{"type":"string","maxLength":320,"description":"Where the reply goes."},"topic":{"type":"string","enum":["general","limits","partnership","other"]},"message":{"type":"string","maxLength":10000,"description":"20 to 5,000 characters after trimming."},"page":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Site path the visitor came from, if known."},"turnstileToken":{"type":"string","maxLength":4096,"description":"Cloudflare Turnstile token from the widget on the page."},"website":{"type":"string","maxLength":1000,"description":"Honeypot: must be empty. People never see this field."}},"required":["name","email","topic","message","page","turnstileToken","website"],"additionalProperties":false},"example":{"name":"Ann","email":"ann@shop.example","topic":"limits","message":"Please raise my store limit to twenty stores.","page":"/app/","turnstileToken":"XXXX.DUMMY.TOKEN.XXXX","website":""}}}}}},"/v1/checkout/invoices/{invoiceId}":{"get":{"operationId":"getV1CheckoutInvoicesByinvoiceId","summary":"Payment page data","description":"Public data of the hosted payment page, by the unguessable invoice id: amount per token and network, deposit addresses and what the page needs to recompute each address itself and refuse a tampered one. Exposes nothing private.","tags":["Checkout"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"storeName":{"type":"string"},"storeWebsiteUrl":{"type":["string","null"]},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"]},"returnUrl":{"type":["string","null"]},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expiresAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"secondsLeft":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Seconds until expiresAt, never negative."},"invoiceSalt":{"type":"string","description":"With payoutAddress and feeBps, lets the page recompute every deposit address and refuse a tampered one."},"payoutAddress":{"type":"string"},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"paidUsdMicros":{"type":"string","description":"Received so far, in millionths of a dollar."},"networks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"displayName":{"type":"string"},"chainId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"depositAddress":{"type":"string"},"factoryAddress":{"type":"string"},"forwarderImplementation":{"type":"string"},"wallet":{"type":"object","properties":{"chainName":{"type":"string"},"nativeCurrency":{"type":"object","properties":{"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["name","symbol","decimals"],"additionalProperties":false},"rpcUrls":{"type":"array","items":{"type":"string"}},"blockExplorerUrls":{"type":"array","items":{"type":"string"}}},"required":["chainName","nativeCurrency","rpcUrls","blockExplorerUrls"],"additionalProperties":false,"description":"Parameters for wallet_addEthereumChain."},"tokens":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string"},"decimals":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"Amount to send in the token's smallest units."}},"required":["symbol","address","decimals","amount"],"additionalProperties":false}}},"required":["key","displayName","chainId","depositAddress","factoryAddress","forwarderImplementation","wallet","tokens"],"additionalProperties":false}}},"required":["id","storeName","storeWebsiteUrl","status","returnUrl","amountUsdCents","expiresAt","secondsLeft","invoiceSalt","payoutAddress","feeBps","paidUsdMicros","networks"],"additionalProperties":false},"example":{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeName":"My Shop","storeWebsiteUrl":"https://shop.example","status":"awaiting_payment","returnUrl":"https://shop.example/checkout/order-received/1042/","amountUsdCents":1999,"expiresAt":"2026-10-16T13:00:00.000Z","secondsLeft":3540,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","feeBps":50,"paidUsdMicros":"0","networks":[{"key":"base","displayName":"Base","chainId":8453,"depositAddress":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B","factoryAddress":"0xf0E1D2c3b4a5968778695A4b3c2d1e0f9A8b7C6d","forwarderImplementation":"0xa1B2c3d4E5f60718293a4B5C6d7E8F9012345678","wallet":{"chainName":"Base","nativeCurrency":{"name":"Ether","symbol":"ETH","decimals":18},"rpcUrls":["https://mainnet.base.org"],"blockExplorerUrls":["https://basescan.org"]},"tokens":[{"symbol":"USDC","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6,"amount":"19990000"}]}]}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Invoice id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Invoice id (UUID)."}}]}},"/v1/auth/siwe/challenge":{"post":{"operationId":"postV1AuthSiweChallenge","summary":"Start sign-in","description":"Step 1 of Sign-In with Ethereum: returns a server-built EIP-4361 message for the wallet to sign. It is valid for a few minutes and only once.","tags":["Auth"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"challengeId":{"type":"string","description":"Pass back with the signature."},"message":{"type":"string","description":"EIP-4361 (Sign-In with Ethereum) message to sign exactly as given."},"expiresAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["challengeId","message","expiresAt"],"additionalProperties":false},"example":{"challengeId":"7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","message":"stablevoy.com wants you to sign in with your Ethereum account:\n0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5\n\nSign in to Stablevoy.\n\nURI: https://stablevoy.com\nVersion: 1\nChain ID: 8453\nNonce: 8f3a1c2b4d5e6f70\nIssued At: 2026-10-16T12:00:00.000Z\nExpiration Time: 2026-10-16T12:05:00.000Z","expiresAt":"2026-10-16T12:05:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_address`: A value is not a valid EVM address (0x followed by 40 hex characters).\n\n`unsupported_chain`: Sign-in was requested for a chain id that Stablevoy does not support.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_address":{"summary":"invalid_address","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_address","title":"invalid address","status":422,"code":"invalid_address","detail":"A value is not a valid EVM address (0x followed by 40 hex characters)."}},"unsupported_chain":{"summary":"unsupported_chain","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_chain","title":"unsupported chain","status":422,"code":"unsupported_chain","detail":"Sign-in was requested for a chain id that Stablevoy does not support."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"The wallet that signs in."},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":4294967296,"description":"EIP-155 chain id of the wallet, e.g. 8453 for Base."}},"required":["address","chainId"],"additionalProperties":false},"example":{"address":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","chainId":8453}}}}}},"/v1/auth/siwe/verify":{"post":{"operationId":"postV1AuthSiweVerify","summary":"Finish sign-in","description":"Step 2: send the signature of the challenge message. Browsers (clientKind web) get httpOnly session cookies and only the expiry in the body; apps (mobile, other) get the access and refresh tokens in the body.","tags":["Auth"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"merchantId":{"type":"string","description":"Merchant id (UUID)."},"accessTokenExpiresAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"accessToken":{"description":"Apps only: send as \"Authorization: Bearer ...\".","type":"string"},"refreshToken":{"description":"Apps only: exchange at /v1/auth/refresh before the access token expires.","type":"string"},"refreshTokenExpiresAt":{"description":"Apps only.","type":"string"}},"required":["merchantId","accessTokenExpiresAt"],"additionalProperties":false},"example":{"merchantId":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f","accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzYzRkIn0.c2lnbmF0dXJl","accessTokenExpiresAt":"2026-10-16T12:15:00.000Z","refreshToken":"rt_9f8e7d6c5b4a39281706f5e4d3c2b1a0","refreshTokenExpiresAt":"2026-11-15T12:00:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"challengeId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"From the challenge response."},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$","description":"Wallet signature (personal_sign), 0x followed by 130 hex characters."},"clientKind":{"type":"string","enum":["web","mobile","other"],"description":"web: tokens go to httpOnly cookies; mobile or other: tokens are returned in the body."}},"required":["challengeId","signature","clientKind"],"additionalProperties":false},"example":{"challengeId":"7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","signature":"0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab","clientKind":"mobile"}}}}}},"/v1/auth/refresh":{"post":{"operationId":"postV1AuthRefresh","summary":"Refresh the session","description":"Exchanges the refresh token (cookie for browsers, body for apps) for a new pair. Each refresh token works once: reusing an old one signs out every session of that login.","tags":["Auth"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"merchantId":{"type":"string","description":"Merchant id (UUID)."},"accessTokenExpiresAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"accessToken":{"description":"Apps only: send as \"Authorization: Bearer ...\".","type":"string"},"refreshToken":{"description":"Apps only: exchange at /v1/auth/refresh before the access token expires.","type":"string"},"refreshTokenExpiresAt":{"description":"Apps only.","type":"string"}},"required":["merchantId","accessTokenExpiresAt"],"additionalProperties":false},"example":{"merchantId":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f","accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzYzRkIn0.c2lnbmF0dXJl","accessTokenExpiresAt":"2026-10-16T12:30:00.000Z","refreshToken":"rt_0a1b2c3d4e5f60718293a4b5c6d7e8f9","refreshTokenExpiresAt":"2026-11-15T12:15:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"refreshToken":{"description":"Apps send it here; browsers send the cookie instead.","type":"string","minLength":16,"maxLength":200}},"additionalProperties":false},"example":{"refreshToken":"rt_9f8e7d6c5b4a39281706f5e4d3c2b1a0"}}}}}},"/v1/auth/logout":{"post":{"operationId":"postV1AuthLogout","summary":"Sign out","description":"Revokes the session of the refresh token and clears the browser cookies.","tags":["Auth"],"security":[],"responses":{"204":{"description":"Done, no content."},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"refreshToken":{"description":"Apps send it here; browsers send the cookie instead.","type":"string","minLength":16,"maxLength":200}},"additionalProperties":false},"example":{"refreshToken":"rt_9f8e7d6c5b4a39281706f5e4d3c2b1a0"}}}}}},"/v1/me":{"get":{"operationId":"getV1Me","summary":"Current account","description":"The signed-in merchant: login wallet, payout wallet and how many stores the account may have.","tags":["Account"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Merchant id (UUID)."},"loginAddress":{"type":"string","description":"Wallet that signs in."},"payoutAddress":{"description":"Wallet that receives payments; null until set.","type":["string","null"]},"maxStores":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many stores this account may have."},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","loginAddress","payoutAddress","maxStores","createdAt"],"additionalProperties":false},"example":{"id":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f","loginAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","maxStores":10,"createdAt":"2026-10-16T12:00:00.000Z"}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/me/onboarding":{"get":{"operationId":"getV1MeOnboarding","summary":"Setup progress","description":"Which setup steps are done on the way to a first paid order: payout wallet, store, a key or payment link, webhook, first payment.","tags":["Account"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payoutAddressSet":{"type":"boolean"},"storeCreated":{"type":"boolean"},"canCharge":{"type":"boolean","description":"An active API key exists or an invoice was created from the dashboard."},"webhookConfigured":{"type":"boolean"},"paymentReceived":{"type":"boolean"}},"required":["payoutAddressSet","storeCreated","canCharge","webhookConfigured","paymentReceived"],"additionalProperties":false},"example":{"payoutAddressSet":true,"storeCreated":true,"canCharge":true,"webhookConfigured":false,"paymentReceived":false}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/me/payout-address/challenge":{"post":{"operationId":"postV1MePayoutAddressChallenge","summary":"Start a payout wallet change","description":"Step 1: returns the message the login wallet must sign to approve the new payout wallet. The address must be EIP-55 checksummed so a typo cannot slip through.","tags":["Account"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"challengeId":{"type":"string","description":"Pass back with the signature."},"message":{"type":"string","description":"EIP-4361 (Sign-In with Ethereum) message to sign exactly as given."},"expiresAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["challengeId","message","expiresAt"],"additionalProperties":false},"example":{"challengeId":"7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","message":"stablevoy.com wants you to sign in with your Ethereum account:\n0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5\n\nSign in to Stablevoy.\n\nURI: https://stablevoy.com\nVersion: 1\nChain ID: 8453\nNonce: 8f3a1c2b4d5e6f70\nIssued At: 2026-10-16T12:00:00.000Z\nExpiration Time: 2026-10-16T12:05:00.000Z","expiresAt":"2026-10-16T12:05:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_address`: A value is not a valid EVM address (0x followed by 40 hex characters).\n\n`address_not_checksummed`: The payout address is not in EIP-55 checksummed form (mixed case), so a typo could not be detected.\n\n`unsupported_chain`: Sign-in was requested for a chain id that Stablevoy does not support.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_address":{"summary":"invalid_address","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_address","title":"invalid address","status":422,"code":"invalid_address","detail":"A value is not a valid EVM address (0x followed by 40 hex characters)."}},"address_not_checksummed":{"summary":"address_not_checksummed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-address_not_checksummed","title":"address not checksummed","status":422,"code":"address_not_checksummed","detail":"The payout address is not in EIP-55 checksummed form (mixed case), so a typo could not be detected."}},"unsupported_chain":{"summary":"unsupported_chain","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_chain","title":"unsupported chain","status":422,"code":"unsupported_chain","detail":"Sign-in was requested for a chain id that Stablevoy does not support."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"New payout wallet, EIP-55 checksummed (mixed case)."},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":4294967296,"description":"EIP-155 chain id of the wallet, e.g. 8453 for Base."}},"required":["payoutAddress","chainId"],"additionalProperties":false},"example":{"payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","chainId":8453}}}}}},"/v1/me/payout-address/confirm":{"post":{"operationId":"postV1MePayoutAddressConfirm","summary":"Confirm a payout wallet change","description":"Step 2: send the signature. The new wallet applies to invoices created from now on; existing invoices keep the wallet they were created with.","tags":["Account"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"204":{"description":"Done, no content."},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_address`: A value is not a valid EVM address (0x followed by 40 hex characters).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_address":{"summary":"invalid_address","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_address","title":"invalid address","status":422,"code":"invalid_address","detail":"A value is not a valid EVM address (0x followed by 40 hex characters)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"EVM address, 0x followed by 40 hex characters."},"challengeId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"From the challenge response."},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$","description":"Signature of the message by the login wallet."}},"required":["payoutAddress","challengeId","signature"],"additionalProperties":false},"example":{"payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","challengeId":"7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","signature":"0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"}}}}}},"/v1/stores":{"get":{"operationId":"getV1Stores","summary":"List stores","description":"Every store of the signed-in merchant.","tags":["Stores"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Store id (UUID)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"enabledNetworks":{"type":"array","items":{"type":"string"}},"minInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform minimum applies."},"maxInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform cap applies."},"webhookUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"defaultReturnUrl":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","name","status","enabledNetworks","minInvoiceUsdCents","maxInvoiceUsdCents","webhookUrl","websiteUrl","defaultReturnUrl","createdAt"],"additionalProperties":false}},"example":[{"id":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","name":"My Shop","status":"active","enabledNetworks":["base","arbitrum"],"minInvoiceUsdCents":null,"maxInvoiceUsdCents":null,"webhookUrl":"https://shop.example/wp-json/stablevoy/v1/webhook","websiteUrl":"https://shop.example","defaultReturnUrl":null,"createdAt":"2026-10-16T12:00:00.000Z"}]}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}},"post":{"operationId":"postV1Stores","summary":"Create a store","description":"A store has its own API keys, webhook, networks and invoice limits. An account may have a limited number of stores (maxStores in GET /v1/me).","tags":["Stores"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Store id (UUID)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"enabledNetworks":{"type":"array","items":{"type":"string"}},"minInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform minimum applies."},"maxInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform cap applies."},"webhookUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"defaultReturnUrl":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","name","status","enabledNetworks","minInvoiceUsdCents","maxInvoiceUsdCents","webhookUrl","websiteUrl","defaultReturnUrl","createdAt"],"additionalProperties":false},"example":{"id":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","name":"My Shop","status":"active","enabledNetworks":["base","arbitrum"],"minInvoiceUsdCents":null,"maxInvoiceUsdCents":null,"webhookUrl":null,"websiteUrl":null,"defaultReturnUrl":null,"createdAt":"2026-10-16T12:00:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_store_name`: The store name is empty or too long.\n\n`store_limit_reached`: The account already has as many stores as it is allowed.\n\n`no_networks`: A store must accept payments on at least one network.\n\n`unsupported_network`: The network key is not one Stablevoy supports here.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_store_name":{"summary":"invalid_store_name","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_store_name","title":"invalid store name","status":422,"code":"invalid_store_name","detail":"The store name is empty or too long."}},"store_limit_reached":{"summary":"store_limit_reached","value":{"type":"https://stablevoy.com/docs/api/errors/#error-store_limit_reached","title":"store limit reached","status":422,"code":"store_limit_reached","detail":"The account already has as many stores as it is allowed."}},"no_networks":{"summary":"no_networks","value":{"type":"https://stablevoy.com/docs/api/errors/#error-no_networks","title":"no networks","status":422,"code":"no_networks","detail":"A store must accept payments on at least one network."}},"unsupported_network":{"summary":"unsupported_network","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_network","title":"unsupported network","status":422,"code":"unsupported_network","detail":"The network key is not one Stablevoy supports here."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to buyers on the payment page."},"enabledNetworks":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":32,"description":"Network key as listed by GET /v1/networks, e.g. \"base\"."},"description":"Networks buyers can pay on. At least one."}},"required":["name","enabledNetworks"],"additionalProperties":false},"example":{"name":"My Shop","enabledNetworks":["base","arbitrum"]}}}}}},"/v1/store":{"get":{"operationId":"getV1Store","summary":"The API key's store","description":"The store the API key belongs to. Plugins call it to check the key and read the limits and enabled networks.","tags":["Stores"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Store id (UUID)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"enabledNetworks":{"type":"array","items":{"type":"string"}},"minInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform minimum applies."},"maxInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform cap applies."},"webhookUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"defaultReturnUrl":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","name","status","enabledNetworks","minInvoiceUsdCents","maxInvoiceUsdCents","webhookUrl","websiteUrl","defaultReturnUrl","createdAt"],"additionalProperties":false},"example":{"id":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","name":"My Shop","status":"active","enabledNetworks":["base","arbitrum"],"minInvoiceUsdCents":null,"maxInvoiceUsdCents":null,"webhookUrl":"https://shop.example/wp-json/stablevoy/v1/webhook","websiteUrl":"https://shop.example","defaultReturnUrl":null,"createdAt":"2026-10-16T12:00:00.000Z"}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}}}},"/v1/stores/{storeId}":{"get":{"operationId":"getV1StoresBystoreId","summary":"Get a store","description":"One store, by a signed-in merchant or with that store's API key.","tags":["Stores"],"security":[{"apiKey":[]},{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Store id (UUID)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"enabledNetworks":{"type":"array","items":{"type":"string"}},"minInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform minimum applies."},"maxInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform cap applies."},"webhookUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"defaultReturnUrl":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","name","status","enabledNetworks","minInvoiceUsdCents","maxInvoiceUsdCents","webhookUrl","websiteUrl","defaultReturnUrl","createdAt"],"additionalProperties":false},"example":{"id":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","name":"My Shop","status":"active","enabledNetworks":["base","arbitrum"],"minInvoiceUsdCents":null,"maxInvoiceUsdCents":null,"webhookUrl":"https://shop.example/wp-json/stablevoy/v1/webhook","websiteUrl":"https://shop.example","defaultReturnUrl":null,"createdAt":"2026-10-16T12:00:00.000Z"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}]},"patch":{"operationId":"patchV1StoresBystoreId","summary":"Update a store","description":"Changes only the fields you send; null clears an optional field. When a webhook URL is set for the first time the response carries webhookSecret, once: store it to verify webhook signatures.","tags":["Stores"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Store id (UUID)."},"name":{"type":"string"},"status":{"type":"string","enum":["active","disabled"]},"enabledNetworks":{"type":"array","items":{"type":"string"}},"minInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform minimum applies."},"maxInvoiceUsdCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null: the platform cap applies."},"webhookUrl":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"defaultReturnUrl":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"webhookSecret":{"anyOf":[{"type":"string","description":"HMAC-SHA256 signing secret for webhooks. Shown only in this response: store it."},{"type":"null"}],"description":"Present once, when a webhook URL was set for the first time; otherwise null."}},"required":["id","name","status","enabledNetworks","minInvoiceUsdCents","maxInvoiceUsdCents","webhookUrl","websiteUrl","defaultReturnUrl","createdAt","webhookSecret"],"additionalProperties":false},"example":{"id":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","name":"My Shop","status":"active","enabledNetworks":["base","arbitrum"],"minInvoiceUsdCents":null,"maxInvoiceUsdCents":null,"webhookUrl":"https://shop.example/wp-json/stablevoy/v1/webhook","websiteUrl":"https://shop.example","defaultReturnUrl":null,"createdAt":"2026-10-16T12:00:00.000Z","webhookSecret":"whsec_3b9f0c1d2e4a5b6c7d8e9f0a1b2c3d4e"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_store_name`: The store name is empty or too long.\n\n`invalid_webhook_url`: The webhook URL is not https, contains credentials, uses an IP address or a local name, or is too long.\n\n`invalid_website_url`: The store website is not an absolute https URL without credentials, or is too long.\n\n`invalid_return_url`: The return URL is not an absolute https URL without credentials, or is too long.\n\n`invalid_limits`: The store invoice limits are not valid: below the platform minimum, above the platform cap, or the minimum is above the maximum.\n\n`no_networks`: A store must accept payments on at least one network.\n\n`unsupported_network`: The network key is not one Stablevoy supports here.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_store_name":{"summary":"invalid_store_name","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_store_name","title":"invalid store name","status":422,"code":"invalid_store_name","detail":"The store name is empty or too long."}},"invalid_webhook_url":{"summary":"invalid_webhook_url","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_webhook_url","title":"invalid webhook url","status":422,"code":"invalid_webhook_url","detail":"The webhook URL is not https, contains credentials, uses an IP address or a local name, or is too long."}},"invalid_website_url":{"summary":"invalid_website_url","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_website_url","title":"invalid website url","status":422,"code":"invalid_website_url","detail":"The store website is not an absolute https URL without credentials, or is too long."}},"invalid_return_url":{"summary":"invalid_return_url","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_return_url","title":"invalid return url","status":422,"code":"invalid_return_url","detail":"The return URL is not an absolute https URL without credentials, or is too long."}},"invalid_limits":{"summary":"invalid_limits","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_limits","title":"invalid limits","status":422,"code":"invalid_limits","detail":"The store invoice limits are not valid: below the platform minimum, above the platform cap, or the minimum is above the maximum."}},"no_networks":{"summary":"no_networks","value":{"type":"https://stablevoy.com/docs/api/errors/#error-no_networks","title":"no networks","status":422,"code":"no_networks","detail":"A store must accept payments on at least one network."}},"unsupported_network":{"summary":"unsupported_network","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_network","title":"unsupported network","status":422,"code":"unsupported_network","detail":"The network key is not one Stablevoy supports here."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"description":"Shown to buyers on the payment page.","type":"string","minLength":1,"maxLength":100},"webhookUrl":{"description":"Public https endpoint for webhooks; null removes it. Setting it the first time returns a signing secret once.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"websiteUrl":{"description":"The shop's address, linked on the payment page.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"defaultReturnUrl":{"description":"Where buyers go after paying when the invoice has no returnUrl.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"enabledNetworks":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":32,"description":"Network key as listed by GET /v1/networks, e.g. \"base\"."},"description":"Networks buyers can pay on. At least one."},"minInvoiceUsdCents":{"description":"Store minimum per invoice; null uses the platform minimum.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in US cents, a positive integer: 1999 is $19.99."},{"type":"null"}]},"maxInvoiceUsdCents":{"description":"Store maximum per invoice; null uses the platform cap.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in US cents, a positive integer: 1999 is $19.99."},{"type":"null"}]},"status":{"description":"disabled stops new invoices.","type":"string","enum":["active","disabled"]}},"additionalProperties":false},"example":{"webhookUrl":"https://shop.example/wp-json/stablevoy/v1/webhook"}}}}}},"/v1/stores/{storeId}/webhook-secret/rotate":{"post":{"operationId":"postV1StoresBystoreIdWebhookSecretRotate","summary":"Rotate the webhook secret","description":"Makes a new signing secret and returns it once. The old one stops working at once, so update your shop right away.","tags":["Webhooks"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"webhookSecret":{"type":"string","description":"HMAC-SHA256 signing secret for webhooks. Shown only in this response: store it."}},"required":["webhookSecret"],"additionalProperties":false},"example":{"webhookSecret":"whsec_3b9f0c1d2e4a5b6c7d8e9f0a1b2c3d4e"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"422":{"description":"`webhook_not_configured`: The action needs a webhook URL and the store has none.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"webhook_not_configured":{"summary":"webhook_not_configured","value":{"type":"https://stablevoy.com/docs/api/errors/#error-webhook_not_configured","title":"webhook not configured","status":422,"code":"webhook_not_configured","detail":"The action needs a webhook URL and the store has none."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}]}},"/v1/stores/{storeId}/api-keys":{"get":{"operationId":"getV1StoresBystoreIdApiKeys","summary":"List API keys","description":"Every key of the store, active and revoked, with its prefix and last use. Secrets are never returned again.","tags":["API keys"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Key id (UUID)."},"name":{"type":"string"},"prefix":{"type":"string","description":"First characters of the key, to recognise it. The secret itself is never shown again."},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"lastUsedAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}],"description":"Last successful API call with this key."},"revokedAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]}},"required":["id","name","prefix","createdAt","lastUsedAt","revokedAt"],"additionalProperties":false}},"example":[{"id":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","name":"WooCommerce","prefix":"sk_live_4f9a","createdAt":"2026-10-16T12:00:00.000Z","lastUsedAt":null,"revokedAt":null}]}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}]},"post":{"operationId":"postV1StoresBystoreIdApiKeys","summary":"Create an API key","description":"Creates a key for server-to-server calls (plugins, your backend). The full key is in this response only: store it. Never put it in a browser or an app.","tags":["API keys"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Key id (UUID)."},"name":{"type":"string"},"prefix":{"type":"string","description":"First characters of the key, to recognise it. The secret itself is never shown again."},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"lastUsedAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}],"description":"Last successful API call with this key."},"revokedAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"secret":{"type":"string","description":"The full key (sk_live_... or sk_test_...). Shown only in this response: store it."}},"required":["id","name","prefix","createdAt","lastUsedAt","revokedAt","secret"],"additionalProperties":false},"example":{"id":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","name":"WooCommerce","prefix":"sk_live_4f9a","createdAt":"2026-10-16T12:00:00.000Z","lastUsedAt":null,"revokedAt":null,"secret":"sk_live_4f9a2b7c1d8e3f6a0b5c9d2e7f1a4b8c3d6e0f9a"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_key_name`: The API key name is empty or too long.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_key_name":{"summary":"invalid_key_name","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_key_name","title":"invalid key name","status":422,"code":"invalid_key_name","detail":"The API key name is empty or too long."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Your label for the key, e.g. \"WooCommerce\"."}},"required":["name"],"additionalProperties":false},"example":{"name":"WooCommerce"}}}}}},"/v1/stores/{storeId}/api-keys/{keyId}":{"delete":{"operationId":"deleteV1StoresBystoreIdApiKeysBykeyId","summary":"Revoke an API key","description":"The key stops working at once. Revoking is permanent; create a new key instead of reusing it.","tags":["API keys"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"204":{"description":"Done, no content."},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"keyId","in":"path","required":true,"description":"API key id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"API key id (UUID)."}}]}},"/v1/invoices":{"post":{"operationId":"postV1Invoices","summary":"Create an invoice","description":"Creates an invoice for the store the API key belongs to and returns its deposit addresses and the hosted payment page (checkoutUrl). Send the buyer to checkoutUrl, then wait for the webhook.\n\nSend an **Idempotency-Key** header (printable ASCII, up to 255 characters, e.g. your order id) to retry safely: the same key with the same body returns the first invoice with replayed: true; the same key with a different body is a conflict.","tags":["Invoices"],"security":[{"apiKey":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Invoice id (UUID)."},"storeId":{"type":"string","description":"Store id (UUID)."},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"],"description":"Lifecycle status; see the payment flow in the docs."},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount to pay in US cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform fee for this invoice in basis points (50 is 0.5%), fixed at creation."},"invoiceSalt":{"type":"string","description":"Salt of the deposit address. With payoutAddress and feeBps it lets anyone recover funds through the factory contract."},"payoutAddress":{"type":"string","description":"Wallet the funds are forwarded to, fixed at creation."},"externalReference":{"description":"Your order id, if given.","type":["string","null"]},"returnUrl":{"description":"Where the buyer returns after paying.","type":["string","null"]},"expiresAt":{"type":"string","description":"After this moment new payments mark the invoice paid_late instead of paid."},"paidAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"holdReason":{"description":"Why the invoice is on_hold (sanctions screening), otherwise null.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"depositAddresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"}},"required":["network","address"],"additionalProperties":false},"description":"One unique address per enabled network."},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment id (UUID)."},"network":{"type":"string","description":"Network key."},"token":{"type":"string","description":"Token symbol, e.g. USDC."},"amount":{"type":"string","description":"Received amount in the token's smallest units (6 decimals for USDC: \"19990000\" is 19.99)."},"txHash":{"type":"string","description":"Transaction hash of the transfer."},"status":{"type":"string","enum":["detected","confirmed"],"description":"detected: seen on chain; confirmed: enough confirmations."},"screeningStatus":{"type":"string","enum":["pending","clear","flagged","provider_error"],"description":"Sanctions screening of the sender."},"detectedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","network","token","amount","txHash","status","screeningStatus","detectedAt"],"additionalProperties":false}},"checkoutUrl":{"type":"string","description":"Hosted payment page to send the buyer to."},"unavailableNetworks":{"type":"array","items":{"type":"string"},"description":"Enabled networks left out of this invoice because they are degraded right now."},"replayed":{"type":"boolean","description":"true when the Idempotency-Key matched an earlier request and that invoice is returned."}},"required":["id","storeId","status","amountUsdCents","feeBps","invoiceSalt","payoutAddress","externalReference","returnUrl","expiresAt","paidAt","holdReason","createdAt","depositAddresses","payments","checkoutUrl","unavailableNetworks","replayed"],"additionalProperties":false},"example":{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeId":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","status":"awaiting_payment","amountUsdCents":1999,"feeBps":50,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/","expiresAt":"2026-10-16T13:00:00.000Z","paidAt":null,"holdReason":null,"createdAt":"2026-10-16T12:00:00.000Z","depositAddresses":[{"network":"base","address":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B"},{"network":"arbitrum","address":"0x9F8e7d6c5B4a39281706F5e4d3C2B1A0f9E8d7c6"}],"payments":[],"checkoutUrl":"https://stablevoy.com/pay/?i=0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","unavailableNetworks":[],"replayed":false}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"409":{"description":"`conflict`: The Idempotency-Key was already used with different parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"conflict","value":{"type":"https://stablevoy.com/docs/api/errors/#error-conflict","title":"conflict","status":409,"code":"conflict","detail":"The Idempotency-Key was already used with different parameters."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_amount`: The amount is not a positive whole number of US cents.\n\n`amount_below_minimum`: The amount is below the store minimum or the platform minimum. limitUsdCents is the minimum that applies.\n\n`amount_above_store_limit`: The amount is above the maximum set for this store. limitUsdCents is that maximum.\n\n`amount_above_platform_cap`: The amount is above the platform cap per invoice. limitUsdCents is the cap.\n\n`invalid_external_reference`: The external reference (your order id) is empty or too long.\n\n`invalid_return_url`: The return URL is not an absolute https URL without credentials, or is too long.\n\n`store_disabled`: The store is disabled and cannot create invoices.\n\n`payout_address_not_set`: The account has no payout address yet, so payments would have nowhere to go.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_amount":{"summary":"invalid_amount","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_amount","title":"invalid amount","status":422,"code":"invalid_amount","detail":"The amount is not a positive whole number of US cents."}},"amount_below_minimum":{"summary":"amount_below_minimum","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_below_minimum","title":"amount below minimum","status":422,"code":"amount_below_minimum","detail":"The amount is below the store minimum or the platform minimum. limitUsdCents is the minimum that applies."}},"amount_above_store_limit":{"summary":"amount_above_store_limit","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_above_store_limit","title":"amount above store limit","status":422,"code":"amount_above_store_limit","detail":"The amount is above the maximum set for this store. limitUsdCents is that maximum."}},"amount_above_platform_cap":{"summary":"amount_above_platform_cap","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_above_platform_cap","title":"amount above platform cap","status":422,"code":"amount_above_platform_cap","detail":"The amount is above the platform cap per invoice. limitUsdCents is the cap."}},"invalid_external_reference":{"summary":"invalid_external_reference","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_external_reference","title":"invalid external reference","status":422,"code":"invalid_external_reference","detail":"The external reference (your order id) is empty or too long."}},"invalid_return_url":{"summary":"invalid_return_url","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_return_url","title":"invalid return url","status":422,"code":"invalid_return_url","detail":"The return URL is not an absolute https URL without credentials, or is too long."}},"store_disabled":{"summary":"store_disabled","value":{"type":"https://stablevoy.com/docs/api/errors/#error-store_disabled","title":"store disabled","status":422,"code":"store_disabled","detail":"The store is disabled and cannot create invoices."}},"payout_address_not_set":{"summary":"payout_address_not_set","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payout_address_not_set","title":"payout address not set","status":422,"code":"payout_address_not_set","detail":"The account has no payout address yet, so payments would have nowhere to go."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}},"503":{"description":"`networks_unavailable`: Every network enabled for the store is degraded right now, so a payment could not be watched safely.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"networks_unavailable":{"summary":"networks_unavailable","value":{"type":"https://stablevoy.com/docs/api/errors/#error-networks_unavailable","title":"networks unavailable","status":503,"code":"networks_unavailable","detail":"Every network enabled for the store is degraded right now, so a payment could not be watched safely."}}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe: the same key and body return the first invoice. Printable ASCII, up to 255 characters.","schema":{"type":"string"},"example":"order-1042"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"amountUsdCents":{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in US cents, a positive integer: 1999 is $19.99."},"externalReference":{"description":"Your order id, 1 to 200 characters. Sent back in webhooks.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"returnUrl":{"description":"https URL the buyer goes back to after paying. Overrides the store default.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]}},"required":["amountUsdCents"],"additionalProperties":false},"example":{"amountUsdCents":1999,"externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/"}}}}},"get":{"operationId":"getV1Invoices","summary":"List invoices","description":"Invoices of the API key's store, newest first, optionally filtered by status. Pages are cursor based: pass nextCursor as cursor until it is null.","tags":["Invoices"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Invoice id (UUID)."},"storeId":{"type":"string","description":"Store id (UUID)."},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"],"description":"Lifecycle status; see the payment flow in the docs."},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount to pay in US cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform fee for this invoice in basis points (50 is 0.5%), fixed at creation."},"invoiceSalt":{"type":"string","description":"Salt of the deposit address. With payoutAddress and feeBps it lets anyone recover funds through the factory contract."},"payoutAddress":{"type":"string","description":"Wallet the funds are forwarded to, fixed at creation."},"externalReference":{"description":"Your order id, if given.","type":["string","null"]},"returnUrl":{"description":"Where the buyer returns after paying.","type":["string","null"]},"expiresAt":{"type":"string","description":"After this moment new payments mark the invoice paid_late instead of paid."},"paidAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"holdReason":{"description":"Why the invoice is on_hold (sanctions screening), otherwise null.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"depositAddresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"}},"required":["network","address"],"additionalProperties":false},"description":"One unique address per enabled network."},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment id (UUID)."},"network":{"type":"string","description":"Network key."},"token":{"type":"string","description":"Token symbol, e.g. USDC."},"amount":{"type":"string","description":"Received amount in the token's smallest units (6 decimals for USDC: \"19990000\" is 19.99)."},"txHash":{"type":"string","description":"Transaction hash of the transfer."},"status":{"type":"string","enum":["detected","confirmed"],"description":"detected: seen on chain; confirmed: enough confirmations."},"screeningStatus":{"type":"string","enum":["pending","clear","flagged","provider_error"],"description":"Sanctions screening of the sender."},"detectedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","network","token","amount","txHash","status","screeningStatus","detectedAt"],"additionalProperties":false}}},"required":["id","storeId","status","amountUsdCents","feeBps","invoiceSalt","payoutAddress","externalReference","returnUrl","expiresAt","paidAt","holdReason","createdAt","depositAddresses","payments"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]}},"required":["items","nextCursor"],"additionalProperties":false},"example":{"items":[{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeId":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","status":"awaiting_payment","amountUsdCents":1999,"feeBps":50,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/","expiresAt":"2026-10-16T13:00:00.000Z","paidAt":null,"holdReason":null,"createdAt":"2026-10-16T12:00:00.000Z","depositAddresses":[{"network":"base","address":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B"},{"network":"arbitrum","address":"0x9F8e7d6c5B4a39281706F5e4d3C2B1A0f9E8d7c6"}],"payments":[]}],"nextCursor":null}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"limit","in":"query","required":true,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size, 1 to 100."}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"description":"nextCursor from the previous page.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"}},{"name":"status","in":"query","required":false,"description":"Only invoices in this status.","schema":{"description":"Only invoices in this status.","type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"]}}]}},"/v1/stores/{storeId}/invoices":{"post":{"operationId":"postV1StoresBystoreIdInvoices","summary":"Create an invoice for a store (dashboard)","description":"The same as POST /v1/invoices, for a signed-in merchant choosing the store, e.g. payment links made in the dashboard. Supports Idempotency-Key the same way.","tags":["Invoices"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Invoice id (UUID)."},"storeId":{"type":"string","description":"Store id (UUID)."},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"],"description":"Lifecycle status; see the payment flow in the docs."},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount to pay in US cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform fee for this invoice in basis points (50 is 0.5%), fixed at creation."},"invoiceSalt":{"type":"string","description":"Salt of the deposit address. With payoutAddress and feeBps it lets anyone recover funds through the factory contract."},"payoutAddress":{"type":"string","description":"Wallet the funds are forwarded to, fixed at creation."},"externalReference":{"description":"Your order id, if given.","type":["string","null"]},"returnUrl":{"description":"Where the buyer returns after paying.","type":["string","null"]},"expiresAt":{"type":"string","description":"After this moment new payments mark the invoice paid_late instead of paid."},"paidAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"holdReason":{"description":"Why the invoice is on_hold (sanctions screening), otherwise null.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"depositAddresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"}},"required":["network","address"],"additionalProperties":false},"description":"One unique address per enabled network."},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment id (UUID)."},"network":{"type":"string","description":"Network key."},"token":{"type":"string","description":"Token symbol, e.g. USDC."},"amount":{"type":"string","description":"Received amount in the token's smallest units (6 decimals for USDC: \"19990000\" is 19.99)."},"txHash":{"type":"string","description":"Transaction hash of the transfer."},"status":{"type":"string","enum":["detected","confirmed"],"description":"detected: seen on chain; confirmed: enough confirmations."},"screeningStatus":{"type":"string","enum":["pending","clear","flagged","provider_error"],"description":"Sanctions screening of the sender."},"detectedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","network","token","amount","txHash","status","screeningStatus","detectedAt"],"additionalProperties":false}},"checkoutUrl":{"type":"string","description":"Hosted payment page to send the buyer to."},"unavailableNetworks":{"type":"array","items":{"type":"string"},"description":"Enabled networks left out of this invoice because they are degraded right now."},"replayed":{"type":"boolean","description":"true when the Idempotency-Key matched an earlier request and that invoice is returned."}},"required":["id","storeId","status","amountUsdCents","feeBps","invoiceSalt","payoutAddress","externalReference","returnUrl","expiresAt","paidAt","holdReason","createdAt","depositAddresses","payments","checkoutUrl","unavailableNetworks","replayed"],"additionalProperties":false},"example":{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeId":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","status":"awaiting_payment","amountUsdCents":1999,"feeBps":50,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/","expiresAt":"2026-10-16T13:00:00.000Z","paidAt":null,"holdReason":null,"createdAt":"2026-10-16T12:00:00.000Z","depositAddresses":[{"network":"base","address":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B"},{"network":"arbitrum","address":"0x9F8e7d6c5B4a39281706F5e4d3C2B1A0f9E8d7c6"}],"payments":[],"checkoutUrl":"https://stablevoy.com/pay/?i=0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","unavailableNetworks":[],"replayed":false}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.\n\n`bad_request`: The request could not be read, for example malformed JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}},"bad_request":{"summary":"bad_request","value":{"type":"https://stablevoy.com/docs/api/errors/#error-bad_request","title":"bad request","status":400,"code":"bad_request","detail":"The request could not be read, for example malformed JSON."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"409":{"description":"`conflict`: The Idempotency-Key was already used with different parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"conflict","value":{"type":"https://stablevoy.com/docs/api/errors/#error-conflict","title":"conflict","status":409,"code":"conflict","detail":"The Idempotency-Key was already used with different parameters."}}}}}},"413":{"description":"`payload_too_large`: The request body is larger than the API accepts (64 KB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payload_too_large","title":"payload too large","status":413,"code":"payload_too_large","detail":"The request body is larger than the API accepts (64 KB)."}}}}}},"415":{"description":"`unsupported_media_type`: The body is not JSON.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"summary":"unsupported_media_type","value":{"type":"https://stablevoy.com/docs/api/errors/#error-unsupported_media_type","title":"unsupported media type","status":415,"code":"unsupported_media_type","detail":"The body is not JSON."}}}}}},"422":{"description":"`invalid_amount`: The amount is not a positive whole number of US cents.\n\n`amount_below_minimum`: The amount is below the store minimum or the platform minimum. limitUsdCents is the minimum that applies.\n\n`amount_above_store_limit`: The amount is above the maximum set for this store. limitUsdCents is that maximum.\n\n`amount_above_platform_cap`: The amount is above the platform cap per invoice. limitUsdCents is the cap.\n\n`invalid_external_reference`: The external reference (your order id) is empty or too long.\n\n`invalid_return_url`: The return URL is not an absolute https URL without credentials, or is too long.\n\n`store_disabled`: The store is disabled and cannot create invoices.\n\n`payout_address_not_set`: The account has no payout address yet, so payments would have nowhere to go.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_amount":{"summary":"invalid_amount","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_amount","title":"invalid amount","status":422,"code":"invalid_amount","detail":"The amount is not a positive whole number of US cents."}},"amount_below_minimum":{"summary":"amount_below_minimum","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_below_minimum","title":"amount below minimum","status":422,"code":"amount_below_minimum","detail":"The amount is below the store minimum or the platform minimum. limitUsdCents is the minimum that applies."}},"amount_above_store_limit":{"summary":"amount_above_store_limit","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_above_store_limit","title":"amount above store limit","status":422,"code":"amount_above_store_limit","detail":"The amount is above the maximum set for this store. limitUsdCents is that maximum."}},"amount_above_platform_cap":{"summary":"amount_above_platform_cap","value":{"type":"https://stablevoy.com/docs/api/errors/#error-amount_above_platform_cap","title":"amount above platform cap","status":422,"code":"amount_above_platform_cap","detail":"The amount is above the platform cap per invoice. limitUsdCents is the cap."}},"invalid_external_reference":{"summary":"invalid_external_reference","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_external_reference","title":"invalid external reference","status":422,"code":"invalid_external_reference","detail":"The external reference (your order id) is empty or too long."}},"invalid_return_url":{"summary":"invalid_return_url","value":{"type":"https://stablevoy.com/docs/api/errors/#error-invalid_return_url","title":"invalid return url","status":422,"code":"invalid_return_url","detail":"The return URL is not an absolute https URL without credentials, or is too long."}},"store_disabled":{"summary":"store_disabled","value":{"type":"https://stablevoy.com/docs/api/errors/#error-store_disabled","title":"store disabled","status":422,"code":"store_disabled","detail":"The store is disabled and cannot create invoices."}},"payout_address_not_set":{"summary":"payout_address_not_set","value":{"type":"https://stablevoy.com/docs/api/errors/#error-payout_address_not_set","title":"payout address not set","status":422,"code":"payout_address_not_set","detail":"The account has no payout address yet, so payments would have nowhere to go."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}},"503":{"description":"`networks_unavailable`: Every network enabled for the store is degraded right now, so a payment could not be watched safely.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"networks_unavailable":{"summary":"networks_unavailable","value":{"type":"https://stablevoy.com/docs/api/errors/#error-networks_unavailable","title":"networks unavailable","status":503,"code":"networks_unavailable","detail":"Every network enabled for the store is degraded right now, so a payment could not be watched safely."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes retries safe: the same key and body return the first invoice. Printable ASCII, up to 255 characters.","schema":{"type":"string"},"example":"order-1042"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"amountUsdCents":{"type":"integer","exclusiveMinimum":0,"maximum":100000000000,"description":"Amount in US cents, a positive integer: 1999 is $19.99."},"externalReference":{"description":"Your order id, 1 to 200 characters. Sent back in webhooks.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"returnUrl":{"description":"https URL the buyer goes back to after paying. Overrides the store default.","anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]}},"required":["amountUsdCents"],"additionalProperties":false},"example":{"amountUsdCents":1999,"externalReference":null,"returnUrl":null}}}}},"get":{"operationId":"getV1StoresBystoreIdInvoices","summary":"List invoices of a store (dashboard)","description":"The same as GET /v1/invoices, for a signed-in merchant choosing the store.","tags":["Invoices"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Invoice id (UUID)."},"storeId":{"type":"string","description":"Store id (UUID)."},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"],"description":"Lifecycle status; see the payment flow in the docs."},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount to pay in US cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform fee for this invoice in basis points (50 is 0.5%), fixed at creation."},"invoiceSalt":{"type":"string","description":"Salt of the deposit address. With payoutAddress and feeBps it lets anyone recover funds through the factory contract."},"payoutAddress":{"type":"string","description":"Wallet the funds are forwarded to, fixed at creation."},"externalReference":{"description":"Your order id, if given.","type":["string","null"]},"returnUrl":{"description":"Where the buyer returns after paying.","type":["string","null"]},"expiresAt":{"type":"string","description":"After this moment new payments mark the invoice paid_late instead of paid."},"paidAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"holdReason":{"description":"Why the invoice is on_hold (sanctions screening), otherwise null.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"depositAddresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"}},"required":["network","address"],"additionalProperties":false},"description":"One unique address per enabled network."},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment id (UUID)."},"network":{"type":"string","description":"Network key."},"token":{"type":"string","description":"Token symbol, e.g. USDC."},"amount":{"type":"string","description":"Received amount in the token's smallest units (6 decimals for USDC: \"19990000\" is 19.99)."},"txHash":{"type":"string","description":"Transaction hash of the transfer."},"status":{"type":"string","enum":["detected","confirmed"],"description":"detected: seen on chain; confirmed: enough confirmations."},"screeningStatus":{"type":"string","enum":["pending","clear","flagged","provider_error"],"description":"Sanctions screening of the sender."},"detectedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","network","token","amount","txHash","status","screeningStatus","detectedAt"],"additionalProperties":false}}},"required":["id","storeId","status","amountUsdCents","feeBps","invoiceSalt","payoutAddress","externalReference","returnUrl","expiresAt","paidAt","holdReason","createdAt","depositAddresses","payments"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]}},"required":["items","nextCursor"],"additionalProperties":false},"example":{"items":[{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeId":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","status":"awaiting_payment","amountUsdCents":1999,"feeBps":50,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/","expiresAt":"2026-10-16T13:00:00.000Z","paidAt":null,"holdReason":null,"createdAt":"2026-10-16T12:00:00.000Z","depositAddresses":[{"network":"base","address":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B"},{"network":"arbitrum","address":"0x9F8e7d6c5B4a39281706F5e4d3C2B1A0f9E8d7c6"}],"payments":[]}],"nextCursor":null}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"limit","in":"query","required":true,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size, 1 to 100."}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"description":"nextCursor from the previous page.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"}},{"name":"status","in":"query","required":false,"description":"Only invoices in this status.","schema":{"description":"Only invoices in this status.","type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"]}}]}},"/v1/invoices/{invoiceId}":{"get":{"operationId":"getV1InvoicesByinvoiceId","summary":"Get an invoice","description":"One invoice with its deposit addresses and every payment received. Use it to double-check a webhook before fulfilling an order.","tags":["Invoices"],"security":[{"apiKey":[]},{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Invoice id (UUID)."},"storeId":{"type":"string","description":"Store id (UUID)."},"status":{"type":"string","enum":["awaiting_payment","confirming","paid","overpaid","underpaid","expired","paid_late","on_hold"],"description":"Lifecycle status; see the payment flow in the docs."},"amountUsdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount to pay in US cents."},"feeBps":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Platform fee for this invoice in basis points (50 is 0.5%), fixed at creation."},"invoiceSalt":{"type":"string","description":"Salt of the deposit address. With payoutAddress and feeBps it lets anyone recover funds through the factory contract."},"payoutAddress":{"type":"string","description":"Wallet the funds are forwarded to, fixed at creation."},"externalReference":{"description":"Your order id, if given.","type":["string","null"]},"returnUrl":{"description":"Where the buyer returns after paying.","type":["string","null"]},"expiresAt":{"type":"string","description":"After this moment new payments mark the invoice paid_late instead of paid."},"paidAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp in UTC."},{"type":"null"}]},"holdReason":{"description":"Why the invoice is on_hold (sanctions screening), otherwise null.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"depositAddresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"address":{"type":"string"}},"required":["network","address"],"additionalProperties":false},"description":"One unique address per enabled network."},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment id (UUID)."},"network":{"type":"string","description":"Network key."},"token":{"type":"string","description":"Token symbol, e.g. USDC."},"amount":{"type":"string","description":"Received amount in the token's smallest units (6 decimals for USDC: \"19990000\" is 19.99)."},"txHash":{"type":"string","description":"Transaction hash of the transfer."},"status":{"type":"string","enum":["detected","confirmed"],"description":"detected: seen on chain; confirmed: enough confirmations."},"screeningStatus":{"type":"string","enum":["pending","clear","flagged","provider_error"],"description":"Sanctions screening of the sender."},"detectedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["id","network","token","amount","txHash","status","screeningStatus","detectedAt"],"additionalProperties":false}}},"required":["id","storeId","status","amountUsdCents","feeBps","invoiceSalt","payoutAddress","externalReference","returnUrl","expiresAt","paidAt","holdReason","createdAt","depositAddresses","payments"],"additionalProperties":false},"example":{"id":"0b7e2f4c-8d1a-4c3b-9e5f-1a2b3c4d5e6f","storeId":"6f1c2b8e-3a4d-4e5f-9a1b-2c3d4e5f6a7b","status":"awaiting_payment","amountUsdCents":1999,"feeBps":50,"invoiceSalt":"0x8f3a1c2b4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8","payoutAddress":"0x5cC5bc5CC5bC5CC5bC5cc5bC5cC5bc5cc5Bc5cc5","externalReference":"order-1042","returnUrl":"https://shop.example/checkout/order-received/1042/","expiresAt":"2026-10-16T13:00:00.000Z","paidAt":null,"holdReason":null,"createdAt":"2026-10-16T12:00:00.000Z","depositAddresses":[{"network":"base","address":"0x1a2b3C4d5e6F7A8B9c0D1e2f3A4B5c6d7e8F9A0B"},{"network":"arbitrum","address":"0x9F8e7d6c5B4a39281706F5e4d3C2B1A0f9E8d7c6"}],"payments":[]}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"description":"Invoice id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Invoice id (UUID)."}}]}},"/v1/stores/{storeId}/webhook/test":{"post":{"operationId":"postV1StoresBystoreIdWebhookTest","summary":"Send a test webhook","description":"Queues a webhook.test event that goes through the real delivery path (signature, retries). Check its delivery with the events endpoints.","tags":["Webhooks"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"eventId":{"type":"string","description":"Id of the queued webhook.test event."}},"required":["eventId"],"additionalProperties":false},"example":{"eventId":"e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9"}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"422":{"description":"`webhook_not_configured`: The action needs a webhook URL and the store has none.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"webhook_not_configured":{"summary":"webhook_not_configured","value":{"type":"https://stablevoy.com/docs/api/errors/#error-webhook_not_configured","title":"webhook not configured","status":422,"code":"webhook_not_configured","detail":"The action needs a webhook URL and the store has none."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}}]}},"/v1/stores/{storeId}/webhook-events":{"get":{"operationId":"getV1StoresBystoreIdWebhookEvents","summary":"List webhook events","description":"Events of the store with their delivery status, newest first, cursor paged.","tags":["Webhooks"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Event id (UUID), also sent in the webhook body. Use it to ignore duplicates."},"type":{"type":"string","enum":["invoice.paid","invoice.overpaid","invoice.underpaid","invoice.expired","invoice.paid_late","invoice.on_hold","webhook.test"]},"deliveryStatus":{"type":"string","enum":["pending","delivered","failed"],"description":"failed: every retry was used up; redeliver to try again."},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextAttemptAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"lastError":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"deliveries":{"description":"Every attempt; only on the single event endpoint.","type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"HTTP status your endpoint answered; null when it could not be reached."},"error":{"type":["string","null"]},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attemptedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["attempt","statusCode","error","durationMs","attemptedAt"],"additionalProperties":false}}},"required":["id","type","deliveryStatus","attempts","nextAttemptAt","lastError","createdAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]}},"required":["items","nextCursor"],"additionalProperties":false},"example":{"items":[{"id":"e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9","type":"invoice.paid","deliveryStatus":"delivered","attempts":1,"nextAttemptAt":"2026-10-16T12:00:00.000Z","lastError":null,"createdAt":"2026-10-16T12:00:00.000Z"}],"nextCursor":null}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"limit","in":"query","required":true,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"description":"Page size, 1 to 100."}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"description":"nextCursor from the previous page.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$"}}]}},"/v1/stores/{storeId}/webhook-events/{eventId}":{"get":{"operationId":"getV1StoresBystoreIdWebhookEventsByeventId","summary":"Get a webhook event","description":"One event with every delivery attempt: the status your endpoint answered, the error and how long it took.","tags":["Webhooks"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Event id (UUID), also sent in the webhook body. Use it to ignore duplicates."},"type":{"type":"string","enum":["invoice.paid","invoice.overpaid","invoice.underpaid","invoice.expired","invoice.paid_late","invoice.on_hold","webhook.test"]},"deliveryStatus":{"type":"string","enum":["pending","delivered","failed"],"description":"failed: every retry was used up; redeliver to try again."},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"nextAttemptAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"lastError":{"type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp in UTC."},"deliveries":{"description":"Every attempt; only on the single event endpoint.","type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"statusCode":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"HTTP status your endpoint answered; null when it could not be reached."},"error":{"type":["string","null"]},"durationMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attemptedAt":{"type":"string","description":"ISO 8601 timestamp in UTC."}},"required":["attempt","statusCode","error","durationMs","attemptedAt"],"additionalProperties":false}}},"required":["id","type","deliveryStatus","attempts","nextAttemptAt","lastError","createdAt"],"additionalProperties":false},"example":{"id":"e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9","type":"invoice.paid","deliveryStatus":"delivered","attempts":1,"nextAttemptAt":"2026-10-16T12:00:00.000Z","lastError":null,"createdAt":"2026-10-16T12:00:00.000Z","deliveries":[{"attempt":1,"statusCode":200,"error":null,"durationMs":182,"attemptedAt":"2026-10-16T12:00:01.000Z"}]}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"eventId","in":"path","required":true,"description":"Webhook event id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Webhook event id (UUID)."}}]}},"/v1/stores/{storeId}/webhook-events/{eventId}/redeliver":{"post":{"operationId":"postV1StoresBystoreIdWebhookEventsByeventIdRedeliver","summary":"Redeliver a webhook event","description":"Queues the event for delivery again, for example after fixing your endpoint. Your handler should ignore events it has already processed (by event id).","tags":["Webhooks"],"security":[{"merchantBearer":[]},{"merchantCookie":[]}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"queued":{"type":"boolean","const":true}},"required":["queued"],"additionalProperties":false},"example":{"queued":true}}}},"400":{"description":"`validation_failed`: The request body, query or path does not match the schema. The issues list names each field and the problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"summary":"validation_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-validation_failed","title":"validation failed","status":400,"code":"validation_failed","detail":"The request body, query or path does not match the schema. The issues list names each field and the problem."}}}}}},"401":{"description":"`authentication_failed`: The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"authentication_failed":{"summary":"authentication_failed","value":{"type":"https://stablevoy.com/docs/api/errors/#error-authentication_failed","title":"authentication failed","status":401,"code":"authentication_failed","detail":"The API key, session or wallet signature is missing, invalid, expired or not allowed for this endpoint. The detail says which."}}}}}},"404":{"description":"`not_found`: The resource or endpoint does not exist, or belongs to another account (we never reveal which).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"not_found","value":{"type":"https://stablevoy.com/docs/api/errors/#error-not_found","title":"not found","status":404,"code":"not_found","detail":"The resource or endpoint does not exist, or belongs to another account (we never reveal which)."}}}}}},"429":{"description":"`rate_limited`: Too many requests from this client in a short time.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"type":"https://stablevoy.com/docs/api/errors/#error-rate_limited","title":"rate limited","status":429,"code":"rate_limited","detail":"Too many requests from this client in a short time."}}}}}},"500":{"description":"`internal_error`: Something failed on our side. The error was logged and we are alerted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal_error":{"summary":"internal_error","value":{"type":"https://stablevoy.com/docs/api/errors/#error-internal_error","title":"internal error","status":500,"code":"internal_error","detail":"Something failed on our side. The error was logged and we are alerted."}}}}}}},"parameters":[{"name":"storeId","in":"path","required":true,"description":"Store id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Store id (UUID)."}},{"name":"eventId","in":"path","required":true,"description":"Webhook event id (UUID).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"Webhook event id (UUID)."}}]}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Store API key: Authorization: Bearer sk_live_... (sk_test_... on testnets)."},"merchantBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token from /v1/auth/siwe/verify, for apps."},"merchantCookie":{"type":"apiKey","in":"cookie","name":"svy_at","description":"Browser session cookie set by /v1/auth/siwe/verify."}},"schemas":{"Problem":{"type":"object","description":"RFC 7807 problem document. Branch on code; show detail to people.","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string","description":"Link to this code in the error catalog."},"title":{"type":"string"},"status":{"type":"integer","description":"The HTTP status, repeated."},"code":{"type":"string","enum":["authentication_failed","unsupported_chain","validation_failed","bad_request","payload_too_large","unsupported_media_type","invalid_address","invalid_amount","amount_below_minimum","amount_above_store_limit","amount_above_platform_cap","invalid_external_reference","invalid_return_url","conflict","store_disabled","invalid_store_name","store_limit_reached","no_networks","invalid_limits","invalid_website_url","invalid_webhook_url","webhook_not_configured","invalid_key_name","payout_address_not_set","address_not_checksummed","unsupported_network","unsupported_token","networks_unavailable","invalid_contact_topic","invalid_contact_name","invalid_contact_email","invalid_contact_message","human_check_failed","human_check_unavailable","not_found","rate_limited","internal_error","invalid_fee","invalid_fee_config","invalid_retry_policy","invalid_store_quota","invalid_ttl","no_networks_configured","no_tokens_configured","no_public_rpc","duplicate_network","invalid_state_transition","screening_unavailable","invalid_bytes32"],"description":"Stable, machine-readable error code."},"detail":{"type":"string","description":"What went wrong, readable by people."},"limitUsdCents":{"type":"integer","description":"Only for amount errors: the limit that applies, in cents."},"issues":{"type":"array","description":"Only for validation_failed: one entry per invalid field.","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}}}}}}