{ "openapi": "3.1.0", "info": { "title": "Cleard routed test USDC", "version": "1.4.0", "description": "Circle test USDC on Base Sepolia uses six-decimal integer base units. Historical TEST programs retain their original deployment. Original payment remains final; approved refund is not guaranteed." }, "servers": [ { "url": "https://sandbox.cleard.ai/v1/routing" } ], "x-availability": "hosted-testnet", "paths": { "/access": { "get": { "summary": "Discover owned programs without issuing credentials or changing reviewer bindings", "parameters": [], "x-required-scope": "account", "security": [ { "account": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "successor_enabled", "deployment_id", "programs" ], "properties": { "successor_enabled": { "type": "boolean" }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "programs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "program_id", "deployment_id", "profile", "created_at", "generation", "predecessor", "reviewer_key_id", "reviewer_public_key", "purchases", "active_credentials" ], "properties": { "program_id": { "type": "string" }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "profile": { "enum": [ "provider", "direct_merchant" ] }, "created_at": { "type": "integer", "minimum": 1 }, "generation": { "type": "integer", "minimum": 0, "maximum": 2 }, "predecessor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "purchases": { "type": "integer", "minimum": 0 }, "active_credentials": { "type": "integer", "minimum": 0 } } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Issue seven-day access; revoke prior credential on renewal", "parameters": [], "x-required-scope": "account", "security": [ { "account": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "program_id", "credential", "expires_at", "scopes", "profile", "reviewer_key_id" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "program_id": { "type": "string" }, "credential": { "type": "string" }, "expires_at": { "type": "integer", "minimum": 1 }, "scopes": { "type": "array", "items": { "enum": [ "merchants:write", "purchases:write", "claims:write", "decisions:write", "refunds:execute", "records:read" ] } }, "profile": { "enum": [ "provider", "direct_merchant" ] }, "reviewer_key_id": { "type": "string" } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "profile", "reviewer_public_key" ], "properties": { "profile": { "enum": [ "provider", "direct_merchant" ] }, "reviewer_public_key": { "type": "string", "description": "Ed25519 SPKI PEM" }, "action": { "enum": [ "create", "renew", "successor" ], "description": "Explicit action required when successor_enabled is true." }, "request_id": { "type": "string", "format": "uuid", "description": "Stable request UUID. A committed repeat returns ACCESS_ALREADY_ISSUED without a secret or additional mutation; explicitly renew if its credential response was lost." }, "program_id": { "type": "string", "description": "Owned selected program for renewal, or latest predecessor for successor." }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Optional explicit renewal of an enabled historical deployment. New access defaults to the current deployment." } } } } } } } }, "/programs/{program}/transactions": { "get": { "summary": "Read scoped relayer operation IDs and hashes for fee reconciliation", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } } ], "x-required-scope": "records:read", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transactions" ], "properties": { "transactions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "operation", "hash" ], "properties": { "operation": { "type": "string" }, "hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/capabilities": { "get": { "summary": "Enabled route metadata", "parameters": [], "x-required-scope": "public", "security": [], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "version", "chain_id", "self_service", "real_funds", "access_expiry_days", "limits", "notification_destination", "notification_delivery", "provider_balances" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "version": { "const": "1.4.0" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "self_service": { "const": true }, "real_funds": { "const": false }, "access_expiry_days": { "const": 7 }, "limits": { "type": "object", "additionalProperties": false, "required": [ "programs_per_user_per_deployment", "programs_per_day", "merchants_per_program", "purchases_per_program" ], "properties": { "programs_per_user_per_deployment": { "enum": [ 1, 3 ] }, "programs_per_day": { "const": 20, "description": "Global new-program admission cap per UTC day across accounts and deployments; not per account." }, "merchants_per_program": { "const": 2 }, "purchases_per_program": { "const": 20 } } }, "notification_destination": { "type": "string" }, "notification_delivery": { "const": "signed, caller-driven retries" }, "provider_balances": { "const": false } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/programs/{program}": { "get": { "summary": "Scoped program and pinned public contract/key metadata", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } } ], "x-required-scope": "records:read", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "program_id", "reviewer_key_id", "reviewer_public_key", "chain_id", "contracts", "abi", "pins", "root", "signer_policy_hash", "record_key", "record_key_id", "merchants", "registrar", "notification_destination", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "program_id": { "type": "string" }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "root": { "type": "object", "description": "Pinned public BLISK setup; contains no signer secrets" }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "merchants": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "wallet", "reference", "enrollment" ], "properties": { "id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] } } } }, "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "notification_destination": { "type": "string" }, "real_funds": { "const": false }, "funding_modes": { "type": "array", "items": { "enum": [ "reserve", "direct_wallet" ] } }, "purchase_capacity": { "type": "object", "additionalProperties": false, "required": [ "limit", "used", "remaining" ], "properties": { "limit": { "const": 20, "type": "integer" }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 } }, "description": "Lifetime capacity shared by browser and client, and by all account programs on this deployment when successors are enabled. Expiry, refunds, successors and renewal do not reset purchases." } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/programs/{program}/merchants": { "post": { "summary": "Create merchant funding authorization and wallet link", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "merchants:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "merchant_id", "wallet", "reference", "funding_policy", "enrollment", "stopped", "authorization", "contracts", "abi", "pins", "chain_id", "real_funds", "id", "wallet_url" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "stopped": { "type": "boolean" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "program_id", "merchant_id", "wallet", "reserve", "chain_id", "version", "root", "policy_hash", "funding_policy" ], "properties": { "program_id": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "root": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "y": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "chain_id": { "enum": [ 31337, 84532 ] }, "real_funds": { "const": false }, "id": { "type": "string", "format": "uuid" }, "wallet_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "merchant_reference", "wallet", "funding_policy" ], "properties": { "merchant_reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } } } } } } }, "/programs/{program}/merchants/{id}/enrollment": { "post": { "summary": "Confirm exact wallet enrollment and personal signature", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "merchants:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "merchant_id", "wallet", "reference", "funding_policy", "enrollment", "stopped", "authorization", "contracts", "abi", "pins", "chain_id", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "stopped": { "type": "boolean" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "program_id", "merchant_id", "wallet", "reserve", "chain_id", "version", "root", "policy_hash", "funding_policy" ], "properties": { "program_id": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "root": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "y": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "real_funds": { "const": false } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "signature" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "signature": { "type": "string" } } } } } } } }, "/programs/{program}/purchases": { "post": { "summary": "Create signed purchase commitment and buyer wallet link", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "purchases:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts", "wallet_url" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0 }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string" }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } }, "wallet_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "merchant_id", "order_id", "beneficiary", "amount", "claim_window", "reason" ], "properties": { "merchant_id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "claim_window": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds from purchase creation, not payment, until claim_deadline. Paying five days after creation with a seven-day window leaves two days to claim." }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] } } } } } } } }, "/programs/{program}/purchases/{id}": { "get": { "summary": "Fresh approved/paid/outstanding and log receipts", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": "records:read", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/programs/{program}/purchases/{id}/activate": { "post": { "summary": "Bounded registrar offers this exact purchase", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "purchases:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} } } } } } }, "/programs/{program}/purchases/{id}/registration": { "post": { "summary": "Confirm direct merchant registration", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "purchases:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } }, "/programs/{program}/purchases/{id}/reconcile": { "post": { "summary": "Reconcile all affected receipt logs atomically", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "purchases:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } }, "/programs/{program}/purchases/{id}/claims": { "post": { "summary": "Verify beneficiary signature and timely onchain claim", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "claims:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } }, "/programs/{program}/purchases/{id}/decisions": { "post": { "summary": "Verify designated reviewer Ed25519 approval", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "decisions:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } } } } } } }, "/programs/{program}/purchases/{id}/refunds": { "post": { "summary": "Record award and collect from the accepted funding source", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "refunds:execute", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} } } } } } }, "/programs/{program}/notifications": { "post": { "summary": "Attempt up to five signed HTTP deliveries", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "purchases:write", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "configured", "delivered", "failed" ], "properties": { "configured": { "const": false }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } } }, { "type": "object", "additionalProperties": false, "required": [ "configured", "delivered", "failed", "destination", "delivery" ], "properties": { "configured": { "const": true }, "delivered": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "destination": { "type": "string" }, "delivery": { "const": "caller-driven" } } } ] } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "probe_first_attempt": { "type": "boolean", "description": "Optional testnet delivery probe: the pinned receiver commits the first valid event attempt and returns 503 once; later dispatch retries the exact signed event." } } } } } }, "description": "Per-program dispatch of up to 5 due events per call, at most 8 dispatch attempts per event with backoff. Caller-driven, fixed same-sandbox receiver; no scheduler or external receiver." } }, "/programs/{program}/notification-receipts": { "get": { "summary": "Read deduplicated signed delivery receipts", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } } ], "x-required-scope": "records:read", "security": [ { "service": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "receipts" ], "properties": { "receipts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "event_id", "digest", "attempts", "received_at" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "attempts": { "type": "integer", "minimum": 0, "description": "Verified receiver deliveries for this event ID, including duplicates and the fail-first probe; maximum 16. Separate from the outbox's maximum 8 dispatch attempts per event." }, "received_at": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notification-receiver": { "post": { "summary": "Accept exact signed outbox event at pinned receiver", "parameters": [ { "name": "Cleard-Notification-Probe", "in": "header", "required": false, "schema": { "enum": [ "fail-first" ] }, "description": "Testnet probe only: after signature/outbox verification, persist the first valid delivery attempt and return 503 once. Retry keeps the same event ID." } ], "x-required-scope": "signed_event", "security": [], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "id", "duplicate" ], "properties": { "id": { "type": "string", "format": "uuid" }, "duplicate": { "type": "boolean" } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payload", "key_id", "signature" ], "properties": { "payload": { "type": "object" }, "key_id": { "type": "string" }, "signature": { "type": "string" } }, "additionalProperties": false } } } } } }, "/wallet/{program}/merchant/{id}": { "get": { "summary": "Read the exact wallet-linked record", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "merchant_id", "wallet", "reference", "funding_policy", "enrollment", "stopped", "authorization", "contracts", "abi", "pins", "chain_id", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "stopped": { "type": "boolean" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "program_id", "merchant_id", "wallet", "reserve", "chain_id", "version", "root", "policy_hash", "funding_policy" ], "properties": { "program_id": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "root": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "y": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "real_funds": { "const": false } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet/{program}/merchant/{id}/enrollment": { "post": { "summary": "Confirm exact wallet enrollment and personal signature", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "merchant_id", "wallet", "reference", "funding_policy", "enrollment", "stopped", "authorization", "contracts", "abi", "pins", "chain_id", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "stopped": { "type": "boolean" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "program_id", "merchant_id", "wallet", "reserve", "chain_id", "version", "root", "policy_hash", "funding_policy" ], "properties": { "program_id": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "root": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "y": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "real_funds": { "const": false } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "signature" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "signature": { "type": "string" } } } } } } } }, "/wallet/{program}/purchase/{id}": { "get": { "summary": "Read the exact wallet-linked record", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet/{program}/purchase/{id}/registration": { "post": { "summary": "Confirm direct merchant registration", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } }, "/wallet/{program}/purchase/{id}/reconcile": { "post": { "summary": "Reconcile all affected receipt logs atomically", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } }, "/wallet/{program}/purchase/{id}/claims": { "post": { "summary": "Verify beneficiary signature and timely onchain claim", "parameters": [ { "in": "path", "name": "program", "required": true, "schema": { "type": "string", "pattern": "^routing-[0-9a-f-]{36}$" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } } ], "x-required-scope": "wallet", "security": [ { "wallet": [] } ], "responses": { "200": { "description": "Successful exact operation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired or revoked access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Denied scope, signature or origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Binding, ordering, state or receipt conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Sandbox capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed; inspect error.code and preserve original intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable, fenced worker or pending transaction. Inspect the code; preserve the original body/key and transaction hash. A 503 alone is not proof of failure before broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } } } } }, "components": { "securitySchemes": { "service": { "type": "http", "scheme": "bearer", "description": "Scoped seven-day credential; cookie rejected" }, "account": { "type": "http", "scheme": "bearer", "description": "Verified existing Supabase account; same-origin secure session cookie also accepted only for access" }, "wallet": { "type": "apiKey", "in": "header", "name": "Cleard-Wallet-Access", "description": "Exact-record capability: merchant seven days; buyer through immutable collection deadline (maximum150days). Wallet signatures are additionally required." } }, "schemas": { "FundingPolicy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "Claim": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "Decision": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "PurchaseTerms": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "PurchaseSnapshot": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "id", "merchant_id", "chain_purchase_id", "terms_hash", "commitment", "registration", "settlement", "payment_allocation", "claim", "decision", "approved", "paid", "outstanding", "chain_paid", "reserve_balance", "frozen", "contracts", "abi", "pins", "record_key", "record_key_id", "payouts" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "chain_purchase_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "commitment": { "type": "object", "additionalProperties": false, "required": [ "key_id", "payload", "signature" ], "properties": { "key_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": false, "required": [ "version", "program_id", "purchase_id", "merchant_id", "merchant", "order_id", "beneficiary", "amount", "token", "chain_id", "reserve", "policy_version", "signer_policy_hash", "funding_policy", "funding_policy_hash", "refund_eligibility", "claim_deadline", "decision_deadline", "collection_deadline", "created_at", "original_payment_final", "guarantee" ], "properties": { "version": { "const": "cleard.routed-purchase.v1" }, "program_id": { "type": "string" }, "purchase_id": { "type": "string", "format": "uuid" }, "merchant_id": { "type": "string", "format": "uuid" }, "merchant": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "order_id": { "type": "string" }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "policy_version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "funding_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "refund_eligibility": { "type": "object", "additionalProperties": false, "required": [ "reason", "reviewer_key_id", "reviewer_public_key", "evidence_rule" ], "properties": { "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "evidence_rule": { "const": "designated_reviewer_evaluates_submitted_evidence" } } }, "claim_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: created_at + requested claim_window. Payment and claim submission never reset it." }, "decision_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: claim_deadline + funding_policy.decisionWindow, frozen at creation. Requires a timely onchain claim; the first award must reach the contract by this deadline." }, "collection_deadline": { "type": "integer", "minimum": 1, "description": "Unix seconds: decision_deadline + funding_policy.recoveryWindow, frozen at creation as an upper bound. V4 collection also stops at the first accepted decision expiry and mandate expiry; unpaid obligations may remain." }, "created_at": { "type": "integer", "minimum": 1 }, "original_payment_final": { "const": true }, "guarantee": { "type": "null" }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." } } }, "signature": { "type": "string" } } }, "registration": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "settlement": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "payment_allocation": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "gross", "merchant_net", "captured", "recovered" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "gross": { "type": "integer", "minimum": 0, "description": "Buyer payment amount." }, "merchant_net": { "type": "integer", "minimum": 0, "description": "Amount of this payment transferred to the merchant; may be zero." }, "captured": { "type": "integer", "minimum": 0, "description": "Amount withheld from this payment, including recovery funding and rolling reserve. Not the remaining reserve balance." }, "recovered": { "type": "integer", "minimum": 0, "description": "All awards paid during this transaction, including previously held reserve; may exceed captured. Do not subtract it again from gross." } }, "description": "Historical PaymentRouted event in integer token base units. gross = merchant_net + captured. At this transaction reserve_after = reserve_before + captured - recovered; snapshot reserve_balance may reflect later activity." }, { "type": "null" } ] }, "claim": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature", "transaction_hash", "evidence_hash", "block_hash" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "requested", "reason", "evidence" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "requested": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "reason": { "enum": [ "digital_non_delivery", "api_result_failure", "accepted_return" ] }, "evidence": { "type": "string", "minLength": 1, "maxLength": 8000 } } }, "signature": { "type": "string" }, "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "payload", "signature" ], "properties": { "payload": { "type": "object", "additionalProperties": false, "required": [ "purchase_id", "terms_hash", "evidence_hash", "decision_id", "approved", "beneficiary", "expires_at" ], "properties": { "purchase_id": { "type": "string", "format": "uuid" }, "terms_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "evidence_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "decision_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "approved": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "beneficiary": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "expires_at": { "type": "integer" } }, "description": "Positive approval signed by the designated reviewer. The service verifies Ed25519 offchain before BLISK refund execution; rejection and terminal denial/early closure are not supported." }, "signature": { "type": "string" } } }, { "type": "null" } ] }, "approved": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "outstanding": { "type": "integer", "minimum": 0 }, "chain_paid": { "type": "integer", "minimum": 0 }, "reserve_balance": { "type": "integer", "minimum": 0, "description": "Current merchant reserve balance at the read, shared across purchases. Not reserved exclusively for this buyer or guaranteed at execution." }, "frozen": { "type": "boolean" }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "transaction_hash", "log_index", "block_hash", "amount" ], "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 }, "block_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "amount": { "type": "integer", "minimum": 0 } } } }, "wallet_funding": { "type": "object", "additionalProperties": false, "required": [ "balance", "allowance", "collected", "deadline", "automatic_inflow_capture" ], "properties": { "balance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "allowance": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "collected": { "type": "integer", "minimum": 0 }, "deadline": { "type": "integer", "minimum": 1 }, "automatic_inflow_capture": { "const": false } } } } }, "Merchant": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "merchant_id", "wallet", "reference", "funding_policy", "enrollment", "stopped", "authorization", "contracts", "abi", "pins", "chain_id", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "stopped": { "type": "boolean" }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "program_id", "merchant_id", "wallet", "reserve", "chain_id", "version", "root", "policy_hash", "funding_policy" ], "properties": { "program_id": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reserve": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "root": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "y": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "funding_policy": { "type": "object", "additionalProperties": false, "required": [ "registrar", "termsHash", "rollingBps", "recoveryBps", "reserveCap", "upfront", "collectionCap", "decisionWindow", "recoveryWindow", "purchaseLimit", "exposureLimit", "riskTier", "basis", "releaseRule" ], "properties": { "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Merchant-authorized purchase registrar address. This hosted API requires the program's published registrar; service access alone grants no wallet authority." }, "termsHash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Nonzero funding-terms digest supplied by the integrator and bound at enrollment. The SDK uses routingHash(policyWithoutTermsHash); distinct from purchase terms_hash and signer_policy_hash." }, "rollingBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: rolling target in basis points of each gross payment (100 = 1%), rounded up in token base units. Limited by reserveCap, remaining collectionCap and payment funds left after recovery. Held reserve can also pay eligible debt." }, "recoveryBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Reserve mode: new-payment recovery target in basis points of gross, rounded up. Limited by eligible debt and remaining collectionCap. Not a ceiling on all refunds in the transaction: prior and newly held reserve may also pay debt." }, "reserveCap": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit cap on held reserve accumulation from deposits and rolling capture, not lifetime collection or a cap on pass-through recovery." }, "upfront": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "description": "Token base-unit reserve balance required when registering each purchase. An admission minimum, not a separate deposit or full collateralization for every purchase." }, "collectionCap": { "type": "integer", "minimum": 1, "maximum": 1000000000000, "description": "Cumulative token base-unit ceiling per merchant enrollment version. Reserve mode counts deposits and routed capture; direct-wallet mode counts successful refund collection. Payouts, withdrawals and retries do not reset the counter." }, "decisionWindow": { "type": "integer", "minimum": 60, "maximum": 2592000, "description": "Seconds after the creation-based claim_deadline until the fixed first-decision deadline. A timely onchain claim preserves this authority; filing does not restart the window." }, "recoveryWindow": { "type": "integer", "minimum": 60, "maximum": 7776000, "description": "Seconds after decision_deadline until the purchase collection upper bound. V4 authority can end earlier at the accepted decision or mandate expiry. Expiry can leave an unpaid obligation." }, "purchaseLimit": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Maximum registered purchase amount in token base units for this merchant enrollment." }, "exposureLimit": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Maximum aggregate remaining registered exposure in token base units. Unpaid registered checkouts count; approval, payment of awards and explicit expiry release reduce exposure under contract rules." }, "riskTier": { "enum": [ "trusted", "higher_risk" ], "description": "Provider-selected risk label. Does not prove KYB, change the contract's funding rules or guarantee reimbursement." }, "basis": { "const": "gross_round_up", "description": "Apply each rate to gross integer base units and round up separately per payment; no fractional carry." }, "releaseRule": { "const": "remaining_exposure", "description": "Reserve withdrawals must leave backing for remaining exposure. Direct-wallet mode locks no balance. releaseExpired releases expired exposure while retaining unpaid approved debt." }, "mode": { "enum": [ 0, 1 ], "description": "V4 only: explicit reserve (0) or direct merchant wallet (1). Risk alone grants no authority." }, "mandateScope": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Server-derived program, merchant, execution-domain and policy digest signed in V4 enrollment." }, "validUntil": { "type": "integer", "minimum": 1, "description": "V4 absolute merchant mandate expiry. All purchase collection deadlines must fit inside it." } }, "description": "Merchant funding policy. Amounts are integer token base units (USDC: 10^6 units per token); windows are seconds. Frozen in each accepted purchase." } } }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "real_funds": { "const": false } } }, "Access": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "program_id", "credential", "expires_at", "scopes", "profile", "reviewer_key_id" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "program_id": { "type": "string" }, "credential": { "type": "string" }, "expires_at": { "type": "integer", "minimum": 1 }, "scopes": { "type": "array", "items": { "enum": [ "merchants:write", "purchases:write", "claims:write", "decisions:write", "refunds:execute", "records:read" ] } }, "profile": { "enum": [ "provider", "direct_merchant" ] }, "reviewer_key_id": { "type": "string" } } }, "Program": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "program_id", "reviewer_key_id", "reviewer_public_key", "chain_id", "contracts", "abi", "pins", "root", "signer_policy_hash", "record_key", "record_key_id", "merchants", "registrar", "notification_destination", "real_funds" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "program_id": { "type": "string" }, "reviewer_key_id": { "type": "string" }, "reviewer_public_key": { "type": "string" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "contracts": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "abi": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "array", "items": { "type": "object" }, "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "array", "items": { "type": "object" } } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "pins": { "type": "object", "additionalProperties": false, "required": [ "MerchantReserveV2", "MockToken", "BliskVerifier" ], "properties": { "MerchantReserveV2": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the selected V3 or V4 collection contract." }, "MockToken": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Compatibility key for the program's token: official Circle test USDC for circle-usdc, historical TEST for legacy-test. No mint permission is implied." }, "BliskVerifier": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "description": "MerchantReserveV2 identifies the selected V3 or V4 collection contract; MockToken identifies its token. Verify deployment_id and pins rather than inferring the deployment from these compatibility key names." }, "root": { "type": "object", "description": "Pinned public BLISK setup; contains no signer secrets" }, "signer_policy_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "record_key": { "type": "string", "description": "Cleard Ed25519 public key used to verify signed records, not the designated reviewer's decision key." }, "record_key_id": { "type": "string" }, "merchants": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "wallet", "reference", "enrollment" ], "properties": { "id": { "type": "string", "format": "uuid" }, "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "reference": { "type": "string" }, "enrollment": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] } } } }, "registrar": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "notification_destination": { "type": "string" }, "real_funds": { "const": false }, "funding_modes": { "type": "array", "items": { "enum": [ "reserve", "direct_wallet" ] } }, "purchase_capacity": { "type": "object", "additionalProperties": false, "required": [ "limit", "used", "remaining" ], "properties": { "limit": { "const": 20, "type": "integer" }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 } }, "description": "Lifetime capacity shared by browser and client, and by all account programs on this deployment when successors are enabled. Expiry, refunds, successors and renewal do not reset purchases." } } }, "Capabilities": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "asset", "version", "chain_id", "self_service", "real_funds", "access_expiry_days", "limits", "notification_destination", "notification_delivery", "provider_balances" ], "properties": { "deployment_id": { "enum": [ "legacy-test", "circle-usdc", "circle-usdc-wallet-v4" ], "description": "Select an enabled deployment from account discovery. circle-usdc-wallet-v4 supports both funding modes; circle-usdc supports reserve funding. legacy-test identifies existing TEST programs. Program bindings are immutable." }, "asset": { "type": "object", "additionalProperties": false, "required": [ "symbol", "decimals", "amount_unit" ], "properties": { "symbol": { "enum": [ "TEST", "USDC" ], "description": "USDC for current Circle testnet programs; TEST for retained historical programs." }, "decimals": { "enum": [ 0, 6 ], "description": "6 for USDC; 0 for historical TEST. Read together with deployment_id and the pinned token; these values are not interchangeable." }, "amount_unit": { "const": "base_units" }, "implementation": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "implementation_sha256": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "version": { "const": "1.4.0" }, "chain_id": { "enum": [ 31337, 84532 ], "description": "Hosted network: Base Sepolia (84532)." }, "self_service": { "const": true }, "real_funds": { "const": false }, "access_expiry_days": { "const": 7 }, "limits": { "type": "object", "additionalProperties": false, "required": [ "programs_per_user_per_deployment", "programs_per_day", "merchants_per_program", "purchases_per_program" ], "properties": { "programs_per_user_per_deployment": { "enum": [ 1, 3 ] }, "programs_per_day": { "const": 20, "description": "Global new-program admission cap per UTC day across accounts and deployments; not per account." }, "merchants_per_program": { "const": 2 }, "purchases_per_program": { "const": 20 } } }, "notification_destination": { "type": "string" }, "notification_delivery": { "const": "signed, caller-driven retries" }, "provider_balances": { "const": false } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable error code. See x-error-catalog; additional codes may be introduced." }, "message": { "type": "string" } } } } } } }, "x-error-catalog": [ { "code": "MANDATE_DEADLINE", "recovery": "shorten_purchase_windows_to_fit_signed_mandate" }, { "code": "INVALID_BENEFICIARY", "recovery": "use_a_distinct_bound_refund_wallet_for_direct_collection" }, { "code": "COLLECTION_EXPIRED", "recovery": "retain_unpaid_obligation_do_not_revive_expired_authority" }, { "code": "DECISION_MISMATCH", "recovery": "retain_original_purchase_decision_and_inspect_chain_state" }, { "code": "ACCESS_ALREADY_ISSUED", "recovery": "discover_owned_program_use_saved_access_or_explicitly_renew" }, { "code": "SUCCESSOR_UNAVAILABLE", "recovery": "wait_for_explicit_successor_activation" }, { "code": "SUCCESSOR_EXISTS", "recovery": "discover_latest_owned_program_before_new_action" }, { "code": "ACCOUNT_CAPACITY", "recovery": "shared_lifetime_capacity_cannot_be_reset_by_successor" }, { "code": "ACCEPTANCE_MISMATCH", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ACCEPTANCE_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ACCESS_CAPACITY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ACCESS_EXISTS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ACCESS_RATE_LIMIT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "AUTH_UNAVAILABLE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "BODY_TOO_LARGE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "BROADCAST_DISABLED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "CHAIN_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "CHAIN_CHANGED", "recovery": "halt_operator_review" }, { "code": "CHAIN_REORG", "recovery": "halt_operator_review" }, { "code": "CLAIM_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "CLAIM_EXISTS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "CLAIM_EXPIRED", "recovery": "business_deadline_terminal" }, { "code": "CONTRACT_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "DECISION_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "DECISION_EXISTS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "DECISION_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "DECISION_SIGNATURE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "DEPLOYMENT_UNAVAILABLE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ENROLLMENT_EXISTS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ENROLLMENT_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "EVENT_ORDER", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "EXECUTION_BOUNDARY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "EXECUTION_DOMAIN", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "FORBIDDEN", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "IDEMPOTENCY_CONFLICT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "IDEMPOTENCY_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_ACCESS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_ADDRESS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_AMOUNT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_JSON", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_POLICY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_PROBE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_QUERY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_RECEIPT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_REQUEST", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_REVIEWER", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_SIGNATURE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "INVALID_TERMS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "JOURNAL_MISMATCH", "recovery": "halt_operator_review" }, { "code": "JSON_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "LEASE_LOST", "recovery": "same_intent_after_backoff" }, { "code": "LOCAL_CHAIN_ONLY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "MERCHANT_CAPACITY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "METHOD_NOT_ALLOWED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOTIFICATION_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOTIFICATION_CONFLICT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOTIFICATION_CONTROLLED_RETRY", "recovery": "same_signed_event_after_backoff" }, { "code": "NOTIFICATION_DESTINATION", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOTIFICATION_LIMIT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOTIFICATION_SIGNATURE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "NOT_FOUND", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ORIGIN_REJECTED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "PAYMENT_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "PAYMENT_REPLAY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "POLICY_CHANGED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "PROGRAM_BINDING_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "PURCHASE_CAP", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "PURCHASE_CAPACITY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "RECEIPT_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "RECEIPT_CONFLICT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "RECEIPT_NOT_CONFIRMED", "recovery": "same_receipt_after_confirmation" }, { "code": "RECONCILIATION_REQUIRED", "recovery": "reconcile_existing_receipt" }, { "code": "RECORD_CONFLICT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "RECORD_SIGNATURE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "REFUND_BINDING", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "REGISTRAR_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "REGISTRATION_EXISTS", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "REGISTRATION_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "REQUEST_EXPIRED", "recovery": "same_intent_after_backoff" }, { "code": "ROUTING_DISABLED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "ROUTING_ERROR", "recovery": "unknown_outcome_status_then_same_intent" }, { "code": "SERVER_CLIENT_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "SERVICE_BUSY", "recovery": "same_intent_after_backoff" }, { "code": "SETTLEMENT_MISMATCH", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "SETTLEMENT_REPLAY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "SETTLEMENT_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "SIGNER_ROOT_CHANGED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TESTNET_FEE_LIMIT", "recovery": "preflight_failed_inspect_saved_intent" }, { "code": "TESTNET_GAS_LIMIT", "recovery": "preflight_failed_inspect_saved_intent" }, { "code": "TEST_GAS_BUDGET_EXCEEDED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TEST_GAS_REQUIRED", "recovery": "preflight_failed_inspect_saved_intent" }, { "code": "TEST_TRANSACTION_BOUNDARY", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_AMOUNT_LIMIT", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_BLACKLISTED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_IMPLEMENTATION_CHANGED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_IMPLEMENTATION_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_METADATA_CHANGED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_METADATA_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_PAUSED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TOKEN_PRECISION_EXCEEDED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "TRANSACTION_PENDING", "recovery": "same_intent_or_status_lookup" }, { "code": "TRANSACTION_REVERTED", "recovery": "terminal_chain_failure_inspect" }, { "code": "UNAUTHORIZED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "WALLET_LINK_EXPIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "WALLET_LINK_REQUIRED", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "WALLET_SIGNATURE", "recovery": "inspect_binding_policy_or_capacity_before_retry" }, { "code": "WALLET_TRANSACTION", "recovery": "inspect_binding_policy_or_capacity_before_retry" } ], "x-retry-guidance": { "same_intent": "Retry only identical method, path, body and Idempotency-Key; inspect current purchase and saved transaction first when the outcome is uncertain.", "request_expired": "REQUEST_EXPIRED is a worker deadline, not an expired commercial claim.", "terminal": "TRANSACTION_REVERTED is terminal for the saved signed transaction. Fix the cause and establish a separately authorized new intent only after canonical failed receipt verification. Never automatically replace a pending transaction.", "capacity": "PURCHASE_CAPACITY is 20 lifetime purchases, shared across browser and client. Enabled successors share that account/deployment limit and ACCOUNT_CAPACITY also enforces two total merchant registrations. Renewal and successors do not reset usage.", "gateway": "An upstream HTML 502/503/504 may have an unknown outcome. The client bounds retries using the same durable intent. Other non-JSON responses are INVALID_RESPONSE, not blind retry permission.", "preflight": "A fee/gas preflight rejection prevents a new broadcast in that attempt, but does not prove that an earlier attempt never broadcast. Check the saved intent and canonical receipt before retrying; do not silently widen budget limits." } }