RequestNetwork · rodrigopavezi · Mar 30, 2026 · Mar 31, 2026 · Mar 31, 2026 · greptile-apps
diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx
@@ -1,42 +1,42 @@
 ---
 title: "Crosschain Payments"
 description: "Multi-network payment routing with automatic bridging via LiFi"
 ---

 <Warning>
 **Breaking change (March 2026):** The crosschain payment flow has been redesigned. The old payment-intent signing flow (`POST /v2/request/payment-intents/:paymentIntentId`) has been removed. Crosschain payments now return executable transaction calldata directly. See updated steps below.
 </Warning>

 ## Overview

 Crosschain payments allow users to pay a request using a stablecoin from a different blockchain network than the one specified on the request. For example, a payer can pay a request for USDC on Base using USDT from their Optimism wallet. Crosschain routing is powered by [LiFi](https://li.fi/), which aggregates bridges and DEXs to find optimal routes.

 ## Benefits

 - **Flexibility:** Payers can pay with their preferred stablecoin on any supported chain.
 - **Cost-Effective:** Automated routing balances cost and speed.
 - **Time-Saving:** Payers don't need to swap or bridge tokens manually.
 - **Simplified UX:** Payment settlement requires only 1 or 2 transactions from the payer.

 ## Crosschain Payments Supported Chains and Currencies

 For crosschain (and samechain) payments, the Request Network API supports USDC and USDT on 4 chains.

 <Info>
 Bridged USDC (USDC.e) is **not** supported for crosschain payments. Only native USDC is supported.
 </Info>

 ### Supported Chains

 - Ethereum
 - Arbitrum One
 - Base
 - OP Mainnet

 ### Supported Currencies

 <Warning>
 Crosschain payments work only with mainnet funds (real money). Test networks are not supported.
 </Warning>

 - USDC
@@ -46,7 +46,7 @@
 
 <Steps>
 <Step title="Create the request">
-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 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 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 of $1 or less due to bridge minimums.
-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 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 of $1 or less due to bridge minimums.
 
 Create the request via [POST /v2/request](https://api.request.network/open-api/#tag/v2request/POST/v2/request).
 </Step>
@@ -64,10 +64,10 @@

 - `chain` and `token` — the source chain and token
 - `fee` — total fee as a decimal
 - `feeBreakdown[]` — detailed fee components (gas, crosschain, platform)
 - `speed` — `"FAST"` for same-chain, seconds estimate for crosschain

 The API may also return samechain routes when the payer has funds on the same chain as `paymentCurrency`.

 ```json Example routes response
 {
@@ -137,7 +137,8 @@
     "paymentTransactionIndex": 1,
     "routeType": "crosschain",
     "quoteExpiresAt": 1742205771,
-    "hasEnoughBalance": true
+    "hasEnoughBalance": true,
+    "sourceAmount": "10.02"
   }
 }
 ```
@@ -145,11 +146,16 @@
 **Metadata fields:**
 - `stepsRequired` — number of transactions to execute (1 or 2)
 - `needsApproval` — whether a token approval transaction is needed first
 - `approvalTransactionIndex` — index of the approval tx in the array (or `null`)
 - `paymentTransactionIndex` — index of the payment/bridge tx
 - `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)
+
+<Info>
+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.
+</Info>
 </Step>
 
 <Step title="Execute the transactions">
@@ -167,7 +173,7 @@
 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
@@ -1,11 +1,11 @@
 ---
 title: "Payee Destinations"
 description: "Register and manage receiving routes using ERC-7828 interop addresses"
 ---

 ## Overview

 Payee destinations define where payments are received. Each destination encodes a wallet address, chain, and token into a single **ERC-7828 interop address**, creating a unique receiving route.

 Destinations are used by:
 - **Secure payments** — to resolve the payee, chain, and token from a `destinationId`
@@ -13,7 +13,7 @@

 ## ERC-7828 Address Format

 A destination ID combines the interop address with the token address:

 ```
 {walletAddress}@eip155:{chainId}#{checksum}:{tokenAddress}
@@ -27,8 +27,13 @@
 This encodes:
 - **Wallet:** `0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7`
 - **Chain:** Base (chainId `8453`)
+- **Checksum:** `ABCD1234` (auto-generated by the API for address verification)
 - **Token:** USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
 
+<Info>
+The checksum portion (`#ABCD1234`) is generated automatically by the API when you create a destination. You do not need to compute it yourself.
+</Info>
+
 ## How It Works
 
 <Steps>
@@ -100,6 +105,8 @@
 New chain ID.
 </ParamField>
 
+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
@@ -5,7 +5,7 @@

 ## Overview

 Payouts let you initiate payments without a separate request creation step. The API creates the request and returns executable transaction calldata in a single call.

 **Three payout modes:**
 - **Single** — Pay one recipient
@@ -14,7 +14,7 @@

 ## Single Payout

 Create a payment request and get transaction calldata in one call.

 ```bash
 curl -X POST "https://api.request.network/v2/payouts" \
@@ -41,11 +41,11 @@
 - `customerInfo` — Payer information (name, email, address)
 - `payer` — Payer wallet address (required for recurring)

 The response includes `requestId` and a `transactions` array with executable calldata.

 ## Batch Payout

 Pay multiple recipients in a single blockchain transaction. All payments must be on the same network.

 ```bash
 curl -X POST "https://api.request.network/v2/payouts/batch" \
@@ -55,13 +55,13 @@
     "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"
       }
@@ -82,8 +82,19 @@
 - `POST /v2/payouts` with `recurrence` object — Create a recurring schedule
 - `POST /v2/payouts/recurring/:id` — Submit the payer's permit signature to activate
 - `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
 
 <CardGroup cols={2}>

diff --git a/api-reference/secure-payments.mdx b/api-reference/secure-payments.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Secure Payments API Reference"
 description: "Generate secure payment URLs, retrieve payment metadata, and get executable calldata."
 ---

 ## Endpoints
@@ -8,8 +8,8 @@
 - `POST /v2/secure-payments` — Create a secure payment
 - `GET /v2/secure-payments` — Lookup by request ID
 - `GET /v2/secure-payments/:token` — Get payment metadata
 - `GET /v2/secure-payments/:token/pay` — Get payment calldata
 - `POST /v2/secure-payments/:token/intent` — Record crosschain payment intent

 ## Authentication

@@ -41,11 +41,11 @@
 Human-readable payment amount (e.g., `"10.50"`). Must be greater than 0.
 </ParamField>

 <ParamField body="feePercentage" type="string">
 Optional fee percentage from `0` to `100` (e.g., `"2.5"` for 2.5%).
 </ParamField>

 <ParamField body="feeAddress" type="string">
 Optional fee recipient address. Required when `feePercentage` is set.
 </ParamField>

@@ -127,7 +127,7 @@

 ## GET /v2/secure-payments/:token

 Retrieve payment metadata and display information. Returns amounts, destination info, status, and optionally crosschain payment options — but **not** executable transaction calldata. Use `/pay` for calldata.

 ### Path parameters

@@ -138,7 +138,7 @@
 ### Query parameters
 
 <ParamField query="wallet" type="string">
-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).
 </ParamField>
 
 <RequestExample>
@@ -166,7 +166,7 @@
    "network": "base"
  },
  "reference": "ORDER-2024-001",
  "paymentOptions": {
    "BASE": {
      "USDC": {
        "balance": "150.00",
@@ -224,26 +224,30 @@

 ## GET /v2/secure-payments/:token/pay
 
 Retrieve executable transaction calldata for the secure payment. For crosschain payments, provide `chain` and `token` query parameters to select the source route.
 
+<Info>
+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.
+</Info>
+
 ### Path parameters
 
 <ParamField path="token" type="string" required>
-Secure payment token.
+Secure payment token (ULID returned from `POST /v2/secure-payments`).
 </ParamField>
 
 ### Query parameters
 
 <ParamField query="wallet" type="string">
-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).
 </ParamField>
 
 <ParamField query="chain" type="string">
-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.
 </ParamField>
 
 <ParamField query="token" type="string">
-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`.
 </ParamField>
 
 <RequestExample>
@@ -327,7 +331,7 @@

 ### Error responses

 - `400`: invalid calldata request or unsupported crosschain configuration
 - `403`: token expired or not payable
 - `404`: token not found
 - `409`: secure payment already completed
@@ -337,7 +341,7 @@

 ## POST /v2/secure-payments/:token/intent

 Record a crosschain payment intent after the payer broadcasts the source-chain LiFi transaction. This allows the system to track the bridge execution and trigger payment detection on the destination chain.

 ### Path parameters


diff --git a/resources/supported-chains-and-currencies.mdx b/resources/supported-chains-and-currencies.mdx
@@ -11,10 +11,10 @@

 EVM chains supported for core payment flows include:

 **Mainnet:**
 - Ethereum
 - Arbitrum One
 - OP Mainnet
 - Base
 - Polygon
 - BSC
@@ -22,10 +22,10 @@
 - Fantom
 - Gnosis
 - Mantle
 - zkSync Era

 **Testnet:**
 - Sepolia

 For non-EVM support, Request Network API also supports Tron for USDT TRC-20 payments.

@@ -38,7 +38,7 @@
 </Card>

 <Info>
 The token list is a superset and may include tokens on chains outside your current payment flow. Cross-reference token entries with supported chains.
 </Info>

 ## Conversion Payments Supported Currencies
@@ -56,12 +56,12 @@
 - USDC
 - USDT
 - DAI
 - FAU (Sepolia)

 ## Tron Supported Network and Currency

 <Card title="Tron" icon="bolt">
 - **Availability:** Mainnet only
 - **Native Token:** TRX
 - **Supported Token:** USDT (TRC-20)
 - **Network ID:** `tron`
@@ -69,7 +69,7 @@
 </Card>
 
 <Warning>
-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.
 </Warning>
 
 To fetch supported payment currencies for an invoice currency:
@@ -78,10 +78,10 @@
 Get payment currency options available for a given invoice currency.
 </Card>

 ## Crosschain Payments Supported Currencies

 <Card title="Crosschain Payments" href="/api-features/crosschain-payments#crosschain-payments-supported-chains-and-currencies" icon="shuffle">
 View the supported chain/currency matrix for crosschain payments.
 </Card>

 ## Crypto-to-fiat Payments Supported Currencies

diff --git a/use-cases/checkout.mdx b/use-cases/checkout.mdx
@@ -1,14 +1,14 @@
 ---
 title: "Checkout"
 icon: "cart-shopping"
 description: "Accept crypto payments at point of purchase with automatic payment attribution and instant confirmation"
 ---

 ## Overview

 Accept crypto payments at the point of purchase with instant attribution and confirmation. Whether you're running an online store, selling digital goods, or processing event tickets, Request Network enables immediate crypto payments with automatic reconciliation at scale.

 Unlike traditional crypto payments where customers send funds and you manually match transactions to orders, Request IDs automatically connect each payment to its specific order with cryptographic certainty.

 **What you get:**
 - **Instant attribution** - Every payment automatically linked to the correct order via Request ID
@@ -123,19 +123,19 @@
 
 ## Developer Tools
 
-<Card 
-  title="Payment Widget Button" 
+<Card
+  title="Payment Widget Button"
   icon="credit-card"
-  href="#"
+  href="https://checkout.request.network"
 >
   **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)
 </Card>
 
