From 7a351c3c30a24af128b306b6bb1cf2efbc1c5685 Mon Sep 17 00:00:00 2001 From: Aimen Sahnoun Date: Mon, 2 Mar 2026 00:29:28 +0400 Subject: [PATCH] =?UTF-8?q?docs(api-features):=20align=20create-requests?= =?UTF-8?q?=20page=20with=20verified=20API=20behavior=20Refactor=20the=20C?= =?UTF-8?q?reate=20Requests=20docs=20to=20keep=20the=20Mintlify=20layout?= =?UTF-8?q?=20while=20replacing=20AI-generated/uncertain=20content=20with?= =?UTF-8?q?=20verified=20guidance=20from=20legacy=20docs.=20-=20Removed=20?= =?UTF-8?q?inaccurate=20sections=20and=20fields=20(`Due=20Date`,=20`Custom?= =?UTF-8?q?er=20Info`,=20`Reference`,=20and=20generic=20=E2=80=9CContent?= =?UTF-8?q?=20Data=E2=80=9D=20block)=20-=20Reworked=20=E2=80=9CRequest=20T?= =?UTF-8?q?ypes=E2=80=9D=20into=20clearer=20workflow-based=20guidance=20(i?= =?UTF-8?q?nvoice-first=20vs=20payment-first)=20-=20Updated=20the=20flow?= =?UTF-8?q?=20diagram=20and=20examples=20to=20reflect=20actual=20request/p?= =?UTF-8?q?ayment=20flow=20-=20Cleaned=20up=20links=20and=20removed=20refe?= =?UTF-8?q?rences=20to=20hidden/unsupported=20pages=20-=20Pointed=20API=20?= =?UTF-8?q?reference=20to=20the=20canonical=20OpenAPI=20URL:=20https://api?= =?UTF-8?q?.request.network/open-api=20Result:=20the=20page=20now=20preser?= =?UTF-8?q?ves=20the=20current=20Mintlify=20structure,=20but=20the=20conte?= =?UTF-8?q?nt=20is=20tighter=20and=20aligned=20with=20real=20API=20usage.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-features/create-requests.mdx | 192 +++++++++++++++++++++---------- 1 file changed, 133 insertions(+), 59 deletions(-) diff --git a/api-features/create-requests.mdx b/api-features/create-requests.mdx index f709055..b9bdda5 100644 --- a/api-features/create-requests.mdx +++ b/api-features/create-requests.mdx @@ -3,81 +3,142 @@ title: "Create Requests" description: "Request creation workflows and configuration for invoices and payment collection" --- - -**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions). - - ## Overview Request creation forms the foundation of Request Network operations, enabling structured payment collection through invoice generation and payment request workflows. -## Request Types +## What You Can Do - - - Traditional invoicing with payee details - - - - Direct payment collection workflows - - +At its core, the Request Network API empowers you to: + +* **Create Requests:** Define payment requests with information such as payee, payer (optional), amount, currency, and recurrence (optional). +* **Facilitate Payments:** Return transaction calldata, ready to be signed by end-users and sent to the blockchain for secure and transparent value transfer. +* **Deliver Webhook Notifications:** Receive instant updates on payment status changes, enabling your application to react dynamically to completed transactions. +* **Partial Payment Support:** Pay a portion of a request instead of the full amount at once. This unlocks powerful use cases such as: + * **Split payment:** Split a payment 50% USDC on Base and 50% with USDT on Optimism. + * **Gradual payment plans:** Allow users to pay large invoices in smaller chunks. + * **Risk mitigation:** Test with small amounts before completing large payments. + +The API automatically tracks payment progress, showing `partially_paid` status until the request is fully paid, and prevents overpayment by capping amounts to the remaining balance. + +## Workflows + +### Invoice-first Workflow + +Create a payment request first, then allow customers to pay at their convenience. + +**Flow:** +1. Create request with payee, amount, and currency +2. Share request ID or payment reference with customer +3. Customer retrieves payment calldata +4. Customer executes transaction +5. Receive webhook confirmation + +**Use Cases:** Professional invoicing, B2B payments, subscription billing + +### Payment-first Workflow + +Send payments directly without creating a request first using the `/payouts` endpoint. + +**Flow:** +1. Call `/payouts` with payee and amount +2. Receive transaction calldata immediately +3. Execute transaction +4. Request is created and paid in one step + +**Use Cases:** Vendor payments, contractor payouts, immediate transfers ## How It Works +The following diagram illustrates the typical flow for creating and paying requests using the Request Network API: + ```mermaid -graph TD - A[Define Request] --> B[Select Payment Network] - B --> C[Configure Properties] - C --> D[Store on IPFS] - D --> E[Index on Blockchain] - E --> F[Generate Request ID] +sequenceDiagram + actor User + participant App + participant Request Network API + participant Blockchain + + User->>App: Create Request + App->>Request Network API: POST /request {apiKey, payee, payer?, amount, invoiceCurrency, paymentCurrency} + Request Network API-->>App: 201 Created {requestId, paymentReference} + + User->>App: Pay Request + App->>Request Network API: GET /request/{paymentReference}/pay {apiKey} + Request Network API-->>App: 200 OK {transactions[calldata], metadata{stepsRequired, needsApproval, approvalTransactionIndex}} + Request Network API-)Request Network API: Start listening {paymentReference} + + opt if needs approval + App->>User: Prompt for approval signature + User-->>App: Sign approval transaction + App->>Blockchain: Submit approval transaction + end + + App->>User: Prompt for payment signature + User-->>App: Sign payment transaction + App->>Blockchain: Submit payment transaction + + Request Network API->>Request Network API: Payment detected, stop listening {paymentReference} + Request Network API->>App: POST {"payment.confirmed", requestId, paymentReference, request scan link, timestamp} + App-->>User: Payment Complete ``` -**Creation Process:** -1. **Define:** Set payee, payer, amount, and currency details -2. **Configure:** Choose payment network and accepted tokens -3. **Store:** Decentralized storage on IPFS -4. **Index:** Blockchain indexing for discovery -5. **Track:** Real-time status monitoring - ## Request Properties ### Core Information -- **Payee:** Request creator/recipient address -- **Payer:** Payment sender address (optional) -- **Amount:** Payment amount and currency -- **Due Date:** Payment deadline (optional) -### Payment Configuration -- **Payment Network:** ERC20, ETH, or specialized networks -- **Accepted Tokens:** Supported payment currencies -- **Conversion Settings:** Fiat-denominated crypto payments +* **Payee:** The wallet address of the payee (Ethereum 0x... or TRON T...). Required for all requests except crypto-to-fiat. +* **Payer:** The wallet address of the payer (optional) +* **Amount:** The payable amount of the invoice, in human readable format +* **Invoice Currency:** Invoice Currency ID, from the [Request Network Token List](/resources/token-list) e.g: USD +* **Payment Currency:** Payment currency ID, from the [Request Network Token List](/resources/token-list) e.g: ETH-sepolia-sepolia -## Payment Network Selection +### Optional Configuration - - - USDC, USDT, DAI token payments - - - - ETH, MATIC, BNB direct payments - - +* **Recurrence:** For recurring payments, specify start date and frequency (DAILY, WEEKLY, MONTHLY, YEARLY) +* **Fee Settings:** Specify fee percentage and fee address for platform fee collection -### Supported Networks -- **Mainnet:** Ethereum, Polygon, Arbitrum, Optimism -- **Mainnet (non-EVM):** Tron (USDT TRC-20 only) -- **Sidechains:** BSC, Gnosis, Fantom, Avalanche -- **Testnets:** Sepolia, Mumbai for development +### Supported Chains and Currencies -## Content Data +See [Supported Chains and Currencies](/resources/supported-chains-and-currencies) for the complete list of available networks and tokens. + +## Quick Example + +Here's a simple example of creating a request: + +```javascript +const response = await fetch('https://api.request.network/v2/request', { + method: 'POST', + headers: { + 'X-Api-Key': process.env.RN_API_KEY, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + payee: '0x...', + amount: '100', + invoiceCurrency: 'USD', + paymentCurrency: 'USDC-base-base' + }) +}); + +const { requestId, paymentReference } = await response.json(); +``` -Attach additional information to requests: -- **Invoice Details:** Line items, tax information -- **Business Information:** Company details, terms -- **Custom Metadata:** Application-specific data +Then get the payment calldata: + +```javascript +const payResponse = await fetch( + `https://api.request.network/v2/request/${paymentReference}/pay`, + { + headers: { 'X-Api-Key': process.env.RN_API_KEY } + } +); + +const { transactions, metadata } = await payResponse.json(); +// Execute transactions with your wallet... +``` + +For a complete working example, see the [Integration Tutorial](/api-setup/integration-tutorial). ## Used In @@ -86,11 +147,24 @@ Attach additional information to requests: Business invoice generation - - Employee payment requests + + Payment collection at checkout + + + + Complete implementation example + + + + Subscription and billing workflows -## Implementation Details +### Key Features + +* **Human-readable amounts:** Send amounts in standard format (e.g., "0.1"), no BigNumber conversions needed +* **Automatic payment tracking:** Real-time status updates via webhooks +* **Flexible currencies:** Request in one currency, pay in another with automatic conversion +* **Partial payments:** Track multiple payments against a single request -See [API Reference - Create Requests](/api-reference/endpoints/create-request) for complete technical documentation. \ No newline at end of file +See [API Reference](https://api.request.network/open-api) for complete technical documentation with OpenAPI specs.