{ "openapi": "3.0.0", "paths": { "/v2/currencies": { "get": { "description": "Get a list of all available tokens, or filter by network, symbol, or id.", "operationId": "CurrenciesV2Controller_getNetworkTokens_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } }, { "name": "network", "required": false, "in": "query", "description": "The network of the token(s)", "schema": { "example": "mainnet", "type": "string" } }, { "name": "symbol", "required": false, "in": "query", "description": "The symbol of the token", "schema": { "example": "USDC", "type": "string" } }, { "name": "firstOnly", "required": false, "in": "query", "description": "Whether to return only the first token. can only be used when both `network` and `symbol` are provided.", "schema": { "example": true, "type": "string" } }, { "name": "id", "required": false, "in": "query", "description": "The Request Network id of the token", "schema": { "example": "USDC-mainnet", "type": "string" } } ], "responses": { "200": { "description": "List of tokens retrieved successfully", "content": { "application/json": { "examples": { "all": { "summary": "All tokens", "value": [ { "id": "USDC-mainnet", "name": "USD Coin", "symbol": "USDC", "decimals": 6, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "network": "mainnet", "type": "ERC20", "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 }, { "id": "USDT-mainnet", "name": "Tether USD", "symbol": "USDT", "decimals": 6, "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "network": "mainnet", "type": "ERC20", "hash": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "chainId": 1 } ] }, "byNetwork": { "summary": "Tokens on mainnet", "value": [ { "id": "USDC-mainnet", "name": "USD Coin", "symbol": "USDC", "decimals": 6, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "network": "mainnet", "type": "ERC20", "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 } ] }, "bySymbolAndNetwork": { "summary": "USDC on mainnet", "value": [ { "id": "USDC-mainnet", "name": "USD Coin", "symbol": "USDC", "decimals": 6, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "network": "mainnet", "type": "ERC20", "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 } ] }, "firstOnly": { "summary": "First match only", "value": { "id": "USDC-mainnet", "name": "USD Coin", "symbol": "USDC", "decimals": 6, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "network": "mainnet", "type": "ERC20", "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 } }, "byId": { "summary": "By ID", "value": { "id": "USDC-mainnet", "name": "USD Coin", "symbol": "USDC", "decimals": 6, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "network": "mainnet", "type": "ERC20", "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "chainId": 1 } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "examples": { "invalidFirstOnly": { "summary": "Invalid firstOnly value", "value": { "statusCode": 400, "message": [ { "code": "custom", "message": "firstOnly must be 'true' or 'false' if provided", "path": [ "firstOnly" ] } ], "error": "Bad Request" } } } } } }, "404": { "description": "Token not found", "content": { "application/json": { "examples": { "notFound": { "summary": "Token not found", "value": { "statusCode": 404, "message": "Token not found", "error": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get currencies", "tags": [ "Currencies", "V2/Currencies" ] } }, "/v2/currencies/{currencyId}/conversion-routes": { "get": { "description": "Get a list of currency objects (with all details) that can be converted to from the specified currency. Optionally filter by network using the 'network' query parameter.", "operationId": "CurrenciesV2Controller_getConversionRoutes_v2", "parameters": [ { "name": "currencyId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } }, { "name": "network", "required": false, "in": "query", "description": "The network of the token to filter by", "schema": { "type": "string" } }, { "name": "networks", "required": false, "in": "query", "description": "A comma-separated list of networks to filter by (e.g., sepolia,mainnet,polygon)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversion routes retrieved successfully", "content": { "application/json": { "examples": { "usdRoutes": { "summary": "USD conversion routes on mainnet", "value": { "currencyId": "USD", "network": "mainnet", "conversionRoutes": [ { "id": "USDT-mainnet", "name": "Tether USD", "symbol": "USDT", "decimals": 6, "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "network": "mainnet", "type": "ERC20", "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", "chainId": 1 }, { "id": "ETH-mainnet", "name": "Ether", "symbol": "ETH", "decimals": 18, "address": "0xf5af88e117747e87fc5929f2ff87221b1447652e", "network": "mainnet", "type": "ETH", "hash": "0xf5af88e117747e87fc5929f2ff87221b1447652e", "chainId": 1 } ] } }, "allNetworks": { "summary": "All networks conversion routes", "value": { "currencyId": "USD", "network": null, "conversionRoutes": [ { "id": "USDT-mainnet", "name": "Tether USD", "symbol": "USDT", "decimals": 6, "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "network": "mainnet", "type": "ERC20", "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", "chainId": 1 }, { "id": "FAU-sepolia", "name": "FAU", "symbol": "FAU", "decimals": 18, "address": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "network": "sepolia", "type": "ERC20", "hash": "0x370de27fdb7d1ff1e1baa7d11c5820a324cf623c", "chainId": 11155111 } ] } }, "multiNetworks": { "summary": "Multiple networks conversion routes", "value": { "currencyId": "USD", "networks": [ "mainnet", "polygon" ], "conversionRoutes": [ { "id": "USDT-mainnet", "name": "Tether USD", "symbol": "USDT", "decimals": 6, "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "network": "mainnet", "type": "ERC20", "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", "chainId": 1 }, { "id": "USDT-polygon", "name": "Tether USD", "symbol": "USDT", "decimals": 6, "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "network": "polygon", "type": "ERC20", "hash": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f", "chainId": 137 } ] } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "examples": { "notFound": { "summary": "Currency not found", "value": { "statusCode": 404, "message": "Token not found", "error": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get conversion routes for a specific currency", "tags": [ "Currencies", "V2/Currencies" ] } }, "/v2/client-ids": { "post": { "description": "Create a new client ID for frontend applications with domain restrictions", "operationId": "ClientIdV2Controller_create_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "allowedDomains": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 10, "description": "List of allowed domain origins (normalized)" }, "feePercentage": { "type": "string", "minLength": 1, "description": "Fee percentage (e.g., '1' = 1%, '2.5' = 2.5%, '2.55' = 2.55%). Maximum 2 decimal places. If set to '0', allows API request fees to take precedence. If set to any other value, overrides any fee passed via API." }, "feeAddress": { "type": "string", "description": "Wallet address to receive fees. Required if feePercentage is set." }, "operatorWalletAddress": { "type": "string", "description": "Wallet address that will act as operator for commerce payments. The API operator wallet will execute transactions on behalf of this address. Can be a smart wallet that has granted permissions to the API operator." }, "defaultPreApprovalExpiry": { "type": "integer", "exclusiveMinimum": true, "description": "Default pre-approval expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint.", "minimum": 0 }, "defaultAuthorizationExpiry": { "type": "integer", "exclusiveMinimum": true, "description": "Default authorization expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint.", "minimum": 0 } }, "required": [ "label", "allowedDomains" ] }, "examples": { "basicClientId": { "summary": "Client ID without fee configuration", "value": { "label": "My Client ID", "allowedDomains": [ "https://example.com" ] } }, "clientIdWithFees": { "summary": "Client ID with fee configuration", "value": { "label": "My Client ID with Fees", "allowedDomains": [ "https://example.com", "https://app.example.com" ], "feePercentage": "2.5", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } } } } } }, "responses": { "201": { "description": "Client ID created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "label": { "type": "string" }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "feePercentage": { "type": "string", "nullable": true }, "feeAddress": { "type": "string", "nullable": true }, "operatorWalletAddress": { "type": "string", "nullable": true }, "defaultPreApprovalExpiry": { "type": "number", "nullable": true }, "defaultAuthorizationExpiry": { "type": "number", "nullable": true }, "status": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "400": { "description": "Bad request - validation failed" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" } }, "summary": "Create a new client ID", "tags": [ "Client IDs", "V2/Client IDs" ] }, "get": { "description": "Get all client IDs for the authenticated platform", "operationId": "ClientIdV2Controller_findAll_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of client IDs", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "label": { "type": "string" }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true } } } } } } }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" } }, "summary": "List all client IDs", "tags": [ "Client IDs", "V2/Client IDs" ] } }, "/v2/client-ids/{id}": { "get": { "description": "Get details of a specific client ID", "operationId": "ClientIdV2Controller_findOne_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Client ID internal identifier", "schema": { "example": "123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client ID details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "label": { "type": "string" }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "feePercentage": { "type": "string", "nullable": true }, "feeAddress": { "type": "string", "nullable": true }, "operatorWalletAddress": { "type": "string", "nullable": true }, "defaultPreApprovalExpiry": { "type": "number", "nullable": true }, "defaultAuthorizationExpiry": { "type": "number", "nullable": true }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Client ID not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get a specific client ID", "tags": [ "Client IDs", "V2/Client IDs" ] }, "put": { "description": "Update client ID settings including domains and rate limits", "operationId": "ClientIdV2Controller_update_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Client ID internal identifier", "schema": { "example": "123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "allowedDomains": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 10, "description": "List of allowed domain origins (normalized)" }, "feePercentage": { "type": "string", "minLength": 1, "description": "Fee percentage (e.g., '1' = 1%, '2.5' = 2.5%, '2.55' = 2.55%). Maximum 2 decimal places. If set to '0', allows API request fees to take precedence. If set to any other value, overrides any fee passed via API. Set to null to unset.", "nullable": true }, "feeAddress": { "type": "string", "description": "Wallet address to receive fees. Required if feePercentage is set. Set to null to unset.", "nullable": true }, "operatorWalletAddress": { "type": "string", "description": "Wallet address that will act as operator for commerce payments. The API operator wallet will execute transactions on behalf of this address. Can be a smart wallet that has granted permissions to the API operator. Set to null to unset. Note: Changing this will only affect new payments; existing payments will continue using their original operator address.", "nullable": true }, "defaultPreApprovalExpiry": { "type": "integer", "exclusiveMinimum": true, "description": "Default pre-approval expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint. Set to null to unset.", "nullable": true, "minimum": 0 }, "defaultAuthorizationExpiry": { "type": "integer", "exclusiveMinimum": true, "description": "Default authorization expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint. Set to null to unset.", "nullable": true, "minimum": 0 }, "status": { "type": "string", "enum": [ "active", "inactive", "revoked" ] } } }, "examples": { "updateBasicInfo": { "summary": "Update basic client ID information", "value": { "label": "Updated Client ID Label", "allowedDomains": [ "https://newdomain.com" ] } }, "addFeeConfiguration": { "summary": "Add fee configuration to existing client ID", "value": { "feePercentage": "1.5", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } }, "removeFeeConfiguration": { "summary": "Remove fee configuration from client ID", "value": { "feePercentage": null, "feeAddress": null } }, "updateStatus": { "summary": "Update client ID status", "value": { "status": "inactive" } }, "updateOperatorWallet": { "summary": "Update operator wallet address for commerce payments", "value": { "operatorWalletAddress": "0x1234567890123456789012345678901234567890" } }, "removeOperatorWallet": { "summary": "Remove operator wallet address (revert to API operator)", "value": { "operatorWalletAddress": null } }, "setDefaultExpirySettings": { "summary": "Set default expiry settings for commerce payments (in seconds)", "value": { "defaultPreApprovalExpiry": 3600, "defaultAuthorizationExpiry": 86400 } }, "removeDefaultExpirySettings": { "summary": "Remove default expiry settings", "value": { "defaultPreApprovalExpiry": null, "defaultAuthorizationExpiry": null } } } } } }, "responses": { "200": { "description": "Client ID updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "label": { "type": "string" }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "feePercentage": { "type": "string", "nullable": true }, "feeAddress": { "type": "string", "nullable": true }, "operatorWalletAddress": { "type": "string", "nullable": true }, "defaultPreApprovalExpiry": { "type": "number", "nullable": true }, "defaultAuthorizationExpiry": { "type": "number", "nullable": true }, "status": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "description": "Bad request - validation failed or cannot reactivate revoked ID" }, "401": { "description": "Unauthorized" }, "404": { "description": "Client ID not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Update a client ID", "tags": [ "Client IDs", "V2/Client IDs" ] }, "delete": { "description": "Revoke a client ID (cannot be reactivated)", "operationId": "ClientIdV2Controller_delete_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Client ID internal identifier", "schema": { "example": "123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client ID revoked successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Client ID not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Revoke a client ID", "tags": [ "Client IDs", "V2/Client IDs" ] } }, "/v2/request": { "post": { "description": "Create a new payment request", "operationId": "RequestControllerV2_createRequest_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payer": { "type": "string", "description": "The wallet address of the payer" }, "payee": { "type": "string", "description": "The wallet address of the payee (Ethereum 0x... or TRON T...). Required for all requests except crypto-to-fiat" }, "amount": { "type": "string", "description": "The payable amount of the invoice, in human readable format" }, "invoiceCurrency": { "type": "string", "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" }, "paymentCurrency": { "type": "string", "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" }, "recurrence": { "type": "object", "properties": { "startDate": { "type": "string", "description": "The start date of the invoice, cannot be in the past" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ], "description": "The frequency of the invoice" } }, "required": [ "startDate", "frequency" ], "description": "The recurrence of the invoice" }, "isCryptoToFiatAvailable": { "type": "boolean", "description": "Whether crypto-to-fiat payment is available for this request" }, "customerInfo": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's first name" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's last name" }, "email": { "type": "string", "maxLength": 255, "format": "email", "description": "Customer's email address" }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 255, "description": "Street address" }, "city": { "type": "string", "maxLength": 100, "description": "City" }, "state": { "type": "string", "maxLength": 100, "description": "State or province" }, "postalCode": { "type": "string", "maxLength": 20, "description": "Postal or ZIP code" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country code (ISO 3166-1 alpha-2)" } }, "description": "Customer's address" } }, "description": "Optional customer information for merchant receipt tracking" }, "reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant reference for receipt tracking and identification" }, "originalRequestId": { "type": "string", "minLength": 1, "description": "ID of the original request for recurring payments" }, "originalRequestPaymentReference": { "type": "string", "minLength": 1, "description": "Payment reference of the original request for recurring payments" } }, "required": [ "amount", "invoiceCurrency", "paymentCurrency" ] }, "examples": { "regularRequest": { "summary": "Regular payment request", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "ETH-sepolia-sepolia" } }, "cryptoToFiatRequest": { "summary": "Crypto-to-fiat payment request", "value": { "amount": "25.50", "invoiceCurrency": "USD", "paymentCurrency": "USDC-sepolia", "isCryptoToFiatAvailable": true } }, "requestWithCustomerInfo": { "summary": "Request with customer information and reference", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "50.00", "invoiceCurrency": "USD", "paymentCurrency": "USDC-sepolia", "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "address": { "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "reference": "ORDER-2024-001234" } }, "recurringInvoice": { "summary": "Recurring invoice", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "ETH-sepolia-sepolia", "recurrence": { "startDate": "2030-01-01", "frequency": "YEARLY" } } } } } } }, "responses": { "201": { "description": "Request created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentReference": { "type": "string", "description": "Unique identifier of the request, used to pay the request as well as check the status of the request", "example": "0xb3581f0b0f74cc61" }, "requestId": { "type": "string", "description": "Unique identifier of the request, commonly used to look up a request in Request Scan", "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" } } } } } }, "400": { "description": "Validation failed" }, "404": { "description": "Wallet not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Create a new request", "tags": [ "Request", "V2/Request" ] } }, "/v2/request/{requestId}": { "get": { "description": "Get the status of a payment request", "operationId": "RequestControllerV2_getRequestStatus_v2", "parameters": [ { "name": "requestId", "required": true, "in": "path", "description": "The requestId for the request", "schema": { "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasBeenPaid": { "type": "boolean", "description": "Whether the request has been paid" }, "paymentReference": { "type": "string", "description": "Unique identifier used for payments and status checks" }, "requestId": { "type": "string", "description": "Unique identifier of the request" }, "isListening": { "type": "boolean", "description": "Whether the system is actively listening for payments on this request" }, "txHash": { "type": "string", "nullable": true, "description": "Transaction hash of the payment, null if not yet paid" }, "recurrence": { "type": "object", "description": "Recurrence configuration for recurring requests" }, "originalRequestId": { "type": "string", "description": "Original request ID for recurring requests" }, "status": { "type": "string", "description": "Current status of the request" }, "isCryptoToFiatAvailable": { "type": "boolean", "description": "Whether crypto-to-fiat conversion is available for this request" }, "originalRequestPaymentReference": { "type": "string", "description": "Payment reference of the original request for recurring payments" }, "payments": { "type": "array", "description": "Array of payments made to this request", "items": { "type": "object" } }, "isRecurrenceStopped": { "type": "boolean", "description": "Whether recurrence has been stopped for this request" }, "customerInfo": { "type": "object", "nullable": true, "description": "Customer information for merchant receipt tracking", "properties": { "firstName": { "type": "string", "description": "Customer's first name" }, "lastName": { "type": "string", "description": "Customer's last name" }, "email": { "type": "string", "description": "Customer's email address" }, "address": { "type": "object", "description": "Customer's address", "properties": { "street": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postalCode": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)" } } } } }, "reference": { "type": "string", "nullable": true, "description": "Merchant reference for receipt tracking and identification" }, "amountInUsd": { "type": "string", "nullable": true, "description": "Request amount in USD (actual if paid, current market rate if unpaid)" }, "conversionRate": { "type": "string", "nullable": true, "description": "Conversion rate. Available for: unpaid requests and fully paid requests with single payment. Null for: partially paid requests and fully paid requests with multiple payments." }, "rateSource": { "type": "string", "enum": [ "lifi", "chainlink", "coingecko", "unknown", "mixed" ], "description": "Source of the conversion rate" }, "conversionBreakdown": { "type": "object", "nullable": true, "description": "Detailed breakdown for partial payments or multiple payments. Provides individual payment rates when top-level rate is null.", "properties": { "paidAmount": { "type": "string" }, "paidAmountInUsd": { "type": "string" }, "remainingAmount": { "type": "string" }, "remainingAmountInUsd": { "type": "string" }, "currentMarketRate": { "type": "string", "nullable": true }, "currentMarketRateSource": { "type": "string", "enum": [ "lifi", "chainlink", "coingecko", "unknown" ], "nullable": true }, "payments": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "amountInUsd": { "type": "string" }, "conversionRate": { "type": "string" }, "rateSource": { "type": "string", "enum": [ "lifi", "chainlink", "coingecko", "unknown" ] }, "timestamp": { "type": "string" } } } } } }, "fees": { "type": "array", "nullable": true, "description": "Associated fees (actual if paid, empty if unpaid)", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "platform", "crosschain", "crypto-to-fiat", "offramp" ], "description": "Type of fee" }, "provider": { "type": "string", "description": "Fee provider" }, "amount": { "type": "string", "description": "Fee amount in human-readable format (formatted with token decimals)" }, "currency": { "type": "string", "description": "Fee currency" } } } } } }, "examples": { "paid": { "summary": "Request has been paid", "value": { "hasBeenPaid": true, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "isListening": false, "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } }, "notPaid": { "summary": "Request has not been paid", "value": { "hasBeenPaid": false, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "isListening": false, "txHash": null } }, "withCustomerInfo": { "summary": "Request with customer information and reference", "value": { "hasBeenPaid": false, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "isListening": true, "txHash": null, "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "address": { "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "reference": "ORDER-2024-001234" } }, "paidWithUsdInfo": { "summary": "Fully paid request with single payment", "value": { "hasBeenPaid": true, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "amountInUsd": "100.00", "conversionRate": "2487.52", "rateSource": "coingecko", "fees": [ { "type": "platform", "provider": "request-network", "amount": "2.00", "currency": "USDC" }, { "type": "gas", "provider": "sepolia", "amount": "0.002", "currency": "ETH" } ] } }, "partiallyPaidWithBreakdown": { "summary": "Partially paid request (conversion rate is null)", "value": { "hasBeenPaid": false, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "amountInUsd": "100.12", "conversionRate": null, "rateSource": "mixed", "conversionBreakdown": { "paidAmount": "75.00", "paidAmountInUsd": "75.00", "remainingAmount": "25.00", "remainingAmountInUsd": "25.12", "currentMarketRate": "2501.23", "currentMarketRateSource": "coingecko", "payments": [ { "amount": "75.00", "amountInUsd": "75.00", "conversionRate": "2487.52", "rateSource": "chainlink", "timestamp": "2025-01-01T10:00:00Z" } ] }, "fees": [ { "type": "platform", "provider": "request-network", "amount": "1.50", "currency": "USDC" }, { "type": "gas", "provider": "sepolia", "amount": "0.0015", "currency": "ETH" } ] } }, "unpaidRequest": { "summary": "Unpaid request with current market rates", "value": { "hasBeenPaid": false, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "amountInUsd": "100.25", "conversionRate": "2501.23", "rateSource": "coingecko", "fees": [] } }, "multiplePayments": { "summary": "Fully paid request with multiple payments (conversion rate is null)", "value": { "hasBeenPaid": true, "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "amountInUsd": "100.00", "conversionRate": null, "rateSource": "mixed", "conversionBreakdown": { "paidAmount": "100.00", "paidAmountInUsd": "100.00", "remainingAmount": "0", "remainingAmountInUsd": "0", "currentMarketRate": null, "currentMarketRateSource": null, "payments": [ { "amount": "50.00", "amountInUsd": "50.00", "conversionRate": "2500.00", "rateSource": "coingecko", "timestamp": "2025-01-01T10:00:00Z" }, { "amount": "50.00", "amountInUsd": "50.00", "conversionRate": "2480.30", "rateSource": "chainlink", "timestamp": "2025-01-02T15:30:00Z" } ] }, "fees": [ { "type": "platform", "provider": "request-network", "amount": "2.00", "currency": "USDC" }, { "type": "gas", "provider": "sepolia", "amount": "0.002", "currency": "ETH" }, { "type": "crosschain", "provider": "lifi", "amount": "0.05", "currency": "USDC" } ] } } } } } }, "404": { "description": "Request not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get request status", "tags": [ "Request", "V2/Request" ] }, "patch": { "description": "Update a recurring request", "operationId": "RequestControllerV2_updateRequest_v2", "parameters": [ { "name": "requestId", "required": true, "in": "path", "description": "The requestId for the request", "schema": { "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isRecurrenceStopped": { "type": "boolean", "description": "Whether the recurrence is stopped" } }, "required": [ "isRecurrenceStopped" ] }, "examples": { "stopRecurrence": { "summary": "Stop recurring invoice", "value": { "isRecurrenceStopped": true } }, "resumeRecurrence": { "summary": "Resume recurring invoice", "value": { "isRecurrenceStopped": false } } } } } }, "responses": { "200": { "description": "Recurrence updated successfully" }, "404": { "description": "Request not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Update a recurring request", "tags": [ "Request", "V2/Request" ] } }, "/v2/request/{requestId}/pay": { "get": { "description": "Get the calldata needed to pay a request. For same-chain payments, returns transaction calldata that can be directly executed. For crosschain payments (when chain and token parameters are provided and differ from the request's native chain), returns a payment intent that needs to be signed and processed through the crosschain bridge. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected.", "operationId": "RequestControllerV2_getPaymentCalldata_v2", "parameters": [ { "name": "requestId", "required": true, "in": "path", "description": "The requestId of the request", "schema": { "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } }, { "name": "wallet", "required": false, "in": "query", "description": "The wallet address of the payer.", "schema": { "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "type": "string" } }, { "name": "chain", "required": false, "in": "query", "description": "The source chain of the crosschain payment", "x-feature-flag": "crosschainDisabled", "schema": { "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM" ], "type": "string" } }, { "name": "token", "required": false, "in": "query", "description": "The source token of the crosschain payment", "x-feature-flag": "crosschainDisabled", "schema": { "enum": [ "USDC", "USDT" ], "type": "string" } }, { "name": "amount", "required": false, "in": "query", "description": "The amount to pay, in human readable format", "schema": { "type": "string" } }, { "name": "clientUserId", "required": false, "in": "query", "description": "Optional client user ID for off-ramp payments", "schema": { "example": "user-123", "type": "string" } }, { "name": "paymentDetailsId", "required": false, "in": "query", "description": "Optional payment details ID for off-ramp payments", "schema": { "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9", "type": "string" } }, { "name": "feePercentage", "required": false, "in": "query", "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)", "schema": { "example": "0.02", "type": "string" } }, { "name": "feeAddress", "required": false, "in": "query", "description": "Address to receive the fee", "schema": { "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "type": "string" } } ], "responses": { "200": { "description": "Payment calldata retrieved successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "title": "Same-chain Payment Response", "description": "Response for same-chain payments with transaction calldata", "properties": { "transactions": { "type": "array", "description": "Array of transactions to execute for the payment", "items": { "type": "object", "properties": { "data": { "type": "string", "description": "Transaction calldata" }, "to": { "type": "string", "description": "Target contract address" }, "value": { "type": "object", "description": "Payment amount in EVM-compatible format", "properties": { "type": { "type": "string", "enum": [ "BigNumber" ] }, "hex": { "type": "string", "description": "Amount encoded in hex" } } } }, "required": [ "data", "to", "value" ] } }, "metadata": { "type": "object", "description": "Metadata about the payment requirements", "properties": { "stepsRequired": { "type": "number", "description": "Number of transactions required" }, "needsApproval": { "type": "boolean", "description": "Whether token approval is needed" }, "approvalTransactionIndex": { "type": "number", "nullable": true, "description": "Index of the approval transaction if needed" }, "hasEnoughBalance": { "type": "boolean", "description": "Whether payer has sufficient balance" }, "hasEnoughGas": { "type": "boolean", "description": "Whether payer has sufficient gas" } }, "required": [ "stepsRequired", "needsApproval", "hasEnoughBalance", "hasEnoughGas" ] } }, "required": [ "transactions", "metadata" ] }, { "type": "object", "title": "Crosschain Payment Response", "description": "Response for crosschain payments with payment intent to be signed", "properties": { "paymentIntentId": { "type": "string", "description": "Unique identifier for the payment intent" }, "paymentIntent": { "type": "string", "description": "EIP-712 typed data for payment intent signature" }, "approvalPermitPayload": { "type": "string", "nullable": true, "description": "EIP-712 typed data for token approval permit (for EIP-2612 compliant tokens)" }, "approvalCalldata": { "type": "object", "nullable": true, "description": "Transaction calldata for token approval (for non-EIP-2612 tokens)", "properties": { "to": { "type": "string", "description": "Token contract address" }, "data": { "type": "string", "description": "Approval transaction calldata" }, "value": { "type": "string", "description": "Transaction value (usually '0x0')" } } }, "metadata": { "type": "object", "description": "Metadata about the crosschain payment", "properties": { "supportsEIP2612": { "type": "boolean", "description": "Whether the token supports EIP-2612 permits" } }, "required": [ "supportsEIP2612" ] } }, "required": [ "paymentIntentId", "paymentIntent", "metadata" ] } ] }, "examples": { "native": { "summary": "Native currency payment", "value": { "transactions": [ { "data": "0xb868980b...00", "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687", "value": { "type": "BigNumber", "hex": "0x038d7ea4c68000" } } ], "metadata": { "stepsRequired": 1, "needsApproval": false, "approvalTransactionIndex": null, "hasEnoughBalance": true, "hasEnoughGas": true } } }, "token": { "summary": "ERC20 token payment", "value": { "transactions": [ { "data": "0x095ea7b3...ff", "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324cf623C", "value": 0 }, { "data": "0xc219a14d...00", "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE", "value": 0 } ], "metadata": { "stepsRequired": 2, "needsApproval": true, "approvalTransactionIndex": 0, "hasEnoughBalance": true, "hasEnoughGas": true } } }, "currencyThatSupportsEIP2612": { "summary": "Crosschain payment with a currency that supports EIP-2612", "x-feature-flag": "crosschainDisabled", "value": { "paymentIntentId": "01JPHNEY8RRJTB94Q34GAW8BC3", "paymentIntent": "{\n \"domain\": {\n \"name\": \"Permit2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\"\n },\n \"types\": {\n \"PermitBatchWitnessTransferFrom\": [\n {\n \"name\": \"permitted\",\n \"type\": \"TokenPermissions[]\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"witness\",\n \"type\": \"PaymentIntent\"\n }\n ],\n \"TokenPermissions\": [\n {\n \"name\": \"token\",\n \"type\": \"address\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n }\n ],\n \"PaymentIntent\": [\n {\n \"name\": \"payment_type\",\n \"type\": \"uint8\"\n },\n {\n \"name\": \"operator_data\",\n \"type\": \"OperatorData\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"source\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"destination\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"processing_date\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"expires_at\",\n \"type\": \"uint256\"\n }\n ],\n \"OperatorData\": [\n {\n \"name\": \"operatorId\",\n \"type\": \"bytes32\"\n },\n {\n \"name\": \"operator\",\n \"type\": \"address\"\n },\n {\n \"name\": \"treasury_account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"fee\",\n \"type\": \"uint256\"\n }\n ],\n \"Domain\": [\n {\n \"name\": \"account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"network_id\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"payment_token\",\n \"type\": \"address\"\n }\n ]\n },\n \"values\": {\n \"permitted\": [\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"1998000\"\n },\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"0\"\n },\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"2000\"\n }\n ],\n \"spender\": \"0x4B1d5b0aF5AbAe333C8d2CCa2a346e0D5f68C427\",\n \"nonce\": \"1742202173708\",\n \"deadline\": \"1742205771\",\n \"witness\": {\n \"payment_type\": 0,\n \"operator_data\": {\n \"operatorId\": \"0x6ab1463ead4ba60b8e08155b29ea2b3c91731e78be09b6e12b6c25414d724dd0\",\n \"operator\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"treasury_account\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"fee\": \"0\"\n },\n \"amount\": \"2000000\",\n \"source\": {\n \"account\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"network_id\": \"42161\",\n \"payment_token\": \"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n },\n \"destination\": {\n \"account\": \"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7\",\n \"network_id\": \"8453\",\n \"payment_token\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n },\n \"processing_date\": \"1742220173\",\n \"expires_at\": \"1742205771\"\n }\n }\n}", "approvalPermitPayload": "{\n \"domain\": {\n \"name\": \"USD Coin\",\n \"version\": \"2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\"\n },\n \"types\": {\n \"Permit\": [\n {\n \"name\": \"owner\",\n \"type\": \"address\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"value\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n }\n ]\n },\n \"values\": {\n \"owner\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"spender\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\",\n \"value\": \"115792089237316195423570985008687907853269984665640564039457584007913129639935\",\n \"nonce\": \"1\",\n \"deadline\": 1742205771\n }\n}", "metadata": { "supportsEIP2612": true } } }, "currencyThatDoesNotSupportEIP2612": { "summary": "Crosschain payment with a currency that does not support EIP-2612", "x-feature-flag": "crosschainDisabled", "value": { "paymentIntentId": "01JPHNFMRC2JFG4W08FGDG4KD3", "paymentIntent": "{\n \"domain\": {\n \"name\": \"Permit2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\"\n },\n \"types\": {\n \"PermitBatchWitnessTransferFrom\": [\n {\n \"name\": \"permitted\",\n \"type\": \"TokenPermissions[]\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"witness\",\n \"type\": \"PaymentIntent\"\n }\n ],\n \"TokenPermissions\": [\n {\n \"name\": \"token\",\n \"type\": \"address\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n }\n ],\n \"PaymentIntent\": [\n {\n \"name\": \"payment_type\",\n \"type\": \"uint8\"\n },\n {\n \"name\": \"operator_data\",\n \"type\": \"OperatorData\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"source\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"destination\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"processing_date\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"expires_at\",\n \"type\": \"uint256\"\n }\n ],\n \"OperatorData\": [\n {\n \"name\": \"operatorId\",\n \"type\": \"bytes32\"\n },\n {\n \"name\": \"operator\",\n \"type\": \"address\"\n },\n {\n \"name\": \"treasury_account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"fee\",\n \"type\": \"uint256\"\n }\n ],\n \"Domain\": [\n {\n \"name\": \"account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"network_id\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"payment_token\",\n \"type\": \"address\"\n }\n ]\n },\n \"values\": {\n \"permitted\": [\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"1998000\"\n },\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"0\"\n },\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"2000\"\n }\n ],\n \"spender\": \"0x4B1d5b0aF5AbAe333C8d2CCa2a346e0D5f68C427\",\n \"nonce\": \"1742202196746\",\n \"deadline\": \"1742205796\",\n \"witness\": {\n \"payment_type\": 0,\n \"operator_data\": {\n \"operatorId\": \"0x6ab1463ead4ba60b8e08155b29ea2b3c91731e78be09b6e12b6c25414d724dd0\",\n \"operator\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"treasury_account\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"fee\": \"0\"\n },\n \"amount\": \"2000000\",\n \"source\": {\n \"account\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"network_id\": \"42161\",\n \"payment_token\": \"0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9\"\n },\n \"destination\": {\n \"account\": \"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7\",\n \"network_id\": \"8453\",\n \"payment_token\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n },\n \"processing_date\": \"1742220196\",\n \"expires_at\": \"1742205796\"\n }\n }\n}", "approvalCalldata": { "to": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "data": "0x095ea7b3000000000000000000000000000000000022d473030f116ddee9f6b43ac78ba3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "value": "0x0" }, "metadata": { "supportsEIP2612": false } } } } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "examples": { "queryParamsValidation": { "summary": "Query Validation Failed", "value": { "message": "Validation failed", "errors": [ { "field": "wallet", "message": "Invalid Ethereum address" }, { "field": "chain", "message": "Invalid enum value. Expected 'POLYGON' | 'BASE' | 'OPTIMISM' | 'ETHEREUM' | 'ARBITRUM', received {input}" }, { "field": "token", "message": "Invalid enum value. Expected 'USDC' | 'USDT', received {input}" } ] } }, "tokenNotSupportedCrosschain": { "summary": "Token not supported for crosschain payment", "value": { "message": "FAU is not supported in crosschain payment.", "error": "Bad Request", "statusCode": 400 } } } } } }, "404": { "description": "Request not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get payment calldata", "tags": [ "Request", "V2/Request" ] } }, "/v2/request/{requestId}/routes": { "get": { "description": "Get available payment routes for a request. This endpoint analyzes the payer's wallet balance across supported chains and returns possible payment methods. Routes include direct same-chain payments and crosschain bridging options when the payer has sufficient balance on different chains than the request's native chain.", "operationId": "RequestControllerV2_getRequestPaymentRoutes_v2", "parameters": [ { "name": "requestId", "required": true, "in": "path", "description": "The requestId of the request", "schema": { "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } }, { "name": "wallet", "required": true, "in": "query", "description": "The wallet address of the payer", "schema": { "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "type": "string" } }, { "name": "amount", "required": false, "in": "query", "description": "The amount to pay, in human readable format", "schema": { "type": "string" } }, { "name": "feePercentage", "required": false, "in": "query", "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)", "schema": { "type": "string" } }, { "name": "feeAddress", "required": false, "in": "query", "description": "Address to receive the fee", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available payment routes", "content": { "application/json": { "schema": { "type": "object", "description": "Available payment routes for the request", "properties": { "routes": { "type": "array", "description": "Array of available payment routes", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the route" }, "fee": { "type": "number", "description": "Total fee for this route (as a decimal, e.g., 0.001 = 0.1%)" }, "feeBreakdown": { "type": "array", "description": "Detailed breakdown of all fees for this route", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "platform", "crosschain", "crypto-to-fiat", "offramp" ], "description": "Type of fee" }, "stage": { "type": "string", "enum": [ "sending", "receiving", "proxying", "refunding", "overall" ], "description": "Stage when the fee is applied" }, "provider": { "type": "string", "description": "Provider that charged the fee" }, "amount": { "type": "string", "description": "Fee amount in human-readable format (formatted with token decimals)" }, "amountInUSD": { "type": "string", "description": "Fee amount in USD" }, "currency": { "type": "string", "description": "Fee currency" }, "receiverAddress": { "type": "string", "description": "Address that received the fee" }, "network": { "type": "string", "description": "Network where the fee was paid" }, "rateProvider": { "type": "string", "description": "Provider used for rate conversion" } } } }, "speed": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Route speed - 'FAST' for direct payments, number of seconds for crosschain" }, "price_impact": { "type": "number", "description": "Price impact of the route (as a decimal)" }, "chain": { "type": "string", "description": "Source chain for the payment" }, "token": { "type": "string", "description": "Token symbol for the payment" } }, "required": [ "id", "fee", "speed", "chain", "token" ] } } }, "required": [ "routes" ] }, "examples": { "requestNetworkRoute": { "summary": "Only request network route", "value": { "routes": [ { "id": "REQUEST_NETWORK_PAYMENT", "fee": 0, "speed": "FAST", "price_impact": 0, "chain": "MAINNET", "token": "REQ" } ] } }, "sameChainRoute": { "summary": "Same-chain payment possible", "value": { "routes": [ { "id": "REQUEST_NETWORK_PAYMENT", "fee": 0, "speed": "FAST", "price_impact": 0, "chain": "BASE", "token": "USDC" }, { "id": "BASE-BASE-USDC-USDC", "fee": 0.001, "speed": "FAST", "price_impact": 0, "chain": "BASE", "token": "USDC" } ] } }, "crosschainRoute": { "summary": "Crosschain possible", "value": { "routes": [ { "id": "REQUEST_NETWORK_PAYMENT", "fee": 0, "speed": "FAST", "price_impact": 0, "chain": "BASE", "token": "USDC" }, { "id": "POLYGON_BASE_USDC_USDC", "fee": 0.001, "speed": "FAST", "price_impact": 0.999, "chain": "POLYGON", "token": "USDC" } ] } }, "noRoutes": { "summary": "No routes available", "value": { "routes": [] } } } } } }, "400": { "description": "Invalid or missing wallet address" }, "404": { "description": "Request not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get payment routes", "tags": [ "Request", "V2/Request" ], "x-feature-flag": "crosschainDisabled" } }, "/v2/request/payment-intents/{paymentIntentId}": { "post": { "description": "Send a payment intent", "operationId": "RequestControllerV2_sendPaymentIntent_v2", "parameters": [ { "name": "paymentIntentId", "required": true, "in": "path", "description": "The payment intent ID", "schema": { "example": "01JNZYZPK7B4YBPD44TM72NDNJ", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signedPaymentIntent": { "type": "object", "properties": { "signature": { "type": "string", "description": "The signature of the permit2 approval for token transfer" }, "nonce": { "type": "string", "description": "The unique nonce for this permit2 transaction" }, "deadline": { "type": "string", "description": "The Unix timestamp when this permit2 approval expires" } }, "required": [ "signature", "nonce", "deadline" ], "description": "The signed payment intent data." }, "signedApprovalPermit": { "type": "object", "properties": { "signature": { "type": "string", "description": "The signature for the EIP2612 gasless token approval" }, "nonce": { "type": "string", "description": "The unique nonce for the EIP2612 permit" }, "deadline": { "type": "string", "description": "The Unix timestamp when this EIP2612 permit expires" } }, "required": [ "signature", "nonce", "deadline" ], "description": "The EIP2612 gasless token approval data that allows Permit2 to access user tokens" } }, "required": [ "signedPaymentIntent" ] } } } }, "responses": { "200": { "description": "Payment intent sent successfully" }, "404": { "description": "Payment intent data not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Send a payment intent", "tags": [ "Request", "V2/Request" ], "x-feature-flag": "crosschainDisabled" } }, "/v2/payer": { "post": { "description": "Checks compliance status and returns necessary URLs for completing compliance.", "operationId": "PayerV2Controller_getComplianceData_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientUserId": { "type": "string", "minLength": 1, "description": "Client User ID" }, "email": { "type": "string", "format": "email", "description": "Email" }, "firstName": { "type": "string", "minLength": 1, "description": "First Name" }, "lastName": { "type": "string", "minLength": 1, "description": "Last Name" }, "beneficiaryType": { "type": "string", "enum": [ "individual", "business" ] }, "companyName": { "type": "string", "description": "Company Name" }, "dateOfBirth": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth in YYYY-MM-DD format" }, "addressLine1": { "type": "string", "minLength": 1, "description": "Address Line 1" }, "addressLine2": { "type": "string", "description": "Address Line 2" }, "city": { "type": "string", "minLength": 1, "description": "City" }, "state": { "type": "string", "minLength": 1, "description": "State" }, "postcode": { "type": "string", "minLength": 1, "description": "Postcode" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country" }, "nationality": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Nationality" }, "phone": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$", "description": "Phone in E.164 format" }, "ssn": { "type": "string", "minLength": 1, "description": "Social Security Number" }, "sourceOfFunds": { "type": "string", "description": "Source of Funds" }, "businessActivity": { "type": "string", "description": "Business Activity" } }, "required": [ "clientUserId", "email", "firstName", "lastName", "beneficiaryType", "dateOfBirth", "addressLine1", "city", "state", "postcode", "country", "nationality", "phone", "ssn" ] }, "examples": { "individualBeneficiary": { "summary": "Individual beneficiary compliance data", "value": { "clientUserId": "user-123", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "beneficiaryType": "individual", "dateOfBirth": "1985-12-12", "addressLine1": "123 Main Street", "city": "New York", "state": "NY", "postcode": "10001", "country": "US", "nationality": "US", "phone": "+12125551234", "ssn": "123-45-6789" } }, "businessBeneficiary": { "summary": "Business beneficiary compliance data", "value": { "clientUserId": "business-456", "email": "cfo@company.com", "firstName": "Jane", "lastName": "Smith", "beneficiaryType": "business", "companyName": "Acme Corporation Inc.", "dateOfBirth": "1980-05-15", "addressLine1": "456 Business Ave", "addressLine2": "Suite 200", "city": "San Francisco", "state": "CA", "postcode": "94102", "country": "US", "nationality": "US", "phone": "+14155552000", "ssn": "987-65-4321", "sourceOfFunds": "Business revenue from software services", "businessActivity": "Software development and consulting" } } } } } }, "responses": { "200": { "description": "Compliance data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreementUrl": { "type": "string", "format": "uri" }, "kycUrl": { "type": "string", "format": "uri" }, "status": { "type": "object", "properties": { "agreementStatus": { "type": "string", "enum": [ "not_started", "completed" ] }, "kycStatus": { "type": "string", "enum": [ "not_started", "completed" ] } }, "required": [ "agreementStatus", "kycStatus" ] }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "status" ] }, "examples": { "success": { "summary": "Successful response", "value": { "agreementUrl": "https://core-api.pay.so/v1/public/agreements?email=john.doe%40example.com", "kycUrl": "https://sumsub.com/idensic/l/#/sbx_VvK9E9P2A23xQPoA", "status": { "agreementStatus": "not_started", "kycStatus": "not_started" } } } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Compliance is only required for off-ramp requests" }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Request with payment reference pay-ref-123 not found" }, "error": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Create compliance data for a user", "tags": [ "Payer", "V2/Payer" ] } }, "/v2/payer/{clientUserId}": { "patch": { "description": "Update the agreement completion status for a user.", "operationId": "PayerV2Controller_updateComplianceStatus_v2", "parameters": [ { "name": "clientUserId", "required": true, "in": "path", "description": "The client user ID to update", "schema": { "example": "user-123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agreementCompleted": { "type": "boolean" } }, "required": [ "agreementCompleted" ], "example": { "agreementCompleted": true } } } } }, "responses": { "200": { "description": "Compliance status updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "agreementCompleted must be provided" }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Payer with client user ID user-123 not found" }, "error": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Update agreement status", "tags": [ "Payer", "V2/Payer" ] }, "get": { "description": "Retrieves the comprehensive compliance status for a specific user, including KYC and agreement status.", "operationId": "PayerV2Controller_getComplianceStatus_v2", "parameters": [ { "name": "clientUserId", "required": true, "in": "path", "description": "The client user ID to check compliance status for", "schema": { "example": "user-123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compliance status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "kycStatus": { "type": "string", "example": "completed" }, "agreementStatus": { "type": "string", "example": "completed" }, "isCompliant": { "type": "boolean", "example": true }, "userId": { "type": "string", "example": "a25a4274-8f50-4579-b476-8f35b297d4ad" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Payer with client user ID user-123 not found" }, "error": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get compliance status for a user", "tags": [ "Payer", "V2/Payer" ] } }, "/v2/payer/{clientUserId}/payment-details": { "post": { "description": "Create payment details for a user", "operationId": "PayerV2Controller_createPaymentDetails_v2", "parameters": [ { "name": "clientUserId", "required": true, "in": "path", "description": "The client user ID", "schema": { "example": "user-123", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankName": { "type": "string", "minLength": 1, "description": "Name of the bank" }, "accountName": { "type": "string", "minLength": 1, "description": "Name of the account holder" }, "accountNumber": { "type": "string", "description": "Bank account number" }, "routingNumber": { "type": "string", "description": "Bank routing number (US)" }, "beneficiaryType": { "type": "string", "enum": [ "individual", "business" ], "description": "Type of beneficiary" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Three-letter currency code (ISO 4217)" }, "addressLine1": { "type": "string", "minLength": 1, "description": "Primary address line" }, "addressLine2": { "type": "string", "description": "Secondary address line" }, "city": { "type": "string", "minLength": 1, "description": "City name" }, "state": { "type": "string", "description": "State or province code" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter country code (ISO 3166-1 alpha-2)" }, "dateOfBirth": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth in YYYY-MM-DD format" }, "postalCode": { "type": "string", "minLength": 1, "description": "Postal or ZIP code" }, "rails": { "type": "string", "enum": [ "local", "swift", "wire" ], "default": "local", "description": "Payment rail type" }, "sortCode": { "type": "string", "description": "UK bank sort code" }, "iban": { "type": "string", "description": "International Bank Account Number" }, "swiftBic": { "type": "string", "description": "SWIFT/BIC code" }, "documentNumber": { "type": "string", "description": "Government-issued ID number" }, "documentType": { "type": "string", "description": "Type of government-issued ID (e.g., passport, driver's license)" }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "description": "Type of bank account" }, "ribNumber": { "type": "string", "description": "French RIB number" }, "bsbNumber": { "type": "string", "description": "Australian BSB number" }, "ncc": { "type": "string", "description": "New Zealand NCC number" }, "branchCode": { "type": "string", "description": "Bank branch code" }, "bankCode": { "type": "string", "description": "Bank code" }, "ifsc": { "type": "string", "description": "Indian Financial System Code" } }, "required": [ "bankName", "accountName", "beneficiaryType", "currency", "addressLine1", "city", "country", "dateOfBirth", "postalCode" ] }, "examples": { "localUSBusiness": { "summary": "US business account with local rails", "value": { "bankName": "Chase", "accountName": "Acme Corp Business Account", "accountNumber": "253009233489", "routingNumber": "026013356", "beneficiaryType": "business", "currency": "usd", "addressLine1": "24 Theatre St.", "city": "Paramount", "state": "CA", "postalCode": "90723", "country": "US", "dateOfBirth": "1985-12-12", "rails": "local", "accountType": "checking" } }, "swiftInternational": { "summary": "International account with SWIFT rails", "value": { "bankName": "Deutsche Bank", "accountName": "John Doe", "beneficiaryType": "individual", "currency": "eur", "addressLine1": "Unter den Linden 1", "city": "Berlin", "postalCode": "10117", "country": "DE", "dateOfBirth": "1990-03-22", "rails": "swift", "iban": "DE89370400440532013000", "swiftBic": "DEUTDEFF" } }, "ukAccount": { "summary": "UK account with sort code", "value": { "bankName": "Barclays", "accountName": "Jane Smith", "accountNumber": "12345678", "beneficiaryType": "individual", "currency": "gbp", "addressLine1": "123 High Street", "city": "London", "postalCode": "SW1A 1AA", "country": "GB", "dateOfBirth": "1988-07-10", "rails": "local", "sortCode": "200000" } } } } } }, "responses": { "201": { "description": "Payment details created successfully", "content": { "application/json": { "schema": { "properties": { "payment_detail": { "type": "object", "properties": { "id": { "type": "string", "example": "pd_123456" }, "clientUserId": { "type": "string", "example": "user-123" }, "bankName": { "type": "string", "example": "Chase" }, "accountName": { "type": "string", "example": "Gordon's Chase Business Account" }, "currency": { "type": "string", "example": "usd" }, "beneficiaryType": { "type": "string", "enum": [ "individual", "business" ], "example": "business" } } } } } } } }, "400": { "description": "Invalid request data", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Invalid bank account details" }, "error": { "type": "string", "example": "Bad Request" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "User with ID user-123 not found" }, "error": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Create payment details", "tags": [ "Payer", "V2/Payer" ] }, "get": { "description": "Retrieves the registered bank account details for a user. Optionally filter by payment details ID.", "operationId": "PayerV2Controller_getPaymentDetails_v2", "parameters": [ { "name": "clientUserId", "required": true, "in": "path", "description": "The client user ID to get payment details for", "schema": { "example": "user-123", "type": "string" } }, { "name": "paymentDetailsId", "required": false, "in": "query", "description": "Optional ID of specific payment details to retrieve", "schema": { "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "paymentDetails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9" }, "userId": { "type": "string", "example": "a25a4274-8f50-4579-b476-8f35b297d4ad" }, "bankName": { "type": "string", "example": "Chase" }, "accountName": { "type": "string", "example": "Gordon's Chase Business Account" }, "beneficiaryType": { "type": "string", "example": "business" }, "accountNumber": { "type": "string", "example": "253009233489" }, "routingNumber": { "type": "string", "example": "026013356" }, "currency": { "type": "string", "example": "usd" }, "status": { "type": "string", "example": "approved" }, "rails": { "type": "string", "example": "local" } } } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "User or payment details not found", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "number", "example": 404 }, "message": { "type": "string", "example": "Payer with client user ID user-123 not found" }, "error": { "type": "string", "example": "Not Found" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get payment details for a user", "tags": [ "Payer", "V2/Payer" ] } }, "/v2/payments": { "get": { "description": "Search for payments by transaction hash, wallet address, payment reference, request ID, or merchant reference. Supports filtering by payment type, currencies, date ranges, and pagination. Returns complete payment details including customer information and fees. When searching by transaction hash or wallet address, returns ALL payments from batch transactions. Most search parameters are optional, but at least one must be provided and they default to an AND relationship.", "operationId": "PaymentV2Controller_searchPayments_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } }, { "name": "txHash", "required": false, "in": "query", "description": "Search by blockchain transaction hash (source or destination). Returns ALL payments from the same transaction, including batch payments. Must be a valid 66-character hex string starting with '0x'. Example: '0x1234567890abcdef...'", "schema": { "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "type": "string" } }, { "name": "walletAddress", "required": false, "in": "query", "description": "Search by wallet address (payer or payee). Supports Ethereum (0x...) and TRON (T...) addresses. Returns ALL payments involving this address, including batch payments where the address is either sender or recipient.", "schema": { "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "type": "string" } }, { "name": "paymentReference", "required": false, "in": "query", "description": "Search by unique payment reference generated by the Request Network. This is the hex identifier used for on-chain payments. Example: '0xb3581f0b0f74cc61'", "schema": { "example": "0xb3581f0b0f74cc61", "type": "string" } }, { "name": "requestId", "required": false, "in": "query", "description": "Search by Request Network request ID. This is the unique identifier for the payment request. Example: '01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb'", "schema": { "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "type": "string" } }, { "name": "reference", "required": false, "in": "query", "description": "Search by your custom merchant reference used for receipt tracking and order identification. This is the reference you provided when creating the payment. Example: 'ORDER-2024-001234' or 'INV-5678'", "schema": { "example": "ORDER-2024-001234", "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by payment type: 'direct' (same currency), 'conversion' (currency conversion), 'crosschain' (cross-chain payment), 'recurring' (subscription payment)", "schema": { "enum": [ "direct", "conversion", "crosschain", "recurring" ], "type": "string" } }, { "name": "invoiceCurrency", "required": false, "in": "query", "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD", "schema": { "example": "USD", "type": "string" } }, { "name": "paymentCurrency", "required": false, "in": "query", "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia", "schema": { "example": "USDC", "type": "string" } }, { "name": "fromDate", "required": false, "in": "query", "description": "Filter payments from this date (inclusive). Must be in ISO 8601 format in UTC (ending with 'Z'). Example: '2024-01-01T00:00:00.000Z'", "schema": { "example": "2024-01-01T00:00:00.000Z", "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "description": "Filter payments until this date (inclusive). Must be in ISO 8601 format in UTC (ending with 'Z'). Must be after fromDate if both are provided. Example: '2024-01-31T23:59:59.999Z'", "schema": { "example": "2024-01-31T23:59:59.999Z", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "", "schema": { "example": "20", "type": "string" } }, { "name": "offset", "required": false, "in": "query", "description": "", "schema": { "example": "0", "type": "string" } } ], "responses": { "200": { "description": "Payment search results with comprehensive payment data and pagination metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the payment" }, "amount": { "type": "string", "description": "Payment amount as a human-readable decimal string (formatUnits)" }, "sourceNetwork": { "type": "string", "description": "Network where the payment originated" }, "destinationNetwork": { "type": "string", "description": "Network where the payment was received" }, "sourceTxHash": { "type": "string", "nullable": true, "description": "Transaction hash on the source network" }, "destinationTxHash": { "type": "string", "nullable": true, "description": "Transaction hash on the destination network" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was processed" }, "type": { "type": "string", "enum": [ "direct", "conversion", "crosschain", "recurring" ], "description": "Type of payment" }, "conversionRateSource": { "type": "string", "nullable": true, "description": "Conversion rate used for source currency" }, "conversionRateDestination": { "type": "string", "nullable": true, "description": "Conversion rate used for destination currency" }, "convertedAmountSource": { "type": "string", "nullable": true, "description": "Converted amount in source currency" }, "convertedAmountDestination": { "type": "string", "nullable": true, "description": "Converted amount in destination currency" }, "currency": { "type": "string", "description": "Invoice currency symbol" }, "paymentCurrency": { "type": "string", "description": "Payment currency symbol" }, "fees": { "type": "array", "nullable": true, "description": "Array of fees associated with the payment", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "platform", "crosschain", "crypto-to-fiat", "offramp" ], "description": "Type of fee" }, "stage": { "type": "string", "enum": [ "sending", "receiving", "proxying", "refunding" ], "description": "Stage when the fee is applied" }, "provider": { "type": "string", "description": "Provider that charged the fee" }, "amount": { "type": "string", "description": "Fee amount in human-readable format (formatted with token decimals)" }, "amountInUSD": { "type": "string", "description": "Fee amount in USD" }, "currency": { "type": "string", "description": "Fee currency" }, "receiverAddress": { "type": "string", "description": "Address that received the fee" }, "network": { "type": "string", "description": "Network where the fee was paid" }, "rateProvider": { "type": "string", "description": "Provider used for rate conversion" } } } }, "recurringPaymentId": { "type": "string", "nullable": true, "description": "ID of the recurring payment this payment belongs to" }, "rateProvider": { "type": "string", "enum": [ "lifi", "chainlink", "coingecko", "unknown" ], "nullable": true, "description": "Provider used for exchange rate data" }, "request": { "type": "object", "description": "Associated request information", "properties": { "requestId": { "type": "string", "description": "Request ID" }, "paymentReference": { "type": "string", "description": "Payment reference" }, "hasBeenPaid": { "type": "boolean", "description": "Whether the request has been fully paid" }, "customerInfo": { "type": "object", "nullable": true, "description": "Customer information", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } } } }, "reference": { "type": "string", "nullable": true, "description": "Merchant reference" } } } }, "required": [ "id", "amount", "sourceNetwork", "destinationNetwork", "timestamp", "type", "currency", "paymentCurrency" ] }, "description": "Array of matching payments with complete payment details" }, "pagination": { "type": "object", "description": "Pagination information for navigating through results", "properties": { "total": { "type": "number", "description": "Total number of payments matching the search criteria", "example": 157 }, "limit": { "type": "number", "description": "Maximum number of results returned in this response", "example": 20 }, "offset": { "type": "number", "description": "Number of results skipped (for pagination)", "example": 0 }, "hasMore": { "type": "boolean", "description": "Whether there are more results available beyond this page", "example": true } }, "required": [ "total", "limit", "offset", "hasMore" ] } }, "required": [ "payments", "pagination" ] }, "examples": { "searchByTxHash": { "summary": "Search by transaction hash", "value": { "payments": [ { "id": "01HXAMPLE1234567890ABCDEF", "amount": "1000000000000000000", "sourceNetwork": "sepolia", "destinationNetwork": "sepolia", "sourceTxHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "destinationTxHash": null, "timestamp": "2024-01-15T10:30:00.000Z", "type": "conversion", "conversionRateSource": null, "conversionRateDestination": null, "convertedAmountSource": null, "convertedAmountDestination": null, "currency": "USD", "paymentCurrency": "ETH", "fees": [ { "type": "gas", "amount": "21000000000000000", "currency": "ETH", "provider": "request-network" } ], "recurringPaymentId": null, "rateProvider": "chainlink", "request": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "hasBeenPaid": true, "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com" }, "reference": "ORDER-2024-001234" } } ], "pagination": { "total": 1, "limit": 20, "offset": 0, "hasMore": false } } }, "searchByWalletAndDateRange": { "summary": "Search by wallet address with date filtering", "value": { "payments": [ { "id": "01HXAMPLE1111222233334444", "amount": "50000000", "sourceNetwork": "base", "destinationNetwork": "base", "sourceTxHash": "0x1111222233334444555566667777888899990000aaaabbbbccccddddeeeeffff", "destinationTxHash": null, "timestamp": "2024-01-14T16:20:00.000Z", "type": "conversion", "currency": "USD", "paymentCurrency": "USDC", "fees": [ { "type": "platform", "amount": "500000", "currency": "USDC", "provider": "request-network" } ], "request": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xe1f2a3b4c5d67890", "hasBeenPaid": true, "reference": "SERVICE-2024-789" } }, { "id": "01HXAMPLE5555666677778888", "amount": "25000000", "sourceNetwork": "base", "destinationNetwork": "base", "sourceTxHash": "0x5555666677778888999900001111222233334444555566667777888899990000", "destinationTxHash": null, "timestamp": "2024-01-13T09:15:00.000Z", "type": "conversion", "currency": "USD", "paymentCurrency": "USDC", "request": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xf1e2d3c4b5a67890", "hasBeenPaid": true, "reference": "PRODUCT-2024-456" } } ], "pagination": { "total": 2, "limit": 20, "offset": 0, "hasMore": false } } }, "searchByMerchantReference": { "summary": "Search by merchant reference with pagination", "value": { "payments": [ { "id": "01HXAMPLE9999888877776666", "amount": "150000000000000000000", "sourceNetwork": "sepolia", "destinationNetwork": "sepolia", "sourceTxHash": "0x9999888877776666555544443333222211110000ffffeeeedddcccbbbaaa999", "destinationTxHash": null, "timestamp": "2024-01-15T11:45:00.000Z", "type": "conversion", "conversionRateSource": "0.0004", "conversionRateDestination": "2500.0", "convertedAmountSource": "150000000000000000000", "convertedAmountDestination": "60000000", "currency": "USD", "paymentCurrency": "ETH", "fees": [ { "type": "conversion", "amount": "600000000000000000", "currency": "ETH", "provider": "request-network" } ], "request": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xa1b2c3d4e5f67890", "hasBeenPaid": true, "customerInfo": { "firstName": "Sarah", "lastName": "Wilson", "email": "sarah.wilson@company.com", "address": { "street": "789 Pine Street", "city": "Seattle", "state": "WA", "postalCode": "98101", "country": "US" } }, "reference": "SUBSCRIPTION-ANNUAL-2024" } } ], "pagination": { "total": 15, "limit": 1, "offset": 0, "hasMore": true } } } } } } }, "400": { "description": "Invalid search parameters or validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "toDate" }, "message": { "type": "string", "example": "toDate must be after or equal to fromDate" } } } } } } } } }, "401": { "description": "Authentication required - API key or client ID missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Unauthorized" }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Search payments with advanced filtering", "tags": [ "V2/Payments" ] } }, "/v2/payouts": { "post": { "description": "Initiate a payment without having to create a request first. Supports both one-time and recurring payments. For recurring payments, specify the recurrence object with start date, frequency, total executions, and payer address. The system will create a recurring payment schedule and return the necessary transactions for allowance approval and signature submission. Optionally includes customer information (firstName, lastName, email, address) and a merchant reference field for checkout widget implementations and receipt tracking.", "operationId": "PayoutV2Controller_payRequest_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payee": { "type": "string", "description": "The wallet address of the payee (Ethereum 0x... or TRON T...)" }, "amount": { "type": "string", "description": "The payable amount of the invoice, in human readable format" }, "invoiceCurrency": { "type": "string", "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" }, "paymentCurrency": { "type": "string", "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" }, "feePercentage": { "type": "string", "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)" }, "feeAddress": { "type": "string", "description": "Address to receive the fee (Ethereum 0x... or TRON T...)" }, "recurrence": { "type": "object", "properties": { "startDate": { "type": "string", "description": "The start date of the payment, cannot be in the past" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ], "description": "The frequency of the payment" }, "totalPayments": { "type": "number", "minimum": 2, "maximum": 256, "description": "The total number of times the payment will be executed (max 256)." }, "payer": { "type": "string", "description": "The wallet address of the payer. Cannot be the same as the payee address." } }, "required": [ "startDate", "frequency", "totalPayments", "payer" ], "description": "Configuration details for recurring payments" }, "payerWallet": { "type": "string", "description": "The wallet address of the payer, use to check if payer approval exists" }, "payerAddress": { "type": "string", "description": "The wallet address of the payer (alias for payerWallet)" }, "customerInfo": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's first name" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Customer's last name" }, "email": { "type": "string", "maxLength": 255, "format": "email", "description": "Customer's email address" }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 255, "description": "Street address" }, "city": { "type": "string", "maxLength": 100, "description": "City" }, "state": { "type": "string", "maxLength": 100, "description": "State or province" }, "postalCode": { "type": "string", "maxLength": 20, "description": "Postal or ZIP code" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country code (ISO 3166-1 alpha-2)" } }, "description": "Customer's address" } }, "description": "Optional customer information for merchant receipt tracking" }, "reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant reference for receipt tracking and identification" } }, "required": [ "payee", "amount", "invoiceCurrency", "paymentCurrency" ] }, "examples": { "oneTimePayment": { "summary": "One-time payment example", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "ETH-sepolia-sepolia", "feePercentage": "0.02", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } }, "tronUsdtPayment": { "summary": "TRON USDT payment example", "value": { "payee": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", "amount": "10", "invoiceCurrency": "USDT-tron", "paymentCurrency": "USDT-tron" } }, "recurringPayment": { "summary": "Recurring payment example", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "ETH-sepolia-sepolia", "feePercentage": "0.02", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "recurrence": { "startDate": "2030-01-01", "frequency": "DAILY", "totalPayments": 30, "payer": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570" } } }, "erc20Payment": { "summary": "ERC20 token payment example", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "100", "invoiceCurrency": "FAU-sepolia", "paymentCurrency": "FAU-sepolia", "feePercentage": "0.01", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } }, "checkoutWidgetPayment": { "summary": "Checkout widget payment with customer info and reference", "value": { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "25.50", "invoiceCurrency": "USD", "paymentCurrency": "USDC-sepolia", "feePercentage": "2.5", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "address": { "street": "123 Main Street", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } }, "reference": "ORDER-2024-001234" } } } } } }, "responses": { "201": { "description": "Request created and payment initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } }, "required": [ "requestId" ] }, "examples": { "nativeCurrency": { "summary": "Native currency payment (e.g., ETH)", "value": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "transactions": [ { "data": "0xb868980b...00", "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687", "value": { "type": "BigNumber", "hex": "0x038d7ea4c68000" } } ], "metadata": { "stepsRequired": 1, "needsApproval": false, "approvalTransactionIndex": null, "hasEnoughBalance": true, "hasEnoughGas": true } } }, "erc20Token": { "summary": "ERC20 token payment (requires approval)", "value": { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "paymentReference": "0xb3581f0b0f74cc61", "transactions": [ { "data": "0x095ea7b3...ff", "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324cf623C", "value": 0 }, { "data": "0xc219a14d...00", "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE", "value": 0 } ], "metadata": { "stepsRequired": 2, "needsApproval": true, "approvalTransactionIndex": 0, "hasEnoughBalance": true, "hasEnoughGas": true } } }, "recurringPayment": { "summary": "Recurring payment response (requires signature)", "value": { "id": "01JXYJKCAHGFTDR15F2D072ESG", "transactions": [ { "to": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", "data": "0x095ea7b30000000000000000000000000363dD3ccD4f187d7033c57354CA81f998451D590000000000000000000000000000000000000000000000000000000000000000", "value": "0x0" } ], "recurringPaymentPermit": { "domain": { "name": "ERC20RecurringPaymentProxy", "version": "1", "chainId": 11155111, "verifyingContract": "0x0363dD3ccD4f187d7033c57354CA81f998451D59" }, "types": { "SchedulePermit": [ { "name": "subscriber", "type": "address" }, { "name": "token", "type": "address" }, { "name": "recipient", "type": "address" }, { "name": "feeAddress", "type": "address" }, { "name": "amount", "type": "uint128" }, { "name": "feeAmount", "type": "uint128" }, { "name": "gasFee", "type": "uint128" }, { "name": "periodSeconds", "type": "uint32" }, { "name": "firstExec", "type": "uint32" }, { "name": "totalExecutions", "type": "uint8" }, { "name": "nonce", "type": "uint256" }, { "name": "deadline", "type": "uint256" } ] }, "values": { "subscriber": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570", "token": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", "recipient": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10000000000000000000", "feeAmount": "0", "gasFee": "0", "periodSeconds": 86400, "firstExec": 1735732800, "totalExecutions": 30, "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "deadline": 1738404800 } }, "metadata": { "stepsRequired": 2, "totalNeededAllowance": "300000000000000000000", "currentAllowance": "0", "additionalAllowanceNeeded": "300000000000000000000", "existingPaymentsAmount": "0" } } } } } } }, "404": { "description": "Wallet not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Initiate a payment", "tags": [ "Pay", "V2/Payouts" ] } }, "/v2/payouts/batch": { "post": { "description": "Pays multiple payment requests in one transaction by either creating new requests or using existing request IDs. All requests must be on the same network. Supports mixed ERC20, Native, and conversion requests.", "operationId": "PayoutV2Controller_payBatchRequest_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "payee": { "type": "string", "description": "The wallet address of the payee (Ethereum 0x... or TRON T...)" }, "amount": { "type": "string", "description": "The payable amount of the invoice, in human readable format" }, "invoiceCurrency": { "type": "string", "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" }, "paymentCurrency": { "type": "string", "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" } }, "required": [ "payee", "amount", "invoiceCurrency", "paymentCurrency" ] }, "description": "A list of payment requests to be created andprocessed in batch. All requests must be on the same network and contain payment/invoice currency information. Either `requests` or `requestIds` must be provided, but not both." }, "requestIds": { "type": "array", "items": { "type": "string" }, "description": "The request IDs of the existing requests to be paid. Requests must be on the same network. Either `requests` or `requestIds` must be provided, but not both." }, "payer": { "type": "string", "description": "The wallet address of the payer, user to check if approval is needed or not." }, "feePercentage": { "type": "string", "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)" }, "feeAddress": { "type": "string", "description": "Address to receive the fee" } }, "example": { "requests": [ { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "2", "invoiceCurrency": "FAU-sepolia", "paymentCurrency": "FAU-sepolia" }, { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "2", "invoiceCurrency": "fUSDC-sepolia", "paymentCurrency": "fUSDC-sepolia" }, { "payee": "0xb07D2398d2004378cad234DA0EF14f1c94A530e4", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "FAU-sepolia" }, { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "0.00001", "invoiceCurrency": "ETH-sepolia-sepolia", "paymentCurrency": "ETH-sepolia-sepolia" }, { "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "amount": "10", "invoiceCurrency": "USD", "paymentCurrency": "ETH-sepolia-sepolia" } ], "payer": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570" } } } } }, "responses": { "201": { "description": "Batch payment calldata retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "ERC20ApprovalTransactions": { "type": "array", "description": "Array of ERC20 approval transactions needed before the batch payment. Only present when token approval is required.", "items": { "type": "object", "properties": { "data": { "type": "string", "description": "Transaction calldata for the ERC20 approval" }, "to": { "type": "string", "description": "Target ERC20 token contract address for approval" }, "value": { "type": "integer", "description": "Always 0 for ERC20 approvals" } }, "required": [ "data", "to", "value" ] } }, "ERC20BatchPaymentTransaction": { "type": "object", "description": "The batch payment transaction for ERC20 tokens. Only present when the batch contains ERC20 payments.", "properties": { "data": { "type": "string", "description": "Transaction calldata for the ERC20 batch payment" }, "to": { "type": "string", "description": "Target batch payment contract address" }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BigNumber" ] }, "hex": { "type": "string", "description": "Payment amount in EVM-compatible format, encoded in hex. Usually 0 for ERC20 payments" } }, "required": [ "type", "hex" ] } }, "required": [ "data", "to", "value" ] }, "ETHBatchPaymentTransaction": { "type": "object", "description": "The batch payment transaction for native ETH. Only present when the batch contains ETH payments.", "properties": { "data": { "type": "string", "description": "Transaction calldata for the ETH batch payment" }, "to": { "type": "string", "description": "Target batch payment contract address" }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BigNumber" ] }, "hex": { "type": "string", "description": "Payment amount in EVM-compatible format, encoded in hex. Contains the ETH value to send" } }, "required": [ "type", "hex" ] } }, "required": [ "data", "to", "value" ] } }, "additionalProperties": false }, "examples": { "erc20_and_eth_with_approval": { "summary": "Batch payment with approval needed", "value": { "ERC20ApprovalTransactions": [ { "data": "0x095ea7b3...", "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "value": 0 } ], "batchPaymentTransaction": { "data": "0x92cddb91...", "to": "0x67818703c92580c0e106e401F253E8A410A66f8B", "value": { "type": "BigNumber", "hex": "0x0d83b3d1afc58b" } } } }, "erc20_and_eth_no_approval": { "summary": "Batch payment without approval needed", "value": { "ERC20ApprovalTransactions": [], "batchPaymentTransaction": { "data": "0x92cddb91...", "to": "0x67818703c92580c0e106e401F253E8A410A66f8B", "value": { "type": "BigNumber", "hex": "0x0d83b3d1afc58b" } } } } } } } }, "400": { "description": "Requests must be on the same network", "content": { "application/json": { "examples": { "requestsOnDifferentNetworks": { "summary": "Requests on different networks", "value": { "message": "All requests must be on the same network", "error": "Bad Request", "statusCode": 400 } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Pay multiple requests in one transaction", "tags": [ "Pay", "V2/Payouts" ] } }, "/v2/payouts/recurring/{id}": { "post": { "description": "Submit a signature for a recurring payment permit to activate the recurring payment schedule. This endpoint is called after creating a recurring payment and obtaining the permit data. The signature authorizes the recurring payment contract to execute payments on behalf of the payer according to the schedule. Once activated, payments will be executed automatically at the specified intervals.", "operationId": "PayoutV2Controller_submitRecurringPaymentSignature_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ID of the recurring payment", "schema": { "example": "01JXYJKCAHGFTDR15F2D072ESG", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permitSignature": { "type": "string", "description": "The signature of the recurring payment permit." } }, "required": [ "permitSignature" ], "example": { "permitSignature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b" } } } } }, "responses": { "201": { "description": "Recurring payment signature submitted successfully", "content": { "application/json": { "examples": { "success": { "summary": "Signature submitted successfully", "value": { "message": "Recurring payment activated successfully", "id": "01JXYJKCAHGFTDR15F2D072ESG", "status": "active" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "examples": { "invalidSignature": { "summary": "Invalid signature provided", "value": { "message": "Invalid signature provided", "error": "Bad Request", "statusCode": 400 } }, "alreadyActive": { "summary": "Recurring payment is already active", "value": { "message": "Recurring payment is already active", "error": "Bad Request", "statusCode": 400 } } } } } }, "404": { "description": "Recurring payment not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Submit a recurring payment signature", "tags": [ "Pay", "V2/Payouts" ] }, "get": { "description": "Retrieve the current status and execution details of a recurring payment. Returns information about executed payments, remaining executions, next payment date, and overall status. This endpoint is useful for monitoring recurring payment progress and checking if payments are being executed as expected. Note: Customer information (PII) is not included in the response for security reasons.", "operationId": "PayoutV2Controller_getRecurringPaymentStatus_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ID of the recurring payment", "schema": { "example": "01JXYJKCAHGFTDR15F2D072ESG", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recurring payment status retrieved successfully", "content": { "application/json": { "examples": { "active": { "summary": "Active recurring payment", "value": { "processedPayments": 3, "totalPayments": 30, "lastPaymentDate": "2025-01-04T10:00:00.000Z", "nextPaymentDate": "2025-01-05T10:00:00.000Z", "status": "active", "requests": [ { "paymentReference": "0xb3581f0b0f74cc61", "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" } ], "payments": [ { "id": "01JXYJKCAHGFTDR15F2D072ESG", "amount": "10", "timestamp": "2025-01-04T10:00:00.000Z", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } ] } }, "paused": { "summary": "Paused recurring payment", "value": { "processedPayments": 5, "totalPayments": 30, "lastPaymentDate": "2025-01-05T10:00:00.000Z", "nextPaymentDate": null, "status": "paused", "failureCount": 3, "failureReason": "Insufficient token allowance" } }, "completed": { "summary": "Completed recurring payment", "value": { "processedPayments": 30, "totalPayments": 30, "lastPaymentDate": "2025-01-30T10:00:00.000Z", "nextPaymentDate": null, "status": "completed" } } } } } }, "404": { "description": "Recurring payment not found", "content": { "application/json": { "examples": { "notFound": { "summary": "Recurring payment not found", "value": { "message": "Recurring payment not found", "error": "Not Found", "statusCode": 404 } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get the status of a recurring payment", "tags": [ "Pay", "V2/Payouts" ] }, "patch": { "description": "Update a recurring payment by cancelling it or unpausing it. When cancelling, optionally returns a transaction to decrease allowance. When unpausing, resumes execution of a paused recurring payment.", "operationId": "PayoutV2Controller_updateRecurringPayment_v2", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ID of the recurring payment", "schema": { "example": "01JXYJKCAHGFTDR15F2D072ESG", "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key)", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel", "unpause" ], "description": "The action to perform on the recurring payment" } }, "required": [ "action" ], "example": { "action": "cancel" } } } } }, "responses": { "200": { "description": "Recurring payment updated successfully", "content": { "application/json": { "examples": { "cancelled": { "summary": "Recurring payment cancelled", "value": { "id": "01JXYJKCAHGFTDR15F2D072ESG", "status": "cancelled", "transactions": [ { "to": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", "data": "0x095ea7b30000000000000000000000000363dD3ccD4f187d7033c57354CA81f998451D590000000000000000000000000000000000000000000000000000000000000000", "value": "0x0" } ], "metadata": { "remainingPayments": 5, "remainingAmount": "5000000000000000000", "processedPayments": 3, "totalPayments": 8 } } }, "unpaused": { "summary": "Recurring payment unpaused", "value": { "id": "01JXYJKCAHGFTDR15F2D072ESG", "status": "active", "metadata": { "processedPayments": 3, "totalPayments": 8, "nextPaymentDate": "2024-01-15T10:00:00.000Z" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "examples": { "alreadyCancelled": { "summary": "Recurring payment is already cancelled", "value": { "message": "Recurring payment is already cancelled", "error": "Bad Request", "statusCode": 400 } }, "completed": { "summary": "Cannot cancel a completed recurring payment", "value": { "message": "Cannot cancel a completed recurring payment", "error": "Bad Request", "statusCode": 400 } }, "notPaused": { "summary": "Recurring payment is not paused", "value": { "message": "Recurring payment is not paused", "error": "Bad Request", "statusCode": 400 } }, "invalidAction": { "summary": "Invalid action provided", "value": { "message": "Invalid action: invalid_action", "error": "Bad Request", "statusCode": 400 } } } } } }, "404": { "description": "Recurring payment not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Update a recurring payment", "tags": [ "Pay", "V2/Payouts" ] } }, "/v2/secure-payments": { "post": { "description": "Creates a secure payment entry with a token. Accepts an array of payment requests using destination IDs (composite ERC-7828 payee address + token address). The server resolves chain, wallet, and currency from each destination ID. Single item creates a single incoming payment. Multiple items preserve the legacy incoming-payment batch shape and are unrelated to multicall payout parents; create multicall payout parents only through /v2/secure-payments/multicall-payouts. All requests must resolve to the same network. Returns a secure payment URL.", "operationId": "SecurePaymentController_createSecurePayment_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID, session, or orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (required when paired with orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-orchestrator-key", "in": "header", "description": "Orchestrator key for authentication (must be paired with Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use the session_token cookie). Only consulted when no x-orchestrator-key, x-api-key, or x-client-id header is present.", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID / orchestrator auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "destinationId": { "type": "string", "minLength": 1, "description": "Destination ID in composite format: ERC-7828 payee address + token address, separated by ':' (e.g. '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C').\n\nOptional. The server always resolves the destination itself \u2014 from the payee destination bound to the authenticating Client ID, falling back to the platform's active destination \u2014 so you can omit this field whenever the Client ID has a bound payee destination. When you do send it, it must equal the resolved destination ID: a different value is rejected with 403 'Destination does not match the configured payment destination.' Every item in `requests[]` therefore resolves to the same destination. A backend Client ID (one with no allowed domains) must be bound to a payee destination, otherwise creation fails with 403." }, "amount": { "type": "string", "description": "The payable amount, in human readable format" } }, "required": [ "amount" ] }, "minItems": 1, "description": "Array of payment requests. Single item = single incoming payment. Multiple items preserve the legacy incoming-payment batch shape and are unrelated to multicall payout parents. A batch varies only the amounts: every item resolves to the caller's single configured destination, so one create call cannot collect into several different payee destinations." }, "feePercentage": { "type": "string", "description": "DEPRECATED. Legacy fee percentage; ignored. Fees are now resolved server-side from the fee plan snapshot." }, "feeAddress": { "type": "string", "description": "DEPRECATED. Legacy fee recipient; ignored. Fees are now resolved server-side from the fee plan snapshot." }, "reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant reference for receipt tracking and identification" }, "payerIdentifier": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Payer identifier for tracking who is making the payment" }, "redirectUrl": { "type": "string", "description": "URL the payer is redirected to after a successful payment" }, "redirectLabel": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>&\"'`]*$", "description": "Optional label describing the redirect destination" }, "accessPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inherit", "off", "kyt_all_wallets" ] }, "screeningProvider": { "type": "string", "enum": [ "hypernative", "merklescience" ], "nullable": true }, "hideUntilApproved": { "type": "boolean" }, "hidePayeeAddress": { "type": "boolean" }, "allowedPayerAddresses": { "type": "array", "items": { "type": "string" } } }, "description": "Optional per-payment access policy override. If omitted, the payment inherits the destination access policy." } }, "required": [ "requests" ] }, "examples": { "singlePayment": { "summary": "Single payment example", "value": { "requests": [ { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "amount": "10" } ] } }, "singlePaymentResolvedDestination": { "summary": "Single payment, destination resolved from the Client ID", "value": { "requests": [ { "amount": "10" } ] } }, "singlePaymentWithFees": { "summary": "Single payment with fees example", "value": { "requests": [ { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "amount": "10" } ], "feePercentage": "2.5", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } }, "batchPayment": { "summary": "Legacy incoming batch payment example (every item resolves to the same destination)", "value": { "requests": [ { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "amount": "10" }, { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "amount": "5" } ] } } } } } }, "responses": { "201": { "description": "Secure payment entry created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Array of request IDs created for this secure payment" }, "securePaymentUrl": { "type": "string", "format": "uri", "description": "URL to the secure payment page" }, "token": { "type": "string", "description": "Secure payment token" }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Resolved fee plan snapshot. Null when fees don't apply \u2014 e.g. non-stablecoin currency, or a batch that spans multiple currencies (not yet supported).", "nullable": true } }, "required": [ "requestIds", "securePaymentUrl", "token", "feePlan" ] }, "examples": { "singlePayment": { "summary": "Single payment response", "value": { "requestIds": [ "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" ], "securePaymentUrl": "https://secure.request.network/01ABC123DEF456GHI789JKL", "token": "01ABC123DEF456GHI789JKL" } }, "batchPayment": { "summary": "Batch payment response", "value": { "requestIds": [ "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cde" ], "securePaymentUrl": "https://secure.request.network/01ABC123DEF456GHI789JKL", "token": "01ABC123DEF456GHI789JKL" } } } } } }, "400": { "description": "Invalid request body, no active payment destination for the platform, `requests[]` items resolving to more than one network, or a multi-item batch on a TRON network." }, "401": { "description": "Unauthorized" }, "403": { "description": "The supplied `destinationId` does not match the destination resolved for the caller, the authenticated platform is not wallet-based, or a backend Client ID (no allowed domains) is not bound to a payee destination." }, "429": { "description": "Too Many Requests" } }, "summary": "Create a secure payment entry", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" }, "get": { "description": "Looks up the secure payment associated with a given request ID. Returns the payment link URL, status, and metadata. Requires a SIWE session.", "operationId": "SecurePaymentController_findSecurePayment_v2", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use session_token cookie)", "required": true, "schema": { "type": "string" } }, { "name": "requestId", "required": true, "in": "query", "description": "Request ID to look up the associated secure payment", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Secure payment found", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Secure payment token" }, "securePaymentUrl": { "type": "string", "format": "uri", "description": "URL to the secure payment page" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "invalidated", "compliance_failed" ], "description": "Current status of the secure payment" }, "paymentType": { "type": "string", "enum": [ "single", "batch" ], "description": "Type of payment: single or batch" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the secure payment was created", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the secure payment token expires" }, "redirectUrl": { "type": "string", "description": "Optional redirect URL configured at creation time. Null when no redirect was set.", "nullable": true }, "redirectLabel": { "type": "string", "description": "Optional label describing the redirect destination. Null when no label was provided.", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "description": "When the secure payment was completed", "nullable": true }, "payerAddress": { "type": "string", "description": "Detected payer address for the completed secure payment", "nullable": true }, "payerKytResults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "walletType": { "type": "string", "enum": [ "eoa", "smart_account" ] }, "parentWalletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "reasonCode": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "providerReference": { "type": "string", "nullable": true }, "reportUrl": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "rawStatus": { "type": "string", "nullable": true }, "evaluatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true } }, "required": [ "walletAddress", "walletType", "parentWalletAddress", "status", "reasonCode", "provider", "providerReference", "reportUrl", "notes", "rawStatus", "evaluatedAt" ], "description": "KYT result for a wallet screened for a secure payment" }, "description": "KYT results for the actual detected payer wallets only" }, "payeeKytResults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "walletType": { "type": "string", "enum": [ "eoa", "smart_account" ] }, "parentWalletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "reasonCode": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "providerReference": { "type": "string", "nullable": true }, "reportUrl": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "rawStatus": { "type": "string", "nullable": true }, "evaluatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true } }, "required": [ "walletAddress", "walletType", "parentWalletAddress", "status", "reasonCode", "provider", "providerReference", "reportUrl", "notes", "rawStatus", "evaluatedAt" ], "description": "KYT result for a wallet screened for a secure payment" }, "description": "KYT results for outgoing payout payee wallets only" }, "destination": { "type": "object", "properties": { "destinationId": { "type": "string", "description": "Composite destination ID: ERC-7828 payee address + token address (e.g., '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C'). Omitted when payee-address fields are masked." }, "payeeAddress": { "type": "string", "description": "Payee address in ERC-7828 human-readable format" }, "tokenAddress": { "type": "string", "description": "ERC20 token contract address" }, "walletAddress": { "type": "string", "description": "Raw wallet address" }, "network": { "type": "string", "description": "Blockchain network name" }, "isMasked": { "type": "boolean", "description": "Whether payee-address fields in this destination are intentionally masked" } }, "required": [ "payeeAddress", "tokenAddress", "walletAddress", "network" ], "description": "Resolved destination for the selected request row, when stored", "nullable": true }, "claimedDestination": { "type": "object", "properties": { "destinationId": { "type": "string", "description": "Composite destination ID: ERC-7828 payee address + token address (e.g., '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C'). Omitted when payee-address fields are masked." }, "payeeAddress": { "type": "string", "description": "Payee address in ERC-7828 human-readable format" }, "tokenAddress": { "type": "string", "description": "ERC20 token contract address" }, "walletAddress": { "type": "string", "description": "Raw wallet address" }, "network": { "type": "string", "description": "Blockchain network name" }, "isMasked": { "type": "boolean", "description": "Whether payee-address fields in this destination are intentionally masked" } }, "required": [ "payeeAddress", "tokenAddress", "walletAddress", "network" ], "description": "Recipient claimed destination snapshot captured when the payout was created. Null when the recipient had no claimed destination or the row predates this snapshot.", "nullable": true }, "orchestratorId": { "type": "string", "description": "Orchestrator ID associated with the secure payment, if any", "nullable": true }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Fee plan snapshot persisted at secure payment creation. Immutable, so it reflects the fees that applied to the payment whether it is still pending or already completed. Null when no snapshot was stored \u2014 e.g. non-stablecoin currency, or a batch that spans multiple currencies (not yet supported).", "nullable": true }, "network": { "type": "string", "description": "Request destination network. Dashboard uses this as an advisory multicall selection hint; creation and /pay still revalidate server-side." }, "currency": { "type": "string", "description": "Request payment currency ID, when available. Null means the row predates the hint or has malformed stored currency data.", "nullable": true }, "executionKind": { "type": "string", "enum": [ "evm_same_chain", "evm_cross_chain", "tron_batch" ], "description": "Per-row execution-family hint for Dashboard selection. EVM rows can form same-chain or cross-chain multicalls depending on the selected set; Tron rows can only form Tron batches. Null means unsupported or inconsistent stored route data.", "nullable": true }, "identityMode": { "type": "string", "enum": [ "manual_dashboard", "client_id" ], "description": "Backend-derived identity bucket hint for multicall selection. Dashboard may use it to prevent mixed manual/clientId selections, but creation remains authoritative." }, "clientId": { "type": "string", "description": "ClientId identity bucket when identityMode is client_id.", "nullable": true }, "branding": { "type": "object", "properties": { "whitelabelEnabled": { "type": "boolean" }, "source": { "type": "string", "enum": [ "client_id", "request_network" ] } }, "required": [ "whitelabelEnabled", "source" ], "description": "Dashboard selection hint for neutral versus clientId-backed branding. Lets Dashboard distinguish neutral rows from clientId-backed rows so it can prevent mixed-branding selections at the UI level; creation remains authoritative." }, "childExecutable": { "type": "boolean", "description": "Whether this secure-payment child currently passes creation-time child validation." }, "blockReason": { "type": "string", "enum": [ "not_found", "not_owned", "not_outgoing", "not_single_payment", "invalid_child_linkage", "already_paid", "request_processing", "secure_payment_expired", "secure_payment_not_pending", "compliance_failed", "not_payable_child" ], "description": "Creation-validation block reason when childExecutable is false. Null when the child is currently executable.", "nullable": true } }, "required": [ "token", "securePaymentUrl", "status", "paymentType", "createdAt", "expiresAt", "redirectUrl", "redirectLabel", "completedAt", "payerAddress", "payerKytResults", "payeeKytResults", "destination", "claimedDestination", "orchestratorId", "feePlan", "network", "currency", "executionKind", "identityMode", "clientId", "branding", "childExecutable", "blockReason" ] }, "examples": { "found": { "summary": "Secure payment found for request", "value": { "token": "01ABC123DEF456GHI789JKL", "securePaymentUrl": "https://secure.request.network/?token=01ABC123DEF456GHI789JKL", "status": "pending", "paymentType": "single", "createdAt": "2025-01-15T10:30:00.000Z", "expiresAt": "2025-01-15T10:45:00.000Z", "redirectUrl": "https://merchant.example.com/thank-you", "redirectLabel": "Back to merchant" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "No secure payment found for this request ID" }, "429": { "description": "Too Many Requests" } }, "summary": "Find secure payment by request ID", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/payouts": { "post": { "description": "Creates a single-payment secure-payment link for an outgoing payout. The caller provides the raw recipient details (wallet, network, currency, amount); the API resolves or creates the wallet/network/currency destination tuple and links the payout to that tuple. Returns the same response shape as POST /v2/secure-payments/ so the resulting link loads on the secure payment page without a separate code path.", "operationId": "SecurePaymentController_createPayoutSecurePayment_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID, session, or orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (required when paired with orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-orchestrator-key", "in": "header", "description": "Orchestrator key for authentication (must be paired with Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use the session_token cookie). Only consulted when no x-orchestrator-key, x-api-key, or x-client-id header is present.", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID / orchestrator auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "description": "Recipient wallet address (EVM 0x... or TRON T...)" }, "creatorWalletAddress": { "type": "string", "description": "Wallet address that created the payout link. This is not necessarily the wallet that will execute the payment." }, "network": { "type": "string", "minLength": 1, "description": "Blockchain network the payout targets (e.g., 'mainnet', 'sepolia', 'tron')" }, "currency": { "type": "string", "minLength": 1, "description": "Currency ID in the '-' format (e.g., 'USDC-mainnet', 'FAU-sepolia')" }, "amount": { "type": "string", "description": "The payout amount, in human readable format" }, "reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant reference for receipt tracking and identification" }, "recipientIdentifier": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Recipient identifier for tracking outgoing payout recipients" }, "feePercentage": { "type": "string", "description": "DEPRECATED. Legacy fee percentage; ignored. Fees are now resolved server-side from the fee plan snapshot." }, "feeAddress": { "type": "string", "description": "DEPRECATED. Legacy fee recipient; ignored. Fees are now resolved server-side from the fee plan snapshot." }, "redirectUrl": { "type": "string", "description": "URL the payer is redirected to after a successful payment" }, "redirectLabel": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>&\"'`]*$", "description": "Optional label describing the redirect destination" }, "accessPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inherit", "off", "kyt_all_wallets" ] }, "screeningProvider": { "type": "string", "enum": [ "hypernative", "merklescience" ], "nullable": true }, "hideUntilApproved": { "type": "boolean" }, "hidePayeeAddress": { "type": "boolean" }, "allowedPayerAddresses": { "type": "array", "items": { "type": "string" } } }, "description": "Optional per-payment access policy override." } }, "required": [ "recipient", "creatorWalletAddress", "network", "currency", "amount" ] }, "examples": { "payout": { "summary": "Payout example", "value": { "recipient": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "network": "sepolia", "currency": "FAU-sepolia", "amount": "10", "recipientIdentifier": "recipient-acme" } }, "payoutWithFees": { "summary": "Payout with fees example", "value": { "recipient": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "network": "sepolia", "currency": "FAU-sepolia", "amount": "10", "feePercentage": "2.5", "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "reference": "PAYOUT-2025-001" } } } } } }, "responses": { "201": { "description": "Payout secure payment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Array of request IDs created for this secure payment" }, "securePaymentUrl": { "type": "string", "format": "uri", "description": "URL to the secure payment page" }, "token": { "type": "string", "description": "Secure payment token" }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Resolved fee plan snapshot. Null when fees don't apply \u2014 e.g. non-stablecoin currency, or a batch that spans multiple currencies (not yet supported).", "nullable": true } }, "required": [ "requestIds", "securePaymentUrl", "token", "feePlan" ] } } } }, "400": { "description": "Invalid payout request (e.g., unsupported network or currency)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Platform is not allowed to create payouts" }, "429": { "description": "Too Many Requests" } }, "summary": "Create a secure payment for an outgoing payout", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/fees/preview": { "post": { "description": "Calculation-only preview of the fee plan that would apply to a payment with the given amount, currency, and flow. Uses the same fee resolver as creation. Has no side effects: does not create a secure payment, payment request, or persist any snapshot.", "operationId": "SecurePaymentController_previewFees_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID, session, or orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (required when paired with orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-orchestrator-key", "in": "header", "description": "Orchestrator key for authentication (must be paired with Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use the session_token cookie). Only consulted when no x-orchestrator-key, x-api-key, or x-client-id header is present.", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID / orchestrator auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "Base/displayed amount in human-readable units, as a decimal string (e.g. \"12.5\")." }, "currency": { "type": "string", "minLength": 1, "description": "Currency symbol or currency ID (e.g. 'USDC' or 'USDC-mainnet'). Must resolve to a supported stablecoin." }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ], "description": "`get_paid` for incoming payments (recipient creates link), `pay` for outgoing payments (payer initiates)." }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ], "description": "Payment-level override of the flow default. Per-fee config bearer still wins." } }, "required": [ "amount", "currency", "flow" ] }, "examples": { "getPaid": { "summary": "Get-paid preview (recipient bears fees by default)", "value": { "amount": "100", "currency": "USDC", "flow": "get_paid" } }, "pay": { "summary": "Pay preview (payer bears fees by default)", "value": { "amount": "100", "currency": "USDC", "flow": "pay" } }, "withOverride": { "summary": "Get-paid with payer-borne override", "value": { "amount": "100", "currency": "USDC", "flow": "get_paid", "defaultFeeBearer": "payer" } } } } } }, "responses": { "200": { "description": "Fee plan preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ] } } } }, "400": { "description": "Unsupported currency or invalid combination" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" } }, "summary": "Preview the fee plan for a payment", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/batch-payouts": { "post": { "description": "Creates a single batch payout link from multiple existing pending single payout tokens. The individual tokens are invalidated and a new batch payment URL is returned. All payouts must target the same network.", "operationId": "SecurePaymentController_createBatchPayoutSecurePayment_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID or session)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (optional if using API key or session)", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use the session_token cookie). Only consulted when no x-orchestrator-key, x-api-key, or x-client-id header is present.", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2, "description": "Tokens of existing pending single payout secure payments to combine into one batch payment link" }, "redirectUrl": { "type": "string", "description": "URL the payer is redirected to after a successful payment" }, "redirectLabel": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^<>&\"'`]*$", "description": "Optional label describing the redirect destination" } }, "required": [ "tokens" ] } } } }, "responses": { "201": { "description": "Batch payout secure payment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Array of request IDs created for this secure payment" }, "securePaymentUrl": { "type": "string", "format": "uri", "description": "URL to the secure payment page" }, "token": { "type": "string", "description": "Secure payment token" }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Resolved fee plan snapshot. Null when fees don't apply \u2014 e.g. non-stablecoin currency, or a batch that spans multiple currencies (not yet supported).", "nullable": true } }, "required": [ "requestIds", "securePaymentUrl", "token", "feePlan" ] } } } }, "400": { "description": "Invalid request (e.g., tokens on different networks, non-pending tokens, less than 2 tokens)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Platform is not allowed to create payouts" }, "429": { "description": "Too Many Requests" } }, "summary": "Create a batch secure payment for multiple outgoing payouts", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/{token}": { "get": { "description": "Retrieves secure payment display data and resolved destination info. The token must be valid, not expired, and the payment must be in 'pending' status.", "operationId": "SecurePaymentController_getSecurePaymentByToken_v2", "parameters": [ { "name": "token", "in": "path", "description": "Secure payment token (ULID) returned by POST /v2/secure-payments, POST /v2/secure-payments/payouts, or POST /v2/secure-payments/multicall-payouts. Distinct from the `token` query parameter, which selects the crosschain source currency.", "required": true, "schema": { "type": "string" } }, { "name": "token", "required": false, "in": "query", "description": "The source token of the crosschain payment. Pair with `chain`; both must be sent together. Not the secure payment token \u2014 that is the `{token}` path parameter.", "schema": { "enum": [ "USDC", "USDT", "EURC", "USDT0" ], "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } }, { "name": "wallet", "required": false, "in": "query", "description": "The wallet address of the payer (optional, used to check existing approvals)", "schema": { "type": "string" } }, { "name": "chain", "required": false, "in": "query", "description": "The source chain of the crosschain payment", "schema": { "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM", "POLYGON", "BNB" ], "type": "string" } }, { "name": "eoaWallet", "required": false, "in": "query", "description": "The EOA wallet address that holds the funds. When provided, balance checks and LiFi quotes use this address while the wallet param is used for calldata building (smart account flow).", "schema": { "type": "string" } }, { "name": "isSafe", "required": false, "in": "query", "description": "When true, prepares calldata for a Gnosis Safe multisig payer (wallet must be the Safe address). Mutually exclusive with eoaWallet.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Secure payment data retrieved successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "single" ], "description": "Type of payment: single or batch" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "invalidated", "compliance_failed" ] }, "redirectUrl": { "type": "string", "description": "Optional redirect URL configured at creation time. Null when no redirect was set.", "nullable": true }, "redirectLabel": { "type": "string", "description": "Optional label describing the redirect destination. Null when no label was provided.", "nullable": true }, "orchestratorId": { "type": "string", "description": "Orchestrator ID associated with the secure payment, if any", "nullable": true }, "branding": { "type": "object", "properties": { "id": { "type": "string" }, "clientIdId": { "type": "string" }, "orchestratorId": { "type": "string" }, "logoPath": { "type": "string" }, "pageBackgroundColor": { "type": "string" }, "cardBackgroundColor": { "type": "string" }, "primaryActionColor": { "type": "string" }, "primaryTextColor": { "type": "string" }, "secondaryTextColor": { "type": "string" }, "termsPath": { "type": "string" }, "privacyPath": { "type": "string" }, "displayRequestBranding": { "type": "boolean" } }, "required": [ "id" ], "nullable": true }, "paymentOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "balance": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" }, "neededAmount": { "type": "string" } }, "required": [ "balance", "hasEnoughBalance", "neededAmount" ] } } }, "analytics": { "type": "object", "properties": { "creationTimestamp": { "type": "string", "format": "date-time" }, "totalPaymentAmountUsd": { "type": "string" }, "protocolFeeAmountUsd": { "type": "string" }, "orchestratorPayerFeeAmountUsd": { "type": "string" }, "orchestratorRecipientFeeAmountUsd": { "type": "string" }, "feeAmountsUsdUnavailableReason": { "type": "string", "enum": [ "fee_plan_unavailable" ] }, "numberOfPaymentsExcludingFees": { "type": "integer", "minimum": 0 }, "destinationIds": { "type": "array", "items": { "type": "string" } }, "payoutKytProvider": { "type": "string" } }, "description": "Vendor-neutral analytics metadata that SPP maps into Mixpanel shared properties. Amount values are decimal USD strings to avoid frontend precision loss." }, "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Request Network request IDs represented by this payment" }, "payee": { "type": "string", "description": "Payee wallet address" }, "network": { "type": "string", "description": "Blockchain network" }, "amount": { "type": "string", "description": "Payment amount" }, "paymentCurrency": { "type": "string", "description": "Payment currency ID" }, "isNativeCurrency": { "type": "boolean", "description": "Whether the payment currency is the native currency (e.g., ETH)" }, "destination": { "type": "object", "properties": { "destinationId": { "type": "string", "description": "Composite destination ID: ERC-7828 payee address + token address (e.g., '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C'). Omitted when payee-address fields are masked." }, "payeeAddress": { "type": "string", "description": "Payee address in ERC-7828 human-readable format" }, "tokenAddress": { "type": "string", "description": "ERC20 token contract address" }, "walletAddress": { "type": "string", "description": "Raw wallet address" }, "network": { "type": "string", "description": "Blockchain network name" }, "isMasked": { "type": "boolean", "description": "Whether payee-address fields in this destination are intentionally masked" } }, "required": [ "payeeAddress", "tokenAddress", "walletAddress", "network" ], "description": "Resolved destination for this payment, or null when the payment is not linked to a stored destination (e.g., payouts created from raw recipient details).", "nullable": true }, "reference": { "type": "string", "description": "Merchant reference for the payment", "nullable": true }, "isPayeeAddressMasked": { "type": "boolean", "description": "Whether payee-address fields are intentionally masked until access is approved" }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Fee plan snapshot captured at creation time. Null when fees don't apply (non-stablecoin currency, payment created before fee plan rollout, etc.).", "nullable": true }, "accessDecision": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "walletResults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "walletType": { "type": "string", "enum": [ "eoa", "smart_account" ] }, "parentWalletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "evaluatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": [ "walletAddress", "walletType", "status", "reasonCode", "provider" ] } } }, "required": [ "status", "reasonCode", "provider", "walletResults" ] } }, "required": [ "paymentType", "status", "redirectUrl", "redirectLabel", "branding", "requestIds", "payee", "network", "amount", "paymentCurrency", "isNativeCurrency", "destination", "reference", "feePlan" ] }, { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "batch" ], "description": "Type of payment: single or batch" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "invalidated", "compliance_failed" ] }, "redirectUrl": { "type": "string", "description": "Optional redirect URL configured at creation time. Null when no redirect was set.", "nullable": true }, "redirectLabel": { "type": "string", "description": "Optional label describing the redirect destination. Null when no label was provided.", "nullable": true }, "orchestratorId": { "type": "string", "description": "Orchestrator ID associated with the secure payment, if any", "nullable": true }, "branding": { "type": "object", "properties": { "id": { "type": "string" }, "clientIdId": { "type": "string" }, "orchestratorId": { "type": "string" }, "logoPath": { "type": "string" }, "pageBackgroundColor": { "type": "string" }, "cardBackgroundColor": { "type": "string" }, "primaryActionColor": { "type": "string" }, "primaryTextColor": { "type": "string" }, "secondaryTextColor": { "type": "string" }, "termsPath": { "type": "string" }, "privacyPath": { "type": "string" }, "displayRequestBranding": { "type": "boolean" } }, "required": [ "id" ], "nullable": true }, "paymentOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "balance": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" }, "neededAmount": { "type": "string" } }, "required": [ "balance", "hasEnoughBalance", "neededAmount" ] } } }, "analytics": { "type": "object", "properties": { "creationTimestamp": { "type": "string", "format": "date-time" }, "totalPaymentAmountUsd": { "type": "string" }, "protocolFeeAmountUsd": { "type": "string" }, "orchestratorPayerFeeAmountUsd": { "type": "string" }, "orchestratorRecipientFeeAmountUsd": { "type": "string" }, "feeAmountsUsdUnavailableReason": { "type": "string", "enum": [ "fee_plan_unavailable" ] }, "numberOfPaymentsExcludingFees": { "type": "integer", "minimum": 0 }, "destinationIds": { "type": "array", "items": { "type": "string" } }, "payoutKytProvider": { "type": "string" } }, "description": "Vendor-neutral analytics metadata that SPP maps into Mixpanel shared properties. Amount values are decimal USD strings to avoid frontend precision loss." }, "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Request Network request IDs represented by this payment" }, "payees": { "type": "array", "items": { "type": "string" }, "description": "Array of payee wallet addresses. Order matches amounts and paymentCurrencies arrays." }, "network": { "type": "string", "description": "Blockchain network" }, "amounts": { "type": "array", "items": { "type": "string" }, "description": "Array of payment amounts. Order matches payees and paymentCurrencies arrays." }, "paymentCurrencies": { "type": "array", "items": { "type": "string" }, "description": "Array of payment currency IDs. Order matches payees and amounts arrays. Each index corresponds to one payment request." }, "isNativeCurrency": { "type": "array", "items": { "type": "boolean" }, "description": "Array indicating whether each payment currency is native. Order matches payees, amounts, and paymentCurrencies arrays." }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "destinationId": { "type": "string", "description": "Composite destination ID: ERC-7828 payee address + token address (e.g., '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C'). Omitted when payee-address fields are masked." }, "payeeAddress": { "type": "string", "description": "Payee address in ERC-7828 human-readable format" }, "tokenAddress": { "type": "string", "description": "ERC20 token contract address" }, "walletAddress": { "type": "string", "description": "Raw wallet address" }, "network": { "type": "string", "description": "Blockchain network name" }, "isMasked": { "type": "boolean", "description": "Whether payee-address fields in this destination are intentionally masked" } }, "required": [ "payeeAddress", "tokenAddress", "walletAddress", "network" ], "nullable": true }, "description": "Resolved destinations for each payment in the batch. Order matches payees array. Entries may be null when a payment is not linked to a stored destination." }, "reference": { "type": "string", "description": "Merchant reference for the payment", "nullable": true }, "isPayeeAddressMasked": { "type": "boolean", "description": "Whether payee-address fields are intentionally masked until access is approved" }, "feePlan": { "allOf": [ { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Fee plan snapshot captured at creation time. Null when fees don't apply (non-stablecoin currency, payment created before fee plan rollout, etc.).", "nullable": true }, { "description": "Fee plan snapshot captured at creation time. Null when fees don't apply (non-stablecoin currency, multi-currency batch, payment created before fee plan rollout, etc.)." } ] }, "accessDecision": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "walletResults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "walletType": { "type": "string", "enum": [ "eoa", "smart_account" ] }, "parentWalletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "evaluatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": [ "walletAddress", "walletType", "status", "reasonCode", "provider" ] } } }, "required": [ "status", "reasonCode", "provider", "walletResults" ] } }, "required": [ "paymentType", "status", "redirectUrl", "redirectLabel", "branding", "requestIds", "payees", "network", "amounts", "paymentCurrencies", "isNativeCurrency", "destinations", "reference", "feePlan" ] }, { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "single", "batch" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "expired", "invalidated", "compliance_failed" ] }, "redirectUrl": { "type": "string", "description": "Optional redirect URL configured at creation time. Null when no redirect was set.", "nullable": true }, "redirectLabel": { "type": "string", "description": "Optional label describing the redirect destination. Null when no label was provided.", "nullable": true }, "orchestratorId": { "type": "string", "description": "Orchestrator ID associated with the secure payment, if any", "nullable": true }, "branding": { "type": "object", "properties": { "id": { "type": "string" }, "clientIdId": { "type": "string" }, "orchestratorId": { "type": "string" }, "logoPath": { "type": "string" }, "pageBackgroundColor": { "type": "string" }, "cardBackgroundColor": { "type": "string" }, "primaryActionColor": { "type": "string" }, "primaryTextColor": { "type": "string" }, "secondaryTextColor": { "type": "string" }, "termsPath": { "type": "string" }, "privacyPath": { "type": "string" }, "displayRequestBranding": { "type": "boolean" } }, "required": [ "id" ], "nullable": true }, "paymentOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "balance": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" }, "neededAmount": { "type": "string" } }, "required": [ "balance", "hasEnoughBalance", "neededAmount" ] } } }, "analytics": { "type": "object", "properties": { "creationTimestamp": { "type": "string", "format": "date-time" }, "totalPaymentAmountUsd": { "type": "string" }, "protocolFeeAmountUsd": { "type": "string" }, "orchestratorPayerFeeAmountUsd": { "type": "string" }, "orchestratorRecipientFeeAmountUsd": { "type": "string" }, "feeAmountsUsdUnavailableReason": { "type": "string", "enum": [ "fee_plan_unavailable" ] }, "numberOfPaymentsExcludingFees": { "type": "integer", "minimum": 0 }, "destinationIds": { "type": "array", "items": { "type": "string" } }, "payoutKytProvider": { "type": "string" } }, "description": "Vendor-neutral analytics metadata that SPP maps into Mixpanel shared properties. Amount values are decimal USD strings to avoid frontend precision loss." }, "accessDecision": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "walletResults": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "walletType": { "type": "string", "enum": [ "eoa", "smart_account" ] }, "parentWalletAddress": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "rejected", "error" ] }, "reasonCode": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "evaluatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": [ "walletAddress", "walletType", "status", "reasonCode", "provider" ] } } }, "required": [ "status", "reasonCode", "provider", "walletResults" ] } }, "required": [ "paymentType", "status", "branding" ] }, { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "multicall" ] }, "status": { "type": "string", "enum": [ "pending", "expired", "completed", "partially_settled" ] }, "redirectUrl": { "type": "string", "nullable": true }, "redirectLabel": { "type": "string", "nullable": true }, "orchestratorId": { "type": "string", "nullable": true }, "branding": { "type": "object", "properties": { "id": { "type": "string" }, "clientIdId": { "type": "string" }, "orchestratorId": { "type": "string" }, "logoPath": { "type": "string" }, "pageBackgroundColor": { "type": "string" }, "cardBackgroundColor": { "type": "string" }, "primaryActionColor": { "type": "string" }, "primaryTextColor": { "type": "string" }, "secondaryTextColor": { "type": "string" }, "termsPath": { "type": "string" }, "privacyPath": { "type": "string" }, "displayRequestBranding": { "type": "boolean" } }, "required": [ "id" ], "nullable": true }, "paymentOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "balance": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" }, "neededAmount": { "type": "string" } }, "required": [ "balance", "hasEnoughBalance", "neededAmount" ] } } }, "analytics": { "type": "object", "properties": { "creationTimestamp": { "type": "string", "format": "date-time" }, "totalPaymentAmountUsd": { "type": "string" }, "protocolFeeAmountUsd": { "type": "string" }, "orchestratorPayerFeeAmountUsd": { "type": "string" }, "orchestratorRecipientFeeAmountUsd": { "type": "string" }, "feeAmountsUsdUnavailableReason": { "type": "string", "enum": [ "fee_plan_unavailable" ] }, "numberOfPaymentsExcludingFees": { "type": "integer", "minimum": 0 }, "destinationIds": { "type": "array", "items": { "type": "string" } }, "payoutKytProvider": { "type": "string" } }, "description": "Vendor-neutral analytics metadata that SPP maps into Mixpanel shared properties. Amount values are decimal USD strings to avoid frontend precision loss." }, "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Request Network request IDs represented by this payment" }, "token": { "type": "string", "description": "Multicall payout token" }, "canExecute": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "children": { "type": "array", "items": { "type": "object", "properties": { "securePaymentToken": { "type": "string", "description": "Child secure-payment token" }, "requestId": { "type": "string", "description": "Request Network request ID for the child payout" }, "position": { "type": "integer", "minimum": 0, "description": "0-indexed child order" }, "executable": { "type": "boolean", "description": "Whether this child can currently be executed in the multicall" }, "blockReason": { "type": "string", "enum": [ "not_found", "not_owned", "not_outgoing", "not_single_payment", "invalid_child_linkage", "already_paid", "request_processing", "secure_payment_expired", "secure_payment_not_pending", "compliance_failed", "not_payable_child" ], "description": "Structured reason when executable is false; otherwise null", "nullable": true }, "messageKey": { "type": "string", "description": "Stable localized-message key for the block reason", "nullable": true }, "context": { "type": "object", "properties": { "requestId": { "type": "string" }, "securePaymentToken": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "hasBeenPaid": { "type": "boolean" }, "securePaymentStatus": { "type": "string" }, "requestStatus": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "network": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "requestId", "securePaymentToken", "position", "hasBeenPaid" ], "description": "Per-child block context used by SPP to render recovery details" }, "recoveryAction": { "type": "string", "enum": [ "remove_child", "recreate_reduced", "wait_for_quote_refresh", "switch_route", "recreate_after_cooldown", "support_required" ], "description": "Suggested recovery action when the child is blocked", "nullable": true }, "feePlan": { "allOf": [ { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Fee plan snapshot captured at creation time. Null when fees don't apply (non-stablecoin currency, payment created before fee plan rollout, etc.).", "nullable": true }, { "description": "Persisted child fee-plan snapshot. Null when fees do not apply or no snapshot exists." } ] }, "amount": { "type": "string", "description": "Human-readable child amount in the child's payment currency. Null when unavailable.", "nullable": true }, "payee": { "type": "string", "description": "Resolved child recipient address. Null when unavailable.", "nullable": true }, "reference": { "type": "string", "description": "Merchant reference for the child payment. Null when none was provided.", "nullable": true } }, "required": [ "securePaymentToken", "requestId", "position", "executable", "blockReason", "messageKey", "context", "recoveryAction", "feePlan", "amount", "payee", "reference" ] } }, "totals": { "type": "object", "properties": { "childCount": { "type": "integer", "minimum": 0 }, "blockedChildCount": { "type": "integer", "minimum": 0 }, "byDestinationCurrency": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "currency": { "type": "string" }, "totalAmount": { "type": "string" } }, "required": [ "network", "currency", "totalAmount" ] } }, "amountSummary": { "type": "object", "properties": { "grossAmount": { "type": "string" }, "netRecipientAmount": { "type": "string" }, "totalFees": { "type": "string" }, "payeeBorneFees": { "type": "string" }, "payerBorneFees": { "type": "string" }, "payerTotal": { "type": "string" } }, "required": [ "grossAmount", "netRecipientAmount", "totalFees", "payeeBorneFees", "payerBorneFees", "payerTotal" ] } }, "required": [ "childCount", "blockedChildCount", "byDestinationCurrency", "amountSummary" ] } }, "required": [ "paymentType", "status", "redirectUrl", "redirectLabel", "orchestratorId", "branding", "analytics", "requestIds", "token", "canExecute", "expiresAt", "createdAt", "children", "totals" ] } ] }, "examples": { "singlePayment": { "summary": "Single payment response", "value": { "paymentType": "single", "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "network": "sepolia", "amount": "10000000000000000000", "paymentCurrency": "FAU-sepolia", "status": "pending", "destination": { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "payeeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4", "tokenAddress": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "walletAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "network": "sepolia" }, "reference": "INV-2025-001" } }, "batchPayment": { "summary": "Batch payment response", "value": { "paymentType": "batch", "payees": [ "0xb07d2398d2004378cad234da0ef14f1c94a530e4", "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" ], "network": "sepolia", "amounts": [ "50", "10" ], "paymentCurrencies": [ "FAU-sepolia", "FAU-sepolia" ], "status": "pending", "destinations": [ { "destinationId": "0xb07d2398d2004378cad234da0ef14f1c94a530e4@eip155:11155111#C3D4E5F6:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "payeeAddress": "0xb07d2398d2004378cad234da0ef14f1c94a530e4@eip155:11155111#C3D4E5F6", "tokenAddress": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "walletAddress": "0xb07d2398d2004378cad234da0ef14f1c94a530e4", "network": "sepolia" }, { "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "payeeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4", "tokenAddress": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", "walletAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "network": "sepolia" } ], "reference": "BATCH-REF-001" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Secure payment token expired or invalid status" }, "404": { "description": "Secure payment not found" }, "409": { "description": "Secure payment has already been completed", "content": { "application/json": { "examples": { "alreadyPaid": { "summary": "Payment already completed", "value": { "message": "Secure payment has already been completed", "status": "completed", "branding": { "id": "brand_1", "clientIdId": "client_1", "logoPath": "/branding/client/logo.png", "pageBackgroundColor": "#ffffff", "cardBackgroundColor": "#ffffff", "primaryActionColor": "#00d395", "primaryTextColor": "#475569", "secondaryTextColor": "#94a3b8", "termsPath": "/branding/client/terms.html", "privacyPath": "/branding/client/privacy.html", "displayRequestBranding": false }, "requestStatuses": [ { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "hasBeenPaid": true, "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } ] } } } } } }, "423": { "description": "Secure payment is in progress", "content": { "application/json": { "examples": { "paymentInProgress": { "summary": "Secure payment is in progress", "value": { "message": "Secure payment is in progress", "status": "pending", "branding": { "id": "brand_1", "clientIdId": "client_1", "logoPath": "/branding/client/logo.png", "pageBackgroundColor": "#ffffff", "cardBackgroundColor": "#ffffff", "primaryActionColor": "#00d395", "primaryTextColor": "#475569", "secondaryTextColor": "#94a3b8", "termsPath": "/branding/client/terms.html", "privacyPath": "/branding/client/privacy.html", "displayRequestBranding": false }, "requestStatuses": [ { "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", "hasBeenPaid": false, "safeTxHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "chainId": 137, "safePaymentDeadline": 1749760800 } ] } } } } } }, "429": { "description": "Too Many Requests" } }, "summary": "Get secure payment data by token", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/{token}/pay": { "get": { "description": "Retrieves executable payment calldata for a secure payment token. When chain and token are provided, the backend prepares a crosschain payment for the selected source asset; otherwise it returns the existing same-chain or batch payment calldata.", "operationId": "SecurePaymentController_getSecurePaymentCalldataByToken_v2", "parameters": [ { "name": "token", "in": "path", "description": "Secure payment token (ULID) returned by POST /v2/secure-payments, POST /v2/secure-payments/payouts, or POST /v2/secure-payments/multicall-payouts. Distinct from the `token` query parameter, which selects the crosschain source currency.", "required": true, "schema": { "type": "string" } }, { "name": "token", "required": false, "in": "query", "description": "The source token of the crosschain payment. Pair with `chain`; both must be sent together. Not the secure payment token \u2014 that is the `{token}` path parameter.", "schema": { "enum": [ "USDC", "USDT", "EURC", "USDT0" ], "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } }, { "name": "wallet", "required": false, "in": "query", "description": "The wallet address of the payer (optional, used to check existing approvals)", "schema": { "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", "type": "string" } }, { "name": "chain", "required": false, "in": "query", "description": "The source chain of the crosschain payment", "schema": { "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM", "POLYGON", "BNB" ], "type": "string" } }, { "name": "eoaWallet", "required": false, "in": "query", "description": "The EOA wallet address that holds the funds. When provided, balance checks and LiFi quotes use this address while the wallet param is used for calldata building (smart account flow).", "schema": { "type": "string" } }, { "name": "isSafe", "required": false, "in": "query", "description": "When true, prepares calldata for a Gnosis Safe multisig payer (wallet must be the Safe address). Mutually exclusive with eoaWallet.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Secure payment calldata retrieved successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "single" ] }, "transactions": { "type": "array", "items": {}, "description": "Flat ordered list of calls the smart account must execute atomically. Main-payment transactions come first; fee-payment transactions follow." }, "eoaApprovalTransactions": { "type": "array", "items": {} }, "feeBundle": { "type": "object", "properties": { "bundleId": { "type": "string", "description": "ID of the secure_payment_bundle row. Null when fees are described by the plan snapshot but no on-chain bundle was created (e.g. no payer wallet supplied yet).", "nullable": true }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ], "nullable": true }, "amountSummary": { "type": "object", "properties": { "grossAmount": { "type": "string" }, "netRecipientAmount": { "type": "string" }, "totalFees": { "type": "string" }, "payeeBorneFees": { "type": "string" }, "payerBorneFees": { "type": "string" }, "payerTotal": { "type": "string" } }, "required": [ "grossAmount", "netRecipientAmount", "totalFees", "payeeBorneFees", "payerBorneFees", "payerTotal" ], "nullable": true }, "fees": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string" }, "feeComponentId": { "type": "string", "nullable": true }, "feeType": { "type": "string", "nullable": true }, "feeLabel": { "type": "string", "nullable": true }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ], "nullable": true }, "amount": { "type": "string" }, "paymentCurrencyId": { "type": "string" }, "network": { "type": "string" }, "chainId": { "type": "string" }, "recipient": { "type": "string" } }, "required": [ "requestId", "feeComponentId", "feeType", "feeLabel", "feeBearer", "amount", "paymentCurrencyId", "network", "chainId", "recipient" ] }, "description": "One entry per fee leg appended to transactions[]. Order matches the order of fee transactions inside transactions[]." } }, "required": [ "bundleId", "defaultFeeBearer", "amountSummary", "fees" ], "description": "Fee bundle summary for this payment. Null when no fee plan applies.", "nullable": true }, "metadata": { "type": "object", "properties": { "stepsRequired": { "type": "number" }, "needsApproval": { "type": "boolean" }, "transactionSponsorshipFeeUsd": { "type": "string", "nullable": true }, "approvalTransactionIndex": { "type": "number" }, "approvalTransactionsCount": { "type": "number" }, "paymentTransactionIndex": { "type": "number" }, "hasEnoughBalance": { "type": "boolean" }, "hasEnoughGas": { "type": "boolean" }, "hasEnoughAllowance": { "type": "boolean" }, "platformFee": { "type": "object", "properties": { "percentage": { "type": "string" }, "address": { "type": "string" } }, "required": [ "percentage", "address" ] }, "protocolFee": { "type": "object", "properties": { "percentage": { "type": "string" }, "address": { "type": "string" } }, "required": [ "percentage", "address" ] }, "eoaApprovalRequired": { "type": "boolean" }, "eoaApproval": { "type": "object", "properties": { "owner": { "type": "string" }, "spender": { "type": "string" }, "tokenAddress": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "approvalType": { "type": "string", "enum": [ "unlimited" ] } }, "required": [ "owner", "spender", "tokenAddress", "currency", "amount", "approvalType" ] }, "balance": { "type": "string" }, "allowance": { "type": "string" }, "requiredAmount": { "type": "string" }, "nativeBalance": { "type": "string" }, "estimatedNetworkFee": { "type": "string" }, "estimatedNetworkFeeUsd": { "type": "string" }, "estimatedApprovalNetworkFee": { "type": "string" }, "estimatedApprovalNetworkFeeUsd": { "type": "string" }, "estimatedPaymentNetworkFee": { "type": "string" }, "estimatedPaymentNetworkFeeUsd": { "type": "string" }, "approvalFeeLimit": { "type": "string" }, "paymentFeeLimit": { "type": "string" }, "sourceAmount": { "type": "string" }, "routeType": { "type": "string", "enum": [ "crosschain", "samechain" ] }, "quoteFetchedAt": { "type": "string", "format": "date-time" }, "quoteExpiresAt": { "anyOf": [ { "type": "number" }, { "type": "string", "format": "date-time" } ], "description": "Route quote expiry. Legacy single-payment routes may return a Unix timestamp; multicall cross-chain routes return an ISO date-time string." }, "executionDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain execution window for Safe + LiFi routes (min of bridge and swap deadlines). Advisory only.", "minimum": 0 }, "executionDeadlineBreakdown": { "type": "object", "properties": { "bridge": { "type": "object", "properties": { "deadline": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "source": { "type": "string", "enum": [ "decoded", "fallback" ] } }, "required": [ "deadline", "source" ] }, "swap": { "type": "object", "properties": { "deadline": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "tool": { "type": "string" }, "source": { "type": "string", "enum": [ "decoded", "fallback" ] } }, "required": [ "deadline", "source" ] } }, "description": "Per-leg deadline breakdown for Safe + LiFi execution window computation." }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain Safe execution window for the selected route.", "minimum": 0 }, "rawStep": { "type": "object", "additionalProperties": {} }, "costBreakdown": { "type": "object", "properties": { "approvalFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "paymentGasFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "totalGasFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "bridgeFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amount", "hasEnoughBalance" ] }, "fundingStatus": { "type": "object", "properties": { "hasEnoughPaymentToken": { "type": "boolean" }, "hasEnoughApprovalGas": { "type": "boolean" }, "hasEnoughOverall": { "type": "boolean" } }, "required": [ "hasEnoughPaymentToken", "hasEnoughApprovalGas", "hasEnoughOverall" ] }, "totals": { "type": "object", "properties": { "paymentAmount": { "type": "string" }, "paymentCurrency": { "type": "string" }, "sourceAmount": { "type": "string" } }, "required": [ "paymentAmount", "paymentCurrency", "sourceAmount" ] } }, "required": [ "fundingStatus" ] } }, "required": [ "stepsRequired", "needsApproval", "paymentTransactionIndex" ] } }, "required": [ "paymentType", "transactions", "feeBundle", "metadata" ] }, { "type": "object", "properties": { "ERC20ApprovalTransactions": { "type": "array", "items": {} }, "batchPaymentTransaction": {}, "metadata": { "type": "object", "properties": { "hasEnoughBalance": { "type": "boolean" }, "hasEnoughGas": { "type": "boolean", "nullable": true }, "canMakePayment": { "type": "boolean", "nullable": true }, "insufficientTokens": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "type": "string" }, "tokenSymbol": { "type": "string" }, "paymentCurrencyId": { "type": "string" }, "required": { "type": "string" }, "available": { "type": "string" } }, "required": [ "tokenAddress", "required", "available" ] } } }, "required": [ "hasEnoughBalance" ] } }, "required": [ "ERC20ApprovalTransactions" ] }, { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "multicall" ] }, "transactions": { "type": "array", "items": {}, "description": "Flat ordered list of calls the smart account must execute atomically. Main-payment transactions come first; fee-payment transactions follow." }, "eoaApprovalTransactions": { "type": "array", "items": {} }, "feeBundle": { "type": "object", "properties": { "bundleId": { "type": "string", "description": "ID of the secure_payment_bundle row. Null when fees are described by the plan snapshot but no on-chain bundle was created (e.g. no payer wallet supplied yet).", "nullable": true }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ], "nullable": true }, "amountSummary": { "type": "object", "properties": { "grossAmount": { "type": "string" }, "netRecipientAmount": { "type": "string" }, "totalFees": { "type": "string" }, "payeeBorneFees": { "type": "string" }, "payerBorneFees": { "type": "string" }, "payerTotal": { "type": "string" } }, "required": [ "grossAmount", "netRecipientAmount", "totalFees", "payeeBorneFees", "payerBorneFees", "payerTotal" ], "nullable": true }, "fees": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string" }, "feeComponentId": { "type": "string", "nullable": true }, "feeType": { "type": "string", "nullable": true }, "feeLabel": { "type": "string", "nullable": true }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ], "nullable": true }, "amount": { "type": "string" }, "paymentCurrencyId": { "type": "string" }, "network": { "type": "string" }, "chainId": { "type": "string" }, "recipient": { "type": "string" } }, "required": [ "requestId", "feeComponentId", "feeType", "feeLabel", "feeBearer", "amount", "paymentCurrencyId", "network", "chainId", "recipient" ] }, "description": "One entry per fee leg appended to transactions[]. Order matches the order of fee transactions inside transactions[]." } }, "required": [ "bundleId", "defaultFeeBearer", "amountSummary", "fees" ], "description": "Fee bundle summary for this payment. Null when no fee plan applies.", "nullable": true }, "executionKind": { "type": "string", "enum": [ "evm_same_chain", "evm_cross_chain" ] }, "token": { "type": "string", "description": "Multicall parent secure-payment token" }, "network": { "type": "string", "description": "Same-chain destination network" }, "chainId": { "type": "integer" }, "childTokens": { "type": "array", "items": { "type": "string" } }, "requestIds": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0 }, "securePaymentToken": { "type": "string" }, "requestId": { "type": "string" }, "payee": { "type": "string" }, "amount": { "type": "string" }, "paymentCurrency": { "type": "string" }, "paymentReference": { "type": "string", "nullable": true }, "paymentCurrencyAddress": { "type": "string", "nullable": true }, "sourceTokenAddress": { "type": "string", "nullable": true }, "tokenAddress": { "type": "string", "nullable": true }, "network": { "type": "string" }, "destinationCall": { "type": "object", "properties": { "network": { "type": "string", "description": "Destination Request Network chain name" }, "chain": { "type": "string", "description": "Destination LI.FI chain identifier from the proven quote" }, "chainId": { "type": "integer" }, "target": { "type": "string", "description": "Alias of contractAddress for SPP destination-call validation" }, "contractAddress": { "type": "string", "description": "Request Network ERC20 payment proxy on the destination chain" }, "calldata": { "type": "string", "description": "RN proxy calldata proven against the LI.FI contract-call quote" } }, "required": [ "network", "chain", "target", "contractAddress", "calldata" ], "description": "Cross-chain only. Decoded destination-chain RN proxy call that SPP validates before enabling Pay." } }, "required": [ "position", "securePaymentToken", "requestId", "payee", "amount", "paymentCurrency", "paymentReference", "paymentCurrencyAddress", "sourceTokenAddress", "tokenAddress", "network" ] } }, "payees": { "type": "array", "items": { "type": "string" } }, "amounts": { "type": "array", "items": { "type": "string" } }, "references": { "type": "array", "items": { "type": "string", "nullable": true } }, "ERC20ApprovalTransactions": { "type": "array", "items": {} }, "batchPaymentTransaction": {}, "destinationCalls": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "description": "Destination Request Network chain name" }, "chain": { "type": "string", "description": "Destination LI.FI chain identifier from the proven quote" }, "chainId": { "type": "integer" }, "target": { "type": "string", "description": "Alias of contractAddress for SPP destination-call validation" }, "contractAddress": { "type": "string", "description": "Request Network ERC20 payment proxy on the destination chain" }, "calldata": { "type": "string", "description": "RN proxy calldata proven against the LI.FI contract-call quote" } }, "required": [ "network", "chain", "target", "contractAddress", "calldata" ] }, "description": "Cross-chain only. Top-level mirror of children[].destinationCall for validation diagnostics." }, "metadata": { "type": "object", "properties": { "stepsRequired": { "type": "number" }, "needsApproval": { "type": "boolean" }, "transactionSponsorshipFeeUsd": { "type": "string", "nullable": true }, "approvalTransactionIndex": { "type": "number" }, "approvalTransactionsCount": { "type": "number" }, "paymentTransactionIndex": { "type": "number" }, "hasEnoughBalance": { "type": "boolean" }, "hasEnoughGas": { "type": "boolean" }, "hasEnoughAllowance": { "type": "boolean" }, "platformFee": { "type": "object", "properties": { "percentage": { "type": "string" }, "address": { "type": "string" } }, "required": [ "percentage", "address" ] }, "protocolFee": { "type": "object", "properties": { "percentage": { "type": "string" }, "address": { "type": "string" } }, "required": [ "percentage", "address" ] }, "eoaApprovalRequired": { "type": "boolean" }, "eoaApproval": { "type": "object", "properties": { "owner": { "type": "string" }, "spender": { "type": "string" }, "tokenAddress": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "approvalType": { "type": "string", "enum": [ "unlimited" ] } }, "required": [ "owner", "spender", "tokenAddress", "currency", "amount", "approvalType" ] }, "balance": { "type": "string" }, "allowance": { "type": "string" }, "requiredAmount": { "type": "string" }, "nativeBalance": { "type": "string" }, "estimatedNetworkFee": { "type": "string" }, "estimatedNetworkFeeUsd": { "type": "string" }, "estimatedApprovalNetworkFee": { "type": "string" }, "estimatedApprovalNetworkFeeUsd": { "type": "string" }, "estimatedPaymentNetworkFee": { "type": "string" }, "estimatedPaymentNetworkFeeUsd": { "type": "string" }, "approvalFeeLimit": { "type": "string" }, "paymentFeeLimit": { "type": "string" }, "sourceAmount": { "type": "string" }, "routeType": { "type": "string", "enum": [ "crosschain", "samechain" ] }, "quoteFetchedAt": { "type": "string", "format": "date-time" }, "quoteExpiresAt": { "anyOf": [ { "type": "number" }, { "type": "string", "format": "date-time" } ], "description": "Route quote expiry. Legacy single-payment routes may return a Unix timestamp; multicall cross-chain routes return an ISO date-time string." }, "executionDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain execution window for Safe + LiFi routes (min of bridge and swap deadlines). Advisory only.", "minimum": 0 }, "executionDeadlineBreakdown": { "type": "object", "properties": { "bridge": { "type": "object", "properties": { "deadline": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "source": { "type": "string", "enum": [ "decoded", "fallback" ] } }, "required": [ "deadline", "source" ] }, "swap": { "type": "object", "properties": { "deadline": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "tool": { "type": "string" }, "source": { "type": "string", "enum": [ "decoded", "fallback" ] } }, "required": [ "deadline", "source" ] } }, "description": "Per-leg deadline breakdown for Safe + LiFi execution window computation." }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain Safe execution window for the selected route.", "minimum": 0 }, "rawStep": { "type": "object", "additionalProperties": {} }, "costBreakdown": { "type": "object", "properties": { "approvalFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "paymentGasFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "totalGasFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amountNative": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amountNative", "hasEnoughBalance" ] }, "bridgeFee": { "type": "object", "properties": { "required": { "type": "boolean" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "amountUsd": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" } }, "required": [ "required", "currency", "amount", "hasEnoughBalance" ] }, "fundingStatus": { "type": "object", "properties": { "hasEnoughPaymentToken": { "type": "boolean" }, "hasEnoughApprovalGas": { "type": "boolean" }, "hasEnoughOverall": { "type": "boolean" } }, "required": [ "hasEnoughPaymentToken", "hasEnoughApprovalGas", "hasEnoughOverall" ] }, "totals": { "type": "object", "properties": { "paymentAmount": { "type": "string" }, "paymentCurrency": { "type": "string" }, "sourceAmount": { "type": "string" } }, "required": [ "paymentAmount", "paymentCurrency", "sourceAmount" ] } }, "required": [ "fundingStatus" ] }, "approvalTransactionIndices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "batchPaymentTransactionIndex": { "type": "integer", "minimum": 0 }, "feeTransactionIndices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "bridgeTxIndices": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "childCount": { "type": "integer", "minimum": 0 }, "executableLegCount": { "type": "integer", "minimum": 0 }, "aggregateAllowance": { "type": "string" }, "paymentCurrencyId": { "type": "string" }, "network": { "type": "string" }, "bridgeSourceAmount": { "type": "string" }, "sourceSideAmount": { "type": "string" }, "bridgeFeeAmount": { "type": "string" }, "sourceToken": { "type": "string" }, "sourceTokenAddress": { "type": "string" }, "sourceNetwork": { "type": "string" }, "bridge": {}, "feePlanCarried": { "type": "boolean" } }, "required": [ "stepsRequired", "needsApproval", "paymentTransactionIndex", "childCount", "executableLegCount" ] } }, "required": [ "paymentType", "transactions", "feeBundle", "executionKind", "token", "childTokens", "requestIds", "children", "payees", "amounts", "references", "metadata" ] } ] } } } }, "400": { "description": "Invalid secure payment calldata request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Secure payment token expired or invalid status" }, "404": { "description": "Secure payment not found" }, "409": { "description": "Secure payment has already been completed" }, "423": { "description": "Secure payment is in progress" }, "429": { "description": "Too Many Requests" } }, "summary": "Get secure payment calldata by token", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/{token}/tron/broadcast": { "post": { "description": "Relays a locally signed TRON transaction for this secure payment through the configured CatFee Seamless Energy node. The backend rebuilds the expected secure-payment TRON transaction and only forwards the signed transaction if the payload matches.", "operationId": "SecurePaymentController_broadcastTronTransaction_v2", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signedTransaction": { "type": "object", "properties": { "raw_data_hex": { "type": "string", "pattern": "^[a-fA-F0-9]+$" }, "signature": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]+$" }, "minItems": 1 }, "txID": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "raw_data": { "type": "object", "properties": { "contract": { "type": "array", "items": {}, "minItems": 1 }, "fee_limit": { "type": "integer", "minimum": 0 } }, "required": [ "contract" ] } }, "required": [ "raw_data_hex", "signature", "raw_data" ], "description": "Signed TronWeb transaction object compatible with /wallet/broadcasttransaction" } }, "required": [ "signedTransaction" ] } } } }, "responses": { "200": { "description": "TRON transaction broadcast response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean" }, "txid": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid or mismatched TRON transaction" }, "401": { "description": "Unauthorized" }, "403": { "description": "Unauthorized or secure payment not payable" }, "404": { "description": "Secure payment not found" }, "429": { "description": "Too Many Requests" }, "502": { "description": "CatFee broadcast failed" } }, "summary": "Broadcast signed TRON secure payment transaction", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/{token}/refresh-step-transaction": { "post": { "description": "Re-stamps the bridge deadline to 'now' by calling LI.FI /advanced/stepTransaction for a previously selected route step. Call this in parallel for all steps immediately before bundling and submitting the UserOp to avoid deadline expiry.", "operationId": "SecurePaymentController_refreshStepTransaction_v2", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "tool": { "type": "string" }, "action": { "type": "object", "properties": { "toChainId": { "type": "number" }, "toAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "required": [ "toChainId", "toAddress" ] } }, "required": [ "id", "type", "tool", "action" ], "description": "LI.FI route step object from /advanced/routes" } }, "required": [ "step" ] } } } }, "responses": { "200": { "description": "Fresh transactionRequest returned" }, "400": { "description": "Route no longer available or invalid step" }, "401": { "description": "Unauthorized" }, "403": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" } }, "summary": "Refresh bridge step transactionRequest", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/{token}/intent": { "post": { "description": "Records source-side execution metadata after the payer broadcasts a transaction. Single crosschain payments create or reuse a LiFi tracking intent. Multicall parent tokens create or reuse an audit-only execution receipt keyed by parent token and UserOperation hash; receipt rows are not consulted for settlement state.", "operationId": "SecurePaymentController_recordIntent_v2", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "txHash": { "type": "string", "minLength": 66, "maxLength": 66, "pattern": "^0x[a-fA-F0-9]{64}$" }, "safeTxHash": { "type": "string", "minLength": 66, "maxLength": 66, "pattern": "^0x[a-fA-F0-9]{64}$" }, "chain": { "type": "string", "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM", "POLYGON", "BNB" ] }, "token": { "type": "string", "enum": [ "USDC", "USDT", "EURC", "USDT0" ] }, "executionKind": { "type": "string", "enum": [ "evm_same_chain", "evm_cross_chain" ] }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain execution deadline for the Safe + LiFi route. Only valid alongside safeTxHash; used to stop monitoring once crossed.", "minimum": 0 }, "payerAddress": { "type": "string" }, "payerEoaAddress": { "type": "string" }, "sourceNetwork": { "type": "string", "enum": [ "mainnet", "optimism", "bsc", "xdai", "fuse", "matic", "fantom", "zksynceratestnet", "zksyncera", "core", "moonbeam", "mantle", "mantle-testnet", "tombchain", "base", "arbitrum-one", "avalanche", "base-sepolia", "sepolia", "tron", "nile" ] }, "sourceToken": { "type": "string" }, "sourceAmount": { "type": "string" }, "routeKind": { "type": "string", "enum": [ "same_chain", "same_chain_conversion", "crosschain" ] }, "bridgeTool": { "type": "string", "enum": [ "across", "stargate" ], "nullable": true } }, "required": [ "chain", "token" ] }, { "type": "object", "properties": { "txHash": { "type": "string", "minLength": 66, "maxLength": 66, "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Bundler or source-chain transaction hash produced by the submitted UserOperation" }, "safeTxHash": { "type": "string", "minLength": 66, "maxLength": 66, "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Safe transaction hash when execution is still pending on-chain" }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Unix seconds \u2014 hard on-chain execution deadline for the Safe + multicall route. Only valid alongside safeTxHash.", "minimum": 0 }, "chain": { "type": "string", "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM", "POLYGON", "BNB" ], "description": "Source chain where the multicall UserOperation was submitted" }, "smartAccountAddress": { "type": "string", "description": "Smart account that submitted the multicall UserOperation" }, "payerEoaAddress": { "type": "string", "description": "Connected EOA behind the submitted smart account" }, "userOpHash": { "type": "string", "minLength": 66, "maxLength": 66, "pattern": "^0x[a-fA-F0-9]{64}$", "description": "UserOperation hash returned by the bundler" }, "transactionIndices": { "type": "array", "items": { "type": "object", "properties": { "childPosition": { "type": "integer", "minimum": 0, "description": "Zero-based child position in the multicall parent" }, "transactionIndex": { "type": "integer", "minimum": 0, "description": "Zero-based local transaction index in the submitted batch" }, "routeTool": { "type": "string", "description": "Per-child route tool from the multicall pay payload. Across bridge legs require LiFi status tracking; direct legs use normal payment detection.", "nullable": true }, "sourceToken": { "type": "string" }, "sourceAmount": { "type": "string" }, "routeKind": { "type": "string", "enum": [ "same_chain", "same_chain_conversion", "crosschain" ] }, "bridgeTool": { "type": "string", "enum": [ "across", "stargate" ], "nullable": true } }, "required": [ "childPosition", "transactionIndex" ] }, "minItems": 1, "maxItems": 250 } }, "required": [ "chain", "smartAccountAddress", "userOpHash", "transactionIndices" ] } ] }, "examples": { "safePendingIntent": { "summary": "Safe transaction pending on-chain execution", "value": { "safeTxHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "chain": "POLYGON", "token": "USDC", "executionKind": "evm_cross_chain", "safePaymentDeadline": 1749760800, "payerAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } } } } } }, "responses": { "200": { "description": "Intent recorded successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "intentId": { "type": "string", "description": "Tracking intent ID created or reused" }, "paymentReference": { "type": "string", "description": "Payment reference associated with the tracked request" }, "txHash": { "type": "string", "description": "Recorded source-chain transaction hash" }, "safeTxHash": { "type": "string", "description": "Recorded Safe transaction hash pending on-chain execution" }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Recorded Unix-seconds execution deadline for the Safe + LiFi route, when provided", "minimum": 0 }, "isListening": { "type": "boolean", "description": "Whether the tracking intent is being monitored for status" }, "payerAddress": { "type": "string" } }, "required": [ "intentId", "paymentReference", "isListening" ] }, { "type": "object", "properties": { "receiptId": { "type": "string", "description": "Audit receipt ID created or reused" }, "multicallId": { "type": "string", "description": "Multicall parent row ID" }, "parentToken": { "type": "string", "description": "Multicall parent token" }, "txHash": { "type": "string", "description": "Recorded source-chain transaction hash" }, "safeTxHash": { "type": "string", "description": "Recorded Safe transaction hash pending on-chain execution" }, "safePaymentDeadline": { "type": "integer", "exclusiveMinimum": true, "description": "Recorded Unix-seconds execution deadline for the Safe + multicall route, when provided", "minimum": 0 }, "sourceChain": { "type": "string", "enum": [ "BASE", "OPTIMISM", "ARBITRUM", "ETHEREUM", "POLYGON", "BNB" ] }, "smartAccountAddress": { "type": "string", "description": "Submitting smart account" }, "userOpHash": { "type": "string", "description": "Recorded UserOperation hash" }, "transactionIndices": { "type": "array", "items": { "type": "object", "properties": { "childPosition": { "type": "integer", "minimum": 0 }, "transactionIndex": { "type": "integer", "minimum": 0 } }, "required": [ "childPosition", "transactionIndex" ] } }, "isListening": { "type": "boolean", "enum": [ false ], "description": "Multicall execution receipts are audit-only and not polled" } }, "required": [ "receiptId", "multicallId", "parentToken", "sourceChain", "smartAccountAddress", "userOpHash", "transactionIndices", "isListening" ] } ] } } } }, "400": { "description": "Invalid or unsupported crosschain execution payload" }, "401": { "description": "Unauthorized" }, "403": { "description": "Secure payment token expired or invalid status" }, "404": { "description": "Secure payment not found" }, "409": { "description": "Secure payment has already been completed" }, "429": { "description": "Too Many Requests" } }, "summary": "Record secure payment intent", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "securePaymentsDisabled" } }, "/v2/secure-payments/multicall-payouts": { "post": { "description": "Creates a multicall Secure Payment Page link from selected outgoing payout secure-payment tokens. This is distinct from legacy secure-payment batch links and persists only the parent token plus ordered child references.", "operationId": "SecurePaymentMulticallController_createMulticallPayout_v2", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key for authentication (optional if using Client ID, session, or orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication (required when paired with orchestrator key)", "required": false, "schema": { "type": "string" } }, { "name": "x-orchestrator-key", "in": "header", "description": "Orchestrator key for authentication (must be paired with Client ID)", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use the session_token cookie). Only consulted when no x-orchestrator-key, x-api-key, or x-client-id header is present.", "required": false, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (required for Client ID / orchestrator auth, automatically set by browser)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "childTokens": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 2, "maxItems": 1000, "description": "Ordered child secure-payment tokens selected for multicall payout" }, "requestedExecutionKind": { "type": "string", "enum": [ "evm_same_chain", "evm_cross_chain", "tron_batch" ], "description": "Execution kind chosen at creation time. When omitted, stored as null \u2014 the SPP derives evm_same_chain or evm_cross_chain from the payer's source selection at payment time." } }, "required": [ "childTokens" ], "additionalProperties": false }, "examples": { "payouts": { "summary": "Create a multicall payout link", "value": { "childTokens": [ "01JZ4PC7EXAMPLECHILD000001", "01JZ4PC7EXAMPLECHILD000002" ] } } } } } }, "responses": { "201": { "description": "Multicall payout link created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "multicall" ] }, "token": { "type": "string", "description": "Multicall payout token" }, "securePaymentUrl": { "type": "string", "format": "uri", "description": "Secure Payment Page multicall URL returned on creation" }, "status": { "type": "string", "enum": [ "pending", "expired" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "securePaymentToken": { "type": "string", "description": "Child secure-payment token" }, "requestId": { "type": "string", "description": "Request Network request ID for the child payout" }, "position": { "type": "integer", "minimum": 0, "description": "0-indexed child order" }, "eligibility": { "type": "string", "enum": [ "eligible", "stale" ] }, "staleReason": { "type": "string", "enum": [ "secure_payment_expired", "secure_payment_not_pending", "already_paid", "request_processing", "not_payable_child" ] } }, "required": [ "securePaymentToken", "requestId", "position" ] } } }, "required": [ "type", "token", "status", "expiresAt", "createdAt", "items" ] } } } }, "400": { "description": "Invalid multicall payout selection, including stale or ineligible child payout links" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" } }, "summary": "Create a multicall payout link", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "multicallPayoutsDisabled" } }, "/v2/secure-payments/multicall-payouts/{token}": { "get": { "description": "Retrieves the passive multicall payout details payload for Secure Payment Page rendering. It does not return quotes, calldata, wallet routes, or execution data.", "operationId": "SecurePaymentMulticallController_getMulticallPayout_v2", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "Multicall payout token returned by the create endpoint", "schema": { "example": "01JZ4PC7EXAMPLEMULTICALL01", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer token for session authentication (or use session_token cookie)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Multicall payout state retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "multicall" ] }, "status": { "type": "string", "enum": [ "pending", "expired", "completed", "partially_settled" ] }, "redirectUrl": { "type": "string", "nullable": true }, "redirectLabel": { "type": "string", "nullable": true }, "orchestratorId": { "type": "string", "nullable": true }, "branding": { "type": "object", "properties": { "id": { "type": "string" }, "clientIdId": { "type": "string" }, "orchestratorId": { "type": "string" }, "logoPath": { "type": "string" }, "pageBackgroundColor": { "type": "string" }, "cardBackgroundColor": { "type": "string" }, "primaryActionColor": { "type": "string" }, "primaryTextColor": { "type": "string" }, "secondaryTextColor": { "type": "string" }, "termsPath": { "type": "string" }, "privacyPath": { "type": "string" }, "displayRequestBranding": { "type": "boolean" } }, "required": [ "id" ], "nullable": true }, "paymentOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "balance": { "type": "string" }, "hasEnoughBalance": { "type": "boolean" }, "neededAmount": { "type": "string" } }, "required": [ "balance", "hasEnoughBalance", "neededAmount" ] } } }, "analytics": { "type": "object", "properties": { "creationTimestamp": { "type": "string", "format": "date-time" }, "totalPaymentAmountUsd": { "type": "string" }, "protocolFeeAmountUsd": { "type": "string" }, "orchestratorPayerFeeAmountUsd": { "type": "string" }, "orchestratorRecipientFeeAmountUsd": { "type": "string" }, "feeAmountsUsdUnavailableReason": { "type": "string", "enum": [ "fee_plan_unavailable" ] }, "numberOfPaymentsExcludingFees": { "type": "integer", "minimum": 0 }, "destinationIds": { "type": "array", "items": { "type": "string" } }, "payoutKytProvider": { "type": "string" } }, "description": "Vendor-neutral analytics metadata that SPP maps into Mixpanel shared properties. Amount values are decimal USD strings to avoid frontend precision loss." }, "requestIds": { "type": "array", "items": { "type": "string" }, "description": "Request Network request IDs represented by this payment" }, "token": { "type": "string", "description": "Multicall payout token" }, "canExecute": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "children": { "type": "array", "items": { "type": "object", "properties": { "securePaymentToken": { "type": "string", "description": "Child secure-payment token" }, "requestId": { "type": "string", "description": "Request Network request ID for the child payout" }, "position": { "type": "integer", "minimum": 0, "description": "0-indexed child order" }, "executable": { "type": "boolean", "description": "Whether this child can currently be executed in the multicall" }, "blockReason": { "type": "string", "enum": [ "not_found", "not_owned", "not_outgoing", "not_single_payment", "invalid_child_linkage", "already_paid", "request_processing", "secure_payment_expired", "secure_payment_not_pending", "compliance_failed", "not_payable_child" ], "description": "Structured reason when executable is false; otherwise null", "nullable": true }, "messageKey": { "type": "string", "description": "Stable localized-message key for the block reason", "nullable": true }, "context": { "type": "object", "properties": { "requestId": { "type": "string" }, "securePaymentToken": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "hasBeenPaid": { "type": "boolean" }, "securePaymentStatus": { "type": "string" }, "requestStatus": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "network": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "requestId", "securePaymentToken", "position", "hasBeenPaid" ], "description": "Per-child block context used by SPP to render recovery details" }, "recoveryAction": { "type": "string", "enum": [ "remove_child", "recreate_reduced", "wait_for_quote_refresh", "switch_route", "recreate_after_cooldown", "support_required" ], "description": "Suggested recovery action when the child is blocked", "nullable": true }, "feePlan": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "flow": { "type": "string", "enum": [ "get_paid", "pay" ] }, "defaultFeeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "grossAmountUsd": { "type": "string" }, "netRecipientAmountUsd": { "type": "string" }, "payerTotalAmountUsd": { "type": "string" }, "totalFeesUsd": { "type": "string" }, "payeeBorneFeesUsd": { "type": "string" }, "payerBorneFeesUsd": { "type": "string" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "feeBearer": { "type": "string", "enum": [ "payer", "payee" ] }, "feeBearerSource": { "type": "string", "enum": [ "fee_config", "payment_default_override", "flow_default", "forced_fee_policy" ] }, "percentageBps": { "type": "number" }, "capUsd": { "type": "string", "nullable": true }, "fixedAmountUsd": { "type": "string", "nullable": true }, "calculatedAmountUsd": { "type": "string" }, "destinationResolver": { "type": "string" }, "destinationRef": { "type": "object", "properties": { "evmAddress": { "type": "string" }, "tronAddress": { "type": "string" } } }, "configSource": { "type": "string" } }, "required": [ "type", "label", "feeBearer", "feeBearerSource", "percentageBps", "capUsd", "calculatedAmountUsd", "destinationResolver", "destinationRef", "configSource" ] } } }, "required": [ "version", "flow", "defaultFeeBearer", "grossAmountUsd", "netRecipientAmountUsd", "payerTotalAmountUsd", "totalFeesUsd", "payeeBorneFeesUsd", "payerBorneFeesUsd", "fees" ], "description": "Persisted child fee-plan snapshot. Null when fees do not apply or no snapshot exists.", "nullable": true }, "amount": { "type": "string", "description": "Human-readable child amount in the child's payment currency. Null when unavailable.", "nullable": true }, "payee": { "type": "string", "description": "Resolved child recipient address. Null when unavailable.", "nullable": true }, "reference": { "type": "string", "description": "Merchant reference for the child payment. Null when none was provided.", "nullable": true } }, "required": [ "securePaymentToken", "requestId", "position", "executable", "blockReason", "messageKey", "context", "recoveryAction", "feePlan", "amount", "payee", "reference" ] } }, "totals": { "type": "object", "properties": { "childCount": { "type": "integer", "minimum": 0 }, "blockedChildCount": { "type": "integer", "minimum": 0 }, "byDestinationCurrency": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "currency": { "type": "string" }, "totalAmount": { "type": "string" } }, "required": [ "network", "currency", "totalAmount" ] } }, "amountSummary": { "type": "object", "properties": { "grossAmount": { "type": "string" }, "netRecipientAmount": { "type": "string" }, "totalFees": { "type": "string" }, "payeeBorneFees": { "type": "string" }, "payerBorneFees": { "type": "string" }, "payerTotal": { "type": "string" } }, "required": [ "grossAmount", "netRecipientAmount", "totalFees", "payeeBorneFees", "payerBorneFees", "payerTotal" ] } }, "required": [ "childCount", "blockedChildCount", "byDestinationCurrency", "amountSummary" ] } }, "required": [ "paymentType", "status", "redirectUrl", "redirectLabel", "orchestratorId", "branding", "analytics", "requestIds", "token", "canExecute", "expiresAt", "createdAt", "children", "totals" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Multicall payout not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get multicall payout state", "tags": [ "V2/Secure Payment" ], "x-feature-flag": "multicallPayoutsDisabled" } }, "/v2/payee-destination/signing-data": { "get": { "description": "Generate a nonce and return the complete EIP-712 signing data structure for payee destination creation or deactivation", "operationId": "PayeeDestinationController_getSigningData_v2", "parameters": [ { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } }, { "name": "walletAddress", "required": true, "in": "query", "description": "The wallet address that will sign the message", "schema": { "type": "string" } }, { "name": "action", "required": true, "in": "query", "description": "The action to perform (add or deactivate)", "schema": { "enum": [ "add", "deactivate" ], "type": "string" } }, { "name": "tokenAddress", "required": true, "in": "query", "description": "The ERC20 token address for the payee destination", "schema": { "type": "string" } }, { "name": "chainId", "required": true, "in": "query", "description": "The chain ID where the token is deployed", "schema": { "type": "string" } } ], "responses": { "200": { "description": "EIP-712 signing data with nonce" }, "429": { "description": "Too Many Requests" } }, "summary": "Get EIP-712 signing data with nonce", "tags": [ "V2/Payee Destination" ] } }, "/v2/payee-destination": { "post": { "description": "Create a payee destination with EIP-712 signature verification", "operationId": "PayeeDestinationController_createPayeeDestination_v2", "parameters": [ { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "pattern": "^0x[a-fA-F0-9]{130}$", "description": "The EIP-712 signature from the payee" }, "nonce": { "type": "string", "minLength": 1, "description": "The signing session nonce from /signing-data endpoint" } }, "required": [ "signature", "nonce" ] } } } }, "responses": { "201": { "description": "Payee destination created successfully" }, "429": { "description": "Too Many Requests" } }, "summary": "Create payee destination", "tags": [ "V2/Payee Destination" ] }, "get": { "description": "Retrieve the active payee destination for a specific wallet address. Returns null if no active destination exists.", "operationId": "PayeeDestinationController_getActivePayeeDestination_v2", "parameters": [ { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } }, { "name": "walletAddress", "required": true, "in": "query", "description": "The wallet address to filter payee destinations", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active payee destination retrieved successfully (or null if none exists)" }, "429": { "description": "Too Many Requests" } }, "summary": "Get active payee destination for wallet", "tags": [ "V2/Payee Destination" ] } }, "/v2/payee-destination/{destinationId}": { "delete": { "description": "Deactivate a payee destination with EIP-712 signature verification. Sets active=false without deleting the record.", "operationId": "PayeeDestinationController_deactivatePayeeDestination_v2", "parameters": [ { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "pattern": "^0x[a-fA-F0-9]{130}$", "description": "The EIP-712 signature from the payee" }, "nonce": { "type": "string", "minLength": 1, "description": "The signing session nonce from /signing-data endpoint" } }, "required": [ "signature", "nonce" ] } } } }, "responses": { "200": { "description": "Payee destination deactivated successfully" }, "400": { "description": "Destination not found or validation failed" }, "429": { "description": "Too Many Requests" } }, "summary": "Deactivate payee destination", "tags": [ "V2/Payee Destination" ] }, "get": { "description": "Retrieve a payee destination using the format network:walletAddress:tokenAddress", "operationId": "PayeeDestinationController_getPayeeDestination_v2", "parameters": [ { "name": "x-client-id", "in": "header", "description": "Client ID for frontend authentication", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "description": "Origin header (automatically set by browser)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payee destination retrieved successfully" }, "404": { "description": "Payee destination not found" }, "429": { "description": "Too Many Requests" } }, "summary": "Get payee destination by ID", "tags": [ "V2/Payee Destination" ] } } }, "info": { "title": "Request Network API", "description": "API for easily creating and paying Requests with Request Network.", "version": "0.13.0", "contact": {} }, "tags": [ { "name": "V2/Request", "description": "Core payment request operations (V2)" }, { "name": "V2/Payments", "description": "Payment search and management operations (V2)" }, { "name": "V2/Payouts", "description": "Pay a request without creating one first (V2)" }, { "name": "V2/Payer", "description": "Crypto-to-fiat payer management operations (V2)" }, { "name": "V2/Currencies", "description": "Currency operations (V2)" }, { "name": "V2/Client IDs", "description": "Client ID management (V2)" }, { "name": "V2/Secure Payment", "description": "Secure payment operations with token-based access (V2)" }, { "name": "V2/Payee Destination", "description": "Payee destination management (V2)" } ], "servers": [ { "url": "https://api.request.network", "description": "Production server" }, { "url": "https://api.stage.request.network", "description": "Staging server" }, { "url": "http://127.0.0.1:8080", "description": "Local development server" } ], "components": { "schemas": {} }, "externalDocs": { "description": "Request Network Docs", "url": "https://docs.request.network/request-network-api" }, "x-tagGroups": [ { "name": "V1", "tags": [ "V1/Request", "V1/Pay", "V1/Currencies", "V1/Authentication", "V1/API Keys", "V1/Webhooks" ], "description": "v1 endpoints" }, { "name": "V2", "tags": [ "V2/Request", "V2/Payments", "V2/Payouts", "V2/Payer", "V2/Currencies", "V2/Authentication", "V2/API Keys", "V2/Webhooks", "V2/Platforms", "V2/Journey", "V2/Client IDs", "V2/Commerce Payments", "V2/Secure Payment", "V2/Payee Destination" ], "description": "v2 endpoints" } ] }