diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index 696afe7..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 @@ -46,7 +47,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). @@ -137,7 +138,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 +152,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. + @@ -167,7 +174,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 8d680b1..ba70dd9 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 @@ -100,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/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/payouts.mdx b/api-features/payouts.mdx index a66e010..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" } @@ -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/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. diff --git a/api-reference/secure-payments.mdx b/api-reference/secure-payments.mdx index 4969eba..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). @@ -226,24 +226,28 @@ 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 -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). -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/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: diff --git a/use-cases/checkout.mdx b/use-cases/checkout.mdx index 97aa1de..e8392c5 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) @@ -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. @@ -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 Webhooks for instant payment confirmations - **Zero manual work** - No spreadsheets, no guessing, no payment collisions