{ "openapi": "3.1.0", "info": { "title": "Coinvay Merchant API", "version": "1.2.0", "description": "Non-custodial crypto payment integration. Public checkout and documentation are available at https://coinvay.com; merchant records require authentication. Keep API keys and webhook secrets on your backend. No cross-origin browser API integration is provided. Features/limits are administrator-configurable. This is the merchant integration reference, not the internal account-security, key-issuance, billing or admin API." }, "servers": [ { "url": "/", "description": "The origin hosting this reference." } ], "tags": [ { "name": "Invoices" }, { "name": "Checkout" }, { "name": "Merchant configuration" }, { "name": "Customer subscriptions" }, { "name": "Operations" } ], "paths": { "/api/connect/requests": { "post": { "operationId": "startStoreConnection", "summary": "Start store account connection", "description": "Backend-initiated, ten-minute authorization request. Requires a random installation ID, state and S256 PKCE. Store, callback and webhook must have the same public HTTPS origin. Redirect the administrator to the returned authorizationPath. Signing in alone never issues credentials; explicit interactive authorization is required. See /store-connect.md.", "tags": [ "Store connections" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Store name, up to 100 characters" }, "storeUrl": { "type": "string", "description": "Public HTTPS store/backend URL" }, "installation": { "type": "string", "description": "Stable random installation ID, 32–128 URL-safe characters" }, "redirectUri": { "type": "string", "description": "Exact HTTPS backend callback" }, "webhookUrl": { "type": "string", "description": "Optional same-origin HTTPS payment webhook" }, "state": { "type": "string", "description": "Random state bound to initiating administrator session" }, "codeChallenge": { "type": "string", "description": "43-character base64url SHA-256 PKCE challenge" }, "codeChallengeMethod": { "type": "string", "enum": [ "S256" ] } }, "required": [ "name", "storeUrl", "installation", "redirectUri", "state", "codeChallenge", "codeChallengeMethod" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Opaque request ID" }, "authorizationPath": { "type": "string", "description": "Coinvay authorization path" }, "expires": { "type": "string", "description": "ISO expiry" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connect/requests/{requestId}": { "get": { "operationId": "reviewStoreConnection", "summary": "Review connection request", "description": "Nonsecret store origin, requested permissions and callback. Expired or handled requests return 410. Approve or deny through the signed-in Coinvay review screen; a merchant API key cannot grant permission.", "tags": [ "Store connections" ], "security": [], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connect/token": { "post": { "operationId": "exchangeStoreConnection", "summary": "Exchange store authorization code", "description": "Backend only. Validate state against the initiating session before exchanging the single-use code with its PKCE verifier and exact redirect URI. Returns a store-limited API key and per-store webhook signing secret. Encrypt them locally; never expose or log the response. Existing plan active-key limits apply. Reconnecting the same installation rotates credentials while preserving its store ID.", "tags": [ "Store connections" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Single-use 64-character code" }, "codeVerifier": { "type": "string", "description": "Original S256 verifier, 43–128 characters" }, "redirectUri": { "type": "string", "description": "Exact callback registered at start" } }, "required": [ "code", "codeVerifier", "redirectUri" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Store-scoped secret; shown once" }, "webhookSecret": { "type": "string", "description": "Store HMAC secret; shown once" }, "storeId": { "type": "string", "description": "Stable connected store ID" }, "scope": { "type": "string", "description": "Granted store scopes" }, "branding": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stores": { "get": { "operationId": "listStores", "summary": "List connected stores", "description": "Owner-level merchant API key or signed-in account required. Store-limited keys cannot list other connections. Responses contain no secrets.", "tags": [ "Store connections" ], "security": [ { "MerchantKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stores/manual": { "post": { "operationId": "registerManualStore", "summary": "Register manual store setup", "description": "Full merchant API key or signed-in account required. Adds per-store branding and webhook without changing the merchant global settings. Returns a per-store signing secret; store it privately. The manual API key retains its existing full permissions.", "tags": [ "Store connections" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Store name" }, "storeUrl": { "type": "string", "description": "Public HTTPS store/backend URL" }, "installation": { "type": "string", "description": "Random installation ID" }, "webhookUrl": { "type": "string", "description": "Optional same-origin HTTPS webhook" } }, "required": [ "name", "storeUrl", "installation" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stores/{storeId}": { "get": { "operationId": "readStore", "summary": "Read owned store", "description": "Owner or that store’s scoped key only. Returns nonsecret connection status and branding.", "tags": [ "Store connections" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "disconnectStore", "summary": "Disconnect store", "description": "Revokes its scoped API keys and cancels queued store webhook deliveries. Existing invoices, payments and receiving wallets are preserved. Disconnecting a manual store does not revoke the merchant-wide key used elsewhere.", "tags": [ "Store connections" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stores/{storeId}/branding": { "post": { "operationId": "updateStoreBranding", "summary": "Set store checkout identity", "description": "Owner or that store’s scoped key and plan branding feature required. New invoices snapshot businessName/logo. Also accepts multipart/form-data businessName + logo (PNG/JPG/WebP up to 2 MB). Arbitrary logo URLs and SVG uploads are not accepted. Existing invoice identities and other stores remain unchanged.", "tags": [ "Store connections" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "description": "Name shown on this store checkout, up to 100 characters" }, "removeLogo": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "businessName": { "type": "string", "description": "Business name" }, "logo": { "type": "string", "format": "binary" } }, "required": [ "logo" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/currencies": { "get": { "operationId": "getCurrencies", "summary": "Supported order currencies", "description": "Fiat source currencies and ISO decimal precision. No full exchange-rate feed is exposed. Non-USD invoice creation uses a server-fetched Coinbase USD reference, cached for at most five minutes and rounded half up once to USD cents. Rate failure creates no invoice; existing invoices and USD remain payable.", "tags": [ "Invoices" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountingCurrency": { "type": "string", "enum": [ "USD" ] }, "currencies": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "summary": "Service health", "description": "Database connectivity and configured network names; separate from provider health.", "tags": [ "Operations" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "database": { "type": "string" }, "networks": { "type": "array", "items": { "type": "string" } } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/invoices": { "post": { "operationId": "createInvoice", "summary": "Create an invoice", "description": "Creates a merchant-owned invoice. Idempotency-Key is optional, merchant-scoped and persistent; only the first 150 characters are significant. Reusing it returns the original invoice even when the body changes. Use one key per intended order/renewal. Created invoices consume the UTC monthly plan allowance, including cancelled invoices.", "tags": [ "Invoices" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 150 }, "description": "Stable order-specific retry key." } ] }, "get": { "operationId": "listInvoices", "summary": "List invoices", "description": "Up to 1,000 newest invoices for this merchant. No pagination parameters. Use invoice-by-ID for a specific older invoice.", "tags": [ "Invoices" ], "security": [ { "MerchantKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "description": "Current status, accounting amount and order reference. Missing and other merchants' IDs return 404. Your backend can verify Paid before fulfillment.", "tags": [ "Invoices" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/invoices/{id}/cancel": { "post": { "operationId": "cancelInvoice", "summary": "Cancel an invoice", "description": "Only New invoices can be cancelled. Sends no refund and moves no crypto.", "tags": [ "Invoices" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/checkout/{token}": { "get": { "operationId": "getCheckout", "summary": "Read checkout", "description": "Checkout capability; no merchant key at application level. Hosting access still applies. Exposes enabled payment options and a public paid receipt, without customer email. Use signed webhooks or authenticated invoice lookup for fulfillment.", "tags": [ "Checkout" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/checkout/{token}/quote": { "post": { "operationId": "createQuote", "summary": "Create a payment quote", "description": "Locks exact token amount, recipient, asset and network for up to 20 minutes (Bitcoin: 120 minutes), bounded by invoice expiry. A sufficiently fresh matching quote may be reused. Send exactly the quoted amount on the quoted chain. Keep quantity as an integer string. Real merchant plan purchases reject testnet assets.", "tags": [ "Checkout" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Bitcoin", "Tron", "TON", "Ethereum", "BNB Chain", "Base", "Solana", "Polygon", "Arbitrum", "Optimism", "Avalanche", "Base Sepolia" ] }, "asset": { "type": "string", "enum": [ "ETH", "USDC", "USDT", "BNB", "SOL", "BTC", "TRX", "TON", "GRAM", "DAI", "PYUSD", "POL" ] } }, "required": [ "network", "asset" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/checkout/{token}/verify": { "post": { "operationId": "verifyCheckout", "summary": "Verify transaction evidence", "description": "Checks chain, successful canonical transfer, recipient, official asset, time window and confirmations. Merchant invoices accept small shortfalls by default only within both 10 basis points (0.1%) and USD 1 at the locked quote rate. Merchants may disable or adjust limits in Settings. Larger confirmed shortfalls return underpaid=true/status=Underpaid with actual, quoted and shortfall amounts and create no completed payment. Shortfalls ambiguous between invoices require review. Sandbox and Coinvay plan purchases remain exact-amount only. Accepted shortfalls produce Paid with acceptedShortfall=true and retain the actual quantity and invoiceAmount on receipts and signed webhooks. No top-up aggregation is performed. A hash alone is not proof of payment. Pending means wait. Repeated verification of an already-paid invoice may return only paid and a payment ID.", "tags": [ "Checkout" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "string", "description": "Quote ID." }, "hash": { "type": "string", "description": "EVM transaction hash, Bitcoin/Tron transaction ID, TON recipient transaction hash, or Solana signature." } }, "required": [ "quote", "hash" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/checkout/{token}/monitor": { "post": { "operationId": "monitorCheckout", "summary": "Monitor a payment quote", "description": "Scans for candidate transfers and verifies them. Hosted checkout polls about every 10 seconds. Stop on paid. Do not send new funds after quote expiry; a limited recovery scan may detect timely transfers.", "tags": [ "Checkout" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "string", "description": "Quote ID." } }, "required": [ "quote" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings": { "put": { "operationId": "updateSettings", "summary": "Configure webhook and branding", "description": "Update postback URL or business name. A webhook destination must be a public HTTPS hostname, without credentials or a custom port; local hosts and numeric IPs are rejected. Requires the relevant plan feature. Empty postback disables new notifications. Wallet changes require a signed ownership challenge, not this endpoint.", "tags": [ "Merchant configuration" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postback": { "type": "string", "description": "HTTPS destination, or empty string." }, "businessName": { "type": "string", "description": "Checkout name.", "maxLength": 100 } }, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "postback": { "type": "string" }, "businessName": { "type": "string" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/settings/webhook-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate signing secret", "description": "Returns a new webhook secret once. Rotation changes later attempts, including queued retries. Store on your backend separately from the API key; coordinate receiver deployment first. Requires webhooks.", "tags": [ "Merchant configuration" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks/{id}/retry": { "post": { "operationId": "retryWebhook", "summary": "Retry a delivery", "description": "Requires a merchant-owned delivery ID from bootstrap/hooks and webhook access. HTTP 200 describes the retry operation: inspect ok and error for delivery success. Redirects are not followed.", "tags": [ "Operations" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/monitor/tick": { "post": { "operationId": "tickMerchant", "summary": "Run merchant monitoring", "description": "Checks up to five pending merchant quotes and eligible webhook deliveries. Does not install a scheduler. An unattended platform runner uses a separate administrator secret.", "tags": [ "Operations" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object" } }, "webhooks": { "type": "integer" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bootstrap": { "get": { "operationId": "getWorkspace", "summary": "Read workspace data", "description": "Merchant invoices/payments/payouts (up to 1,000 each), subscriptions (up to 500), API-key metadata, recent webhook metadata (50), public settings, networks, plan and usage. Raw keys/signing secrets are not returned. Prefer invoice-by-ID for status polling.", "tags": [ "Operations" ], "security": [ { "MerchantKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "payments": { "type": "array", "items": { "type": "object" } }, "hooks": { "type": "array", "items": { "type": "object" } }, "settings": { "type": "object" }, "billing": { "type": "object" } }, "required": [], "additionalProperties": true } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/subscriptions/{id}/renew": { "post": { "operationId": "renewSubscription", "summary": "Create a renewal invoice", "description": "Requires an active customer subscription and recurring-invoice feature. Creates/reuses the period's renewal invoice. IDs are in bootstrap/subscriptions. Customers pay each invoice themselves; no automatic withdrawal.", "tags": [ "Customer subscriptions" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "summary": "Cancel a customer subscription", "description": "Stops a customer recurring-invoice record. Separate from the merchant's Free/Pro/Enterprise membership. No refund is sent.", "tags": [ "Customer subscriptions" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recurring": { "get": { "operationId": "listAutomaticSubscriptions", "summary": "List automatic subscriptions", "description": "Lists this merchant's fixed-token customer authorizations and separate token receipt history. See /automatic-billing.md for deployment and cancellation.", "tags": [ "Automatic subscriptions" ], "security": [ { "MerchantKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createAutomaticSubscription", "summary": "Create automatic subscription link", "description": "Requires the automatic-subscriptions plan feature, a verified receiving wallet and an enabled billing network. First payment is immediate; later cycles are UTC calendar months. Setup requires finite token approval and activation. This is separate from recurring invoices and merchant plan fees.", "tags": [ "Automatic subscriptions" ], "security": [ { "MerchantKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Customer-visible title", "maxLength": 120 }, "network": { "type": "string", "description": "Configured EVM network", "enum": [ "Ethereum", "Base", "Polygon", "BNB Chain", "Base Sepolia" ] }, "asset": { "type": "string", "description": "Supported ERC-20 token", "enum": [ "USDC", "USDT", "DAI", "PYUSD" ] }, "amount": { "type": "string", "description": "Decimal token amount, not USD" }, "maxPayments": { "type": "integer", "minimum": 1, "maximum": 120 } }, "required": [ "title", "network", "asset", "amount", "maxPayments" ], "additionalProperties": true } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recurring/{id}/close": { "post": { "operationId": "closeAutomaticSubscription", "summary": "Close unused subscription link", "description": "Only unused owner-scoped links can be closed off-chain. Active authorizations require a payer/recipient wallet cancellation.", "tags": [ "Automatic subscriptions" ], "security": [ { "MerchantKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recurring-checkout/{token}": { "get": { "operationId": "readAutomaticTerms", "summary": "Read customer subscription terms", "description": "Public capability link. Returns fixed terms, readiness and public on-chain identifiers; no email or secret.", "tags": [ "Automatic subscriptions" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recurring-checkout/{token}/prepare": { "post": { "operationId": "prepareAutomaticSubscription", "summary": "Prepare wallet authorization or cancellation", "description": "Builds transaction calldata only. The customer signs in their wallet. Cancellation requires the payer or merchant recipient wallet and works independently through the contract.", "tags": [ "Automatic subscriptions" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payer": { "type": "string", "description": "EVM wallet address" }, "action": { "type": "string", "description": "Omit for activation; cancel for cancellation", "enum": [ "cancel" ] } }, "required": [ "payer" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recurring-checkout/{token}/sync": { "post": { "operationId": "syncAutomaticSubscription", "summary": "Verify subscription and collection", "description": "Reads chain state at the required confirmation depth and optionally imports a matching Collected event. Pending authorization returns pending:true. Only Confirmed receipt status is payment evidence.", "tags": [ "Automatic subscriptions" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payer": { "type": "string", "description": "Payer EVM address" }, "tx": { "type": "string", "description": "Optional collection transaction hash" } }, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input or transaction evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Plan feature or allowance unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden, suspended or cross-origin request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Record unavailable to this merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict or missing wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; back off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider or server unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "MerchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "gw_live_…", "description": "Create in signed-in Integration. Cannot mint keys, manage billing or access admin. Separate from hosting authorization." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": true }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "InvoiceInput": { "type": "object", "properties": { "amount": { "description": "Trusted order amount in the supplied currency. Use a decimal string and its ISO minor-unit precision. Converted total must be 0.01–1,000,000 USD. USD retains its two-decimal contract.", "oneOf": [ { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,4})?$", "example": "19.95" }, { "type": "number", "exclusiveMinimum": 0 } ] }, "storeId": { "type": "string", "description": "Owned registered store ID for a manual key; automatic keys are bound to their own store. Branding is snapshotted and idempotency is isolated per store." }, "currency": { "type": "string", "description": "Supported source order currency; defaults to USD. Server converts non-USD prices once at invoice creation. GET /api/currencies lists supported codes and precision.", "enum": [ "AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SOS", "SRD", "SSP", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW" ], "default": "USD" }, "order": { "type": "string", "description": "Your order reference. Not automatically unique; use Idempotency-Key.", "maxLength": 150, "example": "ORDER-1001" }, "user": { "type": "string", "description": "Customer display name.", "maxLength": 120 }, "email": { "type": "string", "description": "Optional valid customer email.", "maxLength": 254 }, "memo": { "type": "string", "description": "Customer-visible instructions.", "maxLength": 2000 }, "recurrence": { "type": "string", "description": "Requires the recurring-invoice plan feature; no automatic wallet debit.", "enum": [ "None", "Daily", "Weekly", "Monthly", "Quarterly", "Yearly" ], "default": "None" }, "expiration": { "type": "string", "description": "Future ISO timestamp or YYYY-MM-DD (end of day UTC). Defaults to 30 days." }, "sendEmail": { "type": "boolean", "default": false, "description": "Requires customer email and configured mail. Inspect warning for a delivery failure after creation; the invoice may already exist." } }, "required": [ "amount" ], "additionalProperties": true }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice ID.", "example": "inv_example" }, "owner": { "type": "string", "description": "Merchant owner ID." }, "originalAmount": { "type": "string", "description": "Original store amount as an exact decimal string; present for non-USD source prices." }, "originalCurrency": { "type": "string", "description": "Original store currency; amount/currency remain the locked USD accounting total." }, "fx": { "type": "object", "properties": { "source": { "type": "string", "description": "Rate provider." }, "sourcePerUsd": { "type": "string", "description": "Original currency units per ONE USD. Divide source amount by this rate." }, "fetchedAt": { "type": "string", "description": "Time Coinvay fetched this indicative rate, not a provider trade timestamp.", "format": "date-time" }, "lockedAt": { "type": "string", "description": "Invoice pricing lock time.", "format": "date-time" }, "rounding": { "type": "string", "description": "USD cents, half up" } }, "required": [], "additionalProperties": true }, "token": { "type": "string", "description": "Checkout capability token; share only with the intended customer." }, "amount": { "type": "number", "description": "USD accounting amount.", "example": 19.95 }, "currency": { "type": "string", "enum": [ "USD" ] }, "order": { "type": "string", "description": "Your order reference." }, "user": { "type": "string", "description": "Customer name." }, "email": { "type": "string", "description": "Customer email." }, "memo": { "type": "string", "description": "Checkout instructions." }, "recurrence": { "type": "string", "description": "Requires the recurring-invoice plan feature; no automatic wallet debit.", "enum": [ "None", "Daily", "Weekly", "Monthly", "Quarterly", "Yearly" ], "default": "None" }, "sendEmail": { "type": "boolean" }, "status": { "type": "string", "enum": [ "New", "Paid", "Expired", "Cancelled" ] }, "time": { "type": "string", "description": "Creation time.", "format": "date-time" }, "expiration": { "type": [ "string", "null" ] }, "checkoutPath": { "type": "string", "description": "Relative hosted URL; resolve against the gateway origin.", "example": "/panel.html#/checkout/EXAMPLE_TOKEN" }, "warning": { "type": [ "string", "null" ], "description": "Optional email delivery warning on creation." } }, "required": [ "id", "owner", "token", "amount", "status", "checkoutPath" ], "additionalProperties": true }, "Checkout": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] }, "originalAmount": { "type": "string", "description": "Original store amount as an exact decimal string; present for non-USD source prices." }, "originalCurrency": { "type": "string", "description": "Original store currency; amount/currency remain the locked USD accounting total." }, "fx": { "type": "object", "properties": { "source": { "type": "string", "description": "Rate provider." }, "sourcePerUsd": { "type": "string", "description": "Original currency units per ONE USD. Divide source amount by this rate." }, "fetchedAt": { "type": "string", "description": "Time Coinvay fetched this indicative rate, not a provider trade timestamp.", "format": "date-time" }, "lockedAt": { "type": "string", "description": "Invoice pricing lock time.", "format": "date-time" }, "rounding": { "type": "string", "description": "USD cents, half up" } }, "required": [], "additionalProperties": true }, "order": { "type": "string" }, "memo": { "type": "string" }, "status": { "type": "string", "enum": [ "New", "Paid", "Expired", "Cancelled" ] }, "expiration": { "type": [ "string", "null" ] }, "businessName": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "planPurchase": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "asset": { "type": "string" }, "testnet": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "receipt": { "type": [ "object", "null" ], "description": "Paid receipt: asset, network, tokenAmount, explorer and time." } }, "required": [ "id", "amount", "status", "options" ], "additionalProperties": true }, "Quote": { "type": "object", "properties": { "id": { "type": "string" }, "invoice": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "recipient": { "type": "string" }, "paymentAddress": { "type": "string", "description": "Wallet-friendly address for payment links and display (TON uses non-bounceable mainnet format)." }, "quantity": { "type": "string", "description": "Exact smallest-unit amount. Never convert through Number.", "pattern": "^\\d+$" }, "amount": { "type": "string", "description": "Decimal token amount, not the USD invoice amount." }, "rate": { "type": "string" }, "decimals": { "type": "integer" }, "contract": { "type": [ "string", "null" ] }, "chainId": { "type": "integer" }, "family": { "type": "string", "enum": [ "evm", "solana", "bitcoin", "tron", "ton" ] }, "testnet": { "type": "boolean" }, "required": { "type": "integer", "description": "Required confirmations; native SOL uses finalized transfers." }, "created": { "type": "string", "format": "date-time" }, "expires": { "type": "string", "format": "date-time" }, "explorer": { "type": "string" } }, "required": [ "id", "network", "asset", "recipient", "quantity", "amount", "expires" ], "additionalProperties": true }, "Verification": { "type": "object", "properties": { "paid": { "type": "boolean" }, "pending": { "type": "boolean" }, "expired": { "type": "boolean" }, "underpaid": { "type": "boolean" }, "acceptedShortfall": { "type": "boolean" }, "status": { "type": "string", "description": "Underpaid means a confirmed transfer below the acceptance limits; it must not trigger fulfilment." }, "receivedQuantity": { "type": "string", "description": "Actual received base units." }, "quotedQuantity": { "type": "string", "description": "Original quoted base units." }, "shortfallQuantity": { "type": "string", "description": "Difference in base units." }, "shortfallAmount": { "type": "string", "description": "Difference in token units." }, "message": { "type": "string" }, "payment": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [], "additionalProperties": true }, "hash": { "type": "string" }, "confirmations": { "type": "integer" }, "explorer": { "type": "string" } }, "required": [], "additionalProperties": true }, "PaymentCompleted": { "type": "object", "properties": { "id": { "type": "string", "description": "Signed payment event ID (pay_…). Use for durable deduplication." }, "event": { "type": "string", "enum": [ "payment.completed" ] }, "invoice": { "type": "string" }, "amount": { "type": "number", "description": "Original USD order total, preserved for existing integrations." }, "invoiceAmount": { "type": "number" }, "receivedUsd": { "type": "number", "description": "Actual received USD equivalent at the locked quote rate." }, "originalAmount": { "type": "string", "description": "Original store amount as an exact decimal string; present for non-USD source prices." }, "originalCurrency": { "type": "string", "description": "Original store currency; amount/currency remain the locked USD accounting total." }, "fx": { "type": "object", "properties": { "source": { "type": "string", "description": "Rate provider." }, "sourcePerUsd": { "type": "string", "description": "Original currency units per ONE USD. Divide source amount by this rate." }, "fetchedAt": { "type": "string", "description": "Time Coinvay fetched this indicative rate, not a provider trade timestamp.", "format": "date-time" }, "lockedAt": { "type": "string", "description": "Invoice pricing lock time.", "format": "date-time" }, "rounding": { "type": "string", "description": "USD cents, half up" } }, "required": [], "additionalProperties": true }, "acceptedShortfall": { "type": "boolean" }, "quotedQuantity": { "type": "string" }, "receivedQuantity": { "type": "string" }, "shortfallQuantity": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD" ] }, "asset": { "type": "string" }, "network": { "type": "string" }, "recipient": { "type": "string" }, "quantity": { "type": "string" }, "tokenAmount": { "type": "string" }, "order": { "type": "string" }, "user": { "type": "string" }, "email": { "type": "string" }, "subscription": { "type": "string" }, "confirmations": { "type": "integer" }, "explorer": { "type": "string" }, "transactionHash": { "type": "string" } }, "required": [ "id", "event", "invoice", "amount", "currency", "transactionHash" ], "additionalProperties": true } } }, "x-networks": [ { "name": "Bitcoin", "chainId": 0, "assets": [ "BTC" ], "confirmations": 6, "testnet": false, "family": "bitcoin" }, { "name": "Tron", "chainId": 728126428, "assets": [ "TRX", "USDT" ], "confirmations": 1, "testnet": false, "family": "tron" }, { "name": "TON", "chainId": -239, "assets": [ "TON" ], "confirmations": 1, "testnet": false, "family": "ton" }, { "name": "Ethereum", "chainId": 1, "assets": [ "ETH", "DAI", "PYUSD", "USDC", "USDT" ], "confirmations": 12, "testnet": false, "family": "evm" }, { "name": "BNB Chain", "chainId": 56, "assets": [ "BNB", "USDT", "USDC" ], "confirmations": 15, "testnet": false, "family": "evm" }, { "name": "Base", "chainId": 8453, "assets": [ "ETH", "USDC", "USDT", "DAI" ], "confirmations": 20, "testnet": false, "family": "evm" }, { "name": "Solana", "chainId": 101, "assets": [ "SOL", "USDT" ], "confirmations": 1, "testnet": false, "family": "solana" }, { "name": "Polygon", "chainId": 137, "assets": [ "POL", "USDC", "PYUSD", "USDT", "DAI" ], "confirmations": 128, "testnet": false, "family": "evm" }, { "name": "Arbitrum", "chainId": 42161, "assets": [ "ETH", "USDC", "USDT" ], "confirmations": 160, "testnet": false, "family": "evm" }, { "name": "Optimism", "chainId": 10, "assets": [ "ETH", "USDC", "USDT" ], "confirmations": 20, "testnet": false, "family": "evm" }, { "name": "Avalanche", "chainId": 43114, "assets": [ "AVAX", "USDC", "USDT" ], "confirmations": 12, "testnet": false, "family": "evm" }, { "name": "Base Sepolia", "chainId": 84532, "assets": [ "ETH", "USDC" ], "confirmations": 3, "testnet": true, "family": "evm" } ], "x-rate-limits": { "merchantWritesPerMinute": 180, "checkoutPerIpPerMinute": 600, "checkoutPerTokenAndIpPerMinute": 90, "jsonBodyBytes": 65536 } }