{"openapi":"3.0.0","paths":{"/v2/health":{"get":{"operationId":"HealthController_check_v2","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/v1/currencies":{"get":{"description":"Get a list of all available tokens, or filter by network, symbol, or id.","operationId":"CurrenciesV1Controller_getNetworkTokens_v1","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":"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","V1/Currencies"]}},"/v1/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":"CurrenciesV1Controller_getConversionRoutes_v1","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 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":"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","V1/Currencies"]}},"/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 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":"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 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":"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"]}},"/v1/request":{"post":{"description":"Create a new payment request","operationId":"RequestControllerV1_createRequest_v1","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":{"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...)"},"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"}},"required":["payee","amount","invoiceCurrency","paymentCurrency"],"example":{"payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","amount":"10","invoiceCurrency":"USD","paymentCurrency":"ETH-sepolia-sepolia","recurrence":{"startDate":"2030-01-01","frequency":"DAILY"}}}}}},"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"},"401":{"description":"Unauthorized"},"404":{"description":"Wallet not found"},"429":{"description":"Too Many Requests"}},"summary":"Create a new request","tags":["Request","V1/Request"]}},"/v1/request/{paymentReference}":{"get":{"description":"Get the status of a payment request","operationId":"RequestControllerV1_getRequestStatus_v1","parameters":[{"name":"paymentReference","required":true,"in":"path","description":"The payment reference of the request","schema":{"example":"0xb3581f0b0f74cc61","type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":true,"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 or not"},"paymentReference":{"type":"string","example":"0xb3581f0b0f74cc61","description":"The payment reference of the request"},"requestId":{"type":"string","description":"The request ID of the request","example":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"},"requestAmount":{"type":"string","nullable":true,"description":"Original requested amount in invoice currency"},"isListening":{"type":"boolean","description":"Whether the request is listening for a payment"},"payments":{"type":"array","description":"Payments made to this request. Use each payment's sourceTxHash and destinationTxHash as the source of truth for transaction hashes.","items":{"type":"object","properties":{"sourceTxHash":{"type":"string","nullable":true},"destinationTxHash":{"type":"string","nullable":true},"detectionSource":{"type":"string","nullable":true},"note":{"type":"string","nullable":true}}}}}},"examples":{"paid":{"summary":"Request has been paid","value":{"hasBeenPaid":true,"paymentReference":"0xb3581f0b0f74cc61","requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","requestAmount":"100.00","isListening":false,"payments":[{"sourceTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","destinationTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","detectionSource":"request-network","note":null}]}},"notPaid":{"summary":"Request has not been paid","value":{"hasBeenPaid":false,"paymentReference":"0xb3581f0b0f74cc61","requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","requestAmount":"100.00","isListening":false,"payments":[]}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Get request status","tags":["Request","V1/Request"]}},"/v1/request/{paymentReference}/stop-recurrence":{"patch":{"description":"Stop a recurring request","operationId":"RequestControllerV1_stopRecurrenceRequest_v1","parameters":[{"name":"paymentReference","required":true,"in":"path","description":"The payment reference of the request","schema":{"example":"0xb3581f0b0f74cc61","type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurrence stopped successfully"},"401":{"description":"Unauthorized"},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Stop a recurring request","tags":["Request","V1/Request"]}},"/v1/request/{paymentReference}/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. Note: Crosschain requests with an expectedAmount less than 1 are rejected.","operationId":"RequestControllerV1_getPaymentCalldata_v1","parameters":[{"name":"paymentReference","required":true,"in":"path","description":"The payment reference of the request","schema":{"example":"0xb3581f0b0f74cc61","type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":true,"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"}}],"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 executable transaction calldata","properties":{"transactions":{"type":"array","description":"Array of transactions to execute for the selected route","items":{"type":"object","properties":{"data":{"type":"string","description":"Transaction calldata"},"to":{"type":"string","description":"Target contract address"},"value":{"oneOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","enum":["BigNumber"]},"hex":{"type":"string"}}}],"description":"Transaction value"},"chainType":{"type":"string","enum":["evm","tron"],"nullable":true}},"required":["data","to","value"]}},"metadata":{"type":"object","description":"Metadata about the crosschain payment","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"},"paymentTransactionIndex":{"type":"number","description":"Index of the executable crosschain transaction"},"hasEnoughBalance":{"type":"boolean","description":"Whether payer has sufficient token balance"},"routeType":{"type":"string","enum":["crosschain","samechain"]},"quoteExpiresAt":{"type":"number","description":"Route quote expiry timestamp"}},"required":["stepsRequired","needsApproval","paymentTransactionIndex","hasEnoughBalance","routeType"]}},"required":["transactions","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 without token approval","x-feature-flag":"crosschainDisabled","value":{"transactions":[{"data":"0xabcdef","to":"0x1234567890123456789012345678901234567890","value":"0x0","from":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","gasLimit":"300000","gasPrice":"1000000000","chainType":"evm"}],"metadata":{"stepsRequired":1,"needsApproval":false,"paymentTransactionIndex":0,"routeType":"crosschain","quoteExpiresAt":1742205771,"hasEnoughBalance":true}}},"currencyThatDoesNotSupportEIP2612":{"summary":"Crosschain payment with approval transaction","x-feature-flag":"crosschainDisabled","value":{"transactions":[{"data":"0x095ea7b3000000000000000000000000123456789012345678901234567890123456789000000000000000000000000000000000000000000000000000000000989680","to":"0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9","value":"0x0","chainType":"evm"},{"data":"0xabcdef","to":"0x1234567890123456789012345678901234567890","value":"0x0","from":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","gasLimit":"300000","gasPrice":"1000000000","chainType":"evm"}],"metadata":{"stepsRequired":2,"needsApproval":true,"approvalTransactionIndex":0,"paymentTransactionIndex":1,"routeType":"crosschain","quoteExpiresAt":1742205771,"hasEnoughBalance":true}}}}}}},"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 '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}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Get payment calldata","tags":["Request","V1/Request"]}},"/v1/request/{paymentReference}/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":"RequestControllerV1_getRequestPaymentRoutes_v1","parameters":[{"name":"paymentReference","required":true,"in":"path","description":"The payment reference of the request","schema":{"example":"0xb3581f0b0f74cc61","type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":true,"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":0,"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":"BASE_OPTIMISM_USDC_USDC","fee":0.001,"speed":10,"price_impact":0.999,"chain":"OPTIMISM","token":"USDC"}]}},"noRoutes":{"summary":"No routes available","value":{"routes":[]}}}}}},"400":{"description":"Invalid or missing wallet address"},"401":{"description":"Unauthorized"},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Get payment routes","tags":["Request","V1/Request"],"x-feature-flag":"crosschainDisabled"}},"/v2/request":{"get":{"description":"List payment requests with pagination. API key and session authentication require a payee wallet address filter; client ID authentication can omit it to list requests created by that client ID","operationId":"RequestControllerV2_listRequests_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":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}},{"name":"walletAddress","required":false,"in":"query","description":"Payee wallet address to filter requests by. Required for API key and session authentication, optional for client ID authentication","schema":{"type":"string"}},{"name":"securePaymentFlow","required":false,"in":"query","description":"When set, limit results to requests linked to a secure payment of the given flow. 'incoming' = payins (someone pays this wallet), 'outgoing' = payouts (this wallet is being paid to). Requests not linked to any secure payment are excluded when this filter is set.","schema":{"enum":["incoming","outgoing"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of results per page (max 100)","schema":{"example":50,"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset","schema":{"example":0,"type":"string"}}],"responses":{"200":{"description":"Requests listed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","description":"List of requests","items":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique identifier of the request"},"paymentReference":{"type":"string","description":"Unique payment reference"},"amount":{"type":"string","nullable":true,"description":"Request amount in human-readable format"},"invoiceCurrency":{"type":"string","description":"Invoice currency symbol (e.g. USD)"},"paymentCurrency":{"type":"string","description":"Payment currency ID"},"hasBeenPaid":{"type":"boolean","description":"Whether the request has been paid"},"status":{"type":"string","nullable":true,"description":"Current status of the request"},"reference":{"type":"string","nullable":true,"description":"Merchant reference"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"When the request was created"},"txHash":{"type":"string","nullable":true,"description":"Transaction hash of the payment, null if not yet paid"},"payee":{"type":"string","nullable":true,"description":"Payee wallet address"},"payer":{"type":"string","nullable":true,"description":"Payer wallet address"},"clientId":{"type":"string","nullable":true,"description":"identifier (ULID) of the API clientId used to create the request"}}}},"pagination":{"type":"object","description":"Pagination metadata","properties":{"total":{"type":"number","description":"Total number of matching requests"},"limit":{"type":"number","description":"Number of results per page"},"offset":{"type":"number","description":"Current pagination offset"}}}},"required":["requests","pagination"]},"examples":{"withResults":{"summary":"List with wallet address filter","value":{"requests":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","paymentReference":"0xb3581f0b0f74cc61","amount":"100.00","invoiceCurrency":"USD","paymentCurrency":"USDC-base","hasBeenPaid":false,"status":"created","reference":"Services for April 2024","createdAt":"2025-01-15T10:30:00.000Z","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","payer":"0x1234567890abcdef1234567890abcdef12345678"}],"pagination":{"total":1,"limit":50,"offset":0}}},"clientIdWithoutWalletAddress":{"summary":"Client ID list without wallet address","value":{"requests":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","paymentReference":"0xb3581f0b0f74cc61","amount":"100.00","invoiceCurrency":"USD","paymentCurrency":"USDC-base","hasBeenPaid":false,"status":"created","reference":"Services for April 2024","createdAt":"2025-01-15T10:30:00.000Z","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","payer":"0x1234567890abcdef1234567890abcdef12345678","clientId":"cli_orchestrator_demo"},{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7caa","paymentReference":"0xb3581f0b0f74cc62","amount":"250.00","invoiceCurrency":"EUR","paymentCurrency":"ETH-base","hasBeenPaid":false,"status":"created","reference":"Services for May 2024","createdAt":"2025-01-16T10:30:00.000Z","payee":"0x742d35Cc6634C0532925a3b844Bc9e7595f8fa40","payer":"0xabcdef1234567890abcdef1234567890abcdef12","clientId":"cli_orchestrator_demo"}],"pagination":{"total":2,"limit":50,"offset":0}}},"empty":{"summary":"Empty list","value":{"requests":[],"pagination":{"total":0,"limit":50,"offset":0}}}}}}},"400":{"description":"Validation failed"},"429":{"description":"Too Many Requests"}},"summary":"List requests","tags":["Request","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...). Optional when using client ID authentication with a configured payee destination."},"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"}},"orchestratorRequest":{"summary":"Orchestrator request (payee resolved from client ID destination)","value":{"amount":"10","invoiceCurrency":"USD","paymentCurrency":"USDC-base"}},"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 or no active payee destination for client ID"},"403":{"description":"Client ID has been revoked"},"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 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":"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"},"payee":{"type":"string","nullable":true,"description":"The payee wallet address for this request"},"isListening":{"type":"boolean","description":"Whether the system is actively listening for payments on this request"},"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. Use each payment's sourceTxHash and destinationTxHash as the source of truth for transaction hashes.","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"},"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":"When the payment was recorded"},"type":{"type":"string","description":"Payment type"},"conversionRateSource":{"type":"string","nullable":true,"description":"Conversion rate used on the source side"},"conversionRateDestination":{"type":"string","nullable":true,"description":"Conversion rate used on the destination side"},"currency":{"type":"string","description":"Invoice currency symbol"},"paymentCurrency":{"type":"string","description":"Payment currency symbol"},"detectionSource":{"type":"string","enum":["lifi","request-network"],"nullable":true,"description":"How this payment was confirmed"},"note":{"type":"string","nullable":true,"description":"Additional context for fallback or non-standard settlement cases"}}}},"isRecurrenceStopped":{"type":"boolean","description":"Whether recurrence has been stopped for this request"},"reference":{"type":"string","nullable":true,"description":"Merchant reference for receipt tracking and identification"},"requestAmount":{"type":"string","nullable":true,"description":"Original requested amount in invoice currency"},"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","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","isListening":false,"payments":[{"id":"01hxexamplepayment001","amount":"100.00","sourceNetwork":"sepolia","destinationNetwork":"sepolia","sourceTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","destinationTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","timestamp":"2025-01-01T10:00:00Z","type":"direct","conversionRateSource":null,"conversionRateDestination":null,"currency":"USD","paymentCurrency":"USDC"}]}},"notPaid":{"summary":"Request has not been paid","value":{"hasBeenPaid":false,"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","isListening":false,"payments":[]}},"withReference":{"summary":"Request with merchant reference","value":{"hasBeenPaid":false,"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","isListening":true,"payments":[],"reference":"ORDER-2024-001234"}},"paidWithUsdInfo":{"summary":"Fully paid request with single payment","value":{"hasBeenPaid":true,"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","paymentReference":"0xb3581f0b0f74cc61","requestAmount":"100.00","payments":[{"id":"01hxexamplepayment001","amount":"100.00","sourceNetwork":"sepolia","destinationNetwork":"sepolia","sourceTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","destinationTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","timestamp":"2025-01-01T10:00:00Z","type":"direct","conversionRateSource":null,"conversionRateDestination":null,"currency":"USD","paymentCurrency":"USDC","detectionSource":"request-network","note":null}],"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","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","paymentReference":"0xb3581f0b0f74cc61","requestAmount":"100.00","payments":[{"id":"01hxpartialpayment001","amount":"75.00","sourceNetwork":"sepolia","destinationNetwork":"base","sourceTxHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","destinationTxHash":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","timestamp":"2025-01-01T10:00:00Z","type":"crosschain","conversionRateSource":"2487.52","conversionRateDestination":"1.00","currency":"USD","paymentCurrency":"ETH","detectionSource":"request-network","note":null}],"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","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","paymentReference":"0xb3581f0b0f74cc61","requestAmount":"100.00","payments":[],"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","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","paymentReference":"0xb3581f0b0f74cc61","requestAmount":"100.00","payments":[{"id":"01hxmultiplepayment001","amount":"50.00","sourceNetwork":"sepolia","destinationNetwork":"sepolia","sourceTxHash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","destinationTxHash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","timestamp":"2025-01-01T10:00:00Z","type":"conversion","conversionRateSource":"2500.00","conversionRateDestination":"2500.00","currency":"USD","paymentCurrency":"USDC","detectionSource":"request-network","note":null},{"id":"01hxmultiplepayment002","amount":"50.00","sourceNetwork":"sepolia","destinationNetwork":"base","sourceTxHash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","destinationTxHash":"0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","timestamp":"2025-01-02T15:30:00Z","type":"crosschain","conversionRateSource":"2480.30","conversionRateDestination":"1.00","currency":"USD","paymentCurrency":"ETH","detectionSource":"request-network","note":null}],"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 executable transaction calldata for the route, including any required approval transaction before the LiFi transaction. 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 executable transaction calldata","properties":{"transactions":{"type":"array","description":"Array of transactions to execute for the selected route","items":{"type":"object","properties":{"data":{"type":"string","description":"Transaction calldata"},"to":{"type":"string","description":"Target contract address"},"value":{"oneOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","enum":["BigNumber"]},"hex":{"type":"string"}}}],"description":"Transaction value"},"chainType":{"type":"string","enum":["evm","tron"],"nullable":true}},"required":["data","to","value"]}},"metadata":{"type":"object","description":"Metadata about the crosschain payment","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"},"paymentTransactionIndex":{"type":"number","description":"Index of the executable crosschain transaction"},"hasEnoughBalance":{"type":"boolean","description":"Whether payer has sufficient token balance"},"routeType":{"type":"string","enum":["crosschain","samechain"]},"quoteExpiresAt":{"type":"number","description":"Route quote expiry timestamp"}},"required":["stepsRequired","needsApproval","paymentTransactionIndex","hasEnoughBalance","routeType"]}},"required":["transactions","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 without token approval","x-feature-flag":"crosschainDisabled","value":{"transactions":[{"data":"0xabcdef","to":"0x1234567890123456789012345678901234567890","value":"0x0","from":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","gasLimit":"300000","gasPrice":"1000000000","chainType":"evm"}],"metadata":{"stepsRequired":1,"needsApproval":false,"paymentTransactionIndex":0,"routeType":"crosschain","quoteExpiresAt":1742205771,"hasEnoughBalance":true}}},"currencyThatDoesNotSupportEIP2612":{"summary":"Crosschain payment with approval transaction","x-feature-flag":"crosschainDisabled","value":{"transactions":[{"data":"0x095ea7b3000000000000000000000000123456789012345678901234567890123456789000000000000000000000000000000000000000000000000000000000989680","to":"0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9","value":"0x0","chainType":"evm"},{"data":"0xabcdef","to":"0x1234567890123456789012345678901234567890","value":"0x0","from":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","gasLimit":"300000","gasPrice":"1000000000","chainType":"evm"}],"metadata":{"stepsRequired":2,"needsApproval":true,"approvalTransactionIndex":0,"paymentTransactionIndex":1,"routeType":"crosschain","quoteExpiresAt":1742205771,"hasEnoughBalance":true}}}}}}},"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"}},"/v1/payer":{"post":{"description":"Checks compliance status and returns necessary URLs for completing compliance.","operationId":"PayerV1Controller_getComplianceData_v1","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","V1/Payer"]}},"/v1/payer/{clientUserId}":{"patch":{"description":"Update the agreement completion status for a user.","operationId":"PayerV1Controller_updateComplianceStatus_v1","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","V1/Payer"]},"get":{"description":"Retrieves the comprehensive compliance status for a specific user, including KYC and agreement status.","operationId":"PayerV1Controller_getComplianceStatus_v1","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","V1/Payer"]}},"/v1/payer/{clientUserId}/payment-details":{"post":{"description":"Create payment details for a user","operationId":"PayerV1Controller_createPaymentDetails_v1","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","V1/Payer"]},"get":{"description":"Retrieves the registered bank account details for a user. Optionally filter by payment details ID.","operationId":"PayerV1Controller_getPaymentDetails_v1","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","V1/Payer"]}},"/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"]}},"/v1/pay":{"post":{"description":"Initiate a payment without having to create a request first","operationId":"PayV1Controller_payRequest_v1","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":{"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"],"example":{"payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","amount":"10","invoiceCurrency":"USD","paymentCurrency":"ETH-sepolia-sepolia"}}}}},"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":"V1: 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}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Wallet not found"},"429":{"description":"Too Many Requests"}},"summary":"Initiate a payment","tags":["Pay","V1/Pay"]}},"/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"]}},"batchPaymentTransaction":{"type":"object","description":"The batch payment transaction that executes all requests in the batch.","properties":{"data":{"type":"string","description":"Transaction calldata for the 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"]},"metadata":{"type":"object","description":"Optional preflight metadata. Present when payer is provided.","properties":{"hasEnoughBalance":{"type":"boolean","description":"Whether payer has enough payment-token/native balance for the whole batch"},"hasEnoughGas":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether payer has enough native gas token. Null when gas cannot be reliably estimated"},"canMakePayment":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Combined readiness across balance and gas checks. Null when gas cannot be reliably estimated for the batch and final readiness remains undetermined by the runtime response"},"insufficientTokens":{"type":"array","description":"Token-level insufficiency details when token balances are not enough","items":{"type":"object","properties":{"tokenAddress":{"type":"string"},"tokenSymbol":{"type":"string"},"paymentCurrencyId":{"type":"string"},"required":{"type":"string","description":"Required token amount for the batch, expressed in the token's smallest unit"},"available":{"type":"string","description":"Available token amount in the payer wallet, expressed in the token's smallest unit"}},"required":["tokenAddress","required","available"]}}},"required":["hasEnoughBalance","hasEnoughGas","canMakePayment"]},"requests":{"type":"array","description":"Array of created request identifiers, one per recipient in the batch. Use these to correlate payment.confirmed webhooks back to each batch item.","items":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique Request Network identifier for this recipient's request"},"paymentReference":{"type":"string","description":"Payment reference used on-chain for payment detection"},"payee":{"type":"string","nullable":true,"description":"The payee address for the request"},"amount":{"type":"string","nullable":true,"description":"The request amount in human-readable format"},"invoiceCurrency":{"type":"string","nullable":true,"description":"The invoice currency for the request"},"paymentCurrency":{"type":"string","nullable":true,"description":"The payment currency for the request"}},"required":["requestId","paymentReference","payee","amount","invoiceCurrency","paymentCurrency"]}}},"required":["ERC20ApprovalTransactions","batchPaymentTransaction","requests"],"additionalProperties":false},"examples":{"erc20_and_eth_with_approval":{"summary":"Batch payment with approval and readiness metadata","value":{"ERC20ApprovalTransactions":[{"data":"0x095ea7b3...","to":"0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C","value":0}],"batchPaymentTransaction":{"data":"0x92cddb91...","to":"0x67818703c92580c0e106e401F253E8A410A66f8B","value":{"type":"BigNumber","hex":"0x0d83b3d1afc58b"}},"requests":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","paymentReference":"a3b2c1d4e5f60718","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","amount":"100","invoiceCurrency":"USD","paymentCurrency":"fUSDC-sepolia"},{"requestId":"02f384fdd3ae5c637eg4b1g2g16ggd6a483bg9863d3c789107f5abd381527b8eec","paymentReference":"b4c3d2e5f6a71829","payee":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","amount":"10","invoiceCurrency":"FAU-sepolia","paymentCurrency":"FAU-sepolia"}],"metadata":{"hasEnoughBalance":true,"hasEnoughGas":true,"canMakePayment":true}}},"erc20_and_eth_no_approval":{"summary":"Batch payment without approval and with insufficient token","value":{"ERC20ApprovalTransactions":[],"batchPaymentTransaction":{"data":"0x92cddb91...","to":"0x67818703c92580c0e106e401F253E8A410A66f8B","value":{"type":"BigNumber","hex":"0x0d83b3d1afc58b"}},"requests":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","paymentReference":"a3b2c1d4e5f60718","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","amount":"2","invoiceCurrency":"FAU-sepolia","paymentCurrency":"FAU-sepolia"}],"metadata":{"hasEnoughBalance":false,"hasEnoughGas":null,"canMakePayment":null,"insufficientTokens":[{"tokenAddress":"0x1c7d4b196cb0c7b01d743fbc6116a902379c7238","tokenSymbol":"fUSDC","paymentCurrencyId":"fUSDC-sepolia","required":"16008000","available":"1593000"}]}}},"without_payer_metadata_absent":{"summary":"Batch payment without payer (no readiness metadata)","value":{"ERC20ApprovalTransactions":[],"batchPaymentTransaction":{"data":"0x92cddb91...","to":"0x67818703c92580c0e106e401F253E8A410A66f8B","value":{"type":"BigNumber","hex":"0x0d83b3d1afc58b"}},"requests":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","paymentReference":"a3b2c1d4e5f60718","payee":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","amount":"10","invoiceCurrency":"USD","paymentCurrency":"ETH-sepolia-sepolia"},{"requestId":"02f384fdd3ae5c637eg4b1g2g16ggd6a483bg9863d3c789107f5abd381527b8eec","paymentReference":"b4c3d2e5f6a71829","payee":"0xb07D2398d2004378cad234DA0EF14f1c94A530e4","amount":"2","invoiceCurrency":"ETH-sepolia-sepolia","paymentCurrency":"ETH-sepolia-sepolia"}]}}}}}},"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/journey":{"post":{"description":"Creates a new journeyRef (tracking ID) to trace the full lifecycle of a payment across multiple processors. This ID should be copied into the reference/memo field of all subsequent payment hops. Optionally, link the journey to an existing payment request.","operationId":"JourneyController_createJourney_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":{"requestId":{"type":"string","description":"The request ID of the request linked to the journey"}}},"examples":{"withRequestId":{"summary":"Link to an existing payment request","value":{"requestId":"01HXYZABCDEF1234567890QWERTYUIOP"}},"standalone":{"summary":"Standalone journey (no request)","value":{}}}}}},"responses":{"201":{"description":"Journey created successfully. Returns the unique journeyRef (tracking ID).","content":{"application/json":{"examples":{"default":{"summary":"JourneyRef created","value":{"journeyId":"01JOURNEYULID1234567890ABCDEF"}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Too Many Requests"}},"summary":"Create a new payment journey (tracking reference)","tags":["V2/Journey"],"x-feature-flag":"journeyDisabled"}},"/v2/journey/{queryId}":{"post":{"description":"Processors call this endpoint to report a new event (step) in a payment's journey. Each event represents a single hop (e.g., exchange, bridge, bank) and should include as much detail as possible. Events are automatically ordered by their processing time to build a full timeline. If a processor does not report, the timeline will simply show the steps that did report.","operationId":"JourneyController_createJourneyEvent_v2","parameters":[{"name":"queryId","required":true,"in":"path","description":"Either a journeyId (e.g., '01JOURNEYULID1234567890ABCDEF') or a txReference from an existing event in the journey (e.g., '0xabc123def456...'). The system will automatically determine which type is provided and locate the appropriate journey.","schema":{"example":"01JOURNEYULID1234567890ABCDEF","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":{"status":{"type":"string","description":"The status of the journey event"},"amount":{"type":"string","description":"The amount of the journey event"},"processedAt":{"type":"string","description":"The date and time the journey event was processed, has to be in UTC format and end with 'Z' example `2025-07-23T14:23:00Z`"},"currency":{"type":"string","description":"The currency of the journey event"},"txReference":{"type":"string","description":"The transaction reference of the journey event"},"rawPayload":{"description":"The raw payload of the journey event"},"nextProcessorId":{"type":"string","description":"The ID of the next processor in the journey"}},"required":["status","amount","processedAt"]},"examples":{"full":{"summary":"Full event with transaction reference and details","value":{"status":"COMPLETED","amount":"1000.00","currency":"USDT","txReference":"0xabc123def456...","processedAt":"2024-06-10T14:23:00Z","rawPayload":{"exchange":"Binance","network":"Ethereum","fee":"2.50","note":"Withdrawal to bridge"}}},"minimal":{"summary":"Minimal event (required fields only)","value":{"status":"PENDING","amount":"500.00","processedAt":"2024-06-10T13:00:00Z"}}}}}},"responses":{"201":{"description":"Journey event created successfully. Returns the event details.","content":{"application/json":{"examples":{"default":{"summary":"Event created","value":{"id":"01EVENTULID1234567890ABCDEF","journeyId":"01JOURNEYULID1234567890ABCDEF","processorId":"01PROCESSORULID1234567890ABCDEF","status":"COMPLETED","amount":"1000.00","currency":"USDT","txReference":"0xabc123def456...","processedAt":"2024-06-10T14:23:00Z","rawPayload":{"exchange":"Binance","network":"Ethereum","fee":"2.50","note":"Withdrawal to bridge"}}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Too Many Requests"}},"summary":"Report a payment event (step) for a journey","tags":["V2/Journey"],"x-feature-flag":"journeyDisabled"}},"/v2/journey/{journeyId}":{"get":{"description":"Returns the journey and all reported events (steps) for a given journeyRef (tracking ID), sorted by processing time. This provides a transparent, end-to-end timeline of the payment's path across all reporting processors.","operationId":"JourneyController_getJourney_v2","parameters":[{"name":"journeyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Journey and its events retrieved successfully.","content":{"application/json":{"examples":{"default":{"summary":"Journey with events","value":{"id":"01JOURNEYULID1234567890ABCDEF","requestId":"01HXYZABCDEF1234567890QWERTYUIOP","createdAt":"2024-06-10T12:00:00Z","events":[{"id":"01EVENTULID1234567890ABCDEF","stepIndex":1,"status":"PENDING","amount":"500.00","currency":"USDT","processedAt":"2024-06-10T13:00:00Z"},{"id":"01EVENTULID1234567890ABCDEG","stepIndex":2,"status":"COMPLETED","amount":"1000.00","currency":"USDT","txReference":"0xabc123def456...","processedAt":"2024-06-10T14:23:00Z","rawPayload":{"exchange":"Binance","network":"Ethereum"}}]}}}}}},"401":{"description":"Unauthorized"},"429":{"description":"Too Many Requests"}},"summary":"Get the full timeline for a payment journey","tags":["V2/Journey"],"x-feature-flag":"journeyDisabled"}},"/v2/commerce-payments/authorize/calldata":{"post":{"description":"Generate calldata for a payer to authorize a payment through the commerce escrow. Creates a Request Network request and returns escrow authorization calldata. Requires API key authentication.","operationId":"CommercePaymentsController_generateAuthorizeCalldata_v2","parameters":[{"name":"origin","required":true,"in":"header","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"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","minLength":1,"description":"The merchant identifier"},"merchantAddress":{"type":"string","description":"The merchant identifier (typically wallet address)"},"buyerAddress":{"type":"string","description":"The buyer wallet address"},"amount":{"type":"string","description":"The payment amount in token's smallest unit"},"paymentCurrency":{"type":"string","description":"Payment currency with network (e.g., 'USDC-base-sepolia', 'ETH-mainnet')"},"maxAmount":{"type":"string","description":"The maximum amount authorized (defaults to amount if not specified)"},"preApprovalExpiry":{"type":"integer","exclusiveMinimum":true,"description":"Unix timestamp for pre-approval expiry","minimum":0},"authorizationExpiry":{"type":"integer","exclusiveMinimum":true,"description":"Unix timestamp for authorization expiry","minimum":0}},"required":["merchantId","merchantAddress","amount","paymentCurrency"],"example":{"merchantId":"merchant_123","merchantAddress":"0x1234567890123456789012345678901234567890","buyerAddress":"0x1234567890123456789012345678901234567890","amount":"1000000","paymentCurrency":"USDC-base","preApprovalExpiry":1735689600,"authorizationExpiry":1735776000}}}}},"responses":{"201":{"description":"Authorization calldata generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Contract address to call"},"data":{"type":"string","description":"Encoded function calldata"},"value":{"type":"string","description":"ETH value to send (usually '0')"},"description":{"type":"string","description":"Human-readable description of this call"}},"required":["to","data","value","description"]},"examples":{"success":{"summary":"Successful calldata generation","value":{"requestId":"0x1234567890abcdef","calldata":"0x...","to":"0xEscrowContractAddress","value":"0","operator":"0xOperatorAddress"}}}}}},"400":{"description":"Invalid request parameters"},"429":{"description":"Too Many Requests"}},"summary":"Generate authorization calldata","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/status":{"get":{"description":"Get the current status and details of a commerce payment. Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_getPaymentStatus_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize","schema":{"example":"0x1234567890abcdef","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":"Payment status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["AUTHORIZED","CAPTURED","VOIDED","REFUNDED","EXPIRED","RECLAIMED","FAILED"],"description":"Event type"},"timestamp":{"type":"string","description":"ISO 8601 timestamp"},"transactionHash":{"type":"string","description":"Transaction hash"},"blockNumber":{"type":"string","description":"Block number"}},"required":["type","timestamp"]},"examples":{"authorized":{"summary":"Authorized payment","value":{"requestId":"0x1234567890abcdef","status":"AUTHORIZED","payer":"0xPayerAddress","merchant":"0xMerchantAddress","operator":"0xOperatorAddress","token":"0xTokenAddress","amount":"1000000","maxAmount":"1000000","capturedAmount":"0","refundedAmount":"0","commercePaymentHash":"0xHash","preApprovalExpiry":"1735689600","authorizationExpiry":"1735776000","refundExpiry":"1736380800","canCapture":true,"canVoid":true,"canRefund":false,"createdAt":"2025-01-01T00:00:00Z","updatedAt":"2025-01-01T00:00:00Z","events":[{"type":"AUTHORIZED","timestamp":"2025-01-01T00:00:00Z","transactionHash":"0xTxHash","blockNumber":"12345"}]}}}}}},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Get payment status","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/authorize":{"post":{"description":"Authorize a payment using the operator's smart account. This executes the authorization transaction after the buyer has pre-approved. Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_authorizePayment_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize/calldata","schema":{"example":"0x1234567890abcdef","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":"Authorization initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique request identifier"},"status":{"type":"string","enum":["PENDING","AUTHORIZING","AUTHORIZED","CAPTURING","PAID","VOIDING","VOIDED","REFUNDING","REFUNDED","PARTIALLY_REFUNDED","EXPIRED","RECLAIMED","FAILED"],"description":"Updated payment status"},"transactionHash":{"type":"string","description":"Transaction hash"},"amount":{"type":"string","description":"Amount being authorized"}},"required":["requestId","status","transactionHash","amount"]},"examples":{"success":{"summary":"Successful authorization","value":{"requestId":"0x1234567890abcdef","status":"AUTHORIZING","transactionHash":"0xTxHash","amount":"1000000"}}}}}},"400":{"description":"Invalid authorization request"},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Authorize payment","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/capture/calldata":{"post":{"description":"Generate calldata for capturing an authorized payment. Returns the transaction calldata that can be used to execute the capture operation. Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_generateCaptureCalldata_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize","schema":{"example":"0x1234567890abcdef","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":{"captureAmount":{"type":"string","description":"The amount to capture from the authorized payment"},"feeBps":{"type":"integer","minimum":0,"maximum":10000,"description":"Fee in basis points (0-10000, where 100 = 1%)"},"feeReceiver":{"type":"string","description":"Address to receive the fee (required if feeBps > 0)"}},"required":["captureAmount"],"example":{"captureAmount":"1000000","feeBps":250,"feeReceiver":"0xFeeReceiverAddress"}}}}},"responses":{"200":{"description":"Capture calldata generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique request identifier"},"calldata":{"type":"string","description":"Encoded transaction calldata"},"to":{"type":"string","description":"The contract address to send the transaction to"},"value":{"type":"string","description":"The value to send with the transaction (0)"},"operator":{"type":"string","description":"The operator address that will execute this transaction"}},"required":["requestId","calldata","to","value","operator"]},"examples":{"success":{"summary":"Successful calldata generation","value":{"requestId":"0x1234567890abcdef","calldata":"0x...","to":"0xEscrowContractAddress","value":"0","operator":"0xOperatorAddress"}}}}}},"400":{"description":"Invalid capture request"},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Generate capture calldata","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/void/calldata":{"post":{"description":"Generate calldata for voiding an authorized payment. Returns the transaction calldata that can be used to execute the void operation. Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_generateVoidCalldata_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize","schema":{"example":"0x1234567890abcdef","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":"Void calldata generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique request identifier"},"calldata":{"type":"string","description":"Encoded transaction calldata"},"to":{"type":"string","description":"The contract address to send the transaction to"},"value":{"type":"string","description":"The value to send with the transaction (0)"},"operator":{"type":"string","description":"The operator address that will execute this transaction"}},"required":["requestId","calldata","to","value","operator"]},"examples":{"success":{"summary":"Successful calldata generation","value":{"requestId":"0x1234567890abcdef","calldata":"0x...","to":"0xEscrowContractAddress","value":"0","operator":"0xOperatorAddress"}}}}}},"400":{"description":"Invalid void request"},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Generate void calldata","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/capture":{"post":{"description":"Capture funds from an authorized payment (operator only operation). Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_capturePayment_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize","schema":{"example":"0x1234567890abcdef","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":{"captureAmount":{"type":"string","description":"The amount to capture from the authorized payment"},"feeBps":{"type":"integer","minimum":0,"maximum":10000,"description":"Fee in basis points (0-10000, where 100 = 1%)"},"feeReceiver":{"type":"string","description":"Address to receive the fee (required if feeBps > 0)"}},"required":["captureAmount"],"example":{"captureAmount":"1000000","feeBps":250,"feeReceiver":"0xFeeReceiverAddress"}}}}},"responses":{"200":{"description":"Capture initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique request identifier"},"status":{"type":"string","enum":["PENDING","AUTHORIZING","AUTHORIZED","CAPTURING","PAID","VOIDING","VOIDED","REFUNDING","REFUNDED","PARTIALLY_REFUNDED","EXPIRED","RECLAIMED","FAILED"],"description":"Updated payment status"},"transactionHash":{"type":"string","description":"Transaction hash"},"captureAmount":{"type":"string","description":"Amount being captured"}},"required":["requestId","status","transactionHash","captureAmount"]},"examples":{"success":{"summary":"Successful capture","value":{"requestId":"0x1234567890abcdef","status":"CAPTURING","transactionHash":"0xTxHash","captureAmount":"1000000"}}}}}},"400":{"description":"Invalid capture request"},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Capture authorized payment","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/v2/commerce-payments/{requestId}/void":{"post":{"description":"Void an authorized payment and return funds to payer (operator only operation). Can be called with either API key or client ID authentication.","operationId":"CommercePaymentsController_voidPayment_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The request ID returned from authorize","schema":{"example":"0x1234567890abcdef","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":{"reason":{"type":"string","description":"Optional reason for voiding the payment"}},"example":{"reason":"merchant_rejected"}}}}},"responses":{"200":{"description":"Void initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique request identifier"},"status":{"type":"string","enum":["PENDING","AUTHORIZING","AUTHORIZED","CAPTURING","PAID","VOIDING","VOIDED","REFUNDING","REFUNDED","PARTIALLY_REFUNDED","EXPIRED","RECLAIMED","FAILED"],"description":"Updated payment status"},"transactionHash":{"type":"string","description":"Transaction hash"},"voidedAmount":{"type":"string","description":"Amount voided"}},"required":["requestId","status","transactionHash","voidedAmount"]},"examples":{"success":{"summary":"Successful void","value":{"requestId":"0x1234567890abcdef","status":"VOIDING","transactionHash":"0xTxHash","voidedAmount":"1000000"}}}}}},"400":{"description":"Invalid void request"},"404":{"description":"Payment not found"},"429":{"description":"Too Many Requests"}},"summary":"Void authorized payment","tags":["V2/Commerce Payments"],"x-feature-flag":"commerceDisabled"}},"/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 payment, multiple items create a batch payment. 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 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":"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":{"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'). Optional when the client ID has a configured payee destination."},"amount":{"type":"string","description":"The payable amount, in human readable format"}},"required":["amount"]},"minItems":1,"description":"Array of payment requests. Single item = single payment, multiple items = batch payment. All requests must resolve to the same network."},"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...)"},"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"}},"required":["requests"]},"examples":{"singlePayment":{"summary":"Single payment example","value":{"requests":[{"destinationId":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C","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":"Batch payment example","value":{"requests":[{"destinationId":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:11155111#A1B2C3D4:0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C","amount":"10"},{"destinationId":"0xb07d2398d2004378cad234da0ef14f1c94a530e4@eip155:11155111#E5F6A7B8: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"}},"required":["requestIds","securePaymentUrl","token"]},"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"}}}}}},"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"],"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"}},"required":["token","securePaymentUrl","status","paymentType","createdAt","expiresAt"]},"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"}}}}}},"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). If the recipient already has an active matching destination on the Request Network, the payout is linked to it; otherwise the payment is created from the raw inputs and stored without a destination. 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 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":"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":{"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 '<symbol>-<network>' 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"},"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...)"}},"required":["recipient","creatorWalletAddress","network","currency","amount"]},"examples":{"payout":{"summary":"Payout example","value":{"recipient":"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7","network":"sepolia","currency":"FAU-sepolia","amount":"10"}},"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"}},"required":["requestIds","securePaymentUrl","token"]}}}},"400":{"description":"Invalid payout request (e.g., unsupported network or currency)"},"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/{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","required":false,"in":"query","description":"The source token of the crosschain payment","schema":{"enum":["USDC","USDT"],"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 (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"}}],"responses":{"200":{"description":"Secure payment data retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"paymentType":{"type":"string","enum":["single"],"description":"Type of payment: single or batch"},"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)"},"status":{"type":"string","enum":["pending","completed","expired","invalidated"],"description":"Current status of the secure payment"},"destination":{"type":["object","null"],"properties":{"destinationId":{"type":"string","description":"Composite destination ID: ERC-7828 payee address + token address (e.g., '0x742d...bEb0@eip155:11155111#80B12379:0x370D...623C')"},"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"}},"required":["destinationId","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)."},"reference":{"type":"string","description":"Merchant reference for the payment","nullable":true}},"required":["paymentType","payee","network","amount","paymentCurrency","isNativeCurrency","status","destination","reference"]},"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"}}}}}},"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","requestStatuses":[{"requestId":"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb","hasBeenPaid":true,"txHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}]}}}}}},"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","required":false,"in":"query","description":"The source token of the crosschain payment","schema":{"enum":["USDC","USDT"],"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 (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"}}],"responses":{"200":{"description":"Secure payment calldata retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{}},"eoaApprovalTransactions":{"type":"array","items":{}},"metadata":{"type":"object","properties":{"stepsRequired":{"type":"number"},"needsApproval":{"type":"boolean"},"approvalTransactionIndex":{"type":"number"},"approvalTransactionsCount":{"type":"number"},"paymentTransactionIndex":{"type":"number"},"hasEnoughBalance":{"type":"boolean"},"hasEnoughGas":{"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"},"sourceAmount":{"type":"string"},"routeType":{"type":"string","enum":["crosschain","samechain"]},"quoteExpiresAt":{"type":"number"},"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"]},"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":["transactions","metadata"]}}}},"400":{"description":"Invalid secure payment calldata request"},"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":"Get secure payment calldata by token","tags":["V2/Secure Payment"],"x-feature-flag":"securePaymentsDisabled"}},"/v2/secure-payments/{token}/intent":{"post":{"description":"Records the source-chain transaction hash for a crosschain secure payment after the payer broadcasts the LiFi transaction. This creates or reuses a tracking intent so the backend can later enrich the detected payment with LiFi crosschain data.","operationId":"SecurePaymentController_recordIntent_v2","parameters":[{"name":"token","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"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"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"]}},"required":["txHash","chain","token"]}}}},"responses":{"200":{"description":"Intent recorded successfully","content":{"application/json":{"schema":{"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"},"isListening":{"type":"boolean","description":"Whether the tracking intent is being monitored for status"}},"required":["intentId","paymentReference","txHash","isListening"]}}}},"400":{"description":"Invalid or unsupported crosschain execution payload"},"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"}}},"info":{"title":"Request Network API","description":"API for easily creating and paying Requests with Request Network.","version":"0.18.3","contact":{}},"tags":[{"name":"V1/Request","description":"Core payment request operations (V1)"},{"name":"V1/Pay","description":"Pay a request without creating one first (V1)"},{"name":"V1/Authentication","description":"Authentication operations (V1)"},{"name":"V1/API Keys","description":"API key management (V1)"},{"name":"V1/Currencies","description":"Currency operations (V1)"},{"name":"V1/Webhooks","description":"Webhook configuration (V1)"},{"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/Authentication","description":"Authentication operations (V2)"},{"name":"V2/API Keys","description":"API key management (V2)"},{"name":"V2/Webhooks","description":"Webhook configuration (V2)"},{"name":"V2/Currencies","description":"Currency operations (V2)"},{"name":"V2/Platforms","description":"Platform operations (V2)"},{"name":"V2/Journey","description":"Journey operations (V2)"},{"name":"V2/Client IDs","description":"Client ID management (V2)"},{"name":"V2/Commerce Payments","description":"Authorization-capture commerce payment operations (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.stage.request.network","description":"Staging server"},{"url":"https://api.request.network","description":"Production 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"}]}