docs(create-requests): rewrite with workflows, examples, and remove AI warning

api-features/create-requests.mdx

@@ -3,81 +3,142 @@ title: "Create Requests"
 description: "Request creation workflows and configuration for invoices and payment collection"
 ---
 
-<Warning>
-**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).
-</Warning>
-
 ## 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
 
-<CardGroup cols={2}>
-  <Card title="Invoice Requests" icon="file-invoice">
-    Traditional invoicing with payee details
-  </Card>
-
-  <Card title="Payment Requests" icon="money-bill">
-    Direct payment collection workflows
-  </Card>
-</CardGroup>
+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 <webhook url> {"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
 
-<CardGroup cols={2}>
-  <Card title="ERC20 Networks" icon="coins">
-    USDC, USDT, DAI token payments
-  </Card>
-
-  <Card title="Native Networks" icon="ethereum">
-    ETH, MATIC, BNB direct payments
-  </Card>
-</CardGroup>
+* **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
   </Card>
 
-  <Card title="Payroll" href="/use-cases/payroll">
-    Employee payment requests
+  <Card title="Checkout" href="/use-cases/checkout">
+    Payment collection at checkout
+  </Card>
+
+  <Card title="Integration Tutorial" href="/api-setup/integration-tutorial">
+    Complete implementation example
+  </Card>
+
+  <Card title="Recurring Payments" href="/api-features/recurring-payments">
+    Subscription and billing workflows
   </Card>
 </CardGroup>
 
-## 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.
+See [API Reference](https://api.request.network/open-api) for complete technical documentation with OpenAPI specs.