From 0d66aac0803ef9ce900f56e049218866ba77aa25 Mon Sep 17 00:00:00 2001 From: Aimen Sahnoun Date: Tue, 3 Mar 2026 14:59:18 +0400 Subject: [PATCH] =?UTF-8?q?docs(api-reference):=20add=20v2=20endpoints=20o?= =?UTF-8?q?verview=20and=20switch=20docs=20OpenAPI=20to=20v2-only=20spec?= =?UTF-8?q?=20Improve=20API=20Reference=20navigation=20by=20introducing=20?= =?UTF-8?q?a=20dedicated=20Endpoints=20Overview=20page=20in=20docs=20and?= =?UTF-8?q?=20wiring=20Mintlify=20OpenAPI=20rendering=20to=20a=20local=20v?= =?UTF-8?q?2-only=20spec.=20-=20add=20`api-reference/endpoints-overview.md?= =?UTF-8?q?x`=20as=20a=20docs-native=20index=20for=20endpoint=20groups=20-?= =?UTF-8?q?=20update=20overview=20cards=20to=20route=20inside=20docs=20(in?= =?UTF-8?q?stead=20of=20external=20links),=20including=20direct=20navigati?= =?UTF-8?q?on=20to=20v2=20Request=20endpoint=20pages=20-=20repurpose=20`re?= =?UTF-8?q?quest-network-api/create-and-pay-requests.mdx`=20into=20an=20en?= =?UTF-8?q?dpoint-overview=20style=20page=20to=20avoid=20legacy=20overlap?= =?UTF-8?q?=20and=20reduce=20duplicated=20=E2=80=9Chow-to=E2=80=9D=20conte?= =?UTF-8?q?nt=20-=20update=20`docs.json`=20Endpoints=20group=20to=20use=20?= =?UTF-8?q?a=20local=20OpenAPI=20source:=20=20=20`api-reference/openapi.v2?= =?UTF-8?q?.json`=20-=20add=20`api-reference/openapi.v2.json`=20(filtered?= =?UTF-8?q?=20v2-only=20OpenAPI=20spec)=20to=20improve=20separation=20betw?= =?UTF-8?q?een=20v1=20and=20v2=20endpoint=20references=20in=20Mintlify=20-?= =?UTF-8?q?=20keep=20API=20Reference=20section=20focused=20on=20discoverab?= =?UTF-8?q?ility=20and=20endpoint=20navigation=20while=20API=20Features=20?= =?UTF-8?q?remains=20implementation-focused?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-reference/endpoints-overview.mdx | 54 + api-reference/openapi.v2.json | 5843 +++++++++++++++++ docs.json | 6 +- .../create-and-pay-requests.mdx | 85 +- 4 files changed, 5956 insertions(+), 32 deletions(-) create mode 100644 api-reference/endpoints-overview.mdx create mode 100644 api-reference/openapi.v2.json diff --git a/api-reference/endpoints-overview.mdx b/api-reference/endpoints-overview.mdx new file mode 100644 index 0000000..a5291dc --- /dev/null +++ b/api-reference/endpoints-overview.mdx @@ -0,0 +1,54 @@ +--- +title: "Endpoints Overview" +description: "Quick index of v2 endpoint groups" +--- + +## Overview + +Use this page as the index for v2 endpoints in the docs-integrated OpenAPI reference. + +## v2 Endpoint Groups + + + + v2 request endpoints for create, status, pay calldata, and routes. + + + + v2 payout endpoints for direct, batch, and recurring operations. + + + + v2 payment search endpoint for reconciliation and reporting. + + + + v2 payer endpoints for KYC, agreement, and payment details. + + + +## Requests (v2) + +- [v2 Request endpoints](https://api.request.network/open-api/#tag/v2request) +- [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request) +- [GET /v2/request/{requestId}](https://api.request.network/open-api/#tag/v2request/GET/v2/request/%7BrequestId%7D) +- [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/%7BrequestId%7D/pay) +- [GET /v2/request/{requestId}/routes](https://api.request.network/open-api/#tag/v2request/GET/v2/request/%7BrequestId%7D/routes) + +## Payouts (v2) + +- [v2 Payout endpoints](https://api.request.network/open-api/#tag/v2payouts) +- [POST /v2/payouts](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts) +- [POST /v2/payouts/batch](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts/batch) +- [POST /v2/payouts/recurring/{id}](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts/recurring/%7Bid%7D) + +## Payments (v2) + +- [GET /v2/payments](https://api.request.network/open-api/#tag/v2payments/GET/v2/payments) + +## Payer / Compliance (v2) + +- [v2 Payer endpoints](https://api.request.network/open-api/#tag/v2payer) +- [POST /v2/payer](https://api.request.network/open-api/#tag/v2payer/POST/v2/payer) +- [GET /v2/payer/{clientUserId}](https://api.request.network/open-api/#tag/v2payer/GET/v2/payer/%7BclientUserId%7D) +- [PATCH /v2/payer/{clientUserId}](https://api.request.network/open-api/#tag/v2payer/PATCH/v2/payer/%7BclientUserId%7D) diff --git a/api-reference/openapi.v2.json b/api-reference/openapi.v2.json new file mode 100644 index 0000000..61095b5 --- /dev/null +++ b/api-reference/openapi.v2.json @@ -0,0 +1,5843 @@ +{ + "openapi": "3.0.0", + "paths": { + "/v2/currencies": { + "get": { + "description": "Get a list of all available tokens, or filter by network, symbol, or id.", + "operationId": "CurrenciesV2Controller_getNetworkTokens_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "network", + "required": false, + "in": "query", + "description": "The network of the token(s)", + "schema": { + "example": "mainnet", + "type": "string" + } + }, + { + "name": "symbol", + "required": false, + "in": "query", + "description": "The symbol of the token", + "schema": { + "example": "USDC", + "type": "string" + } + }, + { + "name": "firstOnly", + "required": false, + "in": "query", + "description": "Whether to return only the first token. can only be used when both `network` and `symbol` are provided.", + "schema": { + "example": true, + "type": "string" + } + }, + { + "name": "id", + "required": false, + "in": "query", + "description": "The Request Network id of the token", + "schema": { + "example": "USDC-mainnet", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of tokens retrieved successfully", + "content": { + "application/json": { + "examples": { + "all": { + "summary": "All tokens", + "value": [ + { + "id": "USDC-mainnet", + "name": "USD Coin", + "symbol": "USDC", + "decimals": 6, + "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "network": "mainnet", + "type": "ERC20", + "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "chainId": 1 + }, + { + "id": "USDT-mainnet", + "name": "Tether USD", + "symbol": "USDT", + "decimals": 6, + "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", + "network": "mainnet", + "type": "ERC20", + "hash": "0xdAC17F958D2ee523a2206206994597C13D831ec7", + "chainId": 1 + } + ] + }, + "byNetwork": { + "summary": "Tokens on mainnet", + "value": [ + { + "id": "USDC-mainnet", + "name": "USD Coin", + "symbol": "USDC", + "decimals": 6, + "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "network": "mainnet", + "type": "ERC20", + "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "chainId": 1 + } + ] + }, + "bySymbolAndNetwork": { + "summary": "USDC on mainnet", + "value": [ + { + "id": "USDC-mainnet", + "name": "USD Coin", + "symbol": "USDC", + "decimals": 6, + "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "network": "mainnet", + "type": "ERC20", + "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "chainId": 1 + } + ] + }, + "firstOnly": { + "summary": "First match only", + "value": { + "id": "USDC-mainnet", + "name": "USD Coin", + "symbol": "USDC", + "decimals": 6, + "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "network": "mainnet", + "type": "ERC20", + "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "chainId": 1 + } + }, + "byId": { + "summary": "By ID", + "value": { + "id": "USDC-mainnet", + "name": "USD Coin", + "symbol": "USDC", + "decimals": 6, + "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "network": "mainnet", + "type": "ERC20", + "hash": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", + "chainId": 1 + } + } + } + } + } + }, + "400": { + "description": "Validation failed", + "content": { + "application/json": { + "examples": { + "invalidFirstOnly": { + "summary": "Invalid firstOnly value", + "value": { + "statusCode": 400, + "message": [ + { + "code": "custom", + "message": "firstOnly must be 'true' or 'false' if provided", + "path": [ + "firstOnly" + ] + } + ], + "error": "Bad Request" + } + } + } + } + } + }, + "404": { + "description": "Token not found", + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "Token not found", + "value": { + "statusCode": 404, + "message": "Token not found", + "error": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get currencies", + "tags": [ + "Currencies", + "V2/Currencies" + ] + } + }, + "/v2/currencies/{currencyId}/conversion-routes": { + "get": { + "description": "Get a list of currency objects (with all details) that can be converted to from the specified currency. Optionally filter by network using the 'network' query parameter.", + "operationId": "CurrenciesV2Controller_getConversionRoutes_v2", + "parameters": [ + { + "name": "currencyId", + "required": true, + "in": "path", + "schema": { + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "network", + "required": false, + "in": "query", + "description": "The network of the token to filter by", + "schema": { + "type": "string" + } + }, + { + "name": "networks", + "required": false, + "in": "query", + "description": "A comma-separated list of networks to filter by (e.g., sepolia,mainnet,polygon)", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Conversion routes retrieved successfully", + "content": { + "application/json": { + "examples": { + "usdRoutes": { + "summary": "USD conversion routes on mainnet", + "value": { + "currencyId": "USD", + "network": "mainnet", + "conversionRoutes": [ + { + "id": "USDT-mainnet", + "name": "Tether USD", + "symbol": "USDT", + "decimals": 6, + "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", + "network": "mainnet", + "type": "ERC20", + "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "chainId": 1 + }, + { + "id": "ETH-mainnet", + "name": "Ether", + "symbol": "ETH", + "decimals": 18, + "address": "0xf5af88e117747e87fc5929f2ff87221b1447652e", + "network": "mainnet", + "type": "ETH", + "hash": "0xf5af88e117747e87fc5929f2ff87221b1447652e", + "chainId": 1 + } + ] + } + }, + "allNetworks": { + "summary": "All networks conversion routes", + "value": { + "currencyId": "USD", + "network": null, + "conversionRoutes": [ + { + "id": "USDT-mainnet", + "name": "Tether USD", + "symbol": "USDT", + "decimals": 6, + "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", + "network": "mainnet", + "type": "ERC20", + "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "chainId": 1 + }, + { + "id": "FAU-sepolia", + "name": "FAU", + "symbol": "FAU", + "decimals": 18, + "address": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", + "network": "sepolia", + "type": "ERC20", + "hash": "0x370de27fdb7d1ff1e1baa7d11c5820a324cf623c", + "chainId": 11155111 + } + ] + } + }, + "multiNetworks": { + "summary": "Multiple networks conversion routes", + "value": { + "currencyId": "USD", + "networks": [ + "mainnet", + "polygon" + ], + "conversionRoutes": [ + { + "id": "USDT-mainnet", + "name": "Tether USD", + "symbol": "USDT", + "decimals": 6, + "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", + "network": "mainnet", + "type": "ERC20", + "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7", + "chainId": 1 + }, + { + "id": "USDT-polygon", + "name": "Tether USD", + "symbol": "USDT", + "decimals": 6, + "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", + "network": "polygon", + "type": "ERC20", + "hash": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f", + "chainId": 137 + } + ] + } + } + } + } + } + }, + "404": { + "description": "Currency not found", + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "Currency not found", + "value": { + "statusCode": 404, + "message": "Token not found", + "error": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get conversion routes for a specific currency", + "tags": [ + "Currencies", + "V2/Currencies" + ] + } + }, + "/v2/client-ids": { + "post": { + "description": "Create a new client ID for frontend applications with domain restrictions", + "operationId": "ClientIdV2Controller_create_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string", + "format": "uri" + }, + "minItems": 1, + "maxItems": 10, + "description": "List of allowed domain origins (normalized)" + }, + "feePercentage": { + "type": "string", + "minLength": 1, + "description": "Fee percentage (e.g., '1' = 1%, '2.5' = 2.5%, '2.55' = 2.55%). Maximum 2 decimal places. If set to '0', allows API request fees to take precedence. If set to any other value, overrides any fee passed via API." + }, + "feeAddress": { + "type": "string", + "description": "Wallet address to receive fees. Required if feePercentage is set." + }, + "operatorWalletAddress": { + "type": "string", + "description": "Wallet address that will act as operator for commerce payments. The API operator wallet will execute transactions on behalf of this address. Can be a smart wallet that has granted permissions to the API operator." + }, + "defaultPreApprovalExpiry": { + "type": "integer", + "exclusiveMinimum": true, + "description": "Default pre-approval expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint.", + "minimum": 0 + }, + "defaultAuthorizationExpiry": { + "type": "integer", + "exclusiveMinimum": true, + "description": "Default authorization expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint.", + "minimum": 0 + } + }, + "required": [ + "label", + "allowedDomains" + ] + }, + "examples": { + "basicClientId": { + "summary": "Client ID without fee configuration", + "value": { + "label": "My Client ID", + "allowedDomains": [ + "https://example.com" + ] + } + }, + "clientIdWithFees": { + "summary": "Client ID with fee configuration", + "value": { + "label": "My Client ID with Fees", + "allowedDomains": [ + "https://example.com", + "https://app.example.com" + ], + "feePercentage": "2.5", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Client ID created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "clientId": { + "type": "string" + }, + "label": { + "type": "string" + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "feePercentage": { + "type": "string", + "nullable": true + }, + "feeAddress": { + "type": "string", + "nullable": true + }, + "operatorWalletAddress": { + "type": "string", + "nullable": true + }, + "defaultPreApprovalExpiry": { + "type": "number", + "nullable": true + }, + "defaultAuthorizationExpiry": { + "type": "number", + "nullable": true + }, + "status": { + "type": "string" + }, + "createdAt": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Bad request - validation failed" + }, + "401": { + "description": "Unauthorized" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Create a new client ID", + "tags": [ + "Client IDs", + "V2/Client IDs" + ] + }, + "get": { + "description": "Get all client IDs for the authenticated platform", + "operationId": "ClientIdV2Controller_findAll_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of client IDs", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "clientId": { + "type": "string" + }, + "label": { + "type": "string" + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "lastUsedAt": { + "type": "string", + "nullable": true + } + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "List all client IDs", + "tags": [ + "Client IDs", + "V2/Client IDs" + ] + } + }, + "/v2/client-ids/{id}": { + "get": { + "description": "Get details of a specific client ID", + "operationId": "ClientIdV2Controller_findOne_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Client ID internal identifier", + "schema": { + "example": "123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Client ID details", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "clientId": { + "type": "string" + }, + "label": { + "type": "string" + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "feePercentage": { + "type": "string", + "nullable": true + }, + "feeAddress": { + "type": "string", + "nullable": true + }, + "operatorWalletAddress": { + "type": "string", + "nullable": true + }, + "defaultPreApprovalExpiry": { + "type": "number", + "nullable": true + }, + "defaultAuthorizationExpiry": { + "type": "number", + "nullable": true + }, + "status": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + }, + "lastUsedAt": { + "type": "string", + "nullable": true + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Client ID not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get a specific client ID", + "tags": [ + "Client IDs", + "V2/Client IDs" + ] + }, + "put": { + "description": "Update client ID settings including domains and rate limits", + "operationId": "ClientIdV2Controller_update_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Client ID internal identifier", + "schema": { + "example": "123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string", + "format": "uri" + }, + "minItems": 1, + "maxItems": 10, + "description": "List of allowed domain origins (normalized)" + }, + "feePercentage": { + "type": "string", + "minLength": 1, + "description": "Fee percentage (e.g., '1' = 1%, '2.5' = 2.5%, '2.55' = 2.55%). Maximum 2 decimal places. If set to '0', allows API request fees to take precedence. If set to any other value, overrides any fee passed via API. Set to null to unset.", + "nullable": true + }, + "feeAddress": { + "type": "string", + "description": "Wallet address to receive fees. Required if feePercentage is set. Set to null to unset.", + "nullable": true + }, + "operatorWalletAddress": { + "type": "string", + "description": "Wallet address that will act as operator for commerce payments. The API operator wallet will execute transactions on behalf of this address. Can be a smart wallet that has granted permissions to the API operator. Set to null to unset. Note: Changing this will only affect new payments; existing payments will continue using their original operator address.", + "nullable": true + }, + "defaultPreApprovalExpiry": { + "type": "integer", + "exclusiveMinimum": true, + "description": "Default pre-approval expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint. Set to null to unset.", + "nullable": true, + "minimum": 0 + }, + "defaultAuthorizationExpiry": { + "type": "integer", + "exclusiveMinimum": true, + "description": "Default authorization expiry duration in seconds for commerce transactions. If set, overrides the value passed in /v2/commerce-payments/authorize/calldata endpoint. Set to null to unset.", + "nullable": true, + "minimum": 0 + }, + "status": { + "type": "string", + "enum": [ + "active", + "inactive", + "revoked" + ] + } + } + }, + "examples": { + "updateBasicInfo": { + "summary": "Update basic client ID information", + "value": { + "label": "Updated Client ID Label", + "allowedDomains": [ + "https://newdomain.com" + ] + } + }, + "addFeeConfiguration": { + "summary": "Add fee configuration to existing client ID", + "value": { + "feePercentage": "1.5", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" + } + }, + "removeFeeConfiguration": { + "summary": "Remove fee configuration from client ID", + "value": { + "feePercentage": null, + "feeAddress": null + } + }, + "updateStatus": { + "summary": "Update client ID status", + "value": { + "status": "inactive" + } + }, + "updateOperatorWallet": { + "summary": "Update operator wallet address for commerce payments", + "value": { + "operatorWalletAddress": "0x1234567890123456789012345678901234567890" + } + }, + "removeOperatorWallet": { + "summary": "Remove operator wallet address (revert to API operator)", + "value": { + "operatorWalletAddress": null + } + }, + "setDefaultExpirySettings": { + "summary": "Set default expiry settings for commerce payments (in seconds)", + "value": { + "defaultPreApprovalExpiry": 3600, + "defaultAuthorizationExpiry": 86400 + } + }, + "removeDefaultExpirySettings": { + "summary": "Remove default expiry settings", + "value": { + "defaultPreApprovalExpiry": null, + "defaultAuthorizationExpiry": null + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Client ID updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "clientId": { + "type": "string" + }, + "label": { + "type": "string" + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "feePercentage": { + "type": "string", + "nullable": true + }, + "feeAddress": { + "type": "string", + "nullable": true + }, + "operatorWalletAddress": { + "type": "string", + "nullable": true + }, + "defaultPreApprovalExpiry": { + "type": "number", + "nullable": true + }, + "defaultAuthorizationExpiry": { + "type": "number", + "nullable": true + }, + "status": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Bad request - validation failed or cannot reactivate revoked ID" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Client ID not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Update a client ID", + "tags": [ + "Client IDs", + "V2/Client IDs" + ] + }, + "delete": { + "description": "Revoke a client ID (cannot be reactivated)", + "operationId": "ClientIdV2Controller_delete_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Client ID internal identifier", + "schema": { + "example": "123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Client ID revoked successfully" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Client ID not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Revoke a client ID", + "tags": [ + "Client IDs", + "V2/Client IDs" + ] + } + }, + "/v2/request": { + "post": { + "description": "Create a new payment request", + "operationId": "RequestControllerV2_createRequest_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payer": { + "type": "string", + "description": "The wallet address of the payer" + }, + "payee": { + "type": "string", + "description": "The wallet address of the payee (Ethereum 0x... or TRON T...). Required for all requests except crypto-to-fiat" + }, + "amount": { + "type": "string", + "description": "The payable amount of the invoice, in human readable format" + }, + "invoiceCurrency": { + "type": "string", + "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" + }, + "paymentCurrency": { + "type": "string", + "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" + }, + "recurrence": { + "type": "object", + "properties": { + "startDate": { + "type": "string", + "description": "The start date of the invoice, cannot be in the past" + }, + "frequency": { + "type": "string", + "enum": [ + "DAILY", + "WEEKLY", + "MONTHLY", + "YEARLY" + ], + "description": "The frequency of the invoice" + } + }, + "required": [ + "startDate", + "frequency" + ], + "description": "The recurrence of the invoice" + }, + "isCryptoToFiatAvailable": { + "type": "boolean", + "description": "Whether crypto-to-fiat payment is available for this request" + }, + "customerInfo": { + "type": "object", + "properties": { + "firstName": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Customer's first name" + }, + "lastName": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Customer's last name" + }, + "email": { + "type": "string", + "maxLength": 255, + "format": "email", + "description": "Customer's email address" + }, + "address": { + "type": "object", + "properties": { + "street": { + "type": "string", + "maxLength": 255, + "description": "Street address" + }, + "city": { + "type": "string", + "maxLength": 100, + "description": "City" + }, + "state": { + "type": "string", + "maxLength": 100, + "description": "State or province" + }, + "postalCode": { + "type": "string", + "maxLength": 20, + "description": "Postal or ZIP code" + }, + "country": { + "type": "string", + "minLength": 2, + "maxLength": 2, + "description": "Country code (ISO 3166-1 alpha-2)" + } + }, + "description": "Customer's address" + } + }, + "description": "Optional customer information for merchant receipt tracking" + }, + "reference": { + "type": "string", + "minLength": 1, + "maxLength": 255, + "description": "Merchant reference for receipt tracking and identification" + }, + "originalRequestId": { + "type": "string", + "minLength": 1, + "description": "ID of the original request for recurring payments" + }, + "originalRequestPaymentReference": { + "type": "string", + "minLength": 1, + "description": "Payment reference of the original request for recurring payments" + } + }, + "required": [ + "amount", + "invoiceCurrency", + "paymentCurrency" + ] + }, + "examples": { + "regularRequest": { + "summary": "Regular payment request", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "ETH-sepolia-sepolia" + } + }, + "cryptoToFiatRequest": { + "summary": "Crypto-to-fiat payment request", + "value": { + "amount": "25.50", + "invoiceCurrency": "USD", + "paymentCurrency": "USDC-sepolia", + "isCryptoToFiatAvailable": true + } + }, + "requestWithCustomerInfo": { + "summary": "Request with customer information and reference", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "50.00", + "invoiceCurrency": "USD", + "paymentCurrency": "USDC-sepolia", + "customerInfo": { + "firstName": "John", + "lastName": "Doe", + "email": "john.doe@example.com", + "address": { + "street": "123 Main Street", + "city": "New York", + "state": "NY", + "postalCode": "10001", + "country": "US" + } + }, + "reference": "ORDER-2024-001234" + } + }, + "recurringInvoice": { + "summary": "Recurring invoice", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "ETH-sepolia-sepolia", + "recurrence": { + "startDate": "2030-01-01", + "frequency": "YEARLY" + } + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Request created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "paymentReference": { + "type": "string", + "description": "Unique identifier of the request, used to pay the request as well as check the status of the request", + "example": "0xb3581f0b0f74cc61" + }, + "requestId": { + "type": "string", + "description": "Unique identifier of the request, commonly used to look up a request in Request Scan", + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" + } + } + } + } + } + }, + "400": { + "description": "Validation failed" + }, + "404": { + "description": "Wallet not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Create a new request", + "tags": [ + "Request", + "V2/Request" + ] + } + }, + "/v2/request/{requestId}": { + "get": { + "description": "Get the status of a payment request", + "operationId": "RequestControllerV2_getRequestStatus_v2", + "parameters": [ + { + "name": "requestId", + "required": true, + "in": "path", + "description": "The requestId for the request", + "schema": { + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Request status retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "hasBeenPaid": { + "type": "boolean", + "description": "Whether the request has been paid" + }, + "paymentReference": { + "type": "string", + "description": "Unique identifier used for payments and status checks" + }, + "requestId": { + "type": "string", + "description": "Unique identifier of the request" + }, + "isListening": { + "type": "boolean", + "description": "Whether the system is actively listening for payments on this request" + }, + "txHash": { + "type": "string", + "nullable": true, + "description": "Transaction hash of the payment, null if not yet paid" + }, + "recurrence": { + "type": "object", + "description": "Recurrence configuration for recurring requests" + }, + "originalRequestId": { + "type": "string", + "description": "Original request ID for recurring requests" + }, + "status": { + "type": "string", + "description": "Current status of the request" + }, + "isCryptoToFiatAvailable": { + "type": "boolean", + "description": "Whether crypto-to-fiat conversion is available for this request" + }, + "originalRequestPaymentReference": { + "type": "string", + "description": "Payment reference of the original request for recurring payments" + }, + "payments": { + "type": "array", + "description": "Array of payments made to this request", + "items": { + "type": "object" + } + }, + "isRecurrenceStopped": { + "type": "boolean", + "description": "Whether recurrence has been stopped for this request" + }, + "customerInfo": { + "type": "object", + "nullable": true, + "description": "Customer information for merchant receipt tracking", + "properties": { + "firstName": { + "type": "string", + "description": "Customer's first name" + }, + "lastName": { + "type": "string", + "description": "Customer's last name" + }, + "email": { + "type": "string", + "description": "Customer's email address" + }, + "address": { + "type": "object", + "description": "Customer's address", + "properties": { + "street": { + "type": "string", + "description": "Street address" + }, + "city": { + "type": "string", + "description": "City" + }, + "state": { + "type": "string", + "description": "State or province" + }, + "postalCode": { + "type": "string", + "description": "Postal or ZIP code" + }, + "country": { + "type": "string", + "description": "Country code (ISO 3166-1 alpha-2)" + } + } + } + } + }, + "reference": { + "type": "string", + "nullable": true, + "description": "Merchant reference for receipt tracking and identification" + }, + "amountInUsd": { + "type": "string", + "nullable": true, + "description": "Request amount in USD (actual if paid, current market rate if unpaid)" + }, + "conversionRate": { + "type": "string", + "nullable": true, + "description": "Conversion rate. Available for: unpaid requests and fully paid requests with single payment. Null for: partially paid requests and fully paid requests with multiple payments." + }, + "rateSource": { + "type": "string", + "enum": [ + "lifi", + "chainlink", + "coingecko", + "unknown", + "mixed" + ], + "description": "Source of the conversion rate" + }, + "conversionBreakdown": { + "type": "object", + "nullable": true, + "description": "Detailed breakdown for partial payments or multiple payments. Provides individual payment rates when top-level rate is null.", + "properties": { + "paidAmount": { + "type": "string" + }, + "paidAmountInUsd": { + "type": "string" + }, + "remainingAmount": { + "type": "string" + }, + "remainingAmountInUsd": { + "type": "string" + }, + "currentMarketRate": { + "type": "string", + "nullable": true + }, + "currentMarketRateSource": { + "type": "string", + "enum": [ + "lifi", + "chainlink", + "coingecko", + "unknown" + ], + "nullable": true + }, + "payments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "type": "string" + }, + "amountInUsd": { + "type": "string" + }, + "conversionRate": { + "type": "string" + }, + "rateSource": { + "type": "string", + "enum": [ + "lifi", + "chainlink", + "coingecko", + "unknown" + ] + }, + "timestamp": { + "type": "string" + } + } + } + } + } + }, + "fees": { + "type": "array", + "nullable": true, + "description": "Associated fees (actual if paid, empty if unpaid)", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "gas", + "platform", + "crosschain", + "crypto-to-fiat", + "offramp" + ], + "description": "Type of fee" + }, + "provider": { + "type": "string", + "description": "Fee provider" + }, + "amount": { + "type": "string", + "description": "Fee amount in human-readable format (formatted with token decimals)" + }, + "currency": { + "type": "string", + "description": "Fee currency" + } + } + } + } + } + }, + "examples": { + "paid": { + "summary": "Request has been paid", + "value": { + "hasBeenPaid": true, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "isListening": false, + "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + } + }, + "notPaid": { + "summary": "Request has not been paid", + "value": { + "hasBeenPaid": false, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "isListening": false, + "txHash": null + } + }, + "withCustomerInfo": { + "summary": "Request with customer information and reference", + "value": { + "hasBeenPaid": false, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "isListening": true, + "txHash": null, + "customerInfo": { + "firstName": "John", + "lastName": "Doe", + "email": "john.doe@example.com", + "address": { + "street": "123 Main Street", + "city": "New York", + "state": "NY", + "postalCode": "10001", + "country": "US" + } + }, + "reference": "ORDER-2024-001234" + } + }, + "paidWithUsdInfo": { + "summary": "Fully paid request with single payment", + "value": { + "hasBeenPaid": true, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "amountInUsd": "100.00", + "conversionRate": "2487.52", + "rateSource": "coingecko", + "fees": [ + { + "type": "platform", + "provider": "request-network", + "amount": "2.00", + "currency": "USDC" + }, + { + "type": "gas", + "provider": "sepolia", + "amount": "0.002", + "currency": "ETH" + } + ] + } + }, + "partiallyPaidWithBreakdown": { + "summary": "Partially paid request (conversion rate is null)", + "value": { + "hasBeenPaid": false, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "amountInUsd": "100.12", + "conversionRate": null, + "rateSource": "mixed", + "conversionBreakdown": { + "paidAmount": "75.00", + "paidAmountInUsd": "75.00", + "remainingAmount": "25.00", + "remainingAmountInUsd": "25.12", + "currentMarketRate": "2501.23", + "currentMarketRateSource": "coingecko", + "payments": [ + { + "amount": "75.00", + "amountInUsd": "75.00", + "conversionRate": "2487.52", + "rateSource": "chainlink", + "timestamp": "2025-01-01T10:00:00Z" + } + ] + }, + "fees": [ + { + "type": "platform", + "provider": "request-network", + "amount": "1.50", + "currency": "USDC" + }, + { + "type": "gas", + "provider": "sepolia", + "amount": "0.0015", + "currency": "ETH" + } + ] + } + }, + "unpaidRequest": { + "summary": "Unpaid request with current market rates", + "value": { + "hasBeenPaid": false, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "amountInUsd": "100.25", + "conversionRate": "2501.23", + "rateSource": "coingecko", + "fees": [] + } + }, + "multiplePayments": { + "summary": "Fully paid request with multiple payments (conversion rate is null)", + "value": { + "hasBeenPaid": true, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "amountInUsd": "100.00", + "conversionRate": null, + "rateSource": "mixed", + "conversionBreakdown": { + "paidAmount": "100.00", + "paidAmountInUsd": "100.00", + "remainingAmount": "0", + "remainingAmountInUsd": "0", + "currentMarketRate": null, + "currentMarketRateSource": null, + "payments": [ + { + "amount": "50.00", + "amountInUsd": "50.00", + "conversionRate": "2500.00", + "rateSource": "coingecko", + "timestamp": "2025-01-01T10:00:00Z" + }, + { + "amount": "50.00", + "amountInUsd": "50.00", + "conversionRate": "2480.30", + "rateSource": "chainlink", + "timestamp": "2025-01-02T15:30:00Z" + } + ] + }, + "fees": [ + { + "type": "platform", + "provider": "request-network", + "amount": "2.00", + "currency": "USDC" + }, + { + "type": "gas", + "provider": "sepolia", + "amount": "0.002", + "currency": "ETH" + }, + { + "type": "crosschain", + "provider": "lifi", + "amount": "0.05", + "currency": "USDC" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Request not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get request status", + "tags": [ + "Request", + "V2/Request" + ] + }, + "patch": { + "description": "Update a recurring request", + "operationId": "RequestControllerV2_updateRequest_v2", + "parameters": [ + { + "name": "requestId", + "required": true, + "in": "path", + "description": "The requestId for the request", + "schema": { + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "isRecurrenceStopped": { + "type": "boolean", + "description": "Whether the recurrence is stopped" + } + }, + "required": [ + "isRecurrenceStopped" + ] + }, + "examples": { + "stopRecurrence": { + "summary": "Stop recurring invoice", + "value": { + "isRecurrenceStopped": true + } + }, + "resumeRecurrence": { + "summary": "Resume recurring invoice", + "value": { + "isRecurrenceStopped": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Recurrence updated successfully" + }, + "404": { + "description": "Request not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Update a recurring request", + "tags": [ + "Request", + "V2/Request" + ] + } + }, + "/v2/request/{requestId}/pay": { + "get": { + "description": "Get the calldata needed to pay a request. For same-chain payments, returns transaction calldata that can be directly executed. For crosschain payments (when chain and token parameters are provided and differ from the request's native chain), returns a payment intent that needs to be signed and processed through the crosschain bridge. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected.", + "operationId": "RequestControllerV2_getPaymentCalldata_v2", + "parameters": [ + { + "name": "requestId", + "required": true, + "in": "path", + "description": "The requestId of the request", + "schema": { + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "wallet", + "required": false, + "in": "query", + "description": "The wallet address of the payer.", + "schema": { + "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "type": "string" + } + }, + { + "name": "chain", + "required": false, + "in": "query", + "description": "The source chain of the crosschain payment", + "x-feature-flag": "crosschainDisabled", + "schema": { + "enum": [ + "BASE", + "OPTIMISM", + "ARBITRUM", + "ETHEREUM" + ], + "type": "string" + } + }, + { + "name": "token", + "required": false, + "in": "query", + "description": "The source token of the crosschain payment", + "x-feature-flag": "crosschainDisabled", + "schema": { + "enum": [ + "USDC", + "USDT" + ], + "type": "string" + } + }, + { + "name": "amount", + "required": false, + "in": "query", + "description": "The amount to pay, in human readable format", + "schema": { + "type": "string" + } + }, + { + "name": "clientUserId", + "required": false, + "in": "query", + "description": "Optional client user ID for off-ramp payments", + "schema": { + "example": "user-123", + "type": "string" + } + }, + { + "name": "paymentDetailsId", + "required": false, + "in": "query", + "description": "Optional payment details ID for off-ramp payments", + "schema": { + "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9", + "type": "string" + } + }, + { + "name": "feePercentage", + "required": false, + "in": "query", + "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)", + "schema": { + "example": "0.02", + "type": "string" + } + }, + { + "name": "feeAddress", + "required": false, + "in": "query", + "description": "Address to receive the fee", + "schema": { + "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Payment calldata retrieved successfully", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "type": "object", + "title": "Same-chain Payment Response", + "description": "Response for same-chain payments with transaction calldata", + "properties": { + "transactions": { + "type": "array", + "description": "Array of transactions to execute for the payment", + "items": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "Transaction calldata" + }, + "to": { + "type": "string", + "description": "Target contract address" + }, + "value": { + "type": "object", + "description": "Payment amount in EVM-compatible format", + "properties": { + "type": { + "type": "string", + "enum": [ + "BigNumber" + ] + }, + "hex": { + "type": "string", + "description": "Amount encoded in hex" + } + } + } + }, + "required": [ + "data", + "to", + "value" + ] + } + }, + "metadata": { + "type": "object", + "description": "Metadata about the payment requirements", + "properties": { + "stepsRequired": { + "type": "number", + "description": "Number of transactions required" + }, + "needsApproval": { + "type": "boolean", + "description": "Whether token approval is needed" + }, + "approvalTransactionIndex": { + "type": "number", + "nullable": true, + "description": "Index of the approval transaction if needed" + }, + "hasEnoughBalance": { + "type": "boolean", + "description": "Whether payer has sufficient balance" + }, + "hasEnoughGas": { + "type": "boolean", + "description": "Whether payer has sufficient gas" + } + }, + "required": [ + "stepsRequired", + "needsApproval", + "hasEnoughBalance", + "hasEnoughGas" + ] + } + }, + "required": [ + "transactions", + "metadata" + ] + }, + { + "type": "object", + "title": "Crosschain Payment Response", + "description": "Response for crosschain payments with payment intent to be signed", + "properties": { + "paymentIntentId": { + "type": "string", + "description": "Unique identifier for the payment intent" + }, + "paymentIntent": { + "type": "string", + "description": "EIP-712 typed data for payment intent signature" + }, + "approvalPermitPayload": { + "type": "string", + "nullable": true, + "description": "EIP-712 typed data for token approval permit (for EIP-2612 compliant tokens)" + }, + "approvalCalldata": { + "type": "object", + "nullable": true, + "description": "Transaction calldata for token approval (for non-EIP-2612 tokens)", + "properties": { + "to": { + "type": "string", + "description": "Token contract address" + }, + "data": { + "type": "string", + "description": "Approval transaction calldata" + }, + "value": { + "type": "string", + "description": "Transaction value (usually '0x0')" + } + } + }, + "metadata": { + "type": "object", + "description": "Metadata about the crosschain payment", + "properties": { + "supportsEIP2612": { + "type": "boolean", + "description": "Whether the token supports EIP-2612 permits" + } + }, + "required": [ + "supportsEIP2612" + ] + } + }, + "required": [ + "paymentIntentId", + "paymentIntent", + "metadata" + ] + } + ] + }, + "examples": { + "native": { + "summary": "Native currency payment", + "value": { + "transactions": [ + { + "data": "0xb868980b...00", + "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687", + "value": { + "type": "BigNumber", + "hex": "0x038d7ea4c68000" + } + } + ], + "metadata": { + "stepsRequired": 1, + "needsApproval": false, + "approvalTransactionIndex": null, + "hasEnoughBalance": true, + "hasEnoughGas": true + } + } + }, + "token": { + "summary": "ERC20 token payment", + "value": { + "transactions": [ + { + "data": "0x095ea7b3...ff", + "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324cf623C", + "value": 0 + }, + { + "data": "0xc219a14d...00", + "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE", + "value": 0 + } + ], + "metadata": { + "stepsRequired": 2, + "needsApproval": true, + "approvalTransactionIndex": 0, + "hasEnoughBalance": true, + "hasEnoughGas": true + } + } + }, + "currencyThatSupportsEIP2612": { + "summary": "Crosschain payment with a currency that supports EIP-2612", + "x-feature-flag": "crosschainDisabled", + "value": { + "paymentIntentId": "01JPHNEY8RRJTB94Q34GAW8BC3", + "paymentIntent": "{\n \"domain\": {\n \"name\": \"Permit2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\"\n },\n \"types\": {\n \"PermitBatchWitnessTransferFrom\": [\n {\n \"name\": \"permitted\",\n \"type\": \"TokenPermissions[]\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"witness\",\n \"type\": \"PaymentIntent\"\n }\n ],\n \"TokenPermissions\": [\n {\n \"name\": \"token\",\n \"type\": \"address\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n }\n ],\n \"PaymentIntent\": [\n {\n \"name\": \"payment_type\",\n \"type\": \"uint8\"\n },\n {\n \"name\": \"operator_data\",\n \"type\": \"OperatorData\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"source\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"destination\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"processing_date\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"expires_at\",\n \"type\": \"uint256\"\n }\n ],\n \"OperatorData\": [\n {\n \"name\": \"operatorId\",\n \"type\": \"bytes32\"\n },\n {\n \"name\": \"operator\",\n \"type\": \"address\"\n },\n {\n \"name\": \"treasury_account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"fee\",\n \"type\": \"uint256\"\n }\n ],\n \"Domain\": [\n {\n \"name\": \"account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"network_id\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"payment_token\",\n \"type\": \"address\"\n }\n ]\n },\n \"values\": {\n \"permitted\": [\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"1998000\"\n },\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"0\"\n },\n {\n \"token\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\",\n \"amount\": \"2000\"\n }\n ],\n \"spender\": \"0x4B1d5b0aF5AbAe333C8d2CCa2a346e0D5f68C427\",\n \"nonce\": \"1742202173708\",\n \"deadline\": \"1742205771\",\n \"witness\": {\n \"payment_type\": 0,\n \"operator_data\": {\n \"operatorId\": \"0x6ab1463ead4ba60b8e08155b29ea2b3c91731e78be09b6e12b6c25414d724dd0\",\n \"operator\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"treasury_account\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"fee\": \"0\"\n },\n \"amount\": \"2000000\",\n \"source\": {\n \"account\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"network_id\": \"42161\",\n \"payment_token\": \"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\"\n },\n \"destination\": {\n \"account\": \"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7\",\n \"network_id\": \"8453\",\n \"payment_token\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n },\n \"processing_date\": \"1742220173\",\n \"expires_at\": \"1742205771\"\n }\n }\n}", + "approvalPermitPayload": "{\n \"domain\": {\n \"name\": \"USD Coin\",\n \"version\": \"2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0xaf88d065e77c8cc2239327c5edb3a432268e5831\"\n },\n \"types\": {\n \"Permit\": [\n {\n \"name\": \"owner\",\n \"type\": \"address\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"value\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n }\n ]\n },\n \"values\": {\n \"owner\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"spender\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\",\n \"value\": \"115792089237316195423570985008687907853269984665640564039457584007913129639935\",\n \"nonce\": \"1\",\n \"deadline\": 1742205771\n }\n}", + "metadata": { + "supportsEIP2612": true + } + } + }, + "currencyThatDoesNotSupportEIP2612": { + "summary": "Crosschain payment with a currency that does not support EIP-2612", + "x-feature-flag": "crosschainDisabled", + "value": { + "paymentIntentId": "01JPHNFMRC2JFG4W08FGDG4KD3", + "paymentIntent": "{\n \"domain\": {\n \"name\": \"Permit2\",\n \"chainId\": 42161,\n \"verifyingContract\": \"0x000000000022D473030F116dDEE9F6B43aC78BA3\"\n },\n \"types\": {\n \"PermitBatchWitnessTransferFrom\": [\n {\n \"name\": \"permitted\",\n \"type\": \"TokenPermissions[]\"\n },\n {\n \"name\": \"spender\",\n \"type\": \"address\"\n },\n {\n \"name\": \"nonce\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"deadline\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"witness\",\n \"type\": \"PaymentIntent\"\n }\n ],\n \"TokenPermissions\": [\n {\n \"name\": \"token\",\n \"type\": \"address\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n }\n ],\n \"PaymentIntent\": [\n {\n \"name\": \"payment_type\",\n \"type\": \"uint8\"\n },\n {\n \"name\": \"operator_data\",\n \"type\": \"OperatorData\"\n },\n {\n \"name\": \"amount\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"source\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"destination\",\n \"type\": \"Domain\"\n },\n {\n \"name\": \"processing_date\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"expires_at\",\n \"type\": \"uint256\"\n }\n ],\n \"OperatorData\": [\n {\n \"name\": \"operatorId\",\n \"type\": \"bytes32\"\n },\n {\n \"name\": \"operator\",\n \"type\": \"address\"\n },\n {\n \"name\": \"treasury_account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"fee\",\n \"type\": \"uint256\"\n }\n ],\n \"Domain\": [\n {\n \"name\": \"account\",\n \"type\": \"address\"\n },\n {\n \"name\": \"network_id\",\n \"type\": \"uint256\"\n },\n {\n \"name\": \"payment_token\",\n \"type\": \"address\"\n }\n ]\n },\n \"values\": {\n \"permitted\": [\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"1998000\"\n },\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"0\"\n },\n {\n \"token\": \"0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9\",\n \"amount\": \"2000\"\n }\n ],\n \"spender\": \"0x4B1d5b0aF5AbAe333C8d2CCa2a346e0D5f68C427\",\n \"nonce\": \"1742202196746\",\n \"deadline\": \"1742205796\",\n \"witness\": {\n \"payment_type\": 0,\n \"operator_data\": {\n \"operatorId\": \"0x6ab1463ead4ba60b8e08155b29ea2b3c91731e78be09b6e12b6c25414d724dd0\",\n \"operator\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"treasury_account\": \"0xd36B6f4040B8449e93eb2B348EdCD2a968AEA9D9\",\n \"fee\": \"0\"\n },\n \"amount\": \"2000000\",\n \"source\": {\n \"account\": \"0xb07D2398d2004378cad234DA0EF14f1c94A530e4\",\n \"network_id\": \"42161\",\n \"payment_token\": \"0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9\"\n },\n \"destination\": {\n \"account\": \"0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7\",\n \"network_id\": \"8453\",\n \"payment_token\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n },\n \"processing_date\": \"1742220196\",\n \"expires_at\": \"1742205796\"\n }\n }\n}", + "approvalCalldata": { + "to": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", + "data": "0x095ea7b3000000000000000000000000000000000022d473030f116ddee9f6b43ac78ba3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", + "value": "0x0" + }, + "metadata": { + "supportsEIP2612": false + } + } + } + } + } + } + }, + "400": { + "description": "Validation failed", + "content": { + "application/json": { + "examples": { + "queryParamsValidation": { + "summary": "Query Validation Failed", + "value": { + "message": "Validation failed", + "errors": [ + { + "field": "wallet", + "message": "Invalid Ethereum address" + }, + { + "field": "chain", + "message": "Invalid enum value. Expected 'POLYGON' | 'BASE' | 'OPTIMISM' | 'ETHEREUM' | 'ARBITRUM', received {input}" + }, + { + "field": "token", + "message": "Invalid enum value. Expected 'USDC' | 'USDT', received {input}" + } + ] + } + }, + "tokenNotSupportedCrosschain": { + "summary": "Token not supported for crosschain payment", + "value": { + "message": "FAU is not supported in crosschain payment.", + "error": "Bad Request", + "statusCode": 400 + } + } + } + } + } + }, + "404": { + "description": "Request not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get payment calldata", + "tags": [ + "Request", + "V2/Request" + ] + } + }, + "/v2/request/{requestId}/routes": { + "get": { + "description": "Get available payment routes for a request. This endpoint analyzes the payer's wallet balance across supported chains and returns possible payment methods. Routes include direct same-chain payments and crosschain bridging options when the payer has sufficient balance on different chains than the request's native chain.", + "operationId": "RequestControllerV2_getRequestPaymentRoutes_v2", + "parameters": [ + { + "name": "requestId", + "required": true, + "in": "path", + "description": "The requestId of the request", + "schema": { + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "wallet", + "required": true, + "in": "query", + "description": "The wallet address of the payer", + "schema": { + "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "type": "string" + } + }, + { + "name": "amount", + "required": false, + "in": "query", + "description": "The amount to pay, in human readable format", + "schema": { + "type": "string" + } + }, + { + "name": "feePercentage", + "required": false, + "in": "query", + "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)", + "schema": { + "type": "string" + } + }, + { + "name": "feeAddress", + "required": false, + "in": "query", + "description": "Address to receive the fee", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Available payment routes", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Available payment routes for the request", + "properties": { + "routes": { + "type": "array", + "description": "Array of available payment routes", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the route" + }, + "fee": { + "type": "number", + "description": "Total fee for this route (as a decimal, e.g., 0.001 = 0.1%)" + }, + "feeBreakdown": { + "type": "array", + "description": "Detailed breakdown of all fees for this route", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "gas", + "platform", + "crosschain", + "crypto-to-fiat", + "offramp" + ], + "description": "Type of fee" + }, + "stage": { + "type": "string", + "enum": [ + "sending", + "receiving", + "proxying", + "refunding", + "overall" + ], + "description": "Stage when the fee is applied" + }, + "provider": { + "type": "string", + "description": "Provider that charged the fee" + }, + "amount": { + "type": "string", + "description": "Fee amount in human-readable format (formatted with token decimals)" + }, + "amountInUSD": { + "type": "string", + "description": "Fee amount in USD" + }, + "currency": { + "type": "string", + "description": "Fee currency" + }, + "receiverAddress": { + "type": "string", + "description": "Address that received the fee" + }, + "network": { + "type": "string", + "description": "Network where the fee was paid" + }, + "rateProvider": { + "type": "string", + "description": "Provider used for rate conversion" + } + } + } + }, + "speed": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ], + "description": "Route speed - 'FAST' for direct payments, number of seconds for crosschain" + }, + "price_impact": { + "type": "number", + "description": "Price impact of the route (as a decimal)" + }, + "chain": { + "type": "string", + "description": "Source chain for the payment" + }, + "token": { + "type": "string", + "description": "Token symbol for the payment" + } + }, + "required": [ + "id", + "fee", + "speed", + "chain", + "token" + ] + } + } + }, + "required": [ + "routes" + ] + }, + "examples": { + "requestNetworkRoute": { + "summary": "Only request network route", + "value": { + "routes": [ + { + "id": "REQUEST_NETWORK_PAYMENT", + "fee": 0, + "speed": "FAST", + "price_impact": 0, + "chain": "MAINNET", + "token": "REQ" + } + ] + } + }, + "sameChainRoute": { + "summary": "Same-chain payment possible", + "value": { + "routes": [ + { + "id": "REQUEST_NETWORK_PAYMENT", + "fee": 0, + "speed": "FAST", + "price_impact": 0, + "chain": "BASE", + "token": "USDC" + }, + { + "id": "BASE-BASE-USDC-USDC", + "fee": 0.001, + "speed": "FAST", + "price_impact": 0, + "chain": "BASE", + "token": "USDC" + } + ] + } + }, + "crosschainRoute": { + "summary": "Crosschain possible", + "value": { + "routes": [ + { + "id": "REQUEST_NETWORK_PAYMENT", + "fee": 0, + "speed": "FAST", + "price_impact": 0, + "chain": "BASE", + "token": "USDC" + }, + { + "id": "POLYGON_BASE_USDC_USDC", + "fee": 0.001, + "speed": "FAST", + "price_impact": 0.999, + "chain": "POLYGON", + "token": "USDC" + } + ] + } + }, + "noRoutes": { + "summary": "No routes available", + "value": { + "routes": [] + } + } + } + } + } + }, + "400": { + "description": "Invalid or missing wallet address" + }, + "404": { + "description": "Request not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get payment routes", + "tags": [ + "Request", + "V2/Request" + ], + "x-feature-flag": "crosschainDisabled" + } + }, + "/v2/request/payment-intents/{paymentIntentId}": { + "post": { + "description": "Send a payment intent", + "operationId": "RequestControllerV2_sendPaymentIntent_v2", + "parameters": [ + { + "name": "paymentIntentId", + "required": true, + "in": "path", + "description": "The payment intent ID", + "schema": { + "example": "01JNZYZPK7B4YBPD44TM72NDNJ", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "signedPaymentIntent": { + "type": "object", + "properties": { + "signature": { + "type": "string", + "description": "The signature of the permit2 approval for token transfer" + }, + "nonce": { + "type": "string", + "description": "The unique nonce for this permit2 transaction" + }, + "deadline": { + "type": "string", + "description": "The Unix timestamp when this permit2 approval expires" + } + }, + "required": [ + "signature", + "nonce", + "deadline" + ], + "description": "The signed payment intent data." + }, + "signedApprovalPermit": { + "type": "object", + "properties": { + "signature": { + "type": "string", + "description": "The signature for the EIP2612 gasless token approval" + }, + "nonce": { + "type": "string", + "description": "The unique nonce for the EIP2612 permit" + }, + "deadline": { + "type": "string", + "description": "The Unix timestamp when this EIP2612 permit expires" + } + }, + "required": [ + "signature", + "nonce", + "deadline" + ], + "description": "The EIP2612 gasless token approval data that allows Permit2 to access user tokens" + } + }, + "required": [ + "signedPaymentIntent" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Payment intent sent successfully" + }, + "404": { + "description": "Payment intent data not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Send a payment intent", + "tags": [ + "Request", + "V2/Request" + ], + "x-feature-flag": "crosschainDisabled" + } + }, + "/v2/payer": { + "post": { + "description": "Checks compliance status and returns necessary URLs for completing compliance.", + "operationId": "PayerV2Controller_getComplianceData_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "clientUserId": { + "type": "string", + "minLength": 1, + "description": "Client User ID" + }, + "email": { + "type": "string", + "format": "email", + "description": "Email" + }, + "firstName": { + "type": "string", + "minLength": 1, + "description": "First Name" + }, + "lastName": { + "type": "string", + "minLength": 1, + "description": "Last Name" + }, + "beneficiaryType": { + "type": "string", + "enum": [ + "individual", + "business" + ] + }, + "companyName": { + "type": "string", + "description": "Company Name" + }, + "dateOfBirth": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "Date of birth in YYYY-MM-DD format" + }, + "addressLine1": { + "type": "string", + "minLength": 1, + "description": "Address Line 1" + }, + "addressLine2": { + "type": "string", + "description": "Address Line 2" + }, + "city": { + "type": "string", + "minLength": 1, + "description": "City" + }, + "state": { + "type": "string", + "minLength": 1, + "description": "State" + }, + "postcode": { + "type": "string", + "minLength": 1, + "description": "Postcode" + }, + "country": { + "type": "string", + "minLength": 2, + "maxLength": 2, + "description": "Country" + }, + "nationality": { + "type": "string", + "minLength": 2, + "maxLength": 2, + "description": "Nationality" + }, + "phone": { + "type": "string", + "pattern": "^\\+?[1-9]\\d{1,14}$", + "description": "Phone in E.164 format" + }, + "ssn": { + "type": "string", + "minLength": 1, + "description": "Social Security Number" + }, + "sourceOfFunds": { + "type": "string", + "description": "Source of Funds" + }, + "businessActivity": { + "type": "string", + "description": "Business Activity" + } + }, + "required": [ + "clientUserId", + "email", + "firstName", + "lastName", + "beneficiaryType", + "dateOfBirth", + "addressLine1", + "city", + "state", + "postcode", + "country", + "nationality", + "phone", + "ssn" + ] + }, + "examples": { + "individualBeneficiary": { + "summary": "Individual beneficiary compliance data", + "value": { + "clientUserId": "user-123", + "email": "john.doe@example.com", + "firstName": "John", + "lastName": "Doe", + "beneficiaryType": "individual", + "dateOfBirth": "1985-12-12", + "addressLine1": "123 Main Street", + "city": "New York", + "state": "NY", + "postcode": "10001", + "country": "US", + "nationality": "US", + "phone": "+12125551234", + "ssn": "123-45-6789" + } + }, + "businessBeneficiary": { + "summary": "Business beneficiary compliance data", + "value": { + "clientUserId": "business-456", + "email": "cfo@company.com", + "firstName": "Jane", + "lastName": "Smith", + "beneficiaryType": "business", + "companyName": "Acme Corporation Inc.", + "dateOfBirth": "1980-05-15", + "addressLine1": "456 Business Ave", + "addressLine2": "Suite 200", + "city": "San Francisco", + "state": "CA", + "postcode": "94102", + "country": "US", + "nationality": "US", + "phone": "+14155552000", + "ssn": "987-65-4321", + "sourceOfFunds": "Business revenue from software services", + "businessActivity": "Software development and consulting" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Compliance data retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "agreementUrl": { + "type": "string", + "format": "uri" + }, + "kycUrl": { + "type": "string", + "format": "uri" + }, + "status": { + "type": "object", + "properties": { + "agreementStatus": { + "type": "string", + "enum": [ + "not_started", + "completed" + ] + }, + "kycStatus": { + "type": "string", + "enum": [ + "not_started", + "completed" + ] + } + }, + "required": [ + "agreementStatus", + "kycStatus" + ] + }, + "userId": { + "type": "string", + "format": "uuid" + } + }, + "required": [ + "status" + ] + }, + "examples": { + "success": { + "summary": "Successful response", + "value": { + "agreementUrl": "https://core-api.pay.so/v1/public/agreements?email=john.doe%40example.com", + "kycUrl": "https://sumsub.com/idensic/l/#/sbx_VvK9E9P2A23xQPoA", + "status": { + "agreementStatus": "not_started", + "kycStatus": "not_started" + } + } + } + } + } + } + }, + "400": { + "description": "Invalid request data", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 400 + }, + "message": { + "type": "string", + "example": "Compliance is only required for off-ramp requests" + }, + "error": { + "type": "string", + "example": "Bad Request" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Request not found", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 404 + }, + "message": { + "type": "string", + "example": "Request with payment reference pay-ref-123 not found" + }, + "error": { + "type": "string", + "example": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Create compliance data for a user", + "tags": [ + "Payer", + "V2/Payer" + ] + } + }, + "/v2/payer/{clientUserId}": { + "patch": { + "description": "Update the agreement completion status for a user.", + "operationId": "PayerV2Controller_updateComplianceStatus_v2", + "parameters": [ + { + "name": "clientUserId", + "required": true, + "in": "path", + "description": "The client user ID to update", + "schema": { + "example": "user-123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "agreementCompleted": { + "type": "boolean" + } + }, + "required": [ + "agreementCompleted" + ], + "example": { + "agreementCompleted": true + } + } + } + } + }, + "responses": { + "200": { + "description": "Compliance status updated successfully", + "content": { + "application/json": { + "schema": { + "properties": { + "success": { + "type": "boolean", + "example": true + } + } + } + } + } + }, + "400": { + "description": "Invalid request data", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 400 + }, + "message": { + "type": "string", + "example": "agreementCompleted must be provided" + }, + "error": { + "type": "string", + "example": "Bad Request" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 404 + }, + "message": { + "type": "string", + "example": "Payer with client user ID user-123 not found" + }, + "error": { + "type": "string", + "example": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Update agreement status", + "tags": [ + "Payer", + "V2/Payer" + ] + }, + "get": { + "description": "Retrieves the comprehensive compliance status for a specific user, including KYC and agreement status.", + "operationId": "PayerV2Controller_getComplianceStatus_v2", + "parameters": [ + { + "name": "clientUserId", + "required": true, + "in": "path", + "description": "The client user ID to check compliance status for", + "schema": { + "example": "user-123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Compliance status retrieved successfully", + "content": { + "application/json": { + "schema": { + "properties": { + "kycStatus": { + "type": "string", + "example": "completed" + }, + "agreementStatus": { + "type": "string", + "example": "completed" + }, + "isCompliant": { + "type": "boolean", + "example": true + }, + "userId": { + "type": "string", + "example": "a25a4274-8f50-4579-b476-8f35b297d4ad" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 404 + }, + "message": { + "type": "string", + "example": "Payer with client user ID user-123 not found" + }, + "error": { + "type": "string", + "example": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get compliance status for a user", + "tags": [ + "Payer", + "V2/Payer" + ] + } + }, + "/v2/payer/{clientUserId}/payment-details": { + "post": { + "description": "Create payment details for a user", + "operationId": "PayerV2Controller_createPaymentDetails_v2", + "parameters": [ + { + "name": "clientUserId", + "required": true, + "in": "path", + "description": "The client user ID", + "schema": { + "example": "user-123", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "bankName": { + "type": "string", + "minLength": 1, + "description": "Name of the bank" + }, + "accountName": { + "type": "string", + "minLength": 1, + "description": "Name of the account holder" + }, + "accountNumber": { + "type": "string", + "description": "Bank account number" + }, + "routingNumber": { + "type": "string", + "description": "Bank routing number (US)" + }, + "beneficiaryType": { + "type": "string", + "enum": [ + "individual", + "business" + ], + "description": "Type of beneficiary" + }, + "currency": { + "type": "string", + "minLength": 3, + "maxLength": 3, + "description": "Three-letter currency code (ISO 4217)" + }, + "addressLine1": { + "type": "string", + "minLength": 1, + "description": "Primary address line" + }, + "addressLine2": { + "type": "string", + "description": "Secondary address line" + }, + "city": { + "type": "string", + "minLength": 1, + "description": "City name" + }, + "state": { + "type": "string", + "description": "State or province code" + }, + "country": { + "type": "string", + "minLength": 2, + "maxLength": 2, + "description": "Two-letter country code (ISO 3166-1 alpha-2)" + }, + "dateOfBirth": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "Date of birth in YYYY-MM-DD format" + }, + "postalCode": { + "type": "string", + "minLength": 1, + "description": "Postal or ZIP code" + }, + "rails": { + "type": "string", + "enum": [ + "local", + "swift", + "wire" + ], + "default": "local", + "description": "Payment rail type" + }, + "sortCode": { + "type": "string", + "description": "UK bank sort code" + }, + "iban": { + "type": "string", + "description": "International Bank Account Number" + }, + "swiftBic": { + "type": "string", + "description": "SWIFT/BIC code" + }, + "documentNumber": { + "type": "string", + "description": "Government-issued ID number" + }, + "documentType": { + "type": "string", + "description": "Type of government-issued ID (e.g., passport, driver's license)" + }, + "accountType": { + "type": "string", + "enum": [ + "checking", + "savings" + ], + "description": "Type of bank account" + }, + "ribNumber": { + "type": "string", + "description": "French RIB number" + }, + "bsbNumber": { + "type": "string", + "description": "Australian BSB number" + }, + "ncc": { + "type": "string", + "description": "New Zealand NCC number" + }, + "branchCode": { + "type": "string", + "description": "Bank branch code" + }, + "bankCode": { + "type": "string", + "description": "Bank code" + }, + "ifsc": { + "type": "string", + "description": "Indian Financial System Code" + } + }, + "required": [ + "bankName", + "accountName", + "beneficiaryType", + "currency", + "addressLine1", + "city", + "country", + "dateOfBirth", + "postalCode" + ] + }, + "examples": { + "localUSBusiness": { + "summary": "US business account with local rails", + "value": { + "bankName": "Chase", + "accountName": "Acme Corp Business Account", + "accountNumber": "253009233489", + "routingNumber": "026013356", + "beneficiaryType": "business", + "currency": "usd", + "addressLine1": "24 Theatre St.", + "city": "Paramount", + "state": "CA", + "postalCode": "90723", + "country": "US", + "dateOfBirth": "1985-12-12", + "rails": "local", + "accountType": "checking" + } + }, + "swiftInternational": { + "summary": "International account with SWIFT rails", + "value": { + "bankName": "Deutsche Bank", + "accountName": "John Doe", + "beneficiaryType": "individual", + "currency": "eur", + "addressLine1": "Unter den Linden 1", + "city": "Berlin", + "postalCode": "10117", + "country": "DE", + "dateOfBirth": "1990-03-22", + "rails": "swift", + "iban": "DE89370400440532013000", + "swiftBic": "DEUTDEFF" + } + }, + "ukAccount": { + "summary": "UK account with sort code", + "value": { + "bankName": "Barclays", + "accountName": "Jane Smith", + "accountNumber": "12345678", + "beneficiaryType": "individual", + "currency": "gbp", + "addressLine1": "123 High Street", + "city": "London", + "postalCode": "SW1A 1AA", + "country": "GB", + "dateOfBirth": "1988-07-10", + "rails": "local", + "sortCode": "200000" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Payment details created successfully", + "content": { + "application/json": { + "schema": { + "properties": { + "payment_detail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "pd_123456" + }, + "clientUserId": { + "type": "string", + "example": "user-123" + }, + "bankName": { + "type": "string", + "example": "Chase" + }, + "accountName": { + "type": "string", + "example": "Gordon's Chase Business Account" + }, + "currency": { + "type": "string", + "example": "usd" + }, + "beneficiaryType": { + "type": "string", + "enum": [ + "individual", + "business" + ], + "example": "business" + } + } + } + } + } + } + } + }, + "400": { + "description": "Invalid request data", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 400 + }, + "message": { + "type": "string", + "example": "Invalid bank account details" + }, + "error": { + "type": "string", + "example": "Bad Request" + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 404 + }, + "message": { + "type": "string", + "example": "User with ID user-123 not found" + }, + "error": { + "type": "string", + "example": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Create payment details", + "tags": [ + "Payer", + "V2/Payer" + ] + }, + "get": { + "description": "Retrieves the registered bank account details for a user. Optionally filter by payment details ID.", + "operationId": "PayerV2Controller_getPaymentDetails_v2", + "parameters": [ + { + "name": "clientUserId", + "required": true, + "in": "path", + "description": "The client user ID to get payment details for", + "schema": { + "example": "user-123", + "type": "string" + } + }, + { + "name": "paymentDetailsId", + "required": false, + "in": "query", + "description": "Optional ID of specific payment details to retrieve", + "schema": { + "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Payment details retrieved successfully", + "content": { + "application/json": { + "schema": { + "properties": { + "paymentDetails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "fa898aec-519c-46be-9b4c-e76ef4ff99d9" + }, + "userId": { + "type": "string", + "example": "a25a4274-8f50-4579-b476-8f35b297d4ad" + }, + "bankName": { + "type": "string", + "example": "Chase" + }, + "accountName": { + "type": "string", + "example": "Gordon's Chase Business Account" + }, + "beneficiaryType": { + "type": "string", + "example": "business" + }, + "accountNumber": { + "type": "string", + "example": "253009233489" + }, + "routingNumber": { + "type": "string", + "example": "026013356" + }, + "currency": { + "type": "string", + "example": "usd" + }, + "status": { + "type": "string", + "example": "approved" + }, + "rails": { + "type": "string", + "example": "local" + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "User or payment details not found", + "content": { + "application/json": { + "schema": { + "properties": { + "statusCode": { + "type": "number", + "example": 404 + }, + "message": { + "type": "string", + "example": "Payer with client user ID user-123 not found" + }, + "error": { + "type": "string", + "example": "Not Found" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get payment details for a user", + "tags": [ + "Payer", + "V2/Payer" + ] + } + }, + "/v2/payments": { + "get": { + "description": "Search for payments by transaction hash, wallet address, payment reference, request ID, or merchant reference. Supports filtering by payment type, currencies, date ranges, and pagination. Returns complete payment details including customer information and fees. When searching by transaction hash or wallet address, returns ALL payments from batch transactions. Most search parameters are optional, but at least one must be provided and they default to an AND relationship.", + "operationId": "PaymentV2Controller_searchPayments_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "txHash", + "required": false, + "in": "query", + "description": "Search by blockchain transaction hash (source or destination). Returns ALL payments from the same transaction, including batch payments. Must be a valid 66-character hex string starting with '0x'. Example: '0x1234567890abcdef...'", + "schema": { + "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "type": "string" + } + }, + { + "name": "walletAddress", + "required": false, + "in": "query", + "description": "Search by wallet address (payer or payee). Supports Ethereum (0x...) and TRON (T...) addresses. Returns ALL payments involving this address, including batch payments where the address is either sender or recipient.", + "schema": { + "example": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "type": "string" + } + }, + { + "name": "paymentReference", + "required": false, + "in": "query", + "description": "Search by unique payment reference generated by the Request Network. This is the hex identifier used for on-chain payments. Example: '0xb3581f0b0f74cc61'", + "schema": { + "example": "0xb3581f0b0f74cc61", + "type": "string" + } + }, + { + "name": "requestId", + "required": false, + "in": "query", + "description": "Search by Request Network request ID. This is the unique identifier for the payment request. Example: '01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb'", + "schema": { + "example": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "type": "string" + } + }, + { + "name": "reference", + "required": false, + "in": "query", + "description": "Search by your custom merchant reference used for receipt tracking and order identification. This is the reference you provided when creating the payment. Example: 'ORDER-2024-001234' or 'INV-5678'", + "schema": { + "example": "ORDER-2024-001234", + "type": "string" + } + }, + { + "name": "type", + "required": false, + "in": "query", + "description": "Filter by payment type: 'direct' (same currency), 'conversion' (currency conversion), 'crosschain' (cross-chain payment), 'recurring' (subscription payment)", + "schema": { + "enum": [ + "direct", + "conversion", + "crosschain", + "recurring" + ], + "type": "string" + } + }, + { + "name": "invoiceCurrency", + "required": false, + "in": "query", + "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD", + "schema": { + "example": "USD", + "type": "string" + } + }, + { + "name": "paymentCurrency", + "required": false, + "in": "query", + "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia", + "schema": { + "example": "USDC", + "type": "string" + } + }, + { + "name": "fromDate", + "required": false, + "in": "query", + "description": "Filter payments from this date (inclusive). Must be in ISO 8601 format in UTC (ending with 'Z'). Example: '2024-01-01T00:00:00.000Z'", + "schema": { + "example": "2024-01-01T00:00:00.000Z", + "type": "string" + } + }, + { + "name": "toDate", + "required": false, + "in": "query", + "description": "Filter payments until this date (inclusive). Must be in ISO 8601 format in UTC (ending with 'Z'). Must be after fromDate if both are provided. Example: '2024-01-31T23:59:59.999Z'", + "schema": { + "example": "2024-01-31T23:59:59.999Z", + "type": "string" + } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "", + "schema": { + "example": "20", + "type": "string" + } + }, + { + "name": "offset", + "required": false, + "in": "query", + "description": "", + "schema": { + "example": "0", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Payment search results with comprehensive payment data and pagination metadata", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the payment" + }, + "amount": { + "type": "string", + "description": "Payment amount as a human-readable decimal string (formatUnits)" + }, + "sourceNetwork": { + "type": "string", + "description": "Network where the payment originated" + }, + "destinationNetwork": { + "type": "string", + "description": "Network where the payment was received" + }, + "sourceTxHash": { + "type": "string", + "nullable": true, + "description": "Transaction hash on the source network" + }, + "destinationTxHash": { + "type": "string", + "nullable": true, + "description": "Transaction hash on the destination network" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the payment was processed" + }, + "type": { + "type": "string", + "enum": [ + "direct", + "conversion", + "crosschain", + "recurring" + ], + "description": "Type of payment" + }, + "conversionRateSource": { + "type": "string", + "nullable": true, + "description": "Conversion rate used for source currency" + }, + "conversionRateDestination": { + "type": "string", + "nullable": true, + "description": "Conversion rate used for destination currency" + }, + "convertedAmountSource": { + "type": "string", + "nullable": true, + "description": "Converted amount in source currency" + }, + "convertedAmountDestination": { + "type": "string", + "nullable": true, + "description": "Converted amount in destination currency" + }, + "currency": { + "type": "string", + "description": "Invoice currency symbol" + }, + "paymentCurrency": { + "type": "string", + "description": "Payment currency symbol" + }, + "fees": { + "type": "array", + "nullable": true, + "description": "Array of fees associated with the payment", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "gas", + "platform", + "crosschain", + "crypto-to-fiat", + "offramp" + ], + "description": "Type of fee" + }, + "stage": { + "type": "string", + "enum": [ + "sending", + "receiving", + "proxying", + "refunding" + ], + "description": "Stage when the fee is applied" + }, + "provider": { + "type": "string", + "description": "Provider that charged the fee" + }, + "amount": { + "type": "string", + "description": "Fee amount in human-readable format (formatted with token decimals)" + }, + "amountInUSD": { + "type": "string", + "description": "Fee amount in USD" + }, + "currency": { + "type": "string", + "description": "Fee currency" + }, + "receiverAddress": { + "type": "string", + "description": "Address that received the fee" + }, + "network": { + "type": "string", + "description": "Network where the fee was paid" + }, + "rateProvider": { + "type": "string", + "description": "Provider used for rate conversion" + } + } + } + }, + "recurringPaymentId": { + "type": "string", + "nullable": true, + "description": "ID of the recurring payment this payment belongs to" + }, + "rateProvider": { + "type": "string", + "enum": [ + "lifi", + "chainlink", + "coingecko", + "unknown" + ], + "nullable": true, + "description": "Provider used for exchange rate data" + }, + "request": { + "type": "object", + "description": "Associated request information", + "properties": { + "requestId": { + "type": "string", + "description": "Request ID" + }, + "paymentReference": { + "type": "string", + "description": "Payment reference" + }, + "hasBeenPaid": { + "type": "boolean", + "description": "Whether the request has been fully paid" + }, + "customerInfo": { + "type": "object", + "nullable": true, + "description": "Customer information", + "properties": { + "firstName": { + "type": "string" + }, + "lastName": { + "type": "string" + }, + "email": { + "type": "string" + }, + "address": { + "type": "object", + "properties": { + "street": { + "type": "string" + }, + "city": { + "type": "string" + }, + "state": { + "type": "string" + }, + "postalCode": { + "type": "string" + }, + "country": { + "type": "string" + } + } + } + } + }, + "reference": { + "type": "string", + "nullable": true, + "description": "Merchant reference" + } + } + } + }, + "required": [ + "id", + "amount", + "sourceNetwork", + "destinationNetwork", + "timestamp", + "type", + "currency", + "paymentCurrency" + ] + }, + "description": "Array of matching payments with complete payment details" + }, + "pagination": { + "type": "object", + "description": "Pagination information for navigating through results", + "properties": { + "total": { + "type": "number", + "description": "Total number of payments matching the search criteria", + "example": 157 + }, + "limit": { + "type": "number", + "description": "Maximum number of results returned in this response", + "example": 20 + }, + "offset": { + "type": "number", + "description": "Number of results skipped (for pagination)", + "example": 0 + }, + "hasMore": { + "type": "boolean", + "description": "Whether there are more results available beyond this page", + "example": true + } + }, + "required": [ + "total", + "limit", + "offset", + "hasMore" + ] + } + }, + "required": [ + "payments", + "pagination" + ] + }, + "examples": { + "searchByTxHash": { + "summary": "Search by transaction hash", + "value": { + "payments": [ + { + "id": "01HXAMPLE1234567890ABCDEF", + "amount": "1000000000000000000", + "sourceNetwork": "sepolia", + "destinationNetwork": "sepolia", + "sourceTxHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "destinationTxHash": null, + "timestamp": "2024-01-15T10:30:00.000Z", + "type": "conversion", + "conversionRateSource": null, + "conversionRateDestination": null, + "convertedAmountSource": null, + "convertedAmountDestination": null, + "currency": "USD", + "paymentCurrency": "ETH", + "fees": [ + { + "type": "gas", + "amount": "21000000000000000", + "currency": "ETH", + "provider": "request-network" + } + ], + "recurringPaymentId": null, + "rateProvider": "chainlink", + "request": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "hasBeenPaid": true, + "customerInfo": { + "firstName": "John", + "lastName": "Doe", + "email": "john.doe@example.com" + }, + "reference": "ORDER-2024-001234" + } + } + ], + "pagination": { + "total": 1, + "limit": 20, + "offset": 0, + "hasMore": false + } + } + }, + "searchByWalletAndDateRange": { + "summary": "Search by wallet address with date filtering", + "value": { + "payments": [ + { + "id": "01HXAMPLE1111222233334444", + "amount": "50000000", + "sourceNetwork": "base", + "destinationNetwork": "base", + "sourceTxHash": "0x1111222233334444555566667777888899990000aaaabbbbccccddddeeeeffff", + "destinationTxHash": null, + "timestamp": "2024-01-14T16:20:00.000Z", + "type": "conversion", + "currency": "USD", + "paymentCurrency": "USDC", + "fees": [ + { + "type": "platform", + "amount": "500000", + "currency": "USDC", + "provider": "request-network" + } + ], + "request": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xe1f2a3b4c5d67890", + "hasBeenPaid": true, + "reference": "SERVICE-2024-789" + } + }, + { + "id": "01HXAMPLE5555666677778888", + "amount": "25000000", + "sourceNetwork": "base", + "destinationNetwork": "base", + "sourceTxHash": "0x5555666677778888999900001111222233334444555566667777888899990000", + "destinationTxHash": null, + "timestamp": "2024-01-13T09:15:00.000Z", + "type": "conversion", + "currency": "USD", + "paymentCurrency": "USDC", + "request": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xf1e2d3c4b5a67890", + "hasBeenPaid": true, + "reference": "PRODUCT-2024-456" + } + } + ], + "pagination": { + "total": 2, + "limit": 20, + "offset": 0, + "hasMore": false + } + } + }, + "searchByMerchantReference": { + "summary": "Search by merchant reference with pagination", + "value": { + "payments": [ + { + "id": "01HXAMPLE9999888877776666", + "amount": "150000000000000000000", + "sourceNetwork": "sepolia", + "destinationNetwork": "sepolia", + "sourceTxHash": "0x9999888877776666555544443333222211110000ffffeeeedddcccbbbaaa999", + "destinationTxHash": null, + "timestamp": "2024-01-15T11:45:00.000Z", + "type": "conversion", + "conversionRateSource": "0.0004", + "conversionRateDestination": "2500.0", + "convertedAmountSource": "150000000000000000000", + "convertedAmountDestination": "60000000", + "currency": "USD", + "paymentCurrency": "ETH", + "fees": [ + { + "type": "conversion", + "amount": "600000000000000000", + "currency": "ETH", + "provider": "request-network" + } + ], + "request": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xa1b2c3d4e5f67890", + "hasBeenPaid": true, + "customerInfo": { + "firstName": "Sarah", + "lastName": "Wilson", + "email": "sarah.wilson@company.com", + "address": { + "street": "789 Pine Street", + "city": "Seattle", + "state": "WA", + "postalCode": "98101", + "country": "US" + } + }, + "reference": "SUBSCRIPTION-ANNUAL-2024" + } + } + ], + "pagination": { + "total": 15, + "limit": 1, + "offset": 0, + "hasMore": true + } + } + } + } + } + } + }, + "400": { + "description": "Invalid search parameters or validation errors", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "statusCode": { + "type": "number", + "example": 400 + }, + "message": { + "type": "string", + "example": "Validation failed" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "toDate" + }, + "message": { + "type": "string", + "example": "toDate must be after or equal to fromDate" + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Authentication required - API key or client ID missing", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "statusCode": { + "type": "number", + "example": 401 + }, + "message": { + "type": "string", + "example": "Unauthorized" + }, + "error": { + "type": "string", + "example": "Unauthorized" + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Search payments with advanced filtering", + "tags": [ + "V2/Payments" + ] + } + }, + "/v2/payouts": { + "post": { + "description": "Initiate a payment without having to create a request first. Supports both one-time and recurring payments. For recurring payments, specify the recurrence object with start date, frequency, total executions, and payer address. The system will create a recurring payment schedule and return the necessary transactions for allowance approval and signature submission. Optionally includes customer information (firstName, lastName, email, address) and a merchant reference field for checkout widget implementations and receipt tracking.", + "operationId": "PayoutV2Controller_payRequest_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "payee": { + "type": "string", + "description": "The wallet address of the payee (Ethereum 0x... or TRON T...)" + }, + "amount": { + "type": "string", + "description": "The payable amount of the invoice, in human readable format" + }, + "invoiceCurrency": { + "type": "string", + "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" + }, + "paymentCurrency": { + "type": "string", + "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" + }, + "feePercentage": { + "type": "string", + "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)" + }, + "feeAddress": { + "type": "string", + "description": "Address to receive the fee (Ethereum 0x... or TRON T...)" + }, + "recurrence": { + "type": "object", + "properties": { + "startDate": { + "type": "string", + "description": "The start date of the payment, cannot be in the past" + }, + "frequency": { + "type": "string", + "enum": [ + "DAILY", + "WEEKLY", + "MONTHLY", + "YEARLY" + ], + "description": "The frequency of the payment" + }, + "totalPayments": { + "type": "number", + "minimum": 2, + "maximum": 256, + "description": "The total number of times the payment will be executed (max 256)." + }, + "payer": { + "type": "string", + "description": "The wallet address of the payer. Cannot be the same as the payee address." + } + }, + "required": [ + "startDate", + "frequency", + "totalPayments", + "payer" + ], + "description": "Configuration details for recurring payments" + }, + "payerWallet": { + "type": "string", + "description": "The wallet address of the payer, use to check if payer approval exists" + }, + "payerAddress": { + "type": "string", + "description": "The wallet address of the payer (alias for payerWallet)" + }, + "customerInfo": { + "type": "object", + "properties": { + "firstName": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Customer's first name" + }, + "lastName": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Customer's last name" + }, + "email": { + "type": "string", + "maxLength": 255, + "format": "email", + "description": "Customer's email address" + }, + "address": { + "type": "object", + "properties": { + "street": { + "type": "string", + "maxLength": 255, + "description": "Street address" + }, + "city": { + "type": "string", + "maxLength": 100, + "description": "City" + }, + "state": { + "type": "string", + "maxLength": 100, + "description": "State or province" + }, + "postalCode": { + "type": "string", + "maxLength": 20, + "description": "Postal or ZIP code" + }, + "country": { + "type": "string", + "minLength": 2, + "maxLength": 2, + "description": "Country code (ISO 3166-1 alpha-2)" + } + }, + "description": "Customer's address" + } + }, + "description": "Optional customer information for merchant receipt tracking" + }, + "reference": { + "type": "string", + "minLength": 1, + "maxLength": 255, + "description": "Merchant reference for receipt tracking and identification" + } + }, + "required": [ + "payee", + "amount", + "invoiceCurrency", + "paymentCurrency" + ] + }, + "examples": { + "oneTimePayment": { + "summary": "One-time payment example", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "ETH-sepolia-sepolia", + "feePercentage": "0.02", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" + } + }, + "tronUsdtPayment": { + "summary": "TRON USDT payment example", + "value": { + "payee": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", + "amount": "10", + "invoiceCurrency": "USDT-tron", + "paymentCurrency": "USDT-tron" + } + }, + "recurringPayment": { + "summary": "Recurring payment example", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "ETH-sepolia-sepolia", + "feePercentage": "0.02", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "recurrence": { + "startDate": "2030-01-01", + "frequency": "DAILY", + "totalPayments": 30, + "payer": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570" + } + } + }, + "erc20Payment": { + "summary": "ERC20 token payment example", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "100", + "invoiceCurrency": "FAU-sepolia", + "paymentCurrency": "FAU-sepolia", + "feePercentage": "0.01", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" + } + }, + "checkoutWidgetPayment": { + "summary": "Checkout widget payment with customer info and reference", + "value": { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "25.50", + "invoiceCurrency": "USD", + "paymentCurrency": "USDC-sepolia", + "feePercentage": "2.5", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "customerInfo": { + "firstName": "John", + "lastName": "Doe", + "email": "john.doe@example.com", + "address": { + "street": "123 Main Street", + "city": "New York", + "state": "NY", + "postalCode": "10001", + "country": "US" + } + }, + "reference": "ORDER-2024-001234" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Request created and payment initiated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "requestId": { + "type": "string" + } + }, + "required": [ + "requestId" + ] + }, + "examples": { + "nativeCurrency": { + "summary": "Native currency payment (e.g., ETH)", + "value": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "transactions": [ + { + "data": "0xb868980b...00", + "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687", + "value": { + "type": "BigNumber", + "hex": "0x038d7ea4c68000" + } + } + ], + "metadata": { + "stepsRequired": 1, + "needsApproval": false, + "approvalTransactionIndex": null, + "hasEnoughBalance": true, + "hasEnoughGas": true + } + } + }, + "erc20Token": { + "summary": "ERC20 token payment (requires approval)", + "value": { + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "transactions": [ + { + "data": "0x095ea7b3...ff", + "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324cf623C", + "value": 0 + }, + { + "data": "0xc219a14d...00", + "to": "0x399F5EE127ce7432E4921a61b8CF52b0af52cbfE", + "value": 0 + } + ], + "metadata": { + "stepsRequired": 2, + "needsApproval": true, + "approvalTransactionIndex": 0, + "hasEnoughBalance": true, + "hasEnoughGas": true + } + } + }, + "recurringPayment": { + "summary": "Recurring payment response (requires signature)", + "value": { + "id": "01JXYJKCAHGFTDR15F2D072ESG", + "transactions": [ + { + "to": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", + "data": "0x095ea7b30000000000000000000000000363dD3ccD4f187d7033c57354CA81f998451D590000000000000000000000000000000000000000000000000000000000000000", + "value": "0x0" + } + ], + "recurringPaymentPermit": { + "domain": { + "name": "ERC20RecurringPaymentProxy", + "version": "1", + "chainId": 11155111, + "verifyingContract": "0x0363dD3ccD4f187d7033c57354CA81f998451D59" + }, + "types": { + "SchedulePermit": [ + { + "name": "subscriber", + "type": "address" + }, + { + "name": "token", + "type": "address" + }, + { + "name": "recipient", + "type": "address" + }, + { + "name": "feeAddress", + "type": "address" + }, + { + "name": "amount", + "type": "uint128" + }, + { + "name": "feeAmount", + "type": "uint128" + }, + { + "name": "gasFee", + "type": "uint128" + }, + { + "name": "periodSeconds", + "type": "uint32" + }, + { + "name": "firstExec", + "type": "uint32" + }, + { + "name": "totalExecutions", + "type": "uint8" + }, + { + "name": "nonce", + "type": "uint256" + }, + { + "name": "deadline", + "type": "uint256" + } + ] + }, + "values": { + "subscriber": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570", + "token": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", + "recipient": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10000000000000000000", + "feeAmount": "0", + "gasFee": "0", + "periodSeconds": 86400, + "firstExec": 1735732800, + "totalExecutions": 30, + "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "deadline": 1738404800 + } + }, + "metadata": { + "stepsRequired": 2, + "totalNeededAllowance": "300000000000000000000", + "currentAllowance": "0", + "additionalAllowanceNeeded": "300000000000000000000", + "existingPaymentsAmount": "0" + } + } + } + } + } + } + }, + "404": { + "description": "Wallet not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Initiate a payment", + "tags": [ + "Pay", + "V2/Payouts" + ] + } + }, + "/v2/payouts/batch": { + "post": { + "description": "Pays multiple payment requests in one transaction by either creating new requests or using existing request IDs. All requests must be on the same network. Supports mixed ERC20, Native, and conversion requests.", + "operationId": "PayoutV2Controller_payBatchRequest_v2", + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "requests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "payee": { + "type": "string", + "description": "The wallet address of the payee (Ethereum 0x... or TRON T...)" + }, + "amount": { + "type": "string", + "description": "The payable amount of the invoice, in human readable format" + }, + "invoiceCurrency": { + "type": "string", + "description": "Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD" + }, + "paymentCurrency": { + "type": "string", + "description": "Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia" + } + }, + "required": [ + "payee", + "amount", + "invoiceCurrency", + "paymentCurrency" + ] + }, + "description": "A list of payment requests to be created andprocessed in batch. All requests must be on the same network and contain payment/invoice currency information. Either `requests` or `requestIds` must be provided, but not both." + }, + "requestIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The request IDs of the existing requests to be paid. Requests must be on the same network. Either `requests` or `requestIds` must be provided, but not both." + }, + "payer": { + "type": "string", + "description": "The wallet address of the payer, user to check if approval is needed or not." + }, + "feePercentage": { + "type": "string", + "description": "Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)" + }, + "feeAddress": { + "type": "string", + "description": "Address to receive the fee" + } + }, + "example": { + "requests": [ + { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "2", + "invoiceCurrency": "FAU-sepolia", + "paymentCurrency": "FAU-sepolia" + }, + { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "2", + "invoiceCurrency": "fUSDC-sepolia", + "paymentCurrency": "fUSDC-sepolia" + }, + { + "payee": "0xb07D2398d2004378cad234DA0EF14f1c94A530e4", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "FAU-sepolia" + }, + { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "0.00001", + "invoiceCurrency": "ETH-sepolia-sepolia", + "paymentCurrency": "ETH-sepolia-sepolia" + }, + { + "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7", + "amount": "10", + "invoiceCurrency": "USD", + "paymentCurrency": "ETH-sepolia-sepolia" + } + ], + "payer": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570" + } + } + } + } + }, + "responses": { + "201": { + "description": "Batch payment calldata retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ERC20ApprovalTransactions": { + "type": "array", + "description": "Array of ERC20 approval transactions needed before the batch payment. Only present when token approval is required.", + "items": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "Transaction calldata for the ERC20 approval" + }, + "to": { + "type": "string", + "description": "Target ERC20 token contract address for approval" + }, + "value": { + "type": "integer", + "description": "Always 0 for ERC20 approvals" + } + }, + "required": [ + "data", + "to", + "value" + ] + } + }, + "ERC20BatchPaymentTransaction": { + "type": "object", + "description": "The batch payment transaction for ERC20 tokens. Only present when the batch contains ERC20 payments.", + "properties": { + "data": { + "type": "string", + "description": "Transaction calldata for the ERC20 batch payment" + }, + "to": { + "type": "string", + "description": "Target batch payment contract address" + }, + "value": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "BigNumber" + ] + }, + "hex": { + "type": "string", + "description": "Payment amount in EVM-compatible format, encoded in hex. Usually 0 for ERC20 payments" + } + }, + "required": [ + "type", + "hex" + ] + } + }, + "required": [ + "data", + "to", + "value" + ] + }, + "ETHBatchPaymentTransaction": { + "type": "object", + "description": "The batch payment transaction for native ETH. Only present when the batch contains ETH payments.", + "properties": { + "data": { + "type": "string", + "description": "Transaction calldata for the ETH batch payment" + }, + "to": { + "type": "string", + "description": "Target batch payment contract address" + }, + "value": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "BigNumber" + ] + }, + "hex": { + "type": "string", + "description": "Payment amount in EVM-compatible format, encoded in hex. Contains the ETH value to send" + } + }, + "required": [ + "type", + "hex" + ] + } + }, + "required": [ + "data", + "to", + "value" + ] + } + }, + "additionalProperties": false + }, + "examples": { + "erc20_and_eth_with_approval": { + "summary": "Batch payment with approval needed", + "value": { + "ERC20ApprovalTransactions": [ + { + "data": "0x095ea7b3...", + "to": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C", + "value": 0 + } + ], + "batchPaymentTransaction": { + "data": "0x92cddb91...", + "to": "0x67818703c92580c0e106e401F253E8A410A66f8B", + "value": { + "type": "BigNumber", + "hex": "0x0d83b3d1afc58b" + } + } + } + }, + "erc20_and_eth_no_approval": { + "summary": "Batch payment without approval needed", + "value": { + "ERC20ApprovalTransactions": [], + "batchPaymentTransaction": { + "data": "0x92cddb91...", + "to": "0x67818703c92580c0e106e401F253E8A410A66f8B", + "value": { + "type": "BigNumber", + "hex": "0x0d83b3d1afc58b" + } + } + } + } + } + } + } + }, + "400": { + "description": "Requests must be on the same network", + "content": { + "application/json": { + "examples": { + "requestsOnDifferentNetworks": { + "summary": "Requests on different networks", + "value": { + "message": "All requests must be on the same network", + "error": "Bad Request", + "statusCode": 400 + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Pay multiple requests in one transaction", + "tags": [ + "Pay", + "V2/Payouts" + ] + } + }, + "/v2/payouts/recurring/{id}": { + "post": { + "description": "Submit a signature for a recurring payment permit to activate the recurring payment schedule. This endpoint is called after creating a recurring payment and obtaining the permit data. The signature authorizes the recurring payment contract to execute payments on behalf of the payer according to the schedule. Once activated, payments will be executed automatically at the specified intervals.", + "operationId": "PayoutV2Controller_submitRecurringPaymentSignature_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "The ID of the recurring payment", + "schema": { + "example": "01JXYJKCAHGFTDR15F2D072ESG", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "permitSignature": { + "type": "string", + "description": "The signature of the recurring payment permit." + } + }, + "required": [ + "permitSignature" + ], + "example": { + "permitSignature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b" + } + } + } + } + }, + "responses": { + "201": { + "description": "Recurring payment signature submitted successfully", + "content": { + "application/json": { + "examples": { + "success": { + "summary": "Signature submitted successfully", + "value": { + "message": "Recurring payment activated successfully", + "id": "01JXYJKCAHGFTDR15F2D072ESG", + "status": "active" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "examples": { + "invalidSignature": { + "summary": "Invalid signature provided", + "value": { + "message": "Invalid signature provided", + "error": "Bad Request", + "statusCode": 400 + } + }, + "alreadyActive": { + "summary": "Recurring payment is already active", + "value": { + "message": "Recurring payment is already active", + "error": "Bad Request", + "statusCode": 400 + } + } + } + } + } + }, + "404": { + "description": "Recurring payment not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Submit a recurring payment signature", + "tags": [ + "Pay", + "V2/Payouts" + ] + }, + "get": { + "description": "Retrieve the current status and execution details of a recurring payment. Returns information about executed payments, remaining executions, next payment date, and overall status. This endpoint is useful for monitoring recurring payment progress and checking if payments are being executed as expected. Note: Customer information (PII) is not included in the response for security reasons.", + "operationId": "PayoutV2Controller_getRecurringPaymentStatus_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "The ID of the recurring payment", + "schema": { + "example": "01JXYJKCAHGFTDR15F2D072ESG", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Recurring payment status retrieved successfully", + "content": { + "application/json": { + "examples": { + "active": { + "summary": "Active recurring payment", + "value": { + "processedPayments": 3, + "totalPayments": 30, + "lastPaymentDate": "2025-01-04T10:00:00.000Z", + "nextPaymentDate": "2025-01-05T10:00:00.000Z", + "status": "active", + "requests": [ + { + "paymentReference": "0xb3581f0b0f74cc61", + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" + } + ], + "payments": [ + { + "id": "01JXYJKCAHGFTDR15F2D072ESG", + "amount": "10", + "timestamp": "2025-01-04T10:00:00.000Z", + "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + } + ] + } + }, + "paused": { + "summary": "Paused recurring payment", + "value": { + "processedPayments": 5, + "totalPayments": 30, + "lastPaymentDate": "2025-01-05T10:00:00.000Z", + "nextPaymentDate": null, + "status": "paused", + "failureCount": 3, + "failureReason": "Insufficient token allowance" + } + }, + "completed": { + "summary": "Completed recurring payment", + "value": { + "processedPayments": 30, + "totalPayments": 30, + "lastPaymentDate": "2025-01-30T10:00:00.000Z", + "nextPaymentDate": null, + "status": "completed" + } + } + } + } + } + }, + "404": { + "description": "Recurring payment not found", + "content": { + "application/json": { + "examples": { + "notFound": { + "summary": "Recurring payment not found", + "value": { + "message": "Recurring payment not found", + "error": "Not Found", + "statusCode": 404 + } + } + } + } + } + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get the status of a recurring payment", + "tags": [ + "Pay", + "V2/Payouts" + ] + }, + "patch": { + "description": "Update a recurring payment by cancelling it or unpausing it. When cancelling, optionally returns a transaction to decrease allowance. When unpausing, resumes execution of a paused recurring payment.", + "operationId": "PayoutV2Controller_updateRecurringPayment_v2", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "The ID of the recurring payment", + "schema": { + "example": "01JXYJKCAHGFTDR15F2D072ESG", + "type": "string" + } + }, + { + "name": "x-api-key", + "in": "header", + "description": "API key for authentication (optional if using Client ID)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication (optional if using API key)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (required for Client ID auth, automatically set by browser)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": [ + "cancel", + "unpause" + ], + "description": "The action to perform on the recurring payment" + } + }, + "required": [ + "action" + ], + "example": { + "action": "cancel" + } + } + } + } + }, + "responses": { + "200": { + "description": "Recurring payment updated successfully", + "content": { + "application/json": { + "examples": { + "cancelled": { + "summary": "Recurring payment cancelled", + "value": { + "id": "01JXYJKCAHGFTDR15F2D072ESG", + "status": "cancelled", + "transactions": [ + { + "to": "0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8", + "data": "0x095ea7b30000000000000000000000000363dD3ccD4f187d7033c57354CA81f998451D590000000000000000000000000000000000000000000000000000000000000000", + "value": "0x0" + } + ], + "metadata": { + "remainingPayments": 5, + "remainingAmount": "5000000000000000000", + "processedPayments": 3, + "totalPayments": 8 + } + } + }, + "unpaused": { + "summary": "Recurring payment unpaused", + "value": { + "id": "01JXYJKCAHGFTDR15F2D072ESG", + "status": "active", + "metadata": { + "processedPayments": 3, + "totalPayments": 8, + "nextPaymentDate": "2024-01-15T10:00:00.000Z" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "examples": { + "alreadyCancelled": { + "summary": "Recurring payment is already cancelled", + "value": { + "message": "Recurring payment is already cancelled", + "error": "Bad Request", + "statusCode": 400 + } + }, + "completed": { + "summary": "Cannot cancel a completed recurring payment", + "value": { + "message": "Cannot cancel a completed recurring payment", + "error": "Bad Request", + "statusCode": 400 + } + }, + "notPaused": { + "summary": "Recurring payment is not paused", + "value": { + "message": "Recurring payment is not paused", + "error": "Bad Request", + "statusCode": 400 + } + }, + "invalidAction": { + "summary": "Invalid action provided", + "value": { + "message": "Invalid action: invalid_action", + "error": "Bad Request", + "statusCode": 400 + } + } + } + } + } + }, + "404": { + "description": "Recurring payment not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Update a recurring payment", + "tags": [ + "Pay", + "V2/Payouts" + ] + } + }, + "/v2/payee-destination/signing-data": { + "get": { + "description": "Generate a nonce and return the complete EIP-712 signing data structure for payee destination creation or deactivation", + "operationId": "PayeeDestinationController_getSigningData_v2", + "parameters": [ + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (automatically set by browser)", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "walletAddress", + "required": true, + "in": "query", + "description": "The wallet address that will sign the message", + "schema": { + "type": "string" + } + }, + { + "name": "action", + "required": true, + "in": "query", + "description": "The action to perform (add or deactivate)", + "schema": { + "enum": [ + "add", + "deactivate" + ], + "type": "string" + } + }, + { + "name": "tokenAddress", + "required": true, + "in": "query", + "description": "The ERC20 token address for the payee destination", + "schema": { + "type": "string" + } + }, + { + "name": "chainId", + "required": true, + "in": "query", + "description": "The chain ID where the token is deployed", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "EIP-712 signing data with nonce" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get EIP-712 signing data with nonce", + "tags": [ + "V2/Payee Destination" + ] + } + }, + "/v2/payee-destination": { + "post": { + "description": "Create a payee destination with EIP-712 signature verification", + "operationId": "PayeeDestinationController_createPayeeDestination_v2", + "parameters": [ + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (automatically set by browser)", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "signature": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{130}$", + "description": "The EIP-712 signature from the payee" + }, + "nonce": { + "type": "string", + "minLength": 1, + "description": "The signing session nonce from /signing-data endpoint" + } + }, + "required": [ + "signature", + "nonce" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Payee destination created successfully" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Create payee destination", + "tags": [ + "V2/Payee Destination" + ] + }, + "get": { + "description": "Retrieve the active payee destination for a specific wallet address. Returns null if no active destination exists.", + "operationId": "PayeeDestinationController_getActivePayeeDestination_v2", + "parameters": [ + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (automatically set by browser)", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "walletAddress", + "required": true, + "in": "query", + "description": "The wallet address to filter payee destinations", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Active payee destination retrieved successfully (or null if none exists)" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get active payee destination for wallet", + "tags": [ + "V2/Payee Destination" + ] + } + }, + "/v2/payee-destination/{destinationId}": { + "delete": { + "description": "Deactivate a payee destination with EIP-712 signature verification. Sets active=false without deleting the record.", + "operationId": "PayeeDestinationController_deactivatePayeeDestination_v2", + "parameters": [ + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (automatically set by browser)", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "signature": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{130}$", + "description": "The EIP-712 signature from the payee" + }, + "nonce": { + "type": "string", + "minLength": 1, + "description": "The signing session nonce from /signing-data endpoint" + } + }, + "required": [ + "signature", + "nonce" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Payee destination deactivated successfully" + }, + "400": { + "description": "Destination not found or validation failed" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Deactivate payee destination", + "tags": [ + "V2/Payee Destination" + ] + }, + "get": { + "description": "Retrieve a payee destination using the format network:walletAddress:tokenAddress", + "operationId": "PayeeDestinationController_getPayeeDestination_v2", + "parameters": [ + { + "name": "x-client-id", + "in": "header", + "description": "Client ID for frontend authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "Origin", + "in": "header", + "description": "Origin header (automatically set by browser)", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Payee destination retrieved successfully" + }, + "404": { + "description": "Payee destination not found" + }, + "429": { + "description": "Too Many Requests" + } + }, + "summary": "Get payee destination by ID", + "tags": [ + "V2/Payee Destination" + ] + } + } + }, + "info": { + "title": "Request Network API", + "description": "API for easily creating and paying Requests with Request Network.", + "version": "0.13.0", + "contact": {} + }, + "tags": [ + { + "name": "V2/Request", + "description": "Core payment request operations (V2)" + }, + { + "name": "V2/Payments", + "description": "Payment search and management operations (V2)" + }, + { + "name": "V2/Payouts", + "description": "Pay a request without creating one first (V2)" + }, + { + "name": "V2/Payer", + "description": "Crypto-to-fiat payer management operations (V2)" + }, + { + "name": "V2/Currencies", + "description": "Currency operations (V2)" + }, + { + "name": "V2/Client IDs", + "description": "Client ID management (V2)" + }, + { + "name": "V2/Payee Destination", + "description": "Payee destination management (V2)" + } + ], + "servers": [ + { + "url": "https://api.request.network", + "description": "Production server" + }, + { + "url": "https://api.stage.request.network", + "description": "Staging server" + }, + { + "url": "http://127.0.0.1:8080", + "description": "Local development server" + } + ], + "components": { + "schemas": {} + }, + "externalDocs": { + "description": "Request Network Docs", + "url": "https://docs.request.network/request-network-api" + }, + "x-tagGroups": [ + { + "name": "V1", + "tags": [ + "V1/Request", + "V1/Pay", + "V1/Currencies", + "V1/Authentication", + "V1/API Keys", + "V1/Webhooks" + ], + "description": "v1 endpoints" + }, + { + "name": "V2", + "tags": [ + "V2/Request", + "V2/Payments", + "V2/Payouts", + "V2/Payer", + "V2/Currencies", + "V2/Authentication", + "V2/API Keys", + "V2/Webhooks", + "V2/Platforms", + "V2/Journey", + "V2/Client IDs", + "V2/Commerce Payments", + "V2/Secure Payment", + "V2/Payee Destination" + ], + "description": "v2 endpoints" + } + ] +} \ No newline at end of file diff --git a/docs.json b/docs.json index 485b97c..a4f699b 100644 --- a/docs.json +++ b/docs.json @@ -124,10 +124,10 @@ "api-reference/secure-payments", "api-reference/webhooks", { - "group": "Endpoints", - "openapi": "https://api.request.network/open-api/openapi.json", + "group": "Endpoints (V2)", + "openapi": "api-reference/openapi.v2.json", "pages": [ - "request-network-api/create-and-pay-requests" + "api-reference/endpoints-overview" ] } ] diff --git a/request-network-api/create-and-pay-requests.mdx b/request-network-api/create-and-pay-requests.mdx index e676dce..dbfc1d7 100644 --- a/request-network-api/create-and-pay-requests.mdx +++ b/request-network-api/create-and-pay-requests.mdx @@ -1,33 +1,60 @@ --- -title: "Create and Pay Requests " +title: "Endpoints Overview" sidebarTitle: "Overview" -description: "The Request Network API provides an interface for creating and paying requests within your application." +description: "Quick index of Request Network API endpoint groups" --- - -**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions). - - - -**Reach out** - -For more details on how to start accepting crypto payments, [get in touch](https://2deywy.share-eu1.hsforms.com/2b92phs9LR_eJdeZoxzmoMA?utm_source=request.network&utm_medium=docs&utm_campaign=evergreen&utm_content=get_in_touch) and we will reach out. - - -## **Core Functionality** - -At its core, the Request Network API empowers you to: - -- **Create Requests:** Define payment requests with information such as payee, payer (optional), amount, currency, and recurrence (optional). -- **Facilitate Payments:** Return transaction calldata, ready to be signed by end-users and sent to the blockchain for secure and transparent value transfer. -- **Deliver Webhook Notifications:** Receive instant updates on payment status changes, enabling your application to react dynamically to completed transactions. -- **Fee Collection:** When paying a request, you can specify a fee percentage (between 0 and 100) and a fee address, which will add the fee on top of the payment amount - meaning the payer will pay the original amount plus the fee percentage, with the fee portion being sent to the specified fee address. -- **Partial Payment Support:** Pay a portion of a request instead of the full amount at once. This unlocks powerful use cases such as: - - **Split payment**: split a payment 50% USDC on Base and 50% with USDT on Optimism. - - **Gradual payment plans:** Allow users to pay large invoices in smaller chunks. - - **Risk mitigation:** Test with small amounts before completing large payments. - The API automatically tracks payment progress, showing `partially_paid` status until the request is fully paid, and prevents overpayment by capping amounts to the remaining balance. - -### Supported Chains and Currencies - -See [Supported Chains and Currencies](https://docs.request.network/request-network-api/supported-chains-and-currencies#request-network-api-supported-currencies) +## Overview + +Use this page as a quick index to the main endpoint groups in Request Network API. + +For implementation guides, use the pages in **API Features**. For full request/response schemas, use the OpenAPI reference links below. + +## Core Endpoint Groups + + + + v2 request endpoints: create, status, pay calldata, and routes. + + + + v2 payout endpoints: direct, batch, and recurring payment operations. + + + + v2 payments search endpoint for reconciliation and reporting. + + + + v2 payer/compliance endpoints for KYC and payment details. + + + +## Frequently Used Endpoints + +- [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request) +- [GET /v2/request/{requestId}](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}) +- [GET /v2/request/{requestId}/pay](https://api.request.network/open-api/#tag/v2request/GET/v2/request/{requestId}/pay) +- [POST /v2/payouts](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts) +- [POST /v2/payouts/batch](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts/batch) +- [GET /v2/payments](https://api.request.network/open-api/#tag/v2payments/GET/v2/payments) + +## OpenAPI Reference + +See the full API specification in the [Request Network OpenAPI docs](https://api.request.network/open-api).