From 22b9b2bc452474d9d7611db54eabcb2b9538129f Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Mon, 30 Mar 2026 16:15:38 -0300 Subject: [PATCH 1/4] 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/4] 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/4] 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: From 7879e821fa54d051f6ee335ed2f4c4f5c41b62ac Mon Sep 17 00:00:00 2001 From: rodrigopavezi Date: Tue, 7 Apr 2026 15:57:16 -0300 Subject: [PATCH 4/4] docs: update for v0.18.0 API, secure payment v0.3.0, and auth API v0.3.1 - Replace Alchemy Account Kit with Safe + Pimlico for smart accounts - Add smart account supported chains list - Add Polygon to crosschain supported chains - Add detectionSource, note, and requestAmount response fields - Document LiFi fallback settlement detection --- api-features/crosschain-payments.mdx | 3 ++- api-features/payment-detection.mdx | 8 ++++++++ api-features/query-payments.mdx | 4 ++++ api-features/query-requests.mdx | 3 +++ api-features/secure-payment-pages.mdx | 8 +++++--- 5 files changed, 22 insertions(+), 4 deletions(-) diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index b1bdcb9..a91c848 100644 --- a/api-features/crosschain-payments.mdx +++ b/api-features/crosschain-payments.mdx @@ -20,7 +20,7 @@ Crosschain payments allow users to pay a request using a stablecoin from a diffe ## Crosschain Payments Supported Chains and Currencies -For crosschain (and samechain) payments, the Request Network API supports USDC and USDT on 4 chains. +For crosschain (and samechain) payments, the Request Network API supports USDC and USDT on 5 chains. Bridged USDC (USDC.e) is **not** supported for crosschain payments. Only native USDC is supported. @@ -32,6 +32,7 @@ Bridged USDC (USDC.e) is **not** supported for crosschain payments. Only native - Arbitrum One - Base - OP Mainnet +- Polygon ### Supported Currencies diff --git a/api-features/payment-detection.mdx b/api-features/payment-detection.mdx index 4a9f477..2358679 100644 --- a/api-features/payment-detection.mdx +++ b/api-features/payment-detection.mdx @@ -65,6 +65,14 @@ All crosschain payments using Request Network API use the **ERC-20 Fee Proxy con 4. Payment detection system identifies the transaction 5. Request status updated automatically +### LiFi Fallback Settlements + +In rare cases, a crosschain bridge may deliver funds to the destination chain but fail to execute the final payment contract call. When this happens, the system detects the LiFi fallback settlement and confirms the payment automatically. + +Fallback-confirmed payments include: +- `detectionSource` set to `"lifi"` +- A `note` field explaining that funds were delivered via fallback settlement + ## Webhook Notifications Configure webhooks to receive real-time notifications for payment events: diff --git a/api-features/query-payments.mdx b/api-features/query-payments.mdx index fcd494d..e3f9d90 100644 --- a/api-features/query-payments.mdx +++ b/api-features/query-payments.mdx @@ -125,6 +125,8 @@ Pagination offset. "type": "direct", "currency": "USD", "paymentCurrency": "USDC", + "detectionSource": "request-network", + "note": null, "fees": [ { "type": "gas", @@ -172,6 +174,8 @@ Pagination offset. | `currency` | string | Invoice currency | | `paymentCurrency` | string | Payment currency | | `fees` | array | Fee breakdown with type, amount, currency, provider | +| `detectionSource` | string \| null | How the payment was confirmed: `"request-network"` or `"lifi"` | +| `note` | string \| null | Additional context for non-standard settlements (e.g., LiFi fallback) | | `recurringPaymentId` | string \| null | Recurring payment ID if applicable | | `request` | object | Linked request with requestId, paymentReference, hasBeenPaid, customerInfo, reference | diff --git a/api-features/query-requests.mdx b/api-features/query-requests.mdx index 9a1b529..d4881da 100644 --- a/api-features/query-requests.mdx +++ b/api-features/query-requests.mdx @@ -26,6 +26,9 @@ Typical fields include: - `paymentReference` - `txHash` - `isListening` +- `requestAmount` — the original requested amount in invoice currency +- `detectionSource` — how the payment was confirmed (`"request-network"` or `"lifi"`) +- `note` — additional context for non-standard settlements (e.g., LiFi fallback) - optional metadata such as `customerInfo` and `reference` diff --git a/api-features/secure-payment-pages.mdx b/api-features/secure-payment-pages.mdx index 3b3eec4..716d6c6 100644 --- a/api-features/secure-payment-pages.mdx +++ b/api-features/secure-payment-pages.mdx @@ -64,19 +64,21 @@ Secure payment pages support crosschain payments. When a payer connects their wa **Supported crosschain currencies:** USDC, USDT -**Supported crosschain chains:** Ethereum, Arbitrum, Base, OP Mainnet +**Supported crosschain chains:** Ethereum, Arbitrum, Base, OP Mainnet, Polygon See [Crosschain Payments](/api-features/crosschain-payments) for details on crosschain routing via LiFi. ## Smart Account Payments -The secure payment page supports gas-sponsored payments via [Alchemy Account Kit](https://accountkit.alchemy.com/) smart accounts (ERC-4337). When available, payers can use a smart account to execute payments without paying gas fees. +The secure payment page supports gas-sponsored payments via [Safe](https://safe.global/) smart accounts (ERC-4337), bundled and sponsored through [Pimlico](https://pimlico.io/). When available, payers can use a smart account to execute payments without paying gas fees. **How it works:** 1. The payer approves a spending cap from their EOA wallet to the smart account 2. The smart account batches the `transferFrom` (EOA to smart account) and the payment transaction into a single UserOperation -3. Gas is sponsored via an Alchemy gas policy — the payer pays zero gas +3. Gas is sponsored via Pimlico's paymaster — the payer pays zero gas + +**Supported chains for smart account payments:** Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, and Sepolia (testnet). Smart account payments are a client-side feature of the hosted secure payment page. There is no separate API for smart accounts — the same `GET /v2/secure-payments/:token/pay` endpoint provides the transaction calldata.