@@ -155,7 +155,7 @@
  </Card>

  <Card title="Conversion Payments" icon="exchange">
    You price in fiat but want customers to pay in crypto at current exchange rates
  </Card>
 </CardGroup>

@@ -164,12 +164,12 @@
 ### Online Store Checkout
 Retailer processes thousands of daily orders with automatic payment attribution.

 **Example:** Customers pay in crypto at checkout, each order gets a unique Request ID for automatic matching to the correct order.

 ### 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.
@@ -192,9 +192,9 @@
     Recommended for checkout - bundles request creation with payment transaction generation
   </Card>
 
-  <Card 
-    title="Payment Widget Button" 
-    href="#"
+  <Card
+    title="Payment Widget Button"
+    href="https://checkout.request.network"
     icon="credit-card"
   >
     Pre-built React component with wallet connection and payment processing

diff --git a/use-cases/invoicing.mdx b/use-cases/invoicing.mdx
@@ -1,16 +1,16 @@
 ---
 title: "Invoicing"
 icon: "file-invoice"
 description: "Create crypto invoices with automatic payment detection and reconciliation"
 ---

 ## Overview

 Bring instant, verifiable payments to your invoicing flow. Generate invoices in fiat or crypto, let customers pay in their preferred token across [10+ EVM chains and Tron](/resources/supported-chains-and-currencies) in 500+ currencies, and receive automatic reconciliation with on-chain payment detection - no manual tracking, no infrastructure overhead.

 **What you get:**
 - **Permanent records** - Invoices stored on <Tooltip tip="InterPlanetary File System - a distributed storage network for permanent data">IPFS</Tooltip> create a tamper-proof audit trail
 - **Multi-currency flexibility** - Invoice in USD, get paid in crypto with automatic conversion
 - **Instant reconciliation** - Every invoice automatically linked to its <Tooltip tip="Blockchain-recorded transaction verified by network validators">on-chain</Tooltip> payment
 - **Cross-chain support** - Accept payments across [10+ EVM chains and Tron](/resources/supported-chains-and-currencies) in 500+ currencies
 - **Webhook automation** - Real-time payment confirmations for backend integration
