diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx index 696afe7..b1bdcb9 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). @@ -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. + @@ -167,7 +173,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/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-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