diff --git a/api-features/batch-payments.mdx b/api-features/batch-payments.mdx
new file mode 100644
index 0000000..02dffc8
--- /dev/null
+++ b/api-features/batch-payments.mdx
@@ -0,0 +1,56 @@
+---
+title: "Batch Payments"
+description: "Process multiple payments in a single transaction for gas optimization"
+---
+
+## Overview
+
+Batch payments allow you to process multiple direct or conversion payments in a single blockchain transaction, significantly reducing gas costs and simplifying payment operations.
+
+## How It Works
+
+```mermaid
+graph TD
+ A[Multiple Recipients] --> B[Single Transaction]
+ B --> C[Atomic Execution]
+ C --> D[All Succeed or All Fail]
+```
+
+**Benefits:**
+- **Gas Savings:** Up to 60% reduction in total gas costs
+- **Atomic Operations:** All payments succeed or fail together
+- **Simplified Management:** One transaction to monitor
+
+## Requirements
+
+- All payments must be on the same network
+- Supports Native, ERC20, and Conversion payments
+- Maximum batch size limited by block gas limit
+
+## Use Cases
+
+
+
+ Pay multiple employees simultaneously
+
+
+
+ Process multiple supplier invoices
+
+
+
+## Used In
+
+
+
+ Efficient employee payments
+
+
+
+ Bulk vendor payments
+
+
+
+## Implementation Details
+
+See [API Reference - Batch Payments](/api-reference/batch-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/conversion-payments.mdx b/api-features/conversion-payments.mdx
new file mode 100644
index 0000000..c08d3cf
--- /dev/null
+++ b/api-features/conversion-payments.mdx
@@ -0,0 +1,54 @@
+---
+title: "Conversion Payments"
+description: "Fiat-denominated requests settled in cryptocurrency with real-time conversion"
+---
+
+## Overview
+
+Conversion payments allow you to create requests denominated in fiat currencies (USD, EUR) while receiving settlement in cryptocurrency, with automatic exchange rate conversion at payment time.
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Request: $100 USD] --> B[Real-time Rate]
+ B --> C[Pay: 0.041 ETH]
+ C --> D[Receive: 0.041 ETH]
+```
+
+**Benefits:**
+- Stable pricing in familiar currencies
+- Automatic exchange rate handling
+- No manual conversion required
+
+## Supported Fiat Currencies
+
+- **USD** - US Dollar
+- **EUR** - Euro
+- **GBP** - British Pound
+- **CNY** - Chinese Yuan
+- **JPY** - Japanese Yen
+
+## Exchange Rate Sources
+
+Real-time rates from multiple providers ensure accuracy and reliability.
+
+## Used In
+
+
+
+ Professional invoices in fiat
+
+
+
+ E-commerce pricing
+
+
+
+ Predictable subscription pricing
+
+
+
+## Implementation Details
+
+See [API Reference - Conversion Payments](/api-reference/conversion-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/create-requests.mdx b/api-features/create-requests.mdx
new file mode 100644
index 0000000..8fa54dd
--- /dev/null
+++ b/api-features/create-requests.mdx
@@ -0,0 +1,91 @@
+---
+title: "Create Requests"
+description: "Request creation workflows and configuration for invoices and payment collection"
+---
+
+## Overview
+
+Request creation forms the foundation of Request Network operations, enabling structured payment collection through invoice generation and payment request workflows.
+
+## Request Types
+
+
+
+ Traditional invoicing with payee details
+
+
+
+ Direct payment collection workflows
+
+
+
+## How It Works
+
+```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]
+```
+
+**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
+
+## Payment Network Selection
+
+
+
+ USDC, USDT, DAI token payments
+
+
+
+ ETH, MATIC, BNB direct payments
+
+
+
+### Supported Networks
+- **Mainnet:** Ethereum, Polygon, Arbitrum, Optimism
+- **Sidechains:** BSC, Gnosis, Fantom, Avalanche
+- **Testnets:** Sepolia, Mumbai for development
+
+## Content Data
+
+Attach additional information to requests:
+- **Invoice Details:** Line items, tax information
+- **Business Information:** Company details, terms
+- **Custom Metadata:** Application-specific data
+
+## Used In
+
+
+
+ Business invoice generation
+
+
+
+ Employee payment requests
+
+
+
+## Implementation Details
+
+See [API Reference - Create Requests](/api-reference/endpoints/create-request) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/crosschain-payments.mdx b/api-features/crosschain-payments.mdx
new file mode 100644
index 0000000..3e23b78
--- /dev/null
+++ b/api-features/crosschain-payments.mdx
@@ -0,0 +1,67 @@
+---
+title: "Crosschain Payments"
+description: "Multi-network payment routing with automatic bridging and optimization"
+---
+
+## Overview
+
+Crosschain payments enable seamless transactions across different blockchain networks, allowing payers to send from their preferred chain while payees receive on their preferred network.
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Payer: USDC on Polygon] --> B[Bridge Protocol]
+ B --> C[Payee: USDC on Base]
+```
+
+**Benefits:**
+- Access to funds across multiple chains
+- Automatic routing optimization
+- No manual bridging required
+
+## Samechain Payments
+
+A special case of crosschain infrastructure that converts currencies on the same network (e.g., ETH → USDC on Ethereum).
+
+## Supported Networks
+
+
+
+ Ethereum, BSC, Avalanche, Fantom
+
+
+
+ Polygon, Arbitrum, Base, Optimism
+
+
+
+## Bridge Protocols
+
+- **LayerZero:** Ultra Light Node security
+- **Stargate:** Liquidity-based bridging
+- **Automatic Selection:** Optimal route chosen
+
+## Used In
+
+
+
+ Flexible payment options
+
+
+
+ Accept from any chain
+
+
+
+ Send to preferred networks
+
+
+
+ Multi-chain employee payments
+
+
+
+## Implementation Details
+
+See [API Reference - Crosschain Payments](/api-reference/crosschain-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/crypto-to-fiat-payments.mdx b/api-features/crypto-to-fiat-payments.mdx
new file mode 100644
index 0000000..e50883e
--- /dev/null
+++ b/api-features/crypto-to-fiat-payments.mdx
@@ -0,0 +1,61 @@
+---
+title: "Crypto-to-fiat Payments"
+description: "USDC payments settled directly to bank accounts with automatic conversion"
+---
+
+## Overview
+
+Crypto-to-fiat payments enable seamless conversion from cryptocurrency to traditional bank account deposits, combining the speed of crypto with the familiarity of fiat settlement.
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Payer: USDC] --> B[KYC Verification]
+ B --> C[Compliance Check]
+ C --> D[Bank Transfer]
+ D --> E[Payee: USD in Bank]
+```
+
+**Benefits:**
+- **Fiat Settlement:** Receive traditional currency in bank accounts
+- **Regulatory Compliance:** Built-in KYC and compliance workflows
+- **Global Reach:** Support for multiple countries and currencies
+
+## Requirements
+
+
+
+ Identity verification required for compliance
+
+
+
+ Valid bank account for settlement
+
+
+
+## Supported Networks
+
+- **Production:** USDC on Ethereum, Polygon, Arbitrum
+- **Sandbox:** USDC on Sepolia (testing)
+
+## Settlement Time
+
+- **Processing:** 1-3 business days
+- **Compliance:** Additional time for KYC verification
+
+## Used In
+
+
+
+ Traditional business payments
+
+
+
+ Employee fiat compensation
+
+
+
+## Implementation Details
+
+See [API Reference - Crypto-to-fiat Payments](/api-reference/crypto-to-fiat-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/custom-fees.mdx b/api-features/custom-fees.mdx
new file mode 100644
index 0000000..272fb76
--- /dev/null
+++ b/api-features/custom-fees.mdx
@@ -0,0 +1,79 @@
+---
+title: "Custom Fees"
+description: "Flexible fee structures for service providers and payment processors"
+---
+
+## Overview
+
+Custom fees enable service providers to add their own fees to payment requests, supporting business models that require fee collection from transactions.
+
+## Fee Types
+
+
+
+ Absolute amount in any currency
+
+
+
+ Relative fees based on payment amount
+
+
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Base Amount: $100] --> B[+ Service Fee: $5]
+ B --> C[+ Network Fee: 0.5%]
+ C --> D[Total: $105.50]
+```
+
+**Fee Collection:**
+- **Automatic:** Fees collected during payment
+- **Split:** Separate fee recipient addresses
+- **Transparent:** Clear fee breakdown for payers
+
+## Fee Configuration
+
+### Service Provider Fees
+- **Platform Fee:** Your service commission
+- **Processing Fee:** Payment handling charges
+- **Custom Fee:** Application-specific charges
+
+### Network Fees
+- **Gas Optimization:** Efficient transaction bundling
+- **Cross-chain:** Bridge and routing fees
+- **Multi-token:** Token conversion costs
+
+## Fee Recipients
+
+### Single Recipient
+All fees collected to one address
+
+### Multiple Recipients
+Split fees across multiple addresses with defined percentages
+
+### Fee Tokens
+- **Same Currency:** Fees in request currency
+- **Different Currency:** Fees in alternative tokens
+- **Multi-currency:** Mixed fee structures
+
+## Integration Patterns
+
+
+
+ Platform commission on transactions
+
+
+
+ Processing fees and margins
+
+
+
+## Detailed Fee Breakdowns
+
+Complete fee transparency including USD amounts available in payment queries and responses.
+
+## Implementation Details
+
+See [API Reference - Custom Fees](/api-reference/custom-fees) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/fee-breakdowns.mdx b/api-features/fee-breakdowns.mdx
new file mode 100644
index 0000000..9073730
--- /dev/null
+++ b/api-features/fee-breakdowns.mdx
@@ -0,0 +1,105 @@
+---
+title: "Fee Breakdowns"
+description: "Comprehensive fee transparency with USD amounts and detailed cost structures"
+---
+
+## Overview
+
+Detailed fee breakdowns provide complete transparency into all costs associated with payments, including network fees, service fees, and USD equivalent amounts for better financial planning.
+
+## Fee Components
+
+
+
+ Blockchain transaction costs
+
+
+
+ Platform and processing fees
+
+
+
+## How It Works
+
+```mermaid
+graph TD
+ A[Payment Request] --> B[Calculate Base Amount]
+ B --> C[Add Service Fees]
+ C --> D[Add Network Fees]
+ D --> E[Convert to USD]
+ E --> F[Fee Breakdown Response]
+```
+
+**Calculation Process:**
+1. **Base Amount:** Original payment amount
+2. **Service Fees:** Platform and custom fees
+3. **Network Fees:** Gas and transaction costs
+4. **USD Conversion:** Real-time exchange rates
+5. **Breakdown:** Itemized fee structure
+
+## Fee Categories
+
+### Platform Fees
+- **Request Network Fee:** Protocol usage fee
+- **API Service Fee:** Request API processing fee
+- **Custom Fees:** Application-specific charges
+
+### Network Fees
+- **Gas Fees:** Transaction execution costs
+- **Bridge Fees:** Cross-chain transfer costs
+- **Token Conversion:** DEX swap fees
+
+## USD Amount Calculations
+
+### Real-time Conversion
+- **Live Rates:** Current market exchange rates
+- **Historical Rates:** Rates at payment time
+- **Multi-currency:** Support for various fiat currencies
+
+### Breakdown Format
+```json
+{
+ "baseAmount": {
+ "crypto": "100 USDC",
+ "usd": "$100.00"
+ },
+ "fees": {
+ "network": {
+ "crypto": "0.25 USDC",
+ "usd": "$0.25"
+ },
+ "service": {
+ "crypto": "2.5 USDC",
+ "usd": "$2.50"
+ }
+ },
+ "total": {
+ "crypto": "102.75 USDC",
+ "usd": "$102.75"
+ }
+}
+```
+
+## Integration Points
+
+
+
+ Fee estimates for payment routing
+
+
+
+ Historical fee information
+
+
+
+## Available Endpoints
+
+Fee breakdowns are included in:
+- **Payment route calculations**
+- **GET /payments responses**
+- **Request creation responses**
+- **Payment status updates**
+
+## Implementation Details
+
+See [API Reference - Fee Breakdowns](/api-reference/fee-breakdowns) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/partial-payments.mdx b/api-features/partial-payments.mdx
new file mode 100644
index 0000000..201ae7f
--- /dev/null
+++ b/api-features/partial-payments.mdx
@@ -0,0 +1,65 @@
+---
+title: "Partial Payments"
+description: "Split payments across multiple transactions and funding sources"
+---
+
+## Overview
+
+Partial payments allow requests to be fulfilled through multiple transactions, enabling split payments, installment plans, and flexible funding approaches.
+
+## How It Works
+
+```mermaid
+graph TD
+ A[Request: $1000] --> B[Payment 1: $400]
+ A --> C[Payment 2: $300]
+ A --> D[Payment 3: $300]
+ B --> E[Request Fulfilled]
+ C --> E
+ D --> E
+```
+
+**Benefits:**
+- **Flexible Payment Plans:** Installments and split payments
+- **Multiple Funding Sources:** Different wallets, chains, or currencies
+- **Risk Management:** Partial fulfillment tracking
+
+## Use Cases
+
+
+
+ Break large payments into smaller amounts
+
+
+
+ Group payments or shared expenses
+
+
+
+## Supported Payment Types
+
+Works with all payment types except Crypto-to-fiat payments:
+- Native & ERC20 payments
+- Conversion payments
+- Crosschain payments
+- Batch payments
+
+## Used In
+
+
+
+ Large invoice installments
+
+
+
+ Flexible payment options
+
+
+
+ Partial subscription payments
+
+
+
+## Implementation Details
+
+See [API Reference - Partial Payments](/api-reference/partial-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/payment-detection.mdx b/api-features/payment-detection.mdx
new file mode 100644
index 0000000..99992e5
--- /dev/null
+++ b/api-features/payment-detection.mdx
@@ -0,0 +1,73 @@
+---
+title: "Payment Detection"
+description: "Real-time monitoring and verification of blockchain payment completion"
+---
+
+## Overview
+
+Payment detection automatically monitors blockchain networks to verify when payments are completed, providing real-time status updates without manual verification.
+
+## Detection Methods
+
+
+
+ Direct network monitoring
+
+
+
+ Smart contract event detection
+
+
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Payment Initiated] --> B[Blockchain Monitor]
+ B --> C[Transaction Confirmed]
+ C --> D[Payment Detected]
+ D --> E[Status Updated]
+```
+
+**Process:**
+1. **Monitor:** Continuous blockchain scanning
+2. **Detect:** Payment transaction identification
+3. **Verify:** Confirmation count validation
+4. **Update:** Real-time status synchronization
+
+## Supported Networks
+
+### Mainnet Networks
+- Ethereum, Polygon, Arbitrum, Optimism
+- Gnosis, BSC, Fantom, Avalanche
+
+### Testnet Networks
+- Sepolia, Mumbai, Arbitrum Goerli
+
+## Detection Features
+
+### Real-time Updates
+- **Instant Detection:** Sub-second payment identification
+- **Confirmation Tracking:** Block confirmation monitoring
+- **Status Webhooks:** Automatic notifications
+
+### Multi-currency Support
+- **Native Tokens:** ETH, MATIC, BNB, AVAX
+- **ERC20 Tokens:** USDC, USDT, DAI, and more
+- **Custom Tokens:** Any ERC20-compatible token
+
+## Integration Points
+
+
+
+ Automated payment notifications
+
+
+
+ Manual payment status checking
+
+
+
+## Implementation Details
+
+See [API Reference - Payment Detection](/api-reference/payment-detection) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/payment-types-overview.mdx b/api-features/payment-types-overview.mdx
new file mode 100644
index 0000000..bd9761a
--- /dev/null
+++ b/api-features/payment-types-overview.mdx
@@ -0,0 +1,54 @@
+---
+title: "Payment Types Overview"
+description: "Understanding Invoice-first vs Payment-first workflows and direct payment types"
+---
+
+## Overview
+
+Request Network supports two primary payment workflows and multiple payment types to accommodate different business needs.
+
+## Payment Workflows
+
+### Invoice-first Workflow
+Create a payment request first, then allow customers to pay at their convenience.
+
+**Use Cases:** Professional invoicing, B2B payments, formal payment collection
+
+### Payment-first Workflow
+Send payments directly without creating a request first.
+
+**Use Cases:** Vendor payments, contractor payouts, immediate transfers
+
+## Direct Payment Types
+
+**Direct Payments** include Native, ERC20, and Conversion payments - the foundational payment methods that other features build upon.
+
+
+
+ Simple crypto-to-crypto payments
+
+
+
+ Fiat-denominated, crypto-settled
+
+
+
+ Multi-network payment routing
+
+
+
+## Used In
+
+
+
+ Invoice-first workflow with payment requests
+
+
+
+ Payment-first workflow for direct transfers
+
+
+
+## Implementation Details
+
+See [API Reference - Payment Types](/api-reference/payment-types) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/query-payments.mdx b/api-features/query-payments.mdx
new file mode 100644
index 0000000..28210cb
--- /dev/null
+++ b/api-features/query-payments.mdx
@@ -0,0 +1,86 @@
+---
+title: "Query Payments"
+description: "Advanced payment search and filtering with the GET /payments endpoint"
+---
+
+## Overview
+
+The GET /payments endpoint provides comprehensive payment search and filtering capabilities, enabling detailed payment history analysis and transaction monitoring.
+
+## Endpoint Features
+
+
+
+ Multiple search criteria
+
+
+
+ Large dataset management
+
+
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Query Parameters] --> B[Filter Payments]
+ B --> C[Sort Results]
+ C --> D[Paginate Response]
+ D --> E[Return Data]
+```
+
+**Search Process:**
+1. **Filter:** Apply search criteria
+2. **Sort:** Order by date, amount, or status
+3. **Paginate:** Handle large result sets
+4. **Return:** Structured payment data
+
+## Filter Options
+
+### Basic Filters
+- **Date Range:** Start and end dates
+- **Amount Range:** Minimum and maximum amounts
+- **Currency:** Specific token or fiat currency
+- **Status:** Payment completion state
+
+### Advanced Filters
+- **Payer Address:** Filter by payment sender
+- **Payee Address:** Filter by payment recipient
+- **Transaction Hash:** Specific transaction lookup
+- **Request ID:** Payments for specific requests
+
+## Network Filtering
+
+
+
+ Payments on specific blockchain
+
+
+
+ Cross-chain payment search
+
+
+
+### Supported Networks
+Filter payments across Ethereum, Polygon, Arbitrum, BSC, and other supported networks.
+
+## Response Data
+
+### Payment Information
+- **Basic Details:** Amount, currency, timestamp
+- **Network Data:** Blockchain, transaction hash, block number
+- **Participants:** Payer and payee addresses
+- **Status:** Confirmation state and payment completion
+
+### Enhanced Data
+- **Fee Breakdowns:** Detailed fee structure with USD amounts
+- **Exchange Rates:** Historical conversion rates
+- **Gas Costs:** Transaction fee information
+
+## Pagination
+
+Handle large datasets with cursor-based pagination for optimal performance.
+
+## Implementation Details
+
+See [API Reference - GET /payments](/api-reference/endpoints/get-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/query-requests.mdx b/api-features/query-requests.mdx
new file mode 100644
index 0000000..8068890
--- /dev/null
+++ b/api-features/query-requests.mdx
@@ -0,0 +1,101 @@
+---
+title: "Query Requests"
+description: "Request status monitoring, lifecycle management, and information retrieval"
+---
+
+## Overview
+
+Query requests provides comprehensive request status monitoring and information retrieval, enabling real-time tracking of payment requests throughout their lifecycle.
+
+## Request Status Lifecycle
+
+
+
+ Created, pending, partially paid
+
+
+
+ Paid, cancelled, expired
+
+
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Request ID] --> B[Query Status]
+ B --> C[Retrieve Info]
+ C --> D[Check Payments]
+ D --> E[Update Status]
+```
+
+**Query Process:**
+1. **Identify:** Use request ID for lookup
+2. **Retrieve:** Get current request information
+3. **Analyze:** Check payment status and history
+4. **Update:** Reflect latest blockchain state
+
+## Status Types
+
+### Request States
+- `created` - Request initialized and stored
+- `pending` - Awaiting payment completion
+- `paid` - Full payment received and confirmed
+- `cancelled` - Request cancelled by creator
+- `expired` - Past due date without payment
+
+### Payment States
+- `no_payment` - No payment transactions detected
+- `partially_paid` - Partial payment received
+- `paid` - Full payment amount received
+- `overpaid` - Payment exceeds requested amount
+
+## Query Methods
+
+
+
+ Detailed status for specific request
+
+
+
+ Multiple request status in one call
+
+
+
+### Information Retrieved
+- **Basic Details:** Amount, currency, participants
+- **Payment History:** Transaction details and confirmations
+- **Status Timeline:** Creation, updates, completion dates
+- **Network Data:** Blockchain and transaction information
+
+## Real-time Monitoring
+
+### Automatic Updates
+Combine with [Payment Detection](/api-features/payment-detection) for automatic status updates
+
+### Event Integration
+Use [Webhooks & Events](/api-features/webhooks-events) for instant notifications
+
+## Advanced Filtering
+
+Filter requests by:
+- **Date Range:** Creation or due date periods
+- **Status:** Current request or payment state
+- **Participants:** Payee or payer addresses
+- **Amount Range:** Minimum and maximum values
+
+## Used In
+
+
+
+ Real-time payment tracking
+
+
+
+ Invoice status reconciliation
+
+
+
+## Implementation Details
+
+See [API Reference - Query Requests](/api-reference/endpoints/get-request) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/recurring-payments.mdx b/api-features/recurring-payments.mdx
new file mode 100644
index 0000000..a244d04
--- /dev/null
+++ b/api-features/recurring-payments.mdx
@@ -0,0 +1,68 @@
+---
+title: "Recurring Payments"
+description: "Automated payment schedules for subscriptions and recurring billing"
+---
+
+## Overview
+
+Recurring payments enable automated payment collection on predefined schedules, supporting subscription services, installment plans, and regular business expenses.
+
+## Payment Types
+
+
+
+ Monthly/annual subscription billing
+
+
+
+ Scheduled payment disbursements
+
+
+
+## How It Works
+
+```mermaid
+graph TD
+ A[Create Payment Plan] --> B[Schedule Setup]
+ B --> C[First Payment]
+ C --> D[Automatic Execution]
+ D --> E[Next Payment Date]
+ E --> D
+```
+
+**Key Features:**
+- **Flexible Schedules:** Daily, weekly, monthly, yearly intervals
+- **Smart Contracts:** Automated execution without manual intervention
+- **Fail-Safe Logic:** Retry mechanisms and payment recovery
+
+## Configuration Options
+
+### Schedule Types
+- **Fixed Interval:** Regular payments (monthly, quarterly)
+- **Custom Dates:** Specific payment dates
+- **Business Days Only:** Skip weekends and holidays
+
+### Payment Amounts
+- **Fixed Amount:** Same amount each payment
+- **Variable Amount:** Different amounts per payment
+- **Escalation:** Automatic amount increases
+
+## Implementation Examples
+
+
+
+ Monthly software license fees
+
+
+
+ Structured repayment schedules
+
+
+
+## Available In EasyInvoice
+
+Both **Subscriptions** and **Recurring Payouts** are featured in the EasyInvoice demo with working examples.
+
+## Implementation Details
+
+See [API Reference - Recurring Payments](/api-reference/recurring-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/standard-payments.mdx b/api-features/standard-payments.mdx
new file mode 100644
index 0000000..d811de1
--- /dev/null
+++ b/api-features/standard-payments.mdx
@@ -0,0 +1,58 @@
+---
+title: "Standard Native & ERC20 Payments"
+description: "Simple crypto-to-crypto payments using native currencies and ERC20 tokens"
+---
+
+## Overview
+
+Standard payments are the simplest form of crypto transactions - sending tokens directly from one wallet to another without conversion or cross-chain routing.
+
+## Native Currency Payments
+
+Pay using blockchain native currencies like ETH, MATIC, BNB.
+
+**Benefits:**
+- No token approval required
+- Fastest execution
+- Lowest gas costs
+
+## ERC20 Token Payments
+
+Pay using standard tokens like USDC, USDT, DAI.
+
+**Benefits:**
+- Stable value (stablecoins)
+- Wide acceptance
+- Predictable costs
+
+## Supported Networks & Tokens
+
+
+
+ Ethereum, Polygon, Arbitrum, Base, Optimism, BSC, Avalanche, Fantom
+
+
+
+ USDC, USDT, DAI, and hundreds more across all networks
+
+
+
+## Used In
+
+
+
+ Direct vendor payments
+
+
+
+ Employee compensation
+
+
+
+ Simple crypto invoices
+
+
+
+## Implementation Details
+
+See [API Reference - Standard Payments](/api-reference/standard-payments) for complete technical documentation.
\ No newline at end of file
diff --git a/api-features/webhooks-events.mdx b/api-features/webhooks-events.mdx
new file mode 100644
index 0000000..af86100
--- /dev/null
+++ b/api-features/webhooks-events.mdx
@@ -0,0 +1,96 @@
+---
+title: "Webhooks & Events"
+description: "Real-time notifications for payment lifecycle events and request status changes"
+---
+
+## Overview
+
+Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without constant polling.
+
+## Event Categories
+
+
+
+ **Core events:** confirmed, partial, failed, refunded
+
+ Immediate notification when payments are processed or fail
+
+
+
+ **Crypto-to-fiat:** payment.processing with detailed subStatus
+
+ Track multi-step fiat conversion progress
+
+
+
+ **Recurring:** request.recurring
+
+ Automatic subscription renewal generation
+
+
+
+ **KYC & verification:** compliance.updated, payment_detail.updated
+
+ User verification and bank account status changes
+
+
+
+## How It Works
+
+```mermaid
+graph LR
+ A[Event Occurs] --> B[HMAC Signed POST]
+ B --> C[Your Endpoint]
+ C --> D[Verify & Process]
+ D --> E[Return 200 OK]
+```
+
+**Process:**
+1. **Event occurs:** Payment confirmed, request created, compliance updated
+2. **Secure delivery:** HMAC SHA-256 signed POST to your configured endpoint
+3. **Your processing:** Verify `x-request-network-signature`, update application state
+4. **Reliable delivery:** 3 retries (1s, 5s, 15s delays) with 5-second timeout
+
+## Key Features
+
+### Reliability
+- **Idempotency support:** Use `x-request-network-delivery` header for duplicate detection
+- **Delivery confirmation:** Monitor `x-request-network-retry-count` header to track attempts
+
+### Security
+- **HMAC SHA-256 signatures:** Every webhook includes `x-request-network-signature` header
+- **HTTPS required:** Production endpoints must use secure connections
+- **Test webhook identification:** `x-request-network-test` header for development
+
+### Development Tools
+- **Portal testing:** Send test webhooks from [Request Portal](https://portal.request.network)
+- **ngrok integration:** Receive webhooks locally during development
+- **Comprehensive logging:** Request API logs all delivery failures with attempt details
+
+## Common Use Cases
+
+- **Invoice systems:** Automatically mark invoices as paid when `payment.confirmed` received
+- **Order fulfillment:** Release goods or services immediately after payment confirmation
+- **Subscription management:** Handle `request.recurring` for automatic billing renewals
+- **Compliance workflows:** Update user permissions when `compliance.updated` shows KYC approval
+- **Real-time dashboards:** Display live payment status using `payment.processing` subStatus values
+
+## Implementation
+
+
+
+ Complete technical documentation with setup, payloads, and code examples
+
+
+
+ Working webhook implementation example with Express.js
+
+
+
+ Configure webhooks and test delivery
+
+
+
+ Explore payment transactions and request details
+
+
\ No newline at end of file
diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx
index 35c5c68..428edca 100644
--- a/api-reference/webhooks.mdx
+++ b/api-reference/webhooks.mdx
@@ -1,521 +1,424 @@
---
title: "Webhooks"
-description: "Real-time event notifications and webhook configuration guide"
+description: "Complete webhook implementation guide with event types, security, and retry configuration"
---
-## Webhook Overview
+## Overview
-Webhooks provide real-time notifications when events occur in your Request Network integration. Instead of polling for updates, webhooks push event data to your application immediately when payments are detected, requests are created, or other significant events happen.
+Webhooks deliver real-time notifications when payment and request events occur. Configure your endpoints to receive HMAC-signed POST requests with automatic retry logic and comprehensive event data.
-## Webhook Events
+## Webhook Configuration
+
+### Setup in Portal
+1. Navigate to **Platform Settings → Webhooks** in [Request Portal](https://portal.request.network)
+2. Click **Add webhook**
+3. In the dialog that opens, enter URL and click **Create webhook**
+4. Click copy button to copy **Signing Secret** to clipboard (see [Authentication](/api-reference/authentication) for API key setup)
+5. Enable/disable or delete webhooks as needed
+
+### Local Development
+Use [ngrok](https://ngrok.com/docs/traffic-policy/getting-started/agent-endpoints/cli) to receive webhooks locally:
+```bash
+ngrok http 3000
+# Use the HTTPS URL (e.g., https://abc123.ngrok.io/webhook) in Portal
+```
+
+## Event Types
+
+
+See [Payload Examples](#payload-examples) below for detailed webhook structures.
+
### Payment Events
-
-
- **When:** Payment transaction is detected on blockchain
-
- **Use Cases:**
- - Show "Payment Pending" status to users
- - Start order preparation
- - Send confirmation emails
-
- **Typical Timing:** Within 1-5 seconds of transaction
-
-
-
- **When:** Payment is confirmed on blockchain (sufficient confirmations)
-
- **Use Cases:**
- - Complete order fulfillment
- - Update accounting systems
- - Release digital goods
-
- **Typical Timing:** 1-15 minutes after payment
-
-
+| Event | Description | Context | Primary Use |
+|-------|-------------|---------|-------------|
+| `payment.confirmed` | Payment fully completed and settled | After blockchain confirmation | Complete fulfillment, release goods |
+| `payment.partial` | Partial payment received for request | Installments, partial orders | Update balance, allow additional payments |
+| `payment.failed` | Payment execution failed | Recurring payments, cross-chain transfers | Notify failure, retry logic, pause subscriptions |
+| `payment.refunded` | Payment has been refunded to payer | Cross-chain payment failures, refund scenarios | Update order status, notify customer |
-
-
- **When:** Payment transaction fails or is reverted
-
- **Use Cases:**
- - Notify customer of payment failure
- - Reset order status
- - Trigger retry workflows
-
- **Triggers:** Failed transactions, insufficient gas, reverted smart contract calls
-
-
-
- **When:** Partial payment is received for a request
-
- **Use Cases:**
- - Update outstanding balance
- - Notify of partial payment
- - Allow additional payments
-
- **Common Scenarios:** Installment payments, partial order fulfillment
-
-
+### Processing Events
+
+| Event | Description | Context | Primary Use |
+|-------|-------------|---------|-------------|
+| `payment.processing` | Crypto-to-fiat payment in progress | **subStatus values:** initiated, pending_internal_assessment, ongoing_checks, sending_fiat, fiat_sent, bounced | Track crypto-to-fiat payment status, update UI |
### Request Events
-
-
- **When:** New payment request is created
-
- **Payload Includes:**
- - Request ID and details
- - Payment information
- - Custom metadata
-
- **Use Cases:** CRM integration, analytics tracking
-
-
-
- **When:** Request metadata or status is modified
-
- **Payload Includes:**
- - Updated fields
- - Previous values
- - Change timestamp
-
- **Use Cases:** Audit trails, status synchronization
-
-
+| Event | Description | Context | Primary Use |
+|-------|-------------|---------|-------------|
+| `request.recurring` | New recurring request generated | Subscription renewals, scheduled payments | Send renewal notifications, update billing |
-### Subscription Events
+### Compliance Events
-
-
- **When:** Recurring payment is successfully processed
-
- **Use Cases:**
- - Extend subscription period
- - Send renewal confirmation
- - Update billing systems
-
- **For:** [Subscription](/use-cases/subscriptions) use cases
-
-
-
- **When:** Recurring payment fails
-
- **Use Cases:**
- - Notify customer of failed payment
- - Initiate payment retry
- - Manage subscription status
-
- **Common Causes:** Insufficient funds, expired payment methods
-
-
+| Event | Description | Context | Primary Use |
+|-------|-------------|---------|-------------|
+| `compliance.updated` | KYC or agreement status changed | **kycStatus values:** not_started, pending, approved, rejected, retry_required
**agreementStatus values:** not_started, pending, completed, rejected, failed | Update user permissions, notify status |
+| `payment_detail.updated` | Bank account verification status updated | States: approved, failed, pending | Enable fiat payments, update profiles |
-## Webhook Configuration
+## Security Implementation
-### Setting Up Webhooks
-
-
-
- Set up a webhook endpoint URL in the [Request Portal](https://portal.request.network)
-
-
- Choose which event types you want to receive
-
-
- Use the test webhook feature to verify your endpoint
-
-
- Enable webhooks for production traffic
-
-
-
-### Webhook Endpoint Requirements
+### Signature Verification
+Every webhook includes an HMAC SHA-256 signature in the `x-request-network-signature` header:
-
-
- **Endpoint Specifications:**
- - Must be publicly accessible HTTPS URL
- - Should return 2xx status code for successful processing
- - Timeout limit: 30 seconds
- - Must handle duplicate events (idempotency)
+```javascript
+import crypto from "node:crypto";
+
+function verifyWebhookSignature(payload, signature, secret) {
+ const expectedSignature = crypto
+ .createHmac("sha256", secret)
+ .update(JSON.stringify(payload))
+ .digest("hex");
- ```javascript
- app.post('/webhooks/request-network', (req, res) => {
- try {
- // Process webhook event
- const { eventType, data } = req.body;
-
- // Your business logic here
- processEvent(eventType, data);
-
- // Return success status
- res.status(200).send('OK');
-
- } catch (error) {
- // Return error status for retry
- console.error('Webhook processing error:', error);
- res.status(500).send('Error processing webhook');
- }
- });
- ```
-
+ return signature === expectedSignature;
+}
+
+// Usage in your webhook handler
+app.post("/webhook", (req, res) => {
+ const signature = req.headers["x-request-network-signature"];
-
- **Webhook Security:**
- - Verify webhook signatures
- - Use HTTPS only
- - Implement request validation
- - Rate limit webhook endpoints
-
- ```javascript
- const crypto = require('crypto');
-
- function verifyWebhookSignature(req) {
- const signature = req.headers['x-request-signature'];
- const timestamp = req.headers['x-request-timestamp'];
- const payload = JSON.stringify(req.body);
-
- // Verify timestamp (prevent replay attacks)
- const currentTime = Math.floor(Date.now() / 1000);
- if (Math.abs(currentTime - timestamp) > 300) { // 5 minute tolerance
- return false;
- }
-
- // Verify signature
- const expectedSignature = crypto
- .createHmac('sha256', process.env.WEBHOOK_SECRET)
- .update(timestamp + payload)
- .digest('hex');
-
- return crypto.timingSafeEqual(
- Buffer.from(signature, 'hex'),
- Buffer.from(expectedSignature, 'hex')
- );
- }
- ```
-
+ if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
+ return res.status(401).json({ error: "Invalid signature" });
+ }
-
- **Automatic Retries:**
- - Retry schedule: 1s, 5s, 25s, 125s, 625s
- - Maximum 5 retry attempts
- - Exponential backoff with jitter
- - Dead letter queue for failed webhooks
-
- **Error Handling:**
- ```javascript
- app.post('/webhooks/request-network', async (req, res) => {
- try {
- const { eventType, data } = req.body;
-
- // Process event
- await processEvent(eventType, data);
-
- res.status(200).send('OK');
-
- } catch (error) {
- if (error.permanent) {
- // Don't retry permanent errors
- res.status(400).send('Permanent error');
- } else {
- // Retry temporary errors
- res.status(500).send('Temporary error');
- }
- }
- });
- ```
-
-
+ // Process webhook...
+ res.status(200).json({ success: true });
+});
+```
+
+### Security Requirements
+- **HTTPS only:** Production webhooks require HTTPS endpoints
+- **Always verify signatures:** Never process unverified webhook requests
+- **Keep secrets secure:** Store signing secrets as environment variables
+- **Return 2xx for success:** Any 2xx status code confirms successful processing
+
+## Request Headers
+
+Each webhook request includes these headers:
+
+| Header | Description | Example |
+|--------|-------------|---------|
+| `x-request-network-signature` | HMAC SHA-256 signature | `a1b2c3d4e5f6...` |
+| `x-request-network-delivery` | Unique delivery ID (ULID) | `01ARZ3NDEKTSV4RRFFQ69G5FAV` |
+| `x-request-network-retry-count` | Current retry attempt (0-3) | `0` |
+| `x-request-network-test` | Present for test webhooks | `true` |
+| `content-type` | Always JSON | `application/json` |
+
+## Retry Logic
+
+### Automatic Retries
+- **Max attempts:** 3 retries (4 total attempts)
+- **Retry delays:** 1s, 5s, 15s
+- **Trigger conditions:** Non-2xx response codes, timeouts, connection errors
+- **Timeout:** 5 seconds per request
+
+### Response Handling
+```javascript
+// ✅ Success - no retry
+res.status(200).json({ success: true });
+res.status(201).json({ created: true });
+
+// ❌ Error - triggers retry
+res.status(401).json({ error: "Unauthorized" });
+res.status(404).json({ error: "Resource not found" });
+res.status(500).json({ error: "Internal server error" });
+```
+
+### Error Logging
+Request API logs all webhook delivery failures with:
+- Endpoint URL
+- Attempt number
+- Error details
+- Final failure after all retries
-## Webhook Payloads
+## Payload Examples
-### Payment Confirmed Event
+All payment events include an `explorer` field linking to [Request Scan](https://scan.request.network) for transaction details.
-
-```json Payment Confirmed
+**Common Fields:**
+- `requestId` / `requestID`: Unique identifier for the payment request
+- `paymentReference`: Short reference, also unique to a request, used to link payments to the request
+- `timestamp`: ISO 8601 formatted event timestamp
+- `paymentProcessor`: Either `request-network` (crypto) or `request-tech` (fiat)
+
+### Payment Confirmed
+```json
{
- "eventType": "payment_confirmed",
- "timestamp": "2025-09-12T10:30:00Z",
- "data": {
- "requestId": "req_1234567890abcdef",
- "paymentReference": "pay_abcdef1234567890",
- "transactionHash": "0x742d35cc6cf8a8cbeff61cf82c6b8b3b42a67f1d6c1e8a7b9e2f8d5c3a1b0e9f",
- "blockNumber": 18523456,
- "networkName": "matic",
- "amount": "1000000000000000000000", // 1000 USDC (18 decimals)
- "currency": "USDC-matic",
- "payerAddress": "0x1234567890123456789012345678901234567890",
- "payeeAddress": "0x0987654321098765432109876543210987654321",
- "fees": {
- "platformFee": "25000000000000000000", // 25 USDC
- "gasFee": "0.02"
- },
- "metadata": {
- "reason": "Invoice #INV-001",
- "invoiceNumber": "INV-001",
- "customerEmail": "customer@example.com",
- "orderId": "ORD-2025-001"
+ "event": "payment.confirmed",
+ "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "paymentReference": "0x2c3366941274c34c",
+ "explorer": "https://scan.request.network/request/0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "amount": "100.0",
+ "totalAmountPaid": "100.0",
+ "expectedAmount": "100.0",
+ "timestamp": "2025-10-03T14:30:00Z",
+ "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+ "network": "ethereum",
+ "currency": "USDC",
+ "paymentCurrency": "USDC",
+ "isCryptoToFiat": false,
+ "subStatus": "",
+ "paymentProcessor": "request-network",
+ "fees": [
+ {
+ "type": "network",
+ "amount": "0.02",
+ "currency": "ETH"
}
- }
+ ]
}
```
-```json Request Created
+### Payment Processing
+```json
{
- "eventType": "request_created",
- "timestamp": "2025-09-12T10:00:00Z",
- "data": {
- "requestId": "req_1234567890abcdef",
- "expectedAmount": "1000000000000000000000",
- "currency": "USDC-matic",
- "payeeAddress": "0x0987654321098765432109876543210987654321",
- "payerAddress": "0x1234567890123456789012345678901234567890",
- "status": "pending",
- "createdAt": "2025-09-12T10:00:00Z",
- "dueDate": "2025-10-12T10:00:00Z",
- "metadata": {
- "reason": "Professional Services Q3 2025",
- "invoiceNumber": "INV-001",
- "customerInfo": {
- "name": "Acme Corporation",
- "email": "billing@acme.com"
- }
- }
+ "event": "payment.processing",
+ "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "paymentReference": "0x2c3366941274c34c",
+ "offrampId": "offramp_test123456789",
+ "timestamp": "2025-10-03T14:35:00Z",
+ "subStatus": "ongoing_checks",
+ "paymentProcessor": "request-tech",
+ "rawPayload": {
+ "status": "ongoing_checks",
+ "providerId": "provider_test123"
}
}
```
-```json Subscription Renewed
+### Payment Partial
+```json
{
- "eventType": "subscription_renewed",
- "timestamp": "2025-09-12T10:30:00Z",
- "data": {
- "subscriptionId": "sub_1234567890abcdef",
- "requestId": "req_abcdef1234567890",
- "paymentReference": "pay_1234567890abcdef",
- "transactionHash": "0x742d35cc6cf8a8cbeff61cf82c6b8b3b42a67f1d6c1e8a7b9e2f8d5c3a1b0e9f",
- "amount": "2999000000000000000000", // $29.99
- "currency": "USD",
- "renewalPeriod": "monthly",
- "nextRenewalDate": "2025-10-12T10:30:00Z",
- "customerId": "cust_1234567890",
- "subscriptionPlan": {
- "name": "Pro Plan",
- "features": ["feature1", "feature2"],
- "billingCycle": "monthly"
- }
+ "event": "payment.partial",
+ "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "paymentReference": "0x2c3366941274c34c",
+ "explorer": "https://scan.request.network/request/0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "amount": "50.0",
+ "totalAmountPaid": "50.0",
+ "expectedAmount": "100.0",
+ "timestamp": "2025-10-03T14:30:00Z",
+ "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+ "network": "ethereum",
+ "currency": "USDC",
+ "paymentCurrency": "USDC",
+ "isCryptoToFiat": false,
+ "subStatus": "",
+ "paymentProcessor": "request-network",
+ "fees": []
+}
+```
+
+### Payment Failed
+```json
+{
+ "event": "payment.failed",
+ "requestId": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "requestID": "0151b394e3c482c5aebaa04eb04508a8db70595470760293f1b258ed96d1fafa93",
+ "paymentReference": "0x2c3366941274c34c",
+ "subStatus": "insufficient_funds",
+ "paymentProcessor": "request-network"
+}
+```
+
+### Compliance Updated
+```json
+{
+ "event": "compliance.updated",
+ "clientUserId": "user_test123456789",
+ "kycStatus": "approved",
+ "agreementStatus": "completed",
+ "isCompliant": true,
+ "timestamp": "2025-10-03T14:30:00Z",
+ "rawPayload": {
+ "verificationLevel": "full",
+ "documents": "verified"
}
}
```
-
-## Integration Examples
+## Implementation Examples
+
+For a complete working example, see the [EasyInvoice demo](/use-cases/invoicing) which implements webhook handling for payment notifications.
+
+
+
+```javascript
+import express from "express";
+import crypto from "node:crypto";
+
+const app = express();
+const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
-### E-commerce Order Processing
+app.use(express.json());
-
-```javascript Express.js Handler
-app.post('/webhooks/payment-confirmed', async (req, res) => {
+app.post("/webhook/payment", async (req, res) => {
try {
- // Verify webhook signature
- if (!verifyWebhookSignature(req)) {
- return res.status(401).send('Unauthorized');
+ // Verify signature
+ const signature = req.headers["x-request-network-signature"];
+ const expectedSignature = crypto
+ .createHmac("sha256", WEBHOOK_SECRET)
+ .update(JSON.stringify(req.body))
+ .digest("hex");
+
+ if (signature !== expectedSignature) {
+ return res.status(401).json({ error: "Invalid signature" });
}
+
+ // Check for test webhook
+ const isTest = req.headers["x-request-network-test"] === "true";
- const { eventType, data } = req.body;
+ // Process webhook based on event type
+ const { event, requestId } = req.body;
- if (eventType === 'payment_confirmed') {
- const orderId = data.metadata.orderId;
-
- // Update order status
- await updateOrder(orderId, {
- status: 'paid',
- paymentHash: data.transactionHash,
- paidAt: data.timestamp,
- paymentMethod: 'crypto'
- });
-
- // Send confirmation email
- await sendOrderConfirmation(orderId);
-
- // Trigger fulfillment
- await triggerOrderFulfillment(orderId);
-
- console.log(`Order ${orderId} marked as paid`);
+ switch (event) {
+ case "payment.confirmed":
+ await handlePaymentConfirmed(req.body);
+ break;
+ case "payment.processing":
+ await handlePaymentProcessing(req.body);
+ break;
+ case "compliance.updated":
+ await handleComplianceUpdate(req.body);
+ break;
+ default:
+ console.log(`Unhandled event: ${event}`);
}
-
- res.status(200).send('OK');
+
+ return res.status(200).json({ success: true });
} catch (error) {
- console.error('Webhook error:', error);
- res.status(500).send('Error processing webhook');
+ console.error("Webhook processing error:", error);
+ return res.status(500).json({ error: "Processing failed" });
}
});
```
+
+
+
+```javascript
+// app/api/webhook/route.ts
+import crypto from "node:crypto";
+import { NextResponse } from "next/server";
-```javascript SaaS Subscription Handler
-app.post('/webhooks/subscription-events', async (req, res) => {
+export async function POST(request: Request) {
try {
- const { eventType, data } = req.body;
+ const body = await request.json();
- switch (eventType) {
- case 'subscription_renewed':
- // Extend subscription period
- await extendSubscription(data.customerId, data.renewalPeriod);
-
- // Send renewal confirmation
- await sendRenewalConfirmation(data.customerId);
- break;
-
- case 'subscription_failed':
- // Handle failed payment
- await handleFailedSubscriptionPayment(data.customerId);
-
- // Send payment failure notification
- await sendPaymentFailureNotification(data.customerId);
- break;
-
- case 'subscription_cancelled':
- // Deactivate subscription
- await deactivateSubscription(data.customerId);
- break;
+ // Verify signature
+ const signature = request.headers.get("x-request-network-signature");
+ const expectedSignature = crypto
+ .createHmac("sha256", process.env.WEBHOOK_SECRET!)
+ .update(JSON.stringify(body))
+ .digest("hex");
+
+ if (signature !== expectedSignature) {
+ return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
}
+
+ // Process webhook
+ const { event, requestId } = body;
- res.status(200).send('OK');
+ // Your business logic here
+ await processWebhookEvent(event, body);
+
+ return NextResponse.json({ success: true }, { status: 200 });
} catch (error) {
- console.error('Subscription webhook error:', error);
- res.status(500).send('Error processing subscription webhook');
+ console.error("Webhook error:", error);
+
+ if (error instanceof ResourceNotFoundError) {
+ return NextResponse.json({ error: error.message }, { status: 404 });
+ }
+
+ return NextResponse.json(
+ { error: "Internal server error" },
+ { status: 500 }
+ );
}
-});
-```
-
-
-### Database Integration
-
-
-```sql Payment Tracking
--- Create table for payment tracking
-CREATE TABLE payment_events (
- id SERIAL PRIMARY KEY,
- request_id VARCHAR(255) NOT NULL,
- event_type VARCHAR(50) NOT NULL,
- transaction_hash VARCHAR(66),
- block_number INTEGER,
- amount DECIMAL(36, 18),
- currency VARCHAR(20),
- payer_address VARCHAR(42),
- payee_address VARCHAR(42),
- metadata JSONB,
- created_at TIMESTAMP DEFAULT NOW(),
- processed_at TIMESTAMP,
- INDEX idx_request_id (request_id),
- INDEX idx_event_type (event_type),
- INDEX idx_created_at (created_at)
-);
+}
```
+
+
+
+## Testing
+
+### Portal Testing
+1. Go to **Platform Settings → Webhooks** in Request Portal
+2. Create a webhook if you haven't already
+3. Select the webhook event type and click **Send test event**
+4. Monitor your endpoint logs for test requests
+
+### Test Webhook Identification
+Test webhooks include the `x-request-network-test: true` header:
-```javascript Database Handler
-async function savePaymentEvent(eventData) {
- const {
- requestId,
- eventType,
- transactionHash,
- blockNumber,
- amount,
- currency,
- payerAddress,
- payeeAddress,
- metadata
- } = eventData;
+```javascript
+app.post("/webhook", (req, res) => {
+ const isTest = req.headers["x-request-network-test"] === "true";
- // Insert payment event
- const result = await db.query(`
- INSERT INTO payment_events (
- request_id, event_type, transaction_hash, block_number,
- amount, currency, payer_address, payee_address, metadata
- ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
- RETURNING id
- `, [
- requestId, eventType, transactionHash, blockNumber,
- amount, currency, payerAddress, payeeAddress, JSON.stringify(metadata)
- ]);
+ if (isTest) {
+ console.log("Received test webhook");
+ // Handle test scenario
+ }
- return result.rows[0].id;
-}
+ // Process normally...
+});
```
-
-## Testing Webhooks
+## Best Practices
-### Webhook Testing Tools
+### Error Handling
+- **Implement idempotency:** Use delivery IDs to prevent duplicate processing
+- **Graceful degradation:** Handle unknown event types without errors
-
-
- **Local Development:**
- - Expose local server to internet
- - Test webhooks during development
- - Secure tunnels with authentication
-
- ```bash
- # Install ngrok
- npm install -g ngrok
-
- # Expose local server
- ngrok http 3000
-
- # Use ngrok URL as webhook endpoint
- # https://abc123.ngrok.io/webhooks/request-network
- ```
-
-
-
- **Quick Testing:**
- - Temporary webhook endpoints
- - Inspect webhook payloads
- - No setup required
-
- **Process:**
- 1. Go to webhook.site
- 2. Copy the unique URL
- 3. Use as webhook endpoint
- 4. View received webhooks in browser
-
-
+### Performance
+- **Timeout management:** Complete processing within 5 seconds
-### Test Event Simulation
+## Troubleshooting
-
-**Test Webhooks in Request Portal**
+### Common Issues
-Use the Request Portal to send test webhook events to your endpoint for development and testing.
-
+**Signature verification fails:**
+- Check your signing secret matches Portal configuration
+- Ensure you're using the raw request body for signature calculation
+- Verify HMAC SHA-256 implementation
+
+**Webhooks not received:**
+- Confirm endpoint URL is accessible via HTTPS
+- Verify endpoint returns 2xx status codes
+
+### Debugging Tips
+- Use ngrok request inspector to see raw webhook data
+- Monitor retry counts in headers to identify issues
+- Test with Portal's "Send test webhooks" feature
-## What's Next?
+## Related Documentation
-
-
- Secure your API and webhook endpoints
+
+
+ High-level webhook concepts and workflow
-
-
- Learn more about webhook event types and handling
+
+
+ Complete webhook implementation example
-
-
- Common webhook integration patterns and best practices
+
+
+ API key setup and webhook security
+
+
+
+ Understanding payment lifecycle events
+
+
+
+ Configure webhooks and manage API keys
+
+
+
+ Explore transactions and request details
diff --git a/docs.json b/docs.json
index 054640c..f39b279 100644
--- a/docs.json
+++ b/docs.json
@@ -68,9 +68,41 @@
{
"group": "⚙️ API Features",
"pages": [
- "api-features/payment-types",
- "api-features/advanced-features",
- "api-features/integration-patterns"
+ {
+ "group": "Requests",
+ "pages": [
+ "api-features/create-requests"
+ ]
+ },
+ {
+ "group": "Payments",
+ "pages": [
+ "api-features/payment-types-overview",
+ "api-features/standard-payments",
+ "api-features/conversion-payments",
+ "api-features/crypto-to-fiat-payments",
+ "api-features/batch-payments",
+ "api-features/crosschain-payments",
+ "api-features/partial-payments",
+ "api-features/recurring-payments"
+ ]
+ },
+ {
+ "group": "Reconciliation",
+ "pages": [
+ "api-features/payment-detection",
+ "api-features/query-requests",
+ "api-features/query-payments",
+ "api-features/webhooks-events"
+ ]
+ },
+ {
+ "group": "Fee Structure",
+ "pages": [
+ "api-features/custom-fees",
+ "api-features/fee-breakdowns"
+ ]
+ }
]
},
{
diff --git a/index.mdx b/index.mdx
index b57fcde..986a08d 100644
--- a/index.mdx
+++ b/index.mdx
@@ -1,20 +1,10 @@
---
title: "Request Network Docs"
-description: "A protocol for creating payment requests and reconciling payments."
+description: "A protocol for requests, payments, and **100% automated reconciliation**. Requests add business context to payments, **eliminating manual accounting** with cryptographic certainty."
sidebarTitle: "Welcome"
mode: "center"
---
-## What is a Payment Request?
-
-Request Network transforms how businesses handle Web3 payments by creating transparent, traceable payment requests that both parties can trust. Unlike traditional payment methods where you send money and hope for the best, Request Network creates an immutable record that tracks the entire payment lifecycle.
-
-**Key Benefits:**
-- **100% Payment Reconciliation** - Never lose track of who paid what
-- **Multi-Currency Support** - Invoice in USD, get paid in crypto across 10+ chains
-- **Instant Settlement** - No waiting for bank transfers or payment processor holds
-- **Programmable Payments** - crypto-to-fiat, crosschain, recurring, batch, and conversion payment flows
-
## Interactive Demo
@@ -29,37 +19,37 @@ Choose your path based on what you want to build:
Explore specific business scenarios: invoicing, payouts, payroll, checkout, and subscriptions
- Technical documentation for payment types, webhooks, and advanced features
+ The easiest way to integrate. Payment types, webhooks, and developer tools.
- SDK documentation and advanced implementation topics
+ Supported chains, currencies, smart contracts, and community resources
- Supported chains, currencies, smart contracts, and community resources
+ Legacy SDK and protocol documentation for advanced users