@@ -38,7 +38,7 @@
  href="https://easyinvoice.request.network" 
  icon="external-link"
 >
  Create invoices, accept crypto payments, and track payment status - all powered by Request Network API
 </Card>

 **What you'll see:**
@@ -74,20 +74,20 @@
     [Try it now →](https://easyinvoice.request.network)
   </Card>
 
-  <Card 
-    title="Fork EasyInvoice" 
+  <Card
+    title="Fork EasyInvoice"
     icon="code-fork"
-    href="#"
+    href="https://github.com/RequestNetwork/easy-invoice"
   >
     **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)
   </Card>
 </CardGroup>
 
@@ -171,12 +171,12 @@
     Set up your account and get API credentials
   </Card>
 
-  <Card 
-    title="View Invoicing Examples" 
-    href="#"
+  <Card
+    title="View Integration Guide"
+    href="/api-features/secure-payment-integration-guide"
     icon="code"
   >
-    See code examples for common invoicing workflows
+    See integration examples for payment workflows
   </Card>
 
   <Card 

diff --git a/use-cases/payment-detection.mdx b/use-cases/payment-detection.mdx
@@ -1,18 +1,18 @@
 ---
 title: "Payment Detection"
 icon: "credit-card"
 description: "Automatically detect and verify crypto payments with real-time blockchain monitoring and webhooks"
 ---

 ## Overview

 Traditional crypto payments lack business context. You receive a <Tooltip tip="Unique identifier of a transaction recorded on the blockchain">transaction hash,</Tooltip> but don't know which customer, invoice, or order it's for. Manual reconciliation is error-prone and doesn't scale.

 Request IDs solve this by attaching business context to every payment. Each request gets a unique Request ID that connects payments back to your specific invoice, order, or subscription with cryptographic certainty.
 
 **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** - <Tooltip tip="HTTP callbacks that notify your server when payment events occur">Webhooks</Tooltip> for instant payment confirmations
 - **Zero manual work** - No spreadsheets, no guessing, no payment collisions
 
@@ -26,7 +26,7 @@
  </Card>

  <Card title="High Payment Volume" icon="chart-line">
    Processing hundreds or thousands of crypto payments where manual tracking doesn't scale
  </Card>

  <Card title="Wallet Management Overhead" icon="key">
@@ -34,26 +34,26 @@
  </Card>

  <Card title="Cross-chain Payments" icon="link">
    Accepting payments across multiple blockchains and need unified detection without managing multiple APIs
  </Card>
 </CardGroup>

 ## Common Scenarios

 ### E-commerce Checkout
 Accept crypto payments at scale without generating unique addresses for each customer.

 **Example:** An e-commerce platform processes 10,000+ crypto orders per day. Each order gets a unique Request ID - customers pay to a single wallet address, and every payment is automatically attributed to the correct order.

 ### SaaS Subscriptions
 Add crypto as a payment option for recurring billing alongside traditional payment methods.

 **Example:** A SaaS company uses Stripe for card payments but offers USDC for monthly subscriptions. Payment Detection automatically confirms renewals and updates subscription status without manual tracking.

 ### Manual Invoices with Crypto Settlement
 Send invoices through existing channels (email, PDF) and accept crypto payments with automatic reconciliation.

 **Example:** A freelancer emails invoices as PDFs with a Request ID. When clients pay in crypto, the accounting software automatically marks invoices as paid via <Tooltip tip="HTTP callbacks that notify your server when payment events occur">webhook</Tooltip> - no manual checking required.

 <Info>
 These scenarios all use automatic payment detection. [See technical details on detection methods and configuration →](/api-features/payment-detection)