{ "openapi": "3.1.0", "info": { "title": "WalletConnect Pay API", "version": "2026-02-19.preview" }, "servers": [ { "url": "https://api.pay.walletconnect.com" } ], "paths": { "/v1/gateway/payment/{id}": { "get": { "tags": [ "Gateway" ], "summary": "Get a payment", "description": "This endpoint returns only basic information to display to the user to begin the payment flow.", "operationId": "gatewayGetPayment", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/gateway/payment/{id}/cancel": { "post": { "tags": [ "Gateway" ], "operationId": "gatewayCancelPayment", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } } ], "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCancelPaymentResponse" } } } }, "400": { "description": "Payment cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/gateway/payment/{id}/confirm": { "post": { "tags": [ "Gateway" ], "summary": "Confirm a payment", "description": "This endpoint confirms a payment and submits it to the blockchain for processing.", "operationId": "confirm_payment_handler", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } }, { "name": "maxPollMs", "in": "query", "description": "Maximum time to long-poll for payment status, in milliseconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/gateway/payment/{id}/fetch": { "post": { "tags": [ "Gateway" ], "summary": "Fetches an action", "description": "This endpoint fetches an action for a payment.", "operationId": "fetch_handler", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchRequest" } } }, "required": true }, "responses": { "200": { "description": "Action built successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/gateway/payment/{id}/options": { "post": { "tags": [ "Gateway" ], "summary": "Get payment options", "description": "This endpoint takes a list of accounts and returns a list of options that can be used to complete the payment.", "operationId": "gatewayGetPaymentOptions", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } }, { "name": "includePaymentInfo", "in": "query", "description": "Whether to include payment information in the response", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentOptionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment options retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentOptionsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/gateway/payment/{id}/status": { "get": { "tags": [ "Gateway" ], "summary": "Get the payment status", "description": "Retrieves the status of a payment by its ID. Returns a polling delay to wait\nbefore checking the status again.", "operationId": "gatewayGetPaymentStatus", "parameters": [ { "name": "Api-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "App-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Client-Id", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } }, { "name": "maxPollMs", "in": "query", "description": "Maximum time to long-poll for payment status, in milliseconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentStatusResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a new payment", "description": "Creates a new payment with the provided payment details.", "operationId": "paymentsCreatePayment", "parameters": [ { "name": "Api-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Merchant-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" } } }, "required": true }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "PartnerPayments_list", "parameters": [ { "name": "WCP-Version", "in": "header", "required": false, "description": "Optional WalletConnect Pay API version override. If omitted, the partner's pinned version is used.", "schema": { "type": "string", "examples": [ "2026-02-18", "2026-02-19.preview" ] } }, { "in": "query", "name": "startTs", "schema": { "examples": [ "2026-01-06T00:00:00Z" ], "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "RFC3339 timestamp, inclusive" }, { "in": "query", "name": "endTs", "schema": { "examples": [ "2026-01-07T00:00:00Z" ], "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "RFC3339 timestamp, exclusive" }, { "in": "query", "name": "token_symbol", "schema": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": "Filter by token symbol (e.g. `USDC`). CAIP-19 identifiers are not supported. Accepts a single value or multiple repeated params:\n\n- Single: `?token_symbol=USDC`\n- Multiple: `?token_symbol=USDC&token_symbol=EURC`" }, { "in": "query", "name": "asset", "schema": { "deprecated": true, "type": "string" }, "description": "Deprecated. This parameter will be removed in a future API version. Use `token_symbol` param instead." }, { "in": "query", "name": "network", "schema": { "examples": [ "eip155:8453", "eip155:8453,eip155:1" ], "type": "string" }, "description": "Filter by [CAIP-2](https://standards.chainagnostic.org/CAIPs/caip-2) chain ID. Comma-separated for multiple." }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "date", "amount" ] }, "description": "Field to sort by" }, { "in": "query", "name": "sortDir", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction" }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Opaque pagination cursor — use the value from `nextCursor` in the previous response." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size (default 50, max 200)" }, { "in": "query", "name": "status", "schema": { "type": "array", "items": { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired", "cancelled" ] } }, "description": "Filter by payment status. Accepts a single value or multiple repeated params:\n\n- Single: `?status=succeeded`\n- Multiple: `?status=succeeded&status=processing`" }, { "in": "query", "name": "referenceId", "schema": { "type": "string", "minLength": 3, "maxLength": 35, "pattern": "^[A-Za-z0-9 /:.,+-]+$", "examples": [ "order-42" ] }, "description": "Substring search on the merchant-provided reference ID. Between 3 and 35 characters. Allowed characters: ASCII letters, digits, and ` /-:.,+`." }, { "in": "query", "name": "merchantId", "schema": { "type": "array", "items": { "type": "string", "minLength": 1 }, "examples": [ [ "acme-store-1" ], [ "acme-store-1", "widget_co" ] ] }, "description": "Filter by merchant ID. Accepts a single value or multiple repeated params:\n\n- Single: `?merchantId=acme-store-1`\n- Multiple: `?merchantId=acme-store-1&merchantId=widget_co`" } ], "responses": { "200": { "description": "Payments with statistics", "headers": { "WCP-Version": { "description": "WalletConnect Pay API version resolved for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPaymentsResponse" }, "example": { "data": [ { "paymentId": "pay_a1a2ecc101KGF210FP7PN3BK08PZARS1CZ", "merchant": { "id": "acme-store-1", "name": "Acme Store", "iconUrl": "https://imagedelivery.net/example/icon.png" }, "referenceId": "a1b2cad4e5f2783012345678axcdea90", "status": "succeeded", "isTerminal": true, "fiatAmount": { "unit": "iso4217/USD", "value": "500", "display": { "assetSymbol": "USD", "assetName": "US Dollar", "decimals": 2 } }, "tokenAmount": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "5000000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "networkName": "Base", "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "buyer": { "accountCaip10": "eip155:8453:0x0000000000000000000000000000000000000000", "accountProviderName": "MetaMask", "accountProviderIcon": "https://api.walletconnect.com/assets/v1/image/wallet/metamask/md" }, "transaction": { "networkId": "8453", "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": 42 }, "settlement": { "amount": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "4840000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "settled": true, "txHash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "fees": { "total": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "160000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "fixed": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "140000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "percentage": "0.4" }, "createdAt": "2024-01-01T12:00:00.000Z", "lastUpdatedAt": "2024-01-01T12:00:00.000Z", "settledAt": "2024-01-01T12:00:00.000Z" } ], "nextCursor": null, "stats": { "totalRevenue": [ { "amount": 1000, "currency": "USD" } ], "totalTransactions": 100, "totalCustomers": 25 } } } } }, "400": { "description": "Bad request — invalid parameters or API version", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "invalid_params", "params_validation", "invalid_api_version", "unknown_api_version", "api_version_downgrade" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } }, "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "invalid_api_version": { "summary": "Invalid API version", "value": { "code": "invalid_api_version", "message": "Invalid API version" } }, "unknown_api_version": { "summary": "Unknown API version", "value": { "code": "unknown_api_version", "message": "Unknown API version" } }, "api_version_downgrade": { "summary": "Requested API version is older than the partner pin", "value": { "code": "api_version_downgrade", "message": "Requested API version is older than the partner pin" } } } } } }, "401": { "description": "Unauthorized — missing or invalid partner API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "internal_error", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "internal_error": { "summary": "Internal Server Error", "value": { "code": "internal_error", "message": "Internal Server Error" } } } } } }, "502": { "description": "Bad gateway — upstream service returned an error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "bad_gateway", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "bad_gateway": { "summary": "Bad Gateway", "value": { "code": "bad_gateway", "message": "Bad Gateway" } } } } } } }, "tags": [ "Payments" ], "summary": "List payments", "description": "Retrieve paginated payments with optional filters." } }, "/v1/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get payment details", "description": "Retrieves the full details of a payment by its ID, including settlement\ninformation when available.", "operationId": "paymentsGetPayment", "parameters": [ { "name": "Api-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Merchant-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } } ], "responses": { "200": { "description": "Payment details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsGetPaymentResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/{id}/cancel": { "post": { "tags": [ "Payments" ], "operationId": "paymentsCancelPayment", "parameters": [ { "name": "Api-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Merchant-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } } ], "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsCancelPaymentResponse" } } } }, "400": { "description": "Payment cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/{id}/status": { "get": { "tags": [ "Payments" ], "summary": "Get the payment status", "description": "Retrieves the status of a payment by its ID. Returns a polling delay to wait\nbefore checking the status again.", "operationId": "paymentsGetPaymentStatus", "parameters": [ { "name": "Api-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Merchant-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "WCP-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Name", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Version", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Sdk-Platform", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "id", "in": "path", "description": "Payment ID", "required": true, "schema": { "$ref": "#/components/schemas/PaymentId" } }, { "name": "maxPollMs", "in": "query", "description": "Maximum time to long-poll for payment status, in milliseconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentStatusResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/refunds": { "post": { "operationId": "Refunds_create", "parameters": [ { "name": "Merchant-Id", "in": "header", "required": true, "description": "Merchant identifier.", "schema": { "type": "string", "examples": [ "acme-store-1" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "description": "Optional WalletConnect Pay API version override. If omitted, the partner's pinned version is used.", "schema": { "type": "string", "examples": [ "2026-02-18", "2026-02-19.preview" ] } } ], "responses": { "200": { "description": "Payment marked as refunded", "headers": { "WCP-Version": { "description": "WalletConnect Pay API version resolved for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Payment ID that was marked as refunded" } }, "required": [ "paymentId" ] }, "example": { "paymentId": "pay_a1a2ecc101KGF210FP7PN3BK08PZARS1CZ" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "params_validation", "payment_not_succeeded", "invalid_api_version", "unknown_api_version", "api_version_downgrade" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "payment_not_succeeded": { "summary": "Payment is not in a refundable state", "value": { "code": "payment_not_succeeded", "message": "Payment is not in a refundable state" } }, "invalid_api_version": { "summary": "Invalid API version", "value": { "code": "invalid_api_version", "message": "Invalid API version" } }, "unknown_api_version": { "summary": "Unknown API version", "value": { "code": "unknown_api_version", "message": "Unknown API version" } }, "api_version_downgrade": { "summary": "Requested API version is older than the partner pin", "value": { "code": "api_version_downgrade", "message": "Requested API version is older than the partner pin" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key, or missing merchant id", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "missing_merchant_id" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } }, "missing_merchant_id": { "summary": "Missing Merchant ID", "value": { "code": "missing_merchant_id", "message": "Missing Merchant ID" } } } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } }, "409": { "description": "Payment is already refunded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "already_refunded", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "already_refunded": { "summary": "Payment is already refunded", "value": { "code": "already_refunded", "message": "Payment is already refunded" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "internal_error", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "internal_error": { "summary": "Internal Server Error", "value": { "code": "internal_error", "message": "Internal Server Error" } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "bad_gateway", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "bad_gateway": { "summary": "Bad Gateway", "value": { "code": "bad_gateway", "message": "Bad Gateway" } } } } } } }, "tags": [ "Refunds" ], "summary": "Mark a payment as refunded", "description": "Request a full refund for a payment. Calling a second time on the same payment returns 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^pay_[A-Za-z0-9]+$", "description": "Payment ID to refund", "examples": [ "pay_a1a2ecc101KGF210FP7PN3BK08PZARS1CZ" ] } }, "required": [ "paymentId" ] } } } } } }, "/v1/merchants/payments": { "get": { "operationId": "MerchantPayments_list", "parameters": [ { "name": "Merchant-Id", "in": "header", "required": true, "description": "Merchant identifier.", "schema": { "type": "string", "examples": [ "acme-store-1" ] } }, { "name": "WCP-Version", "in": "header", "required": false, "description": "Optional WalletConnect Pay API version override. If omitted, the partner's pinned version is used.", "schema": { "type": "string", "examples": [ "2026-02-18", "2026-02-19.preview" ] } }, { "in": "query", "name": "startTs", "schema": { "examples": [ "2026-01-06T00:00:00Z" ], "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "RFC3339 timestamp, inclusive" }, { "in": "query", "name": "endTs", "schema": { "examples": [ "2026-01-07T00:00:00Z" ], "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "RFC3339 timestamp, exclusive" }, { "in": "query", "name": "token_symbol", "schema": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": "Filter by token symbol (e.g. `USDC`). CAIP-19 identifiers are not supported. Accepts a single value or multiple repeated params:\n\n- Single: `?token_symbol=USDC`\n- Multiple: `?token_symbol=USDC&token_symbol=EURC`" }, { "in": "query", "name": "asset", "schema": { "deprecated": true, "type": "string" }, "description": "Deprecated. This parameter will be removed in a future API version. Use `token_symbol` param instead." }, { "in": "query", "name": "network", "schema": { "examples": [ "eip155:8453", "eip155:8453,eip155:1" ], "type": "string" }, "description": "Filter by [CAIP-2](https://standards.chainagnostic.org/CAIPs/caip-2) chain ID. Comma-separated for multiple." }, { "in": "query", "name": "sortBy", "schema": { "type": "string", "enum": [ "date", "amount" ] }, "description": "Field to sort by" }, { "in": "query", "name": "sortDir", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction" }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Opaque pagination cursor — use the value from `nextCursor` in the previous response." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size (default 50, max 200)" }, { "in": "query", "name": "status", "schema": { "type": "array", "items": { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired", "cancelled" ] } }, "description": "Filter by payment status. Accepts a single value or multiple repeated params:\n\n- Single: `?status=succeeded`\n- Multiple: `?status=succeeded&status=processing`" }, { "in": "query", "name": "referenceId", "schema": { "type": "string", "minLength": 3, "maxLength": 35, "pattern": "^[A-Za-z0-9 /:.,+-]+$", "examples": [ "order-42" ] }, "description": "Substring search on the merchant-provided reference ID. Between 3 and 35 characters. Allowed characters: ASCII letters, digits, and ` /-:.,+`." } ], "responses": { "200": { "description": "Payments with statistics", "headers": { "WCP-Version": { "description": "WalletConnect Pay API version resolved for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPaymentsResponse" }, "example": { "data": [ { "paymentId": "pay_a1a2ecc101KGF210FP7PN3BK08PZARS1CZ", "merchant": { "id": "acme-store-1", "name": "Acme Store", "iconUrl": "https://imagedelivery.net/example/icon.png" }, "referenceId": "a1b2cad4e5f2783012345678axcdea90", "status": "succeeded", "isTerminal": true, "fiatAmount": { "unit": "iso4217/USD", "value": "500", "display": { "assetSymbol": "USD", "assetName": "US Dollar", "decimals": 2 } }, "tokenAmount": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "5000000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "networkName": "Base", "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "buyer": { "accountCaip10": "eip155:8453:0x0000000000000000000000000000000000000000", "accountProviderName": "MetaMask", "accountProviderIcon": "https://api.walletconnect.com/assets/v1/image/wallet/metamask/md" }, "transaction": { "networkId": "8453", "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": 42 }, "settlement": { "amount": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "4840000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "settled": true, "txHash": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "fees": { "total": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "160000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "fixed": { "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "140000", "display": { "assetSymbol": "USDC", "assetName": "USD Coin", "decimals": 6, "iconUrl": "https://api.walletconnect.com/assets/v1/image/token/USDC/md", "networkName": "Base", "networkIconUrl": "https://api.walletconnect.com/assets/v1/image/network/eip155%3A8453/md" } }, "percentage": "0.4" }, "createdAt": "2024-01-01T12:00:00.000Z", "lastUpdatedAt": "2024-01-01T12:00:00.000Z", "settledAt": "2024-01-01T12:00:00.000Z" } ], "nextCursor": null, "stats": { "totalRevenue": [ { "amount": 1000, "currency": "USD" } ], "totalTransactions": 100, "totalCustomers": 25 } } } } }, "400": { "description": "Bad request — invalid parameters or API version", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "invalid_params", "params_validation", "invalid_api_version", "unknown_api_version", "api_version_downgrade" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } }, "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "invalid_api_version": { "summary": "Invalid API version", "value": { "code": "invalid_api_version", "message": "Invalid API version" } }, "unknown_api_version": { "summary": "Unknown API version", "value": { "code": "unknown_api_version", "message": "Unknown API version" } }, "api_version_downgrade": { "summary": "Requested API version is older than the partner pin", "value": { "code": "api_version_downgrade", "message": "Requested API version is older than the partner pin" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key, or missing merchant id", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "missing_merchant_id" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } }, "missing_merchant_id": { "summary": "Missing Merchant ID", "value": { "code": "missing_merchant_id", "message": "Missing Merchant ID" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "internal_error", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "internal_error": { "summary": "Internal Server Error", "value": { "code": "internal_error", "message": "Internal Server Error" } } } } } }, "502": { "description": "Bad gateway — upstream service returned an error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "bad_gateway", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "bad_gateway": { "summary": "Bad Gateway", "value": { "code": "bad_gateway", "message": "Bad Gateway" } } } } } } }, "tags": [ "Payments" ], "summary": "List payments for a merchant", "description": "Retrieve paginated payments with optional filters." } }, "/v1/merchants": { "post": { "operationId": "MerchantManagement_create", "tags": [ "Merchant Management" ], "summary": "Create a merchant", "description": "Create a new merchant under the authenticated partner. Requires an `Idempotency-Key` header so retries safely return the originally-created merchant rather than creating duplicates.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key to ensure idempotent request processing. Max 255 characters.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Merchant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID", "examples": [ "mrch_7kBz2qR9xPvLmN4Yw" ] }, "name": { "type": "string", "description": "Merchant display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact email", "examples": [ "billing@acme.store" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "description": "Current merchant status", "examples": [ "active" ] }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "examples": [ "2025-06-15T10:30:00.000Z" ] } }, "required": [ "id", "name", "email", "status", "createdAt" ] } }, "required": [ "merchant" ] }, "example": { "merchant": { "id": "mrch_7kBz2qR9xPvLmN4Yw", "name": "Acme Store", "email": "billing@acme.store", "status": "active", "createdAt": "2025-06-15T10:30:00.000Z" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "params_validation", "missing_idempotency_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "missing_idempotency_key": { "summary": "Missing Idempotency-Key header", "value": { "code": "missing_idempotency_key", "message": "Missing Idempotency-Key header" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "idempotency_conflict", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "idempotency_conflict": { "summary": "Idempotency key conflict: same key was used with a different request body", "value": { "code": "idempotency_conflict", "message": "Idempotency key conflict: same key was used with a different request body" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "internal_error", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "internal_error": { "summary": "Internal Server Error", "value": { "code": "internal_error", "message": "Internal Server Error" } } } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "bad_gateway", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "bad_gateway": { "summary": "Bad Gateway", "value": { "code": "bad_gateway", "message": "Bad Gateway" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Display name for the merchant", "examples": [ "Acme Store" ] }, "merchantEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Contact email for the merchant", "examples": [ "billing@acme.store" ] }, "iconUrl": { "default": null, "description": "Merchant logo URL (HTTPS only), or null to unset", "examples": [ "https://example.com/logo.png" ], "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "merchantName", "merchantEmail" ], "examples": [ { "merchantName": "Acme Store", "merchantEmail": "billing@acme.store", "iconUrl": "https://example.com/logo.png" } ] } } } } }, "get": { "operationId": "MerchantManagement_list", "tags": [ "Merchant Management" ], "summary": "List merchants", "description": "List the partner's merchants. Supports filtering by `status`, free-text `search` over name and ID, and cursor-based pagination via `cursor` and `limit`.", "responses": { "200": { "description": "Merchants list", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID", "examples": [ "mrch_7kBz2qR9xPvLmN4Yw" ] }, "name": { "type": "string", "description": "Merchant display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact email", "examples": [ "billing@acme.store" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "description": "Current merchant status", "examples": [ "active" ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchant logo URL, or null if not set", "examples": [ "https://imagedelivery.net/example/acme-icon.png" ] }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "examples": [ "2025-06-15T10:30:00.000Z" ] } }, "required": [ "id", "name", "email", "status", "iconUrl", "createdAt" ] } }, "totalCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total number of merchants matching the query (ignoring pagination)" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null if no more results" } }, "required": [ "merchants", "totalCount", "nextCursor" ] }, "example": { "merchants": [ { "id": "mrch_7kBz2qR9xPvLmN4Yw", "name": "Acme Store", "email": "billing@acme.store", "status": "active", "iconUrl": "https://imagedelivery.net/example/acme-icon.png", "createdAt": "2025-06-15T10:30:00.000Z" }, { "id": "mrch_Qx8fTp3YwKjR5vNm2", "name": "Widget Co", "email": null, "status": "active", "iconUrl": null, "createdAt": "2025-07-01T08:00:00.000Z" } ], "totalCount": 2, "nextCursor": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "params_validation", "invalid_params" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } } }, "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "inactive", "suspended" ] }, "description": "Filter by merchant status" }, { "in": "query", "name": "search", "schema": { "examples": [ "Acme" ], "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Search by merchant name or ID (case-insensitive)" }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Opaque pagination cursor — use the value from `nextCursor` in the previous response." }, { "in": "query", "name": "limit", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size (default 20, max 100)" } ] } }, "/v1/merchants/{merchantId}": { "get": { "operationId": "MerchantManagement_get", "tags": [ "Merchant Management" ], "summary": "Get a merchant", "description": "Fetch a merchant's profile along with its configured `settlements` (crypto and fiat). Crypto settlements use [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset IDs and [CAIP-10](https://chainagnostic.org/CAIPs/caip-10) destination accounts.", "responses": { "200": { "description": "Merchant details", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID", "examples": [ "mrch_7kBz2qR9xPvLmN4Yw" ] }, "name": { "type": "string", "description": "Merchant display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact email", "examples": [ "billing@acme.store" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "description": "Current merchant status", "examples": [ "active" ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchant logo URL, or null if not set", "examples": [ "https://imagedelivery.net/example/acme-icon.png" ] }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "examples": [ "2025-06-15T10:30:00.000Z" ] }, "settlements": { "type": "object", "properties": { "crypto": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Crypto settlement ID" }, "asset": { "type": "string", "description": "[CAIP-19](https://standards.chainagnostic.org/CAIPs/caip-19) asset ID", "examples": [ "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "destination": { "type": "string", "description": "[CAIP-10](https://standards.chainagnostic.org/CAIPs/caip-10) settlement destination", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "id", "asset", "destination" ] } }, "fiat": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Settlement config ID" }, "status": { "type": "string", "description": "Fiat settlement status" }, "bankType": { "type": "string", "description": "Bank account type" } }, "required": [ "id", "status", "bankType" ] } } }, "required": [ "crypto", "fiat" ] } }, "required": [ "id", "name", "email", "status", "iconUrl", "createdAt", "settlements" ] } }, "required": [ "merchant" ] }, "example": { "merchant": { "id": "mrch_7kBz2qR9xPvLmN4Yw", "name": "Acme Store", "email": "billing@acme.store", "status": "active", "iconUrl": "https://imagedelivery.net/example/acme-icon.png", "createdAt": "2025-06-15T10:30:00.000Z", "settlements": { "crypto": [ { "id": "crypto_Xk7nWp8XmQj2YrTv6", "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" } ], "fiat": [ { "id": "fiat_Bk4nWp8XmQj2YrTv6", "status": "active", "bankType": "ACH" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ] }, "patch": { "operationId": "MerchantManagement_update", "tags": [ "Merchant Management" ], "summary": "Update a merchant", "description": "Update a merchant's profile. At least one of `merchantName`, `merchantEmail`, or `iconUrl` must be provided. Pass `iconUrl: null` to unset the existing logo.", "responses": { "200": { "description": "Merchant updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID", "examples": [ "mrch_7kBz2qR9xPvLmN4Yw" ] }, "name": { "type": "string", "description": "Merchant display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact email", "examples": [ "billing@acme.store" ] }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended" ], "description": "Current merchant status", "examples": [ "active" ] }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Merchant logo URL, or null if not set", "examples": [ "https://imagedelivery.net/example/acme-icon.png" ] }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "examples": [ "2025-06-15T10:30:00.000Z" ] } }, "required": [ "id", "name", "email", "status", "iconUrl", "createdAt" ] } }, "required": [ "merchant" ] }, "example": { "merchant": { "id": "mrch_7kBz2qR9xPvLmN4Yw", "name": "Acme Store v2", "email": "billing@acme.store", "status": "active", "iconUrl": "https://imagedelivery.net/example/acme-icon.png", "createdAt": "2025-06-15T10:30:00.000Z" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "params_validation", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantName": { "description": "Updated display name", "examples": [ "Acme Store v2" ], "type": "string", "minLength": 1, "maxLength": 256 }, "merchantEmail": { "description": "Updated contact email", "examples": [ "new-billing@acme.store" ], "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "iconUrl": { "description": "Updated logo URL (HTTPS only), or null to unset", "examples": [ "https://example.com/new-logo.png" ], "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ] }, "delete": { "operationId": "MerchantManagement_delete", "tags": [ "Merchant Management" ], "summary": "Delete a merchant", "description": "Soft-delete a merchant. The merchant is hidden from listings and can no longer accept new payments. Already-deleted merchants return `deleted: true` so the call is idempotent.", "responses": { "200": { "description": "Merchant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID" }, "deleted": { "type": "boolean", "description": "Whether the merchant was successfully deleted" } }, "required": [ "id", "deleted" ] }, "example": { "id": "mrch_7kBz2qR9xPvLmN4Yw", "deleted": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ] } }, "/v1/merchants/{merchantId}/settlements": { "get": { "operationId": "Settlements_list", "tags": [ "Settlements" ], "summary": "List settlements", "description": "List the merchant's configured fiat and crypto settlement destinations.", "responses": { "200": { "description": "Settlements list", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiat": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Fiat settlement ID", "examples": [ "fiat_Bk4nWp8XmQj2YrTv6" ] }, "status": { "type": "string", "description": "Fiat settlement status", "examples": [ "active" ] }, "bankType": { "type": "string", "description": "Bank account type", "examples": [ "ACH" ] } }, "required": [ "id", "status", "bankType" ] }, "description": "Fiat settlement configurations attached to the merchant." }, "crypto": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Crypto settlement ID", "examples": [ "crypto_Xk7nWp8XmQj2YrTv6" ] }, "asset": { "type": "string", "description": "[CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset identifier", "examples": [ "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "destination": { "type": "string", "description": "[CAIP-10](https://chainagnostic.org/CAIPs/caip-10) destination wallet", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "id", "asset", "destination" ] }, "description": "Crypto settlement destinations attached to the merchant." } }, "required": [ "fiat", "crypto" ] }, "example": { "fiat": [ { "id": "fiat_Bk4nWp8XmQj2YrTv6", "status": "active", "bankType": "ACH" } ], "crypto": [ { "id": "crypto_Xk7nWp8XmQj2YrTv6", "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ] } }, "/v1/merchants/{merchantId}/settlements/crypto": { "post": { "operationId": "CryptoSettlement_create", "tags": [ "Crypto Settlement" ], "summary": "Create crypto settlements", "description": "Register one or more crypto settlement destinations for the merchant. Each entry pairs a [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) `asset` with a [CAIP-10](https://chainagnostic.org/CAIPs/caip-10) `destination` wallet on the same chain. Each `(merchant, asset)` pair must be unique — registering the same asset twice returns `settlement_asset_conflict`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key to ensure idempotent request processing. Max 255 characters.", "schema": { "type": "string", "maxLength": 255 } }, { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ], "responses": { "201": { "description": "Crypto settlements created", "content": { "application/json": { "schema": { "type": "object", "properties": { "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Crypto settlement ID", "examples": [ "crypto_Xk7nWp8XmQj2YrTv6" ] }, "asset": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}\\/[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset identifier for the token to settle in. Format: `:/:`. For example, USDC on Base is `eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.", "examples": [ "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "destination": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-10](https://chainagnostic.org/CAIPs/caip-10) account identifier for the wallet that should receive the settled funds. Format: `::
`. The chain (`:`) must match the chain of the corresponding `asset`.", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "id", "asset", "destination" ] } } }, "required": [ "settlements" ] }, "example": { "settlements": [ { "id": "crypto_Xk7nWp8XmQj2YrTv6", "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "params_validation", "invalid_params", "missing_idempotency_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } }, "missing_idempotency_key": { "summary": "Missing Idempotency-Key header", "value": { "code": "missing_idempotency_key", "message": "Missing Idempotency-Key header" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "idempotency_conflict", "settlement_asset_conflict" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "idempotency_conflict": { "summary": "Idempotency key conflict: same key was used with a different request body", "value": { "code": "idempotency_conflict", "message": "Idempotency key conflict: same key was used with a different request body" } }, "settlement_asset_conflict": { "summary": "A settlement already exists for this asset", "value": { "code": "settlement_asset_conflict", "message": "A settlement already exists for this asset" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settlements": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}\\/[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset identifier for the token to settle in. Format: `:/:`. For example, USDC on Base is `eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.", "examples": [ "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "destination": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-10](https://chainagnostic.org/CAIPs/caip-10) account identifier for the wallet that should receive the settled funds. Format: `::
`. The chain (`:`) must match the chain of the corresponding `asset`.", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "asset", "destination" ] }, "description": "List of asset/destination pairs to register. Up to 50 entries per request." } }, "required": [ "settlements" ], "examples": [ { "settlements": [ { "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" }, { "asset": "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "destination": "eip155:1:0x1234567890abcdef1234567890abcdef12345678" } ] } ] } } } } } }, "/v1/merchants/{merchantId}/settlements/crypto/{id}": { "put": { "operationId": "CryptoSettlement_update", "tags": [ "Crypto Settlement" ], "summary": "Update a crypto settlement destination", "description": "Change the destination wallet for an existing crypto settlement. The new `destination` must be a [CAIP-10](https://chainagnostic.org/CAIPs/caip-10) account on the same chain as the settlement's `asset`.", "responses": { "200": { "description": "Settlement updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Crypto settlement ID", "examples": [ "crypto_Xk7nWp8XmQj2YrTv6" ] }, "asset": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}\\/[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset identifier for the token to settle in. Format: `:/:`. For example, USDC on Base is `eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.", "examples": [ "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "destination": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-10](https://chainagnostic.org/CAIPs/caip-10) account identifier for the wallet that should receive the settled funds. Format: `::
`. The chain (`:`) must match the chain of the corresponding `asset`.", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "id", "asset", "destination" ] }, "example": { "id": "crypto_Xk7nWp8XmQj2YrTv6", "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "params_validation", "invalid_params" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } }, "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } } } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "examples": [ "crypto_Xk7nWp8XmQj2YrTv6" ] }, "required": true, "description": "Crypto settlement ID" }, { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[-a-zA-Z0-9]{3,8}:[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,128}$", "description": "[CAIP-10](https://chainagnostic.org/CAIPs/caip-10) account identifier for the wallet that should receive the settled funds. Format: `::
`. The chain (`:`) must match the chain of the corresponding `asset`.", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] } }, "required": [ "destination" ], "examples": [ { "destination": "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" } ] } } } } }, "delete": { "operationId": "CryptoSettlement_delete", "tags": [ "Crypto Settlement" ], "summary": "Delete a crypto settlement", "description": "Remove a crypto settlement. Future payments in the deleted asset will no longer be auto-settled.", "responses": { "200": { "description": "Settlement deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Crypto settlement ID" }, "deleted": { "type": "boolean", "description": "Whether the settlement was successfully deleted" } }, "required": [ "id", "deleted" ] }, "example": { "id": "crypto_Xk7nWp8XmQj2YrTv6", "deleted": true } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "not_found", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "not_found": { "summary": "Not Found", "value": { "code": "not_found", "message": "Not Found" } } } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1, "maxLength": 256, "examples": [ "crypto_Xk7nWp8XmQj2YrTv6" ] }, "required": true, "description": "Crypto settlement ID" }, { "schema": { "type": "string" }, "in": "path", "name": "merchantId", "required": true } ] } }, "/v1/merchants/{merchant_id}/payments": { "get": { "operationId": "Payments_get", "tags": [ "Payments" ], "summary": "Get payments for a merchant", "description": "**Deprecated:** Use `GET /v1/merchants/payments` with partner `api-key` and `merchant-id` headers instead.\n\nRetrieve paginated payments with optional filters.", "deprecated": true, "security": [ { "apiKeyLegacy": [] } ], "responses": { "200": { "description": "Payments with statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantLegacyPaymentsResponse" } } } }, "400": { "description": "Bad request — invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "invalid_params", "params_validation" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "issues": { "description": "Field-level validation issues (present on validation errors)", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "message", "code" ] }, "examples": { "invalid_params": { "summary": "Invalid request parameters", "value": { "code": "invalid_params", "message": "Invalid request parameters" } }, "params_validation": { "summary": "Validation failed", "value": { "code": "params_validation", "message": "Validation failed" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key" ], "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "missing_api_key": { "summary": "Missing API key", "value": { "code": "missing_api_key", "message": "Missing API key" } }, "invalid_api_key": { "summary": "Invalid API key", "value": { "code": "invalid_api_key", "message": "Invalid API key" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "internal_error", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "internal_error": { "summary": "Internal Server Error", "value": { "code": "internal_error", "message": "Internal Server Error" } } } } } }, "502": { "description": "Bad gateway — upstream service returned an error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "const": "bad_gateway", "description": "Machine-readable error code" }, "details": { "description": "Additional structured error details", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "message", "code" ] }, "examples": { "bad_gateway": { "summary": "Bad Gateway", "value": { "code": "bad_gateway", "message": "Bad Gateway" } } } } } } }, "parameters": [ { "in": "path", "name": "merchant_id", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "start_ts", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "in": "query", "name": "end_ts", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "in": "query", "name": "asset", "schema": { "type": "string" } }, { "in": "query", "name": "network", "schema": { "type": "string" } }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "date", "amount" ] } }, { "in": "query", "name": "sort_dir", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "status", "schema": { "anyOf": [ { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired" ] }, { "type": "array", "items": { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired" ] } } ] } } ] } } }, "tags": [ { "name": "Gateway" }, { "name": "Payments" }, { "name": "Refunds" }, { "name": "Merchant Management" }, { "name": "Settlements" }, { "name": "Crypto Settlement" } ], "components": { "schemas": { "Action": { "oneOf": [ { "type": "object", "description": "An action that requires a wallet RPC call to complete", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/WalletRpcAction", "description": "An action that requires a wallet RPC call to complete" }, "type": { "type": "string", "enum": [ "walletRpc" ] } } }, { "type": "object", "description": "An action that requires building to complete", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/Build", "description": "An action that requires building to complete" }, "type": { "type": "string", "enum": [ "build" ] } } } ], "example": { "data": { "chain_id": "eip155:8453", "method": "eth_signTypedData_v4", "params": [ "0x0000000000000000000000000000000000000000", "{\"domain\":{\"name\":\"USD Coin\",\"version\":\"2\",\"chainId\":\"0x2105\",\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"},\"types\":{\"EIP712Domain\":[{\"type\":\"string\",\"name\":\"name\"},{\"type\":\"string\",\"name\":\"version\"},{\"type\":\"uint256\",\"name\":\"chainId\"},{\"type\":\"address\",\"name\":\"verifyingContract\"}],\"ReceiveWithAuthorization\":[{\"type\":\"address\",\"name\":\"from\"},{\"type\":\"address\",\"name\":\"to\"},{\"type\":\"uint256\",\"name\":\"value\"},{\"type\":\"uint256\",\"name\":\"validAfter\"},{\"type\":\"uint256\",\"name\":\"validBefore\"},{\"type\":\"bytes32\",\"name\":\"nonce\"}]},\"primaryType\":\"ReceiveWithAuthorization\",\"message\":{\"from\":\"0x0000000000000000000000000000000000000000\",\"nonce\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"to\":\"0x0000000000000000000000000000000000000000\",\"validAfter\":\"0x0\",\"validBefore\":\"0x0\",\"value\":\"0x0\"}}" ] }, "type": "walletRpc" } }, "Amount": { "type": "object", "required": [ "unit", "value", "display" ], "properties": { "display": { "$ref": "#/components/schemas/AmountDisplay", "description": "Display information for the amount" }, "unit": { "type": "string", "description": "Currency unit, prefixed with either \"iso4217/\" or \"caip19/\"", "example": "iso4217/USD" }, "value": { "type": "string", "description": "Amount value, in the currency unit's minor units" } }, "example": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" } }, "AmountDisplay": { "type": "object", "required": [ "assetSymbol", "assetName", "decimals" ], "properties": { "assetName": { "type": "string", "description": "Full name of the asset" }, "assetSymbol": { "type": "string", "description": "Ticker/symbol of the asset" }, "decimals": { "type": "integer", "format": "int32", "description": "Number of minor decimals of the asset", "minimum": 0 }, "iconUrl": { "type": [ "string", "null" ], "description": "URL of the icon of the asset (if token)" }, "networkIconUrl": { "type": [ "string", "null" ], "description": "URL of the icon of the network (if token)" }, "networkName": { "type": [ "string", "null" ], "description": "Name of the network of the asset (if token)" } }, "example": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" } }, "AmountParameter": { "type": "object", "required": [ "unit", "value" ], "properties": { "unit": { "type": "string", "description": "Currency unit, prefixed with either \"iso4217/\" or \"caip19/\"", "example": "iso4217/USD" }, "value": { "type": "string", "description": "Amount value, in the currency unit's minor units" } }, "example": { "unit": "iso4217/USD", "value": "100" } }, "Build": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string" } }, "example": { "data": "..." } }, "BuyerInfo": { "type": "object", "required": [ "accountCaip10", "accountProviderName" ], "properties": { "accountCaip10": { "type": "string", "description": "Account CAIP-10" }, "accountProviderIcon": { "type": [ "string", "null" ], "description": "Account provider icon URL" }, "accountProviderName": { "type": "string", "description": "Account provider name" } }, "example": { "accountCaip10": "eip155:1:0x0000000000000000000000000000000000000000", "accountProviderIcon": "https://example.com/icon.png", "accountProviderName": "Wallet" } }, "CheckoutConfig": { "type": "object", "required": [ "successUrl", "errorUrl" ], "properties": { "errorUrl": { "type": "string", "description": "HTTPS URL to redirect to on payment error" }, "successUrl": { "type": "string", "description": "HTTPS URL to redirect to on successful payment" } }, "example": { "errorUrl": "https://example.com/error", "successUrl": "https://example.com/success" } }, "CollectData": { "type": "object", "required": [ "fields", "schema", "url" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/CollectDataField" }, "description": "Deprecated: Use `schema` and `url` fields instead for webview-based data collection", "deprecated": true }, "schema": { "description": "JSON Schema for validating IC form data (for webview mode)" }, "url": { "type": "string", "description": "URL for webview-based data collection" } }, "example": { "fields": [ { "id": "fullName", "name": "Full name", "required": true, "type": "text" }, { "id": "dob", "name": "Date of birth", "required": true, "type": "date" } ], "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "anyOf": [ { "required": [ "pobCountry", "pobAddress" ] }, { "required": [ "porCountry", "porAddress" ] } ], "properties": { "dob": { "description": "Date of birth in YYYY-MM-DD format", "format": "date", "title": "Date of Birth", "type": "string" }, "fullName": { "description": "User's full legal name", "minLength": 1, "title": "Full Name", "type": "string" }, "pobAddress": { "description": "Place of birth city and state (e.g., 'New York, NY')", "maxLength": 200, "title": "Place of Birth Address", "type": "string" }, "pobCountry": { "description": "Place of birth country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Birth Country", "type": "string" }, "porAddress": { "description": "Place of residence street address, city, and state", "maxLength": 200, "title": "Place of Residence Address", "type": "string" }, "porCountry": { "description": "Place of residence country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Residence Country", "type": "string" }, "tosConfirmed": { "const": true, "description": "Must be true to confirm Terms of Service acceptance", "title": "Terms of Service Confirmation", "type": "boolean" } }, "required": [ "fullName", "dob", "tosConfirmed" ], "type": "object" }, "url": "https://data-collection.walletconnect.com/ic/pay_123?accounts=eip155:1:0x123" } }, "CollectDataField": { "type": "object", "required": [ "type", "id", "name", "required" ], "properties": { "id": { "type": "string", "description": "ID of the field for submission" }, "name": { "type": "string", "description": "Human readable name of the field" }, "required": { "type": "boolean", "description": "Requiredness of the field" }, "type": { "$ref": "#/components/schemas/CollectDataFieldType", "description": "Type of the field" } }, "example": { "id": "fullName", "name": "Full name", "required": true, "type": "text" } }, "CollectDataFieldResult": { "type": "object", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "string" } }, "example": { "id": "fullName", "value": "John" } }, "CollectDataFieldType": { "type": "string", "enum": [ "text", "date", "checkbox" ] }, "CollectDataResult": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/CollectDataFieldResult" } } }, "example": { "fields": [ { "id": "fullName", "value": "John Smith" }, { "id": "dob", "value": "1990-01-01" }, { "id": "tosConfirmed", "value": "true" }, { "id": "pobCountry", "value": "US" }, { "id": "pobAddress", "value": "New York, NY" } ] } }, "ConfirmPaymentRequest": { "type": "object", "required": [ "optionId", "results" ], "properties": { "collectedData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CollectDataResult" } ] }, "optionId": { "type": "string", "description": "ID of the option to confirm" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConfirmPaymentResult" } } }, "example": { "collectedData": { "fields": [ { "id": "fullName", "value": "John Smith" }, { "id": "dob", "value": "1990-01-01" }, { "id": "tosConfirmed", "value": "true" }, { "id": "pobCountry", "value": "US" }, { "id": "pobAddress", "value": "New York, NY" } ] }, "excludeFromRelayer": null, "optionId": "opt_123", "results": [ { "data": [ "0x123" ], "type": "walletRpc" } ] } }, "ConfirmPaymentResponse": { "type": "object", "required": [ "status", "isFinal" ], "properties": { "info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GatewayPaymentInformation", "description": "Payment information (transaction hash). Present when status is\nSucceeded, null otherwise." } ] }, "isFinal": { "type": "boolean", "description": "True if the payment is in a final state and no longer requires polling" }, "pollInMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Time to poll for payment status, in milliseconds. Not present if the\npayment is in a final state.", "minimum": 0 }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Payment status" } }, "example": { "info": null, "isFinal": true, "pollInMs": null, "status": "succeeded" } }, "ConfirmPaymentResult": { "oneOf": [ { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "type": "array", "items": {} }, "type": { "type": "string", "enum": [ "walletRpc" ] } } } ], "example": { "data": [ "0x123" ], "type": "walletRpc" } }, "CreatePayment": { "type": "object", "required": [ "referenceId", "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/AmountParameter", "description": "Amount to be paid" }, "checkout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CheckoutConfig" } ] }, "expiresAt": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional custom expiration timestamp (Unix seconds since epoch).\nMust be in the future if provided. If not provided, defaults to 5 minutes from now." }, "referenceId": { "type": "string", "description": "Merchant/PSP order ID" } }, "example": { "amount": { "unit": "iso4217/USD", "value": "100" }, "checkout": null, "expiresAt": null, "referenceId": "ORDER-123" } }, "CreatePaymentResponse": { "type": "object", "required": [ "paymentId", "status", "expiresAt", "isFinal", "gatewayUrl" ], "properties": { "expiresAt": { "type": "integer", "format": "int64", "description": "Payment expiration timestamp, in seconds since epoch", "minimum": 0 }, "gatewayUrl": { "type": "string", "description": "Gateway URL to redirect the user to for payment" }, "isFinal": { "type": "boolean", "description": "True if the payment is in a final state and no longer requires polling" }, "paymentId": { "$ref": "#/components/schemas/PaymentId", "description": "Payment ID" }, "pollInMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Time to poll for payment status, in milliseconds. Not present if the\npayment is in a final state.", "minimum": 0 }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Payment status" } }, "example": { "expiresAt": 1718236800, "gatewayUrl": "https://api.pay.walletconnect.com/pay_123", "isFinal": false, "paymentId": "pay_fea2ecc101KQFN7X7QP87PNA9SVQNAQAFP", "pollInMs": 1000, "status": "requires_action" } }, "ErrorCode": { "type": "string", "description": "Standard error codes for API responses.\n\nThis prevents typos like \"invlaid_params\" from reaching production.", "enum": [ "rate_limited", "invalid_params", "params_validation", "payment_not_found", "idempotency_conflict", "internal_error", "invalid_api_key", "unauthorized", "forbidden", "invalid_state", "payment_expired", "quote_expired", "missing_api_key", "missing_merchant_api_key", "missing_merchant_id", "header_not_ascii", "not_sandbox_api_key", "merchant_not_found", "merchant_exists", "api_key_not_found", "partner_not_found", "customer_not_found", "wallet_not_found", "executor_not_found", "missing_app_id", "missing_client_id", "invalid_app_id", "conflicting_auth_headers", "missing_auth_headers", "invalid_api_version", "unknown_api_version", "api_version_downgrade", "sanctioned_user", "payment_not_succeeded", "already_refunded" ] }, "ErrorResponse": { "type": "object", "description": "Standard error response structure for API errors.", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" } } }, "FetchRequest": { "type": "object", "required": [ "optionId", "data" ], "properties": { "data": { "type": "string", "description": "Extra build payload" }, "optionId": { "type": "string", "description": "ID of the option to build an action for" } }, "example": { "data": "...", "optionId": "opt_123" } }, "FetchResponse": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "example": { "actions": [ { "data": { "chain_id": "eip155:8453", "method": "eth_signTypedData_v4", "params": [ "0x0000000000000000000000000000000000000000", "{\"domain\":{\"name\":\"USD Coin\",\"version\":\"2\",\"chainId\":\"0x2105\",\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"},\"types\":{\"EIP712Domain\":[{\"type\":\"string\",\"name\":\"name\"},{\"type\":\"string\",\"name\":\"version\"},{\"type\":\"uint256\",\"name\":\"chainId\"},{\"type\":\"address\",\"name\":\"verifyingContract\"}],\"ReceiveWithAuthorization\":[{\"type\":\"address\",\"name\":\"from\"},{\"type\":\"address\",\"name\":\"to\"},{\"type\":\"uint256\",\"name\":\"value\"},{\"type\":\"uint256\",\"name\":\"validAfter\"},{\"type\":\"uint256\",\"name\":\"validBefore\"},{\"type\":\"bytes32\",\"name\":\"nonce\"}]},\"primaryType\":\"ReceiveWithAuthorization\",\"message\":{\"from\":\"0x0000000000000000000000000000000000000000\",\"nonce\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"to\":\"0x0000000000000000000000000000000000000000\",\"validAfter\":\"0x0\",\"validBefore\":\"0x0\",\"value\":\"0x0\"}}" ] }, "type": "walletRpc" } ] } }, "GatewayCancelPaymentResponse": { "type": "object", "required": [ "paymentId", "status", "cancelledReason", "cancelledAt" ], "properties": { "cancelledAt": { "type": "string" }, "cancelledReason": { "type": "string" }, "paymentId": { "$ref": "#/components/schemas/PaymentId" }, "status": { "$ref": "#/components/schemas/PaymentStatus" } }, "example": { "cancelledAt": "2025-01-14T10:30:00Z", "cancelledReason": "cancelled_by_user", "paymentId": "pay_c4a2ecc101KQFN7X7RZACHTYV7JX5C4QET", "status": "cancelled" } }, "GatewayPaymentInformation": { "type": "object", "description": "Payment information returned when a gateway payment succeeds.", "required": [ "txId", "optionAmount" ], "properties": { "optionAmount": { "$ref": "#/components/schemas/Amount", "description": "Amount paid in token units" }, "txId": { "type": "string", "description": "Transaction identifier (hash)" } } }, "GetPaymentOptionsRequest": { "type": "object", "required": [ "accounts" ], "properties": { "accounts": { "type": "array", "items": { "type": "string" } }, "refresh": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "example": { "accounts": [ "eip155:8453:0x123" ], "refresh": null } }, "GetPaymentOptionsResponse": { "type": "object", "properties": { "collectData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CollectData" } ] }, "info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GetPaymentResponse" } ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PaymentOption" } } }, "example": { "collectData": { "fields": [ { "id": "fullName", "name": "Full name", "required": true, "type": "text" }, { "id": "dob", "name": "Date of birth", "required": true, "type": "date" } ], "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "anyOf": [ { "required": [ "pobCountry", "pobAddress" ] }, { "required": [ "porCountry", "porAddress" ] } ], "properties": { "dob": { "description": "Date of birth in YYYY-MM-DD format", "format": "date", "title": "Date of Birth", "type": "string" }, "fullName": { "description": "User's full legal name", "minLength": 1, "title": "Full Name", "type": "string" }, "pobAddress": { "description": "Place of birth city and state (e.g., 'New York, NY')", "maxLength": 200, "title": "Place of Birth Address", "type": "string" }, "pobCountry": { "description": "Place of birth country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Birth Country", "type": "string" }, "porAddress": { "description": "Place of residence street address, city, and state", "maxLength": 200, "title": "Place of Residence Address", "type": "string" }, "porCountry": { "description": "Place of residence country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Residence Country", "type": "string" }, "tosConfirmed": { "const": true, "description": "Must be true to confirm Terms of Service acceptance", "title": "Terms of Service Confirmation", "type": "boolean" } }, "required": [ "fullName", "dob", "tosConfirmed" ], "type": "object" }, "url": "https://data-collection.walletconnect.com/ic/pay_123?accounts=eip155:1:0x123" }, "info": { "amount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "buyer": { "accountCaip10": "eip155:1:0x0000000000000000000000000000000000000000", "accountProviderIcon": "https://example.com/icon.png", "accountProviderName": "Wallet" }, "expiresAt": 1700000000, "merchant": { "iconUrl": "https://example.com/icon.png", "name": "Merchant" }, "status": "requires_action" }, "options": [ { "account": "eip155:1:0x0000000000000000000000000000000000000000", "actions": [ { "data": { "chain_id": "eip155:8453", "method": "eth_signTypedData_v4", "params": [ "0x0000000000000000000000000000000000000000", "{\"domain\":{\"name\":\"USD Coin\",\"version\":\"2\",\"chainId\":\"0x2105\",\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"},\"types\":{\"EIP712Domain\":[{\"type\":\"string\",\"name\":\"name\"},{\"type\":\"string\",\"name\":\"version\"},{\"type\":\"uint256\",\"name\":\"chainId\"},{\"type\":\"address\",\"name\":\"verifyingContract\"}],\"ReceiveWithAuthorization\":[{\"type\":\"address\",\"name\":\"from\"},{\"type\":\"address\",\"name\":\"to\"},{\"type\":\"uint256\",\"name\":\"value\"},{\"type\":\"uint256\",\"name\":\"validAfter\"},{\"type\":\"uint256\",\"name\":\"validBefore\"},{\"type\":\"bytes32\",\"name\":\"nonce\"}]},\"primaryType\":\"ReceiveWithAuthorization\",\"message\":{\"from\":\"0x0000000000000000000000000000000000000000\",\"nonce\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"to\":\"0x0000000000000000000000000000000000000000\",\"validAfter\":\"0x0\",\"validBefore\":\"0x0\",\"value\":\"0x0\"}}" ] }, "type": "walletRpc" } ], "amount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "collectData": { "fields": [ { "id": "fullName", "name": "Full name", "required": true, "type": "text" }, { "id": "dob", "name": "Date of birth", "required": true, "type": "date" } ], "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "anyOf": [ { "required": [ "pobCountry", "pobAddress" ] }, { "required": [ "porCountry", "porAddress" ] } ], "properties": { "dob": { "description": "Date of birth in YYYY-MM-DD format", "format": "date", "title": "Date of Birth", "type": "string" }, "fullName": { "description": "User's full legal name", "minLength": 1, "title": "Full Name", "type": "string" }, "pobAddress": { "description": "Place of birth city and state (e.g., 'New York, NY')", "maxLength": 200, "title": "Place of Birth Address", "type": "string" }, "pobCountry": { "description": "Place of birth country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Birth Country", "type": "string" }, "porAddress": { "description": "Place of residence street address, city, and state", "maxLength": 200, "title": "Place of Residence Address", "type": "string" }, "porCountry": { "description": "Place of residence country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Residence Country", "type": "string" }, "tosConfirmed": { "const": true, "description": "Must be true to confirm Terms of Service acceptance", "title": "Terms of Service Confirmation", "type": "boolean" } }, "required": [ "fullName", "dob", "tosConfirmed" ], "type": "object" }, "url": "https://data-collection.walletconnect.com/ic/pay_123?accounts=eip155:1:0x123" }, "etaS": 5, "expiresAt": 1700000300, "id": "opt_123" } ] } }, "GetPaymentResponse": { "type": "object", "required": [ "status", "amount", "expiresAt", "merchant" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "buyer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerInfo" } ] }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "status": { "$ref": "#/components/schemas/PaymentStatus" } }, "example": { "amount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "buyer": { "accountCaip10": "eip155:1:0x0000000000000000000000000000000000000000", "accountProviderIcon": "https://example.com/icon.png", "accountProviderName": "Wallet" }, "expiresAt": 1700000000, "merchant": { "iconUrl": "https://example.com/icon.png", "name": "Merchant" }, "status": "requires_action" } }, "GetPaymentStatusResponse": { "type": "object", "required": [ "status", "isFinal" ], "properties": { "failureCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentFailureCode", "description": "Machine-readable reason identifying why the payment failed. Present\nonly when `status == \"failed\"`." } ] }, "info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentInformation", "description": "Payment information (transaction hash, amount). Present when status is\nSucceeded, null otherwise." } ] }, "isFinal": { "type": "boolean", "description": "True if the payment is in a final state and no longer requires polling" }, "pollInMs": { "type": [ "integer", "null" ], "format": "int64", "description": "Time to poll for payment status, in milliseconds. Not present if the\npayment is in a final state.", "minimum": 0 }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Payment status" } }, "example": { "info": { "optionAmount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "txId": "0xabc123..." }, "isFinal": true, "pollInMs": null, "status": "succeeded" } }, "MerchantInfo": { "type": "object", "required": [ "name" ], "properties": { "iconUrl": { "type": [ "string", "null" ], "description": "Merchant icon URL" }, "name": { "type": "string", "description": "Merchant name" } }, "example": { "iconUrl": "https://example.com/icon.png", "name": "Merchant" } }, "PaymentFailureCode": { "type": "string", "description": "Machine-readable code identifying why a payment reached `Failed`.\n\nTwo distinct string forms exist per variant:\n- **Strum** (`Display`/`AsRefStr`/`EnumString`): the DynamoDB storage form\n written to the `failure_reason` column. Preserves the existing on-disk\n value for rows written before this type existed.\n- **Serde** (`Serialize`/`Deserialize`): the public API form. Deliberately\n decoupled from the internal term so that compliance-specific wording\n isn't surfaced to external consumers.", "enum": [ "declined_user" ] }, "PaymentId": { "type": "string", "description": "Payment ID", "examples": [ "pay_7fa2ecc101ARZ3NDEKTSV4RRFFQ69G5FAV" ] }, "PaymentInformation": { "type": "object", "description": "Payment information returned when payment succeeds", "required": [ "txId", "optionAmount" ], "properties": { "optionAmount": { "$ref": "#/components/schemas/Amount", "description": "Amount paid in token units" }, "txId": { "type": "string", "description": "Transaction identifier (hash)" } }, "example": { "optionAmount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "txId": "0xabc123..." } }, "PaymentOption": { "type": "object", "required": [ "id", "account", "amount", "etaS", "actions" ], "properties": { "account": { "type": "string", "description": "The account to use for the option" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" }, "description": "Actions required to complete the option" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "The option's token and amount" }, "collectData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CollectData", "description": "Per-option IC data collection info. Present when this option's account requires data collection, null otherwise." } ] }, "etaS": { "type": "integer", "format": "int64", "description": "Estimated time to complete the option, in seconds", "minimum": 0 }, "expiresAt": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp (seconds) after which this quote is stale and confirm_payment\nwill reject it with `quote_expired`. The wallet should re-fetch options before\nthis deadline. `None` for direct-currency options that don't involve a rate.", "minimum": 0 }, "id": { "type": "string", "description": "ID of the option to be used to refer to it in other requests. May be up to 2^16 characters." } }, "example": { "account": "eip155:1:0x0000000000000000000000000000000000000000", "actions": [ { "data": { "chain_id": "eip155:8453", "method": "eth_signTypedData_v4", "params": [ "0x0000000000000000000000000000000000000000", "{\"domain\":{\"name\":\"USD Coin\",\"version\":\"2\",\"chainId\":\"0x2105\",\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"},\"types\":{\"EIP712Domain\":[{\"type\":\"string\",\"name\":\"name\"},{\"type\":\"string\",\"name\":\"version\"},{\"type\":\"uint256\",\"name\":\"chainId\"},{\"type\":\"address\",\"name\":\"verifyingContract\"}],\"ReceiveWithAuthorization\":[{\"type\":\"address\",\"name\":\"from\"},{\"type\":\"address\",\"name\":\"to\"},{\"type\":\"uint256\",\"name\":\"value\"},{\"type\":\"uint256\",\"name\":\"validAfter\"},{\"type\":\"uint256\",\"name\":\"validBefore\"},{\"type\":\"bytes32\",\"name\":\"nonce\"}]},\"primaryType\":\"ReceiveWithAuthorization\",\"message\":{\"from\":\"0x0000000000000000000000000000000000000000\",\"nonce\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"to\":\"0x0000000000000000000000000000000000000000\",\"validAfter\":\"0x0\",\"validBefore\":\"0x0\",\"value\":\"0x0\"}}" ] }, "type": "walletRpc" } ], "amount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "collectData": { "fields": [ { "id": "fullName", "name": "Full name", "required": true, "type": "text" }, { "id": "dob", "name": "Date of birth", "required": true, "type": "date" } ], "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "anyOf": [ { "required": [ "pobCountry", "pobAddress" ] }, { "required": [ "porCountry", "porAddress" ] } ], "properties": { "dob": { "description": "Date of birth in YYYY-MM-DD format", "format": "date", "title": "Date of Birth", "type": "string" }, "fullName": { "description": "User's full legal name", "minLength": 1, "title": "Full Name", "type": "string" }, "pobAddress": { "description": "Place of birth city and state (e.g., 'New York, NY')", "maxLength": 200, "title": "Place of Birth Address", "type": "string" }, "pobCountry": { "description": "Place of birth country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Birth Country", "type": "string" }, "porAddress": { "description": "Place of residence street address, city, and state", "maxLength": 200, "title": "Place of Residence Address", "type": "string" }, "porCountry": { "description": "Place of residence country code (ISO 3166-1 alpha-2)", "pattern": "^[A-Z]{2}$", "title": "Place of Residence Country", "type": "string" }, "tosConfirmed": { "const": true, "description": "Must be true to confirm Terms of Service acceptance", "title": "Terms of Service Confirmation", "type": "boolean" } }, "required": [ "fullName", "dob", "tosConfirmed" ], "type": "object" }, "url": "https://data-collection.walletconnect.com/ic/pay_123?accounts=eip155:1:0x123" }, "etaS": 5, "expiresAt": 1700000300, "id": "opt_123" } }, "PaymentStatus": { "type": "string", "description": "Payment status representing the lifecycle of a payment.\n\nPayments progress through these states from creation to terminal status.\nSome states are specific to the payment source (pull vs push).", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired", "cancelled" ] }, "PaymentsCancelPaymentResponse": { "type": "object", "required": [ "paymentId", "status", "cancelledReason", "cancelledAt" ], "properties": { "cancelledAt": { "type": "string" }, "cancelledReason": { "type": "string" }, "paymentId": { "$ref": "#/components/schemas/PaymentId" }, "status": { "$ref": "#/components/schemas/PaymentStatus" } }, "example": { "cancelledAt": "2025-01-14T10:30:00Z", "cancelledReason": "cancelled_by_merchant", "paymentId": "pay_71a2ecc101KQFN7X7RM3Z9GB4ZGNM17TRB", "status": "cancelled" } }, "PaymentsGetPaymentResponse": { "type": "object", "required": [ "status", "referenceId" ], "properties": { "failureCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentFailureCode", "description": "Machine-readable reason identifying why the payment failed. Present\nonly when `status == \"failed\"`." } ] }, "info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentInformation", "description": "Payment information (transaction hash, amount). Present when status is\nSucceeded, null otherwise." } ] }, "referenceId": { "type": "string", "description": "Merchant-provided reference ID for this payment, as supplied during\npayment creation" }, "settlement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentsSettlementInformation", "description": "Settlement metadata for the MTA → destination transfer. Null when\nsettlement has not completed yet (pending, non-MTA flows, or\npre-confirmation)." } ] }, "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Payment status" } }, "example": { "info": { "optionAmount": { "display": { "assetName": "USD Coin", "assetSymbol": "USDC", "decimals": 6, "iconUrl": "https://assets.walletconnect.com/usdc.png", "networkIconUrl": "https://assets.walletconnect.com/base.png", "networkName": "Base" }, "unit": "caip19/eip155:8453/erc20:0x0000000000000000000000000000000000000000", "value": "1000000" }, "txId": "0xabc123..." }, "referenceId": "ORDER-123", "settlement": null, "status": "succeeded" } }, "PaymentsSettlementAmount": { "type": "object", "description": "Amount information for a successful settlement transfer.", "required": [ "unit" ], "properties": { "unit": { "type": "string", "description": "Settlement unit — the asset or currency used in the settlement\ntransfer. Uses the same unit format as payment amounts\n(e.g. \"caip19/eip155:1/erc20:0xA0b86...\" for crypto,\n\"iso4217/USD\" for fiat).", "example": "iso4217/USD" } } }, "PaymentsSettlementInformation": { "type": "object", "description": "Settlement metadata returned for MTA-based payments.\n\nOnly present once the settlement transfer has completed on-chain.", "properties": { "successful": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentsSettlementSuccessful", "description": "Settlement success details. Null while settlement is pending,\npopulated once the on-chain transfer completes successfully." } ] } }, "example": { "successful": { "amount": { "unit": "caip19/eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }, "txId": "0xabc123def456789abc123def456789abc123def456789abc123def456789abc1" } } }, "PaymentsSettlementSuccessful": { "type": "object", "description": "Details of a successful settlement transfer.", "required": [ "txId", "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/PaymentsSettlementAmount", "description": "Settlement amount — the asset/currency and value transferred." }, "txId": { "type": "string", "description": "Transaction hash of the MTA → settlement destination transfer." } }, "example": { "amount": { "unit": "caip19/eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }, "txId": "0xabc123def456789abc123def456789abc123def456789abc123def456789abc1" } }, "WalletRpcAction": { "type": "object", "required": [ "chain_id", "method", "params" ], "properties": { "chain_id": { "type": "string" }, "method": { "type": "string" }, "params": { "type": "array", "items": {} } }, "example": { "chain_id": "eip155:8453", "method": "eth_signTypedData_v4", "params": [ "0x0000000000000000000000000000000000000000", "{\"domain\":{\"name\":\"USD Coin\",\"version\":\"2\",\"chainId\":\"0x2105\",\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"},\"types\":{\"EIP712Domain\":[{\"type\":\"string\",\"name\":\"name\"},{\"type\":\"string\",\"name\":\"version\"},{\"type\":\"uint256\",\"name\":\"chainId\"},{\"type\":\"address\",\"name\":\"verifyingContract\"}],\"ReceiveWithAuthorization\":[{\"type\":\"address\",\"name\":\"from\"},{\"type\":\"address\",\"name\":\"to\"},{\"type\":\"uint256\",\"name\":\"value\"},{\"type\":\"uint256\",\"name\":\"validAfter\"},{\"type\":\"uint256\",\"name\":\"validBefore\"},{\"type\":\"bytes32\",\"name\":\"nonce\"}]},\"primaryType\":\"ReceiveWithAuthorization\",\"message\":{\"from\":\"0x0000000000000000000000000000000000000000\",\"nonce\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"to\":\"0x0000000000000000000000000000000000000000\",\"validAfter\":\"0x0\",\"validBefore\":\"0x0\",\"value\":\"0x0\"}}" ] } }, "MerchantApiErrorCode": { "type": "string", "enum": [ "invalid_params", "params_validation", "not_found", "internal_error", "bad_gateway", "settlement_asset_conflict", "missing_api_key", "invalid_api_key", "missing_merchant_id", "invalid_api_version", "unknown_api_version", "api_version_downgrade", "idempotency_conflict", "version_conflict", "missing_idempotency_key", "payment_not_succeeded", "already_refunded" ], "description": "Machine-readable error code" }, "MerchantApiErrorResponse": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "$ref": "#/components/schemas/MerchantApiErrorCode" }, "issues": { "type": "array", "description": "Field-level validation issues (present on validation errors)", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "MerchantPaymentFiatAmount": { "type": "object", "properties": { "unit": { "type": "string", "pattern": "^iso4217\\/", "description": "Fiat unit, for example \"iso4217/USD\"" }, "value": { "type": "string", "description": "Amount in minor units for the fiat currency" }, "display": { "type": "object", "properties": { "assetSymbol": { "type": "string" }, "assetName": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "assetSymbol", "assetName", "decimals" ], "description": "Display metadata for fiat-denominated amounts" } }, "required": [ "unit", "value", "display" ], "description": "Fiat-denominated amount" }, "MerchantPaymentTokenAmount": { "type": "object", "properties": { "unit": { "type": "string", "pattern": "^caip19\\/", "description": "Token unit, for example \"caip19/...\"" }, "value": { "type": "string", "description": "Amount in minor units for the token asset" }, "display": { "anyOf": [ { "type": "object", "properties": { "assetSymbol": { "type": "string" }, "assetName": { "type": "string" }, "decimals": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "iconUrl": { "type": "string" }, "networkName": { "type": "string" }, "networkIconUrl": { "type": "string" } }, "required": [ "assetSymbol", "assetName", "decimals" ], "description": "Display metadata for token-denominated amounts" }, { "type": "null" } ] } }, "required": [ "unit", "value", "display" ], "description": "Token-denominated amount" }, "MerchantPaymentSettlement": { "description": "Settlement details. Omitted when settlement details cannot be reported yet. When present, `settled` is always included. When `settled` is `false`, no additional settlement fields are returned. When `settled` is `true`, `amount` and `txHash` are always included.", "type": "object", "properties": { "settled": { "type": "boolean", "description": "Whether settlement is complete." }, "amount": { "description": "Net settlement amount after fees in the settlement unit. Present only when `settled` is `true`.", "anyOf": [ { "$ref": "#/components/schemas/MerchantPaymentFiatAmount" }, { "$ref": "#/components/schemas/MerchantPaymentTokenAmount" } ] }, "txHash": { "description": "Settlement transaction hash. Present only when `settled` is `true`.", "type": "string" } }, "required": [ "settled" ] }, "MerchantPaymentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Unique payment identifier" }, "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Partner-provided merchant ID" }, "name": { "description": "Merchant display name", "type": "string" }, "iconUrl": { "description": "Merchant logo URL", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ] }, "referenceId": { "type": "string", "description": "Idempotency / reference ID provided at payment creation" }, "status": { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired", "cancelled" ] }, "isTerminal": { "type": "boolean", "description": "Whether the payment has reached a final state" }, "fiatAmount": { "$ref": "#/components/schemas/MerchantPaymentFiatAmount" }, "tokenAmount": { "$ref": "#/components/schemas/MerchantPaymentTokenAmount" }, "buyer": { "description": "Buyer wallet information", "type": "object", "properties": { "accountCaip10": { "type": "string", "description": "Buyer address as a [CAIP-10](https://standards.chainagnostic.org/CAIPs/caip-10) account ID", "examples": [ "eip155:8453:0x1234567890abcdef1234567890abcdef12345678" ] }, "accountProviderName": { "description": "Wallet provider name", "examples": [ "MetaMask" ], "type": "string" }, "accountProviderIcon": { "description": "Wallet provider logo URL", "type": "string" } }, "required": [ "accountCaip10" ] }, "transaction": { "description": "On-chain transaction details", "type": "object", "properties": { "networkId": { "type": "string", "description": "Numeric chain ID", "examples": [ "8453" ] }, "hash": { "description": "On-chain transaction hash", "type": "string" }, "nonce": { "description": "Transaction nonce", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "networkId" ] }, "fees": { "description": "Fee breakdown derived from payment option data. Omitted when total fee data is unavailable.", "type": "object", "properties": { "total": { "anyOf": [ { "$ref": "#/components/schemas/MerchantPaymentFiatAmount" }, { "$ref": "#/components/schemas/MerchantPaymentTokenAmount" } ], "description": "Total fee amount." }, "fixed": { "description": "Fixed fee component.", "anyOf": [ { "$ref": "#/components/schemas/MerchantPaymentFiatAmount" }, { "$ref": "#/components/schemas/MerchantPaymentTokenAmount" } ] }, "percentage": { "description": "Percentage fee component as a decimal percentage string, not a ratio. For example, \"0.4\" means 0.4%.", "type": "string" } }, "required": [ "total" ] }, "settlement": { "$ref": "#/components/schemas/MerchantPaymentSettlement" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp" }, "lastUpdatedAt": { "type": "string", "description": "ISO 8601 timestamp" }, "settledAt": { "description": "ISO 8601 timestamp, present only when `settlement.settled` is `true`", "type": "string" } }, "required": [ "paymentId", "merchant", "referenceId", "status", "isTerminal", "createdAt", "lastUpdatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or null if no more results" }, "stats": { "type": "object", "properties": { "totalRevenue": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Revenue amount in currency's standard unit" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "examples": [ "USD" ] } }, "required": [ "amount", "currency" ] } }, "totalTransactions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total payments matching the query" }, "totalCustomers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unique buyers matching the query" } }, "required": [ "totalRevenue", "totalTransactions", "totalCustomers" ], "description": "Aggregate statistics for the query" } }, "required": [ "data", "nextCursor", "stats" ] }, "MerchantLegacyPaymentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string" }, "merchant_id": { "type": "string" }, "reference_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requires_action", "processing", "succeeded", "failed", "expired" ] }, "is_terminal": { "type": "boolean" }, "wallet_name": { "type": "string" }, "chain_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "buyer_caip10": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_caip19": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tx_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nonce": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ] }, "token_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fiat_amount": { "anyOf": [ { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, { "type": "null" } ] }, "fiat_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_tx_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_decimals": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "token_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "chain_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "wallet_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "payment_id", "merchant_id", "reference_id", "status", "is_terminal", "wallet_name", "token_symbol", "token_decimals", "token_logo", "chain_logo", "wallet_logo" ] } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stats": { "type": "object", "properties": { "total_customers": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "total_revenue": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "total_transactions": { "type": "integer", "minimum": 0, "maximum": 2147483647 } }, "required": [ "total_customers", "total_revenue", "total_transactions" ] } }, "required": [ "data", "stats" ] } }, "securitySchemes": { "API Key": { "type": "apiKey", "in": "header", "name": "Api-Key" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "Private API key for wallet authentication" }, "AppId": { "type": "apiKey", "in": "header", "name": "App-Id", "description": "Public App ID for wallet authentication. When using this auth mode, the Client-Id header is also required." }, "apiKey": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "Partner API key." }, "apiKeyLegacy": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "**Deprecated.** Legacy service API key for path-based routes. `Api-Key` header is also accepted for backward compatibility." } } }, "security": [ { "API Key": [] }, { "ApiKey": [] }, { "AppId": [] } ] }