From 22b9b2bc452474d9d7611db54eabcb2b9538129f Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Mon, 30 Mar 2026 16:15:38 -0300 Subject: [PATCH 1/3] docs: fix remaining broken links, clarify edge cases - Fix 2 broken href="#" links in invoicing.mdx (Fork EasyInvoice -> GitHub repo, View Invoicing Examples -> integration guide) - Fix 2 broken href="#" links in checkout.mdx (Payment Widget Button -> checkout demo URL, both instances) - Clarify crosschain minimum amount: "greater than 1 USD equivalent" with example, not just "greater than 1" - Add ERC-7828 checksum clarification in payee-destinations.mdx (auto- generated by API, no manual computation needed) - Add error handling table to payouts.mdx (400, 401, 404, 429) --- api-features/crosschain-payments.mdx | 2 +- api-features/payee-destinations.mdx | 5 +++++ api-features/payouts.mdx | 11 +++++++++++ use-cases/checkout.mdx | 18 +++++++++--------- use-cases/invoicing.mdx | 22 +++++++++++----------- 5 files changed, 37 insertions(+), 21 deletions(-) diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index 696afe7..8b735aa 100644 --- a/api-features/crosschain-payments.mdx +++ b/api-features/crosschain-payments.mdx @@ -46,7 +46,7 @@ Crosschain payments work only with mainnet funds (real money). Test networks are -Create a request with a `paymentCurrency` in the supported stablecoins and networks, and `amount` greater than 1 (crosschain execution under 1 stablecoin is not allowed). +Create a request with a `paymentCurrency` in the supported stablecoins and networks. The `amount` must be greater than 1 USD equivalent (e.g., at least 1.01 USDC) — crosschain routes are not available for amounts under $1 due to bridge minimums. Create the request via [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request). diff --git a/api-features/payee-destinations.mdx b/api-features/payee-destinations.mdx index 8d680b1..a043c97 100644 --- a/api-features/payee-destinations.mdx +++ b/api-features/payee-destinations.mdx @@ -27,8 +27,13 @@ A destination ID combines the interop address with the token address: This encodes: - **Wallet:** `0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7` - **Chain:** Base (chainId `8453`) +- **Checksum:** `ABCD1234` (auto-generated by the API for address verification) - **Token:** USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) + +The checksum portion (`#ABCD1234`) is generated automatically by the API when you create a destination. You do not need to compute it yourself. + + ## How It Works diff --git a/api-features/payouts.mdx b/api-features/payouts.mdx index a66e010..e16246a 100644 --- a/api-features/payouts.mdx +++ b/api-features/payouts.mdx @@ -84,6 +84,17 @@ See [Recurring Payments](/api-features/recurring-payments) for the full lifecycl - `GET /v2/payouts/recurring/:id` — Check status and next payment date - `PATCH /v2/payouts/recurring/:id` — Cancel or unpause +## Error Handling + +| Status | Meaning | +|--------|---------| +| `400` | Invalid request body — check required fields and currency IDs | +| `401` | Authentication failed — verify your `x-api-key` header | +| `404` | Request or recurring payment not found | +| `429` | Rate limited — back off and retry | + +For batch payouts, a `400` may indicate that payments span multiple networks (all must be on the same chain). + ## Endpoint Reference diff --git a/use-cases/checkout.mdx b/use-cases/checkout.mdx index 97aa1de..c1ecc7f 100644 --- a/use-cases/checkout.mdx +++ b/use-cases/checkout.mdx @@ -123,19 +123,19 @@ Not sure which approach fits your needs? [See our detailed comparison of integra ## Developer Tools - **Pre-built React checkout component** - + Drop-in component for crypto payments—works with Easy Invoice Client IDs or direct API integration. - + - Wallet connection and payment processing included - Fully customizable styling - Compatible with all integration options above - + [View demo →](https://checkout.request.network) @@ -192,9 +192,9 @@ NFT marketplace automatically splits payments between sellers, platform, and roy Recommended for checkout - bundles request creation with payment transaction generation - Pre-built React component with wallet connection and payment processing diff --git a/use-cases/invoicing.mdx b/use-cases/invoicing.mdx index 2d8eb6f..51d0a85 100644 --- a/use-cases/invoicing.mdx +++ b/use-cases/invoicing.mdx @@ -74,20 +74,20 @@ Not sure which approach fits your needs? [See our detailed comparison of integra [Try it now →](https://easyinvoice.request.network) - **Customize for your brand** - + Clone and modify the open-source application to match your needs. - + - Full source code access - Custom branding - Add your own features - - [Forking guide →](#) + + [View repository →](https://github.com/RequestNetwork/easy-invoice) @@ -171,12 +171,12 @@ Not sure which approach fits your needs? [See our detailed comparison of integra Set up your account and get API credentials - - See code examples for common invoicing workflows + See integration examples for payment workflows Date: Tue, 31 Mar 2026 06:55:43 -0300 Subject: [PATCH 2/3] docs: second review pass fixes - Fix stale "9 EVM chains, 150+ currencies" in payment-detection.mdx - Fix checkout link to /use-cases/subscriptions (AI-warned page) -> /api-features/recurring-payments - Add Info callout in secure-payments.mdx clarifying path :token vs query token param naming collision - Add PUT response note in payee-destinations.mdx - Fix batch payout example: invoiceCurrency should be "USD" not "USDC-base" - Add null check for approvalTransactionIndex in crosschain code example --- api-features/crosschain-payments.mdx | 2 +- api-features/payee-destinations.mdx | 2 ++ api-features/payouts.mdx | 4 ++-- api-reference/secure-payments.mdx | 10 +++++++--- use-cases/checkout.mdx | 2 +- use-cases/payment-detection.mdx | 2 +- 6 files changed, 14 insertions(+), 8 deletions(-) diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index 8b735aa..2ecb442 100644 --- a/api-features/crosschain-payments.mdx +++ b/api-features/crosschain-payments.mdx @@ -167,7 +167,7 @@ const walletClient = createWalletClient({ const [account] = await walletClient.getAddresses(); // Step 1: Send approval transaction (if needed) -if (metadata.needsApproval) { +if (metadata.needsApproval && metadata.approvalTransactionIndex != null) { const approvalTx = transactions[metadata.approvalTransactionIndex]; const approvalHash = await walletClient.sendTransaction({ account, diff --git a/api-features/payee-destinations.mdx b/api-features/payee-destinations.mdx index a043c97..ba70dd9 100644 --- a/api-features/payee-destinations.mdx +++ b/api-features/payee-destinations.mdx @@ -105,6 +105,8 @@ New ERC20 token contract address. New chain ID. +Returns the updated destination object (same format as POST response). + ### GET /v1/payee-destination Returns the active payee destination for the authenticated wallet, or `null` if none exists. diff --git a/api-features/payouts.mdx b/api-features/payouts.mdx index e16246a..88f2265 100644 --- a/api-features/payouts.mdx +++ b/api-features/payouts.mdx @@ -55,13 +55,13 @@ curl -X POST "https://api.request.network/v2/payouts/batch" \ "requests": [ { "amount": "50", - "invoiceCurrency": "USDC-base", + "invoiceCurrency": "USD", "paymentCurrency": "USDC-base", "payee": "0xb07d2398d2004378cad234da0ef14f1c94a530e4" }, { "amount": "25", - "invoiceCurrency": "USDC-base", + "invoiceCurrency": "USD", "paymentCurrency": "USDC-base", "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7" } diff --git a/api-reference/secure-payments.mdx b/api-reference/secure-payments.mdx index 4969eba..a1fa624 100644 --- a/api-reference/secure-payments.mdx +++ b/api-reference/secure-payments.mdx @@ -226,10 +226,14 @@ curl -X GET "https://api.request.network/v2/secure-payments/01ABC123DEF456GHI789 Retrieve executable transaction calldata for the secure payment. For crosschain payments, provide `chain` and `token` query parameters to select the source route. + +The `:token` in the URL path is the secure payment token (a ULID identifier). The `token` query parameter is the source currency symbol (`USDC` or `USDT`) for crosschain route selection. These are different values. + + ### Path parameters -Secure payment token. +Secure payment token (ULID returned from `POST /v2/secure-payments`). ### Query parameters @@ -239,11 +243,11 @@ Payer wallet address. Used for approval and balance checks. -Source chain for crosschain payments. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`. Must be provided together with `token`. +Source chain for crosschain payments. Values: `BASE`, `OPTIMISM`, `ARBITRUM`, `ETHEREUM`. Must be provided together with the `token` query parameter. -Source token for crosschain payments. Values: `USDC`, `USDT`. Must be provided together with `chain`. +Source currency for crosschain payments. Values: `USDC`, `USDT`. Must be provided together with `chain`. diff --git a/use-cases/checkout.mdx b/use-cases/checkout.mdx index c1ecc7f..e8392c5 100644 --- a/use-cases/checkout.mdx +++ b/use-cases/checkout.mdx @@ -169,7 +169,7 @@ Retailer processes thousands of daily orders with automatic payment attribution. ### Digital Goods & Services Marketplace sells design templates and fonts with instant delivery upon payment. -**Example:** Customer pays in USDC and instantly receives download links. For recurring billing, see [Subscriptions](/use-cases/subscriptions). +**Example:** Customer pays in USDC and instantly receives download links. For recurring billing, see [Recurring Payments](/api-features/recurring-payments). ### Event Ticketing Venue sells thousands of tickets with automatic NFT ticket delivery. diff --git a/use-cases/payment-detection.mdx b/use-cases/payment-detection.mdx index eb85cf4..cb2b197 100644 --- a/use-cases/payment-detection.mdx +++ b/use-cases/payment-detection.mdx @@ -12,7 +12,7 @@ Request IDs solve this by attaching business context to every payment. Each requ **What you get:** - **Automatic attribution** - Every payment linked to its request via Request ID -- **Multi-chain monitoring** - Track payments across 9 EVM chains in 150+ currencies +- **Multi-chain monitoring** - Track payments across [10+ EVM chains and Tron](/resources/supported-chains-and-currencies) in 500+ currencies - **Real-time notifications** - Webhooks for instant payment confirmations - **Zero manual work** - No spreadsheets, no guessing, no payment collisions From 3de5d35a84f04a96f594142ae74b8c074810e128 Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Tue, 31 Mar 2026 07:01:43 -0300 Subject: [PATCH 3/3] docs: document forceApprovalTransactions and Tron wallet optional Align docs with request-api PRs #627 and #628. - Add sourceAmount metadata field to crosschain response example and docs - Add Info callout explaining approval transactions are always included in crosschain calldata (forceApprovalTransactions behavior for USDT zero-reset compatibility) - Document that wallet param is optional for Tron payments across secure-payments GET /:token, GET /:token/pay, and supported chains page (API now uses dead address fallback instead of 400 error) --- api-features/crosschain-payments.mdx | 8 +++++++- api-reference/secure-payments.mdx | 4 ++-- resources/supported-chains-and-currencies.mdx | 2 +- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index 2ecb442..b1bdcb9 100644 --- a/api-features/crosschain-payments.mdx +++ b/api-features/crosschain-payments.mdx @@ -137,7 +137,8 @@ The API returns a `transactions` array with ready-to-execute calldata: "paymentTransactionIndex": 1, "routeType": "crosschain", "quoteExpiresAt": 1742205771, - "hasEnoughBalance": true + "hasEnoughBalance": true, + "sourceAmount": "10.02" } } ``` @@ -150,6 +151,11 @@ The API returns a `transactions` array with ready-to-execute calldata: - `routeType` — `"crosschain"` or `"samechain"` - `quoteExpiresAt` — unix timestamp when the route quote expires - `hasEnoughBalance` — whether the payer has sufficient funds +- `sourceAmount` — the amount the payer needs to send on the source chain (includes bridge fees) + + +The API always includes approval transactions in crosschain calldata responses, even if the payer already has sufficient token allowance. This ensures USDT-style tokens (which require resetting allowance to zero before setting a new one) work correctly. + diff --git a/api-reference/secure-payments.mdx b/api-reference/secure-payments.mdx index a1fa624..3abd89c 100644 --- a/api-reference/secure-payments.mdx +++ b/api-reference/secure-payments.mdx @@ -138,7 +138,7 @@ Secure payment token returned from `POST /v2/secure-payments`. ### Query parameters -Payer wallet address. When provided, the response includes `paymentOptions` with balance information across supported chains. +Payer wallet address. When provided, the response includes `paymentOptions` with balance information across supported chains. Optional for Tron payments (the API uses a fallback address if omitted). @@ -239,7 +239,7 @@ Secure payment token (ULID returned from `POST /v2/secure-payments`). ### Query parameters -Payer wallet address. Used for approval and balance checks. +Payer wallet address. Used for approval and balance checks. Optional for Tron payments (the API uses a fallback address if omitted). diff --git a/resources/supported-chains-and-currencies.mdx b/resources/supported-chains-and-currencies.mdx index 55d2665..5f0b7dc 100644 --- a/resources/supported-chains-and-currencies.mdx +++ b/resources/supported-chains-and-currencies.mdx @@ -69,7 +69,7 @@ For Conversion Payments, supported **payment currencies** include: -Tron uses TRC-20 (not ERC-20). Wallet addresses use the `T...` format. +Tron uses TRC-20 (not ERC-20). Wallet addresses use the `T...` format. The `wallet` parameter is optional for Tron payments — the API uses a fallback address when omitted. To fetch supported payment currencies for an invoice currency: