diff --git a/ai-tools/claude-code.mdx b/ai-tools/claude-code.mdx deleted file mode 100644 index bdc4e04..0000000 --- a/ai-tools/claude-code.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Claude Code setup" -description: "Configure Claude Code for your documentation workflow" -icon: "asterisk" ---- - -Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation. - -## Prerequisites - -- Active Claude subscription (Pro, Max, or API access) - -## Setup - -1. Install Claude Code globally: - - ```bash - npm install -g @anthropic-ai/claude-code -``` - -2. Navigate to your docs directory. -3. (Optional) Add the `CLAUDE.md` file below to your project. -4. Run `claude` to start. - -## Create `CLAUDE.md` - -Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards: - -````markdown -# Mintlify documentation - -## Working relationship -- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so -- ALWAYS ask for clarification rather than making assumptions -- NEVER lie, guess, or make up information - -## Project context -- Format: MDX files with YAML frontmatter -- Config: docs.json for navigation, theme, settings -- Components: Mintlify components - -## Content strategy -- Document just enough for user success - not too much, not too little -- Prioritize accuracy and usability of information -- Make content evergreen when possible -- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason -- Check existing patterns for consistency -- Start by making the smallest reasonable changes - -## Frontmatter requirements for pages -- title: Clear, descriptive page title -- description: Concise summary for SEO/navigation - -## Writing standards -- Second-person voice ("you") -- Prerequisites at start of procedural content -- Test all code examples before publishing -- Match style and formatting of existing pages -- Include both basic and advanced use cases -- Language tags on all code blocks -- Alt text on all images -- Relative paths for internal links - -## Git workflow -- NEVER use --no-verify when committing -- Ask how to handle uncommitted changes before starting -- Create a new branch when no clear branch exists for changes -- Commit frequently throughout development -- NEVER skip or disable pre-commit hooks - -## Do not -- Skip frontmatter on any MDX file -- Use absolute URLs for internal links -- Include untested code examples -- Make assumptions - always ask for clarification -```` diff --git a/ai-tools/cursor.mdx b/ai-tools/cursor.mdx deleted file mode 100644 index fbb7761..0000000 --- a/ai-tools/cursor.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -title: "Cursor setup" -description: "Configure Cursor for your documentation workflow" -icon: "arrow-pointer" ---- - -Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components. - -## Prerequisites - -- Cursor editor installed -- Access to your documentation repository - -## Project rules - -Create project rules that all team members can use. In your documentation repository root: - -```bash -mkdir -p .cursor -``` - -Create `.cursor/rules.md`: - -````markdown -# Mintlify technical writing rule - -You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices. - -## Core writing principles - -### Language and style requirements - -- Use clear, direct language appropriate for technical audiences -- Write in second person ("you") for instructions and procedures -- Use active voice over passive voice -- Employ present tense for current states, future tense for outcomes -- Avoid jargon unless necessary and define terms when first used -- Maintain consistent terminology throughout all documentation -- Keep sentences concise while providing necessary context -- Use parallel structure in lists, headings, and procedures - -### Content organization standards - -- Lead with the most important information (inverted pyramid structure) -- Use progressive disclosure: basic concepts before advanced ones -- Break complex procedures into numbered steps -- Include prerequisites and context before instructions -- Provide expected outcomes for each major step -- Use descriptive, keyword-rich headings for navigation and SEO -- Group related information logically with clear section breaks - -### User-centered approach - -- Focus on user goals and outcomes rather than system features -- Anticipate common questions and address them proactively -- Include troubleshooting for likely failure points -- Write for scannability with clear headings, lists, and white space -- Include verification steps to confirm success - -## Mintlify component reference - -### Callout components - -#### Note - Additional helpful information - - -Supplementary information that supports the main content without interrupting flow - - -#### Tip - Best practices and pro tips - - -Expert advice, shortcuts, or best practices that enhance user success - - -#### Warning - Important cautions - - -Critical information about potential issues, breaking changes, or destructive actions - - -#### Info - Neutral contextual information - - -Background information, context, or neutral announcements - - -#### Check - Success confirmations - - -Positive confirmations, successful completions, or achievement indicators - - -### Code components - -#### Single code block - -Example of a single code block: - -```javascript config.js -const apiConfig = { - baseURL: 'https://api.example.com', - timeout: 5000, - headers: { - 'Authorization': `Bearer ${process.env.API_TOKEN}` - } -}; -``` - -#### Code group with multiple languages - -Example of a code group: - - -```javascript Node.js -const response = await fetch('/api/endpoint', { - headers: { Authorization: `Bearer ${apiKey}` } -}); -``` - -```python Python -import requests -response = requests.get('/api/endpoint', - headers={'Authorization': f'Bearer {api_key}'}) -``` - -```curl cURL -curl -X GET '/api/endpoint' \ - -H 'Authorization: Bearer YOUR_API_KEY' -``` - - -#### Request/response examples - -Example of request/response documentation: - - -```bash cURL -curl -X POST 'https://api.example.com/users' \ - -H 'Content-Type: application/json' \ - -d '{"name": "John Doe", "email": "john@example.com"}' -``` - - - -```json Success -{ - "id": "user_123", - "name": "John Doe", - "email": "john@example.com", - "created_at": "2024-01-15T10:30:00Z" -} -``` - - -### Structural components - -#### Steps for procedures - -Example of step-by-step instructions: - - - - Run `npm install` to install required packages. - - - Verify installation by running `npm list`. - - - - - Create a `.env` file with your API credentials. - - ```bash - API_KEY=your_api_key_here - ``` - - - Never commit API keys to version control. - - - - -#### Tabs for alternative content - -Example of tabbed content: - - - - ```bash - brew install node - npm install -g package-name - ``` - - - - ```powershell - choco install nodejs - npm install -g package-name - ``` - - - - ```bash - sudo apt install nodejs npm - npm install -g package-name - ``` - - - -#### Accordions for collapsible content - -Example of accordion groups: - - - - - **Firewall blocking**: Ensure ports 80 and 443 are open - - **Proxy configuration**: Set HTTP_PROXY environment variable - - **DNS resolution**: Try using 8.8.8.8 as DNS server - - - - ```javascript - const config = { - performance: { cache: true, timeout: 30000 }, - security: { encryption: 'AES-256' } - }; - ``` - - - -### Cards and columns for emphasizing information - -Example of cards and card groups: - - -Complete walkthrough from installation to your first API call in under 10 minutes. - - - - - Learn how to authenticate requests using API keys or JWT tokens. - - - - Understand rate limits and best practices for high-volume usage. - - - -### API documentation components - -#### Parameter fields - -Example of parameter documentation: - - -Unique identifier for the user. Must be a valid UUID v4 format. - - - -User's email address. Must be valid and unique within the system. - - - -Maximum number of results to return. Range: 1-100. - - - -Bearer token for API authentication. Format: `Bearer YOUR_API_KEY` - - -#### Response fields - -Example of response field documentation: - - -Unique identifier assigned to the newly created user. - - - -ISO 8601 formatted timestamp of when the user was created. - - - -List of permission strings assigned to this user. - - -#### Expandable nested fields - -Example of nested field documentation: - - -Complete user object with all associated data. - - - - User profile information including personal details. - - - - User's first name as entered during registration. - - - - URL to user's profile picture. Returns null if no avatar is set. - - - - - - -### Media and advanced components - -#### Frames for images - -Wrap all images in frames: - - -Main dashboard showing analytics overview - - - -Analytics dashboard with charts - - -#### Videos - -Use the HTML video element for self-hosted video content: - - - -Embed YouTube videos using iframe elements: - - - -#### Tooltips - -Example of tooltip usage: - - -API - - -#### Updates - -Use updates for changelogs: - - -## New features -- Added bulk user import functionality -- Improved error messages with actionable suggestions - -## Bug fixes -- Fixed pagination issue with large datasets -- Resolved authentication timeout problems - - -## Required page structure - -Every documentation page must begin with YAML frontmatter: - -```yaml ---- -title: "Clear, specific, keyword-rich title" -description: "Concise description explaining page purpose and value" ---- -``` - -## Content quality standards - -### Code examples requirements - -- Always include complete, runnable examples that users can copy and execute -- Show proper error handling and edge case management -- Use realistic data instead of placeholder values -- Include expected outputs and results for verification -- Test all code examples thoroughly before publishing -- Specify language and include filename when relevant -- Add explanatory comments for complex logic -- Never include real API keys or secrets in code examples - -### API documentation requirements - -- Document all parameters including optional ones with clear descriptions -- Show both success and error response examples with realistic data -- Include rate limiting information with specific limits -- Provide authentication examples showing proper format -- Explain all HTTP status codes and error handling -- Cover complete request/response cycles - -### Accessibility requirements - -- Include descriptive alt text for all images and diagrams -- Use specific, actionable link text instead of "click here" -- Ensure proper heading hierarchy starting with H2 -- Provide keyboard navigation considerations -- Use sufficient color contrast in examples and visuals -- Structure content for easy scanning with headers and lists - -## Component selection logic - -- Use **Steps** for procedures and sequential instructions -- Use **Tabs** for platform-specific content or alternative approaches -- Use **CodeGroup** when showing the same concept in multiple programming languages -- Use **Accordions** for progressive disclosure of information -- Use **RequestExample/ResponseExample** specifically for API endpoint documentation -- Use **ParamField** for API parameters, **ResponseField** for API responses -- Use **Expandable** for nested object properties or hierarchical information -```` diff --git a/ai-tools/windsurf.mdx b/ai-tools/windsurf.mdx deleted file mode 100644 index fce12bf..0000000 --- a/ai-tools/windsurf.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Windsurf setup" -description: "Configure Windsurf for your documentation workflow" -icon: "water" ---- - -Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow. - -## Prerequisites - -- Windsurf editor installed -- Access to your documentation repository - -## Workspace rules - -Create workspace rules that provide Windsurf with context about your documentation project and standards. - -Create `.windsurf/rules.md` in your project root: - -````markdown -# Mintlify technical writing rule - -## Project context - -- This is a documentation project on the Mintlify platform -- We use MDX files with YAML frontmatter -- Navigation is configured in `docs.json` -- We follow technical writing best practices - -## Writing standards - -- Use second person ("you") for instructions -- Write in active voice and present tense -- Start procedures with prerequisites -- Include expected outcomes for major steps -- Use descriptive, keyword-rich headings -- Keep sentences concise but informative - -## Required page structure - -Every page must start with frontmatter: - -```yaml ---- -title: "Clear, specific title" -description: "Concise description for SEO and navigation" ---- -``` - -## Mintlify components - -### Callouts - -- `` for helpful supplementary information -- `` for important cautions and breaking changes -- `` for best practices and expert advice -- `` for neutral contextual information -- `` for success confirmations - -### Code examples - -- When appropriate, include complete, runnable examples -- Use `` for multiple language examples -- Specify language tags on all code blocks -- Include realistic data, not placeholders -- Use `` and `` for API docs - -### Procedures - -- Use `` component for sequential instructions -- Include verification steps with `` components when relevant -- Break complex procedures into smaller steps - -### Content organization - -- Use `` for platform-specific content -- Use `` for progressive disclosure -- Use `` and `` for highlighting content -- Wrap images in `` components with descriptive alt text - -## API documentation requirements - -- Document all parameters with `` -- Show response structure with `` -- Include both success and error examples -- Use `` for nested object properties -- Always include authentication examples - -## Quality standards - -- Test all code examples before publishing -- Use relative paths for internal links -- Include alt text for all images -- Ensure proper heading hierarchy (start with h2) -- Check existing patterns for consistency -```` diff --git a/api-features/advanced-features.mdx b/api-features/advanced-features.mdx new file mode 100644 index 0000000..144800b --- /dev/null +++ b/api-features/advanced-features.mdx @@ -0,0 +1,475 @@ +--- +title: "Advanced Features" +description: "Webhooks, fee handling, custom metadata, and enterprise-grade capabilities" +--- + +## Overview + +Request Network provides advanced features that enable enterprise-grade payment processing, real-time integrations, and sophisticated business logic. These capabilities ensure your payment infrastructure can scale with your business needs. + +## Webhooks & Real-Time Updates + +### Webhook Events +Stay synchronized with payment events through real-time webhook notifications. + + + + **Event Types:** + - `payment_detected` - Payment initiated + - `payment_confirmed` - Payment confirmed on blockchain + - `payment_failed` - Payment failed or rejected + + **Use Cases:** Order fulfillment, inventory updates, customer notifications + + + + **Event Types:** + - `request_created` - New payment request created + - `request_updated` - Request metadata or status changed + - `request_cancelled` - Request cancelled by merchant + + **Use Cases:** CRM integration, accounting system updates + + + + + + **Event Types:** + - `subscription_activated` - New subscription started + - `subscription_renewed` - Successful recurring payment + - `subscription_failed` - Recurring payment failed + - `subscription_cancelled` - Subscription terminated + + **Use Cases:** [Subscription](/use-cases/subscriptions) management, customer lifecycle + + + + **Event Types:** + - `payout_initiated` - Payout process started + - `payout_completed` - Payout successfully sent + - `batch_payout_completed` - All batch payments processed + + **Use Cases:** [Payroll](/use-cases/payroll) confirmation, vendor notifications + + + +### Webhook Configuration + + + + **Webhook Endpoint Setup:** + + 1. Configure endpoint URL in Request Portal + 2. Select event types to receive + 3. Set up authentication (optional) + 4. Test webhook delivery + + ```javascript + // Example webhook endpoint + app.post('/webhooks/request-network', (req, res) => { + const { eventType, data } = req.body; + + // Verify webhook signature (recommended) + if (!verifyWebhookSignature(req)) { + return res.status(401).send('Unauthorized'); + } + + // Process event + handlePaymentEvent(eventType, data); + + res.status(200).send('OK'); + }); + ``` + + + + **Webhook Security Best Practices:** + + - **Signature Verification:** Verify webhook authenticity + - **HTTPS Only:** Always use secure endpoints + - **Idempotency:** Handle duplicate events gracefully + - **Rate Limiting:** Implement endpoint rate limiting + + ```javascript + function verifyWebhookSignature(req) { + const signature = req.headers['x-request-signature']; + const payload = JSON.stringify(req.body); + const expectedSignature = crypto + .createHmac('sha256', webhookSecret) + .update(payload) + .digest('hex'); + + return signature === expectedSignature; + } + ``` + + + + **Automatic Retry Handling:** + + - **Retry Schedule:** 1s, 5s, 25s, 125s intervals + - **Max Attempts:** Up to 5 retry attempts + - **Exponential Backoff:** Increasing delays between retries + - **Dead Letter Queue:** Failed events stored for manual review + + **Error Handling:** + - Return 2xx status codes for successful processing + - Return 4xx for permanent failures (no retry) + - Return 5xx for temporary failures (will retry) + + + +## Platform Fees & Revenue Sharing + +### Fee Configuration +Collect platform fees automatically from every transaction. + + + + **Fixed Percentage Model:** + - Set percentage fee (e.g., 2.5% per transaction) + - Automatic fee calculation and collection + - Fees collected to specified address + - Real-time fee tracking and reporting + + **Perfect For:** Marketplaces, payment processors, SaaS platforms + + + + **Flat Fee Model:** + - Set fixed fee amount per transaction + - Independent of transaction size + - Predictable fee structure + - Suitable for high-volume, low-value transactions + + **Perfect For:** Micropayments, subscription services, utility payments + + + + **Volume-Based Pricing:** + - Different fee rates based on transaction volume + - Automatic tier calculation + - Incentivize higher volume usage + - Enterprise-friendly pricing models + + **Perfect For:** Enterprise platforms, high-volume merchants + + + + **Multi-Party Fee Distribution:** + - Split fees between multiple parties + - Automatic revenue distribution + - Configurable split percentages + - Real-time settlement + + **Perfect For:** Affiliate programs, partner ecosystems, marketplaces + + + +### Fee Implementation + + +```javascript Percentage Fee +const requestWithFee = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USDC-matic', + expectedAmount: '1000', + // ... other request details + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentAddress: merchantAddress, + feeAddress: platformFeeAddress, + feeAmount: '25' // 2.5% fee + } + } +}); +``` + +```javascript Fixed Fee +const requestWithFixedFee = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USDC-matic', + expectedAmount: '1000', + // ... other request details + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentAddress: merchantAddress, + feeAddress: platformFeeAddress, + feeAmount: '10' // $10 fixed fee + } + } +}); +``` + +```javascript Multi-Party Split +const revenueSharingRequest = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USDC-matic', + expectedAmount: '1000', + // ... other request details + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentAddress: merchantAddress, + feeAddress: platformFeeAddress, + feeAmount: '50', // 5% to platform + additionalFees: [ + { + address: affiliateAddress, + amount: '20' // 2% to affiliate + } + ] + } + } +}); +``` + + +## Custom Metadata & Business Logic + +### Metadata Capabilities +Attach business-specific data to payment requests and transactions. + + + + **Built-in Fields:** + - Invoice numbers and references + - Customer information + - Product/service descriptions + - Due dates and payment terms + - Tax information and rates + + ```javascript + const requestWithMetadata = await requestNetwork.createRequest({ + // ... request configuration + contentData: { + reason: 'Professional Services - Q1 2025', + invoiceNumber: 'INV-2025-001', + dueDate: '2025-04-01', + customerInfo: { + name: 'Acme Corporation', + email: 'billing@acme.com', + taxId: 'US123456789' + }, + lineItems: [ + { + description: 'Consulting Services', + quantity: 40, + unitPrice: '150', + total: '6000' + } + ] + } + }); + ``` + + + + **Flexible Schema:** + - Add any JSON-compatible data + - Business-specific identifiers + - Integration system references + - Custom workflow states + + ```javascript + const customMetadata = { + // Standard invoice data + reason: 'Software License Renewal', + invoiceNumber: 'LIC-2025-456', + + // Custom business fields + customFields: { + salesRepId: 'REP-001', + contractNumber: 'CON-2025-789', + departmentCode: 'IT-DEV', + projectId: 'PROJ-ALPHA', + approvalRequired: true, + priority: 'high' + }, + + // Integration references + externalSystems: { + crmId: 'SFDC-12345', + erpOrderId: 'ERP-ORD-789', + ticketNumber: 'TICKET-456' + } + }; + ``` + + + + **Query Capabilities:** + - Search requests by metadata fields + - Filter by custom attributes + - Generate custom reports + - Business intelligence integration + + ```javascript + // Search requests by metadata + const requests = await requestNetwork.searchRequests({ + filters: { + 'contentData.customFields.departmentCode': 'IT-DEV', + 'contentData.customFields.priority': 'high', + createdAt: { + gte: '2025-01-01', + lte: '2025-03-31' + } + } + }); + ``` + + + +## Error Handling & Resilience + +### Payment Failure Management +Robust error handling ensures reliable payment processing. + + + + **Smart Retry Mechanisms:** + - Automatic retry for transient failures + - Exponential backoff strategies + - Maximum retry attempt limits + - Configurable retry policies + + **Failure Types:** + - Network connectivity issues + - Temporary blockchain congestion + - Insufficient gas fee scenarios + + + + **Payment Grace Handling:** + - Configurable grace periods for late payments + - Automatic payment retry scheduling + - Customer notification workflows + - Account suspension management + + **Use Cases:** [Subscription](/use-cases/subscriptions) billing, enterprise accounts + + + +### Error Response Handling + + +```javascript Error Handling +try { + const payment = await requestNetwork.payRequest(requestId, { + amount: paymentAmount, + currency: paymentCurrency + }); + + console.log('Payment successful:', payment.transactionHash); + +} catch (error) { + switch (error.code) { + case 'INSUFFICIENT_FUNDS': + // Handle insufficient balance + showInsufficientFundsError(); + break; + + case 'NETWORK_ERROR': + // Retry payment after delay + setTimeout(() => retryPayment(requestId), 5000); + break; + + case 'INVALID_REQUEST': + // Handle invalid request (don't retry) + showInvalidRequestError(); + break; + + default: + // Generic error handling + showGenericPaymentError(); + } +} +``` + +```javascript Webhook Error Handling +app.post('/webhook/payment-events', async (req, res) => { + try { + const { eventType, data } = req.body; + + // Process event with error handling + await processPaymentEvent(eventType, data); + + res.status(200).send('OK'); + + } catch (error) { + console.error('Webhook processing error:', error); + + // Return appropriate status code + if (error.type === 'PERMANENT_ERROR') { + res.status(400).send('Bad Request'); + } else { + res.status(500).send('Internal Server Error'); + } + } +}); +``` + + +## Performance & Optimization + +### Gas Fee Optimization +Minimize transaction costs through intelligent optimization. + + + + **Efficient Batch Processing:** + - Multiple payments in single transaction + - Shared gas costs across recipients + - Up to 90% gas savings for batch operations + - Atomic execution guarantees + + + + **Optimal Network Routing:** + - Automatic network selection based on cost + - Real-time gas price monitoring + - Cross-chain routing for best rates + - User preference consideration + + + + **Smart Timing Strategies:** + - Off-peak transaction scheduling + - Gas price prediction and queuing + - Priority fee optimization + - Network congestion avoidance + + + +## What's Next? + + + + Learn common integration patterns and best practices + + + + Detailed webhook and API endpoint documentation + + + + Configure webhooks and advanced features + + diff --git a/api-features/integration-patterns.mdx b/api-features/integration-patterns.mdx new file mode 100644 index 0000000..5335601 --- /dev/null +++ b/api-features/integration-patterns.mdx @@ -0,0 +1,677 @@ +--- +title: "Integration Patterns" +description: "Common integration patterns, best practices, and architectural guidance for Request Network implementations" +--- + +## Overview + +This guide covers proven integration patterns, architectural best practices, and common implementation approaches for Request Network. Whether you're building a simple invoicing system or a complex multi-tenant platform, these patterns will help you implement robust, scalable payment infrastructure. + +## Common Integration Architectures + +### Server-Side Integration Pattern +Recommended for production applications requiring security and control. + + + + **Server-Side Flow:** + ``` + Frontend โ†’ Backend API โ†’ Request Network โ†’ Blockchain + โ†“ + Webhook Handler โ† Request Network โ† Payment Confirmation + โ†“ + Business Logic โ†’ Database โ†’ Frontend Updates + ``` + + **Benefits:** + - Secure API key management + - Centralized business logic + - Reliable webhook handling + - Scalable architecture + + + + ```javascript + // Backend API endpoint + app.post('/api/create-invoice', async (req, res) => { + try { + // Validate request + const { amount, currency, customerEmail } = req.body; + + // Create Request Network payment request + const paymentRequest = await requestNetwork.createRequest({ + requestInfo: { + currency, + expectedAmount: amount, + payee: { type: 'ethereumAddress', value: merchantAddress }, + payer: { type: 'ethereumAddress', value: customerAddress } + }, + contentData: { + reason: 'Invoice Payment', + customerEmail, + invoiceId: generateInvoiceId() + } + }); + + // Store in database + await db.invoices.create({ + requestId: paymentRequest.requestId, + amount, + currency, + customerEmail, + status: 'pending' + }); + + res.json({ + requestId: paymentRequest.requestId, + paymentUrl: `${baseUrl}/pay/${paymentRequest.requestId}` + }); + + } catch (error) { + res.status(500).json({ error: error.message }); + } + }); + ``` + + + + **Security Best Practices:** + - API keys stored in environment variables + - Request validation and sanitization + - Rate limiting on API endpoints + - CORS configuration + - Webhook signature verification + + ```javascript + // Environment configuration + const config = { + requestNetwork: { + apiKey: process.env.REQUEST_NETWORK_API_KEY, + webhookSecret: process.env.REQUEST_WEBHOOK_SECRET, + environment: process.env.NODE_ENV === 'production' ? 'mainnet' : 'testnet' + } + }; + + // Middleware for API key validation + const validateApiKey = (req, res, next) => { + const apiKey = req.headers['x-api-key']; + if (!apiKey || !isValidApiKey(apiKey)) { + return res.status(401).json({ error: 'Invalid API key' }); + } + next(); + }; + ``` + + + +### Client-Side Integration Pattern +Suitable for simple applications and rapid prototyping. + + + + **Client-Side Flow:** + ``` + Frontend App โ†’ Request Network SDK โ†’ Blockchain + โ†“ + Payment Widget โ†’ Wallet Connection โ†’ Transaction + โ†“ + Confirmation โ†’ Frontend Updates โ†’ Backend Sync + ``` + + **Benefits:** + - Faster development + - Reduced backend complexity + - Real-time user feedback + - Lower infrastructure costs + + + + ```javascript + // Frontend payment component + import { RequestNetwork } from '@requestnetwork/request-client.js'; + + function PaymentComponent({ invoiceData }) { + const [paymentStatus, setPaymentStatus] = useState('pending'); + + const handlePayment = async () => { + try { + setPaymentStatus('processing'); + + // Create payment request + const request = await requestNetwork.createRequest({ + requestInfo: { + currency: invoiceData.currency, + expectedAmount: invoiceData.amount, + payee: { type: 'ethereumAddress', value: merchantAddress } + } + }); + + // Process payment + const payment = await request.pay(); + + setPaymentStatus('completed'); + onPaymentSuccess(payment); + + } catch (error) { + setPaymentStatus('failed'); + onPaymentError(error); + } + }; + + return ( + + ); + } + ``` + + + + **Consider These Limitations:** + - API keys exposed to frontend + - Limited server-side validation + - Webhook handling requires backend + - Less suitable for production systems + + **When to Use:** + - Prototyping and demos + - Simple payment collection + - Low-volume applications + - Educational purposes + + + +## E-commerce Integration Patterns + +### Shopify Integration +Connect Request Network with Shopify for crypto payment acceptance. + + + + **Integration Components:** + - Shopify App with payment gateway registration + - Backend service for Request Network integration + - Webhook handlers for payment confirmation + - Admin dashboard for configuration + + **Flow:** + 1. Customer selects crypto payment at checkout + 2. Shopify redirects to Request Network payment page + 3. Customer completes crypto payment + 4. Webhook confirms payment to Shopify + 5. Order status updated automatically + + + + ```javascript + // Shopify payment gateway endpoint + app.post('/shopify/payment/create', async (req, res) => { + const { order, return_url, cancel_url } = req.body; + + // Create Request Network payment request + const paymentRequest = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USD', + expectedAmount: order.total_price, + payee: { type: 'ethereumAddress', value: merchantAddress } + }, + contentData: { + reason: `Shopify Order #${order.order_number}`, + shopifyOrderId: order.id, + returnUrl: return_url, + cancelUrl: cancel_url + } + }); + + // Redirect to payment page + res.redirect(`/pay/${paymentRequest.requestId}`); + }); + + // Payment confirmation webhook + app.post('/webhook/payment-confirmed', async (req, res) => { + const { requestId, paymentHash } = req.body; + + // Get order info from Request Network + const request = await requestNetwork.getRequest(requestId); + const shopifyOrderId = request.contentData.shopifyOrderId; + + // Update Shopify order status + await shopifyAPI.orders.update(shopifyOrderId, { + financial_status: 'paid', + transactions: [{ + kind: 'sale', + status: 'success', + amount: request.expectedAmount, + gateway: 'request-network' + }] + }); + + res.status(200).send('OK'); + }); + ``` + + + +### WooCommerce Integration +Enable crypto payments in WordPress/WooCommerce stores. + + + + **WordPress Plugin Structure:** + - Payment gateway plugin registration + - Admin settings page for configuration + - Checkout integration hooks + - Order status management + + **Key Features:** + - Seamless checkout experience + - Automatic order fulfillment + - Refund handling + - Multi-currency support + + + + ```php + id = 'request_network'; + $this->method_title = 'Request Network'; + $this->method_description = 'Accept crypto payments via Request Network'; + + $this->init_form_fields(); + $this->init_settings(); + + // Hook into WooCommerce + add_action('woocommerce_update_options_payment_gateways_' . $this->id, + array($this, 'process_admin_options')); + add_action('woocommerce_api_request_network_webhook', + array($this, 'handle_webhook')); + } + + public function process_payment($order_id) { + $order = wc_get_order($order_id); + + // Create Request Network payment request + $response = wp_remote_post($this->api_endpoint . '/create-request', array( + 'body' => json_encode(array( + 'amount' => $order->get_total(), + 'currency' => $order->get_currency(), + 'order_id' => $order_id, + 'return_url' => $this->get_return_url($order) + )), + 'headers' => array( + 'Content-Type' => 'application/json', + 'Authorization' => 'Bearer ' . $this->api_key + ) + )); + + $payment_data = json_decode(wp_remote_retrieve_body($response), true); + + // Redirect to payment page + return array( + 'result' => 'success', + 'redirect' => $payment_data['payment_url'] + ); + } + } + ``` + + + +## SaaS & Subscription Patterns + +### Multi-Tenant SaaS Architecture +Scale Request Network for multiple customers in a SaaS platform. + + + + **Isolation Strategy:** + - Separate API keys per tenant + - Namespace separation for requests + - Isolated webhook endpoints + - Tenant-specific fee structures + + ```javascript + // Tenant-aware request creation + async function createTenantRequest(tenantId, requestData) { + const tenantConfig = await getTenantConfig(tenantId); + + const request = await requestNetwork.createRequest({ + ...requestData, + contentData: { + ...requestData.contentData, + tenantId, + tenantDomain: tenantConfig.domain + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentAddress: tenantConfig.walletAddress, + feeAddress: platformFeeAddress, + feeAmount: tenantConfig.platformFeePercentage + } + } + }, { + apiKey: tenantConfig.requestNetworkApiKey + }); + + return request; + } + ``` + + + + **Multi-Tenant Webhook Handling:** + - Single webhook endpoint for all tenants + - Route events based on tenant identification + - Isolated processing per tenant + - Failover and retry mechanisms + + ```javascript + app.post('/webhook/payment-events', async (req, res) => { + try { + const { eventType, data } = req.body; + const tenantId = data.contentData?.tenantId; + + if (!tenantId) { + return res.status(400).send('Missing tenant ID'); + } + + // Route to tenant-specific handler + const tenantHandler = getTenantHandler(tenantId); + await tenantHandler.processEvent(eventType, data); + + res.status(200).send('OK'); + + } catch (error) { + console.error('Webhook error:', error); + res.status(500).send('Error processing webhook'); + } + }); + ``` + + + + **SaaS Billing Patterns:** + - Usage-based billing with Request Network + - Platform fees from tenant transactions + - Automated billing for SaaS subscriptions + - Revenue sharing with tenants + + ```javascript + // Calculate and charge platform fees + async function processPlatformBilling(tenantId, billingPeriod) { + const usage = await getUsageMetrics(tenantId, billingPeriod); + const tenantConfig = await getTenantConfig(tenantId); + + const platformFee = calculatePlatformFee(usage, tenantConfig.pricingTier); + + // Create platform billing request + const billingRequest = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USD', + expectedAmount: platformFee.toString(), + payee: { type: 'ethereumAddress', value: platformWalletAddress }, + payer: { type: 'ethereumAddress', value: tenantConfig.walletAddress } + }, + contentData: { + reason: `Platform Fee - ${billingPeriod}`, + tenantId, + usageMetrics: usage, + feeBreakdown: platformFee.breakdown + } + }); + + return billingRequest; + } + ``` + + + +## Enterprise Integration Patterns + +### ERP System Integration +Connect Request Network with enterprise resource planning systems. + + + + **SAP S/4HANA Integration:** + - Invoice creation from SAP sales orders + - Payment status synchronization + - Automatic accounting document creation + - Multi-company and multi-currency support + + ```javascript + // SAP integration service + class SAPRequestNetworkIntegration { + async createInvoiceFromSalesOrder(salesOrderId) { + // Fetch sales order from SAP + const salesOrder = await this.sapAPI.getSalesOrder(salesOrderId); + + // Create Request Network payment request + const paymentRequest = await requestNetwork.createRequest({ + requestInfo: { + currency: salesOrder.currency, + expectedAmount: salesOrder.totalAmount, + payee: { type: 'ethereumAddress', value: companyWalletAddress } + }, + contentData: { + reason: `Invoice for Sales Order ${salesOrderId}`, + sapSalesOrderId: salesOrderId, + sapCustomerId: salesOrder.customerId, + sapCompanyCode: salesOrder.companyCode + } + }); + + // Update SAP with Request Network details + await this.sapAPI.updateSalesOrder(salesOrderId, { + paymentRequestId: paymentRequest.requestId, + paymentStatus: 'pending' + }); + + return paymentRequest; + } + } + ``` + + + + **NetSuite Integration Pattern:** + - SuiteScript for Request Network communication + - Custom records for payment tracking + - Automated journal entry creation + - Revenue recognition automation + + + + **Dynamics 365 Integration:** + - Power Platform connectors + - Custom API integration + - Automated invoice processing + - Financial reporting integration + + + +## Development Best Practices + +### Error Handling Strategies + + +```javascript Retry Pattern +class RequestNetworkClient { + async createRequestWithRetry(requestData, maxRetries = 3) { + let lastError; + + for (let attempt = 1; attempt <= maxRetries; attempt++) { + try { + return await requestNetwork.createRequest(requestData); + } catch (error) { + lastError = error; + + // Don't retry on permanent errors + if (error.code === 'INVALID_REQUEST' || error.code === 'UNAUTHORIZED') { + throw error; + } + + // Exponential backoff + const delay = Math.pow(2, attempt) * 1000; + await new Promise(resolve => setTimeout(resolve, delay)); + + console.log(`Request creation attempt ${attempt} failed, retrying...`); + } + } + + throw lastError; + } +} +``` + +```javascript Circuit Breaker +class CircuitBreaker { + constructor(threshold = 5, timeout = 60000) { + this.failureThreshold = threshold; + this.timeout = timeout; + this.failureCount = 0; + this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN + this.nextAttempt = null; + } + + async call(fn) { + if (this.state === 'OPEN') { + if (Date.now() < this.nextAttempt) { + throw new Error('Circuit breaker is OPEN'); + } + this.state = 'HALF_OPEN'; + } + + try { + const result = await fn(); + this.onSuccess(); + return result; + } catch (error) { + this.onFailure(); + throw error; + } + } + + onSuccess() { + this.failureCount = 0; + this.state = 'CLOSED'; + } + + onFailure() { + this.failureCount++; + if (this.failureCount >= this.failureThreshold) { + this.state = 'OPEN'; + this.nextAttempt = Date.now() + this.timeout; + } + } +} +``` + + +### Performance Optimization + + + + **Cache Request Data:** + ```javascript + // Redis caching for request data + const redis = new Redis(process.env.REDIS_URL); + + async function getCachedRequest(requestId) { + const cacheKey = `request:${requestId}`; + const cached = await redis.get(cacheKey); + + if (cached) { + return JSON.parse(cached); + } + + const request = await requestNetwork.getRequest(requestId); + await redis.setex(cacheKey, 300, JSON.stringify(request)); // 5 min cache + + return request; + } + ``` + + + + **Optimize Batch Operations:** + ```javascript + // Batch multiple operations + async function processBatchPayments(payments) { + const batchSize = 10; + const batches = []; + + for (let i = 0; i < payments.length; i += batchSize) { + batches.push(payments.slice(i, i + batchSize)); + } + + const results = await Promise.allSettled( + batches.map(batch => requestNetwork.createBatchPayout({ + payouts: batch + })) + ); + + return results; + } + ``` + + + + **Optimize Network Connections:** + ```javascript + // HTTP client with connection pooling + const axios = require('axios'); + const { Agent } = require('https'); + + const httpAgent = new Agent({ + keepAlive: true, + maxSockets: 100, + maxFreeSockets: 10, + timeout: 60000 + }); + + const requestNetworkClient = axios.create({ + baseURL: 'https://api.request.network', + httpsAgent: httpAgent, + timeout: 30000 + }); + ``` + + + +## What's Next? + + + + Detailed API endpoint documentation and examples + + + + Set up your development environment and API keys + + + + Explore specific implementation scenarios + + diff --git a/api-features/payment-types.mdx b/api-features/payment-types.mdx new file mode 100644 index 0000000..041d167 --- /dev/null +++ b/api-features/payment-types.mdx @@ -0,0 +1,350 @@ +--- +title: "Payment Types" +description: "Comprehensive guide to Request Network's payment capabilities and transaction types" +--- + +## Overview + +Request Network supports multiple payment types to accommodate different business needs and transaction patterns. From simple direct payments to complex cross-chain transactions, our payment infrastructure provides the flexibility to handle any payment scenario. + +## Standard Payments + +### Direct Payments (Payouts) +Send payments immediately without creating a request first. Perfect for vendor payments, contractor payouts, and one-time transfers. + + + + **Use Case:** Individual vendor payments, contractor fees + + **Features:** + - Instant payment execution + - Real-time confirmation + - Automatic payment records + + **Best For:** [Payouts](/use-cases/payouts), [Payroll](/use-cases/payroll) + + + + **Use Case:** Payroll processing, multiple vendor payments + + **Features:** + - Multiple recipients in one transaction + - Gas cost optimization + - Atomic transaction processing + + **Best For:** [Payroll](/use-cases/payroll), bulk [Payouts](/use-cases/payouts) + + + +### Request-Based Payments (Invoicing) +Create payment requests first, then allow customers to pay. Ideal for invoicing, e-commerce checkout, and formal payment collection. + + + + **Use Case:** Professional invoicing, B2B payments + + **Features:** + - Payment request creation + - Customer payment portal + - Payment tracking and reconciliation + + **Best For:** [Invoicing](/use-cases/invoicing), formal payment collection + + + + **Use Case:** E-commerce, digital goods, services + + **Features:** + - Embedded payment widgets + - Real-time payment confirmation + - Order reconciliation + + **Best For:** [Checkout](/use-cases/checkout), e-commerce integration + + + +## Advanced Payment Types + +### Cross-Chain Payments +Enable payments across different blockchain networks with automatic routing and optimization. + + + + **Cross-Chain Payment Flow:** + 1. Customer selects preferred payment chain + 2. Request Network routes payment optimally + 3. Merchant receives payment on their preferred chain + 4. Automatic bridging and conversion handled transparently + + **Supported Networks:** + - Ethereum, Polygon, Arbitrum, Optimism + - Base, BSC, Avalanche, Fantom + - Gnosis Chain, Celo + + + + **For Merchants:** + - Accept payments from any supported chain + - Receive payments on preferred network + - Reduced friction for customers + + **For Customers:** + - Pay with assets on any chain + - No manual bridging required + - Optimal routing for lowest fees + + + + **Perfect For:** + - Global e-commerce platforms + - Multi-chain DeFi applications + - International B2B payments + - Cross-border transactions + + + +### Conversion Payments (Crypto-to-Fiat) +Accept payments in crypto while receiving fiat currency, or invoice in fiat while accepting crypto payments. + + + + **Business Scenario:** You want to price in familiar fiat terms but receive crypto + + - Set invoice amount in USD + - Customer sees real-time crypto equivalent + - You receive payment in your preferred cryptocurrency + - Automatic price conversion at payment time + + + + **Business Scenario:** You want crypto exposure for pricing but fiat for operations + + - Set invoice amount in cryptocurrency + - Automatic conversion to fiat upon payment + - Receive fiat in your business bank account + - Eliminate crypto volatility risk + + + + **Business Scenario:** Accept both crypto and fiat based on customer preference + + - Customers choose payment currency + - You specify preferred receiving currency + - Automatic conversion and settlement + - Unified payment reconciliation + + + +### Recurring Payments +Automate subscription billing and recurring payment collection with flexible scheduling. + + + + **Frequency Options:** + - Weekly, bi-weekly, monthly + - Quarterly, semi-annual, annual + - Custom intervals + + **Perfect For:** [Subscriptions](/use-cases/subscriptions), SaaS billing + + + + **Automation Features:** + - Scheduled vendor payments + - Automated payroll processing + - Recurring retainer payments + + **Perfect For:** [Payroll](/use-cases/payroll), vendor management + + + + **Advanced Options:** + - Pro-rated billing periods + - Grace periods for failed payments + - Automatic retry logic + + **Perfect For:** Complex billing scenarios + + + +## Payment Implementation Patterns + +### Payment Request Lifecycle + + + + Create payment request with amount, currency, and metadata + + + Share payment link or embed payment widget + + + Customer completes payment using their preferred method + + + Automatic payment detection and business system updates + + + +### Direct Payout Flow + + + + Specify recipient address, amount, and payment currency + + + Payment sent immediately to recipient's wallet + + + Real-time transaction confirmation and record creation + + + Automatic payment record creation for accounting + + + +## Technical Implementation + + +```javascript Payment Request +import { RequestNetwork } from '@requestnetwork/request-client.js'; + +// Create a payment request +const paymentRequest = await requestNetwork.createRequest({ + requestInfo: { + currency: 'USD', + expectedAmount: '1000', + payee: { + type: 'ethereumAddress', + value: merchantAddress + }, + payer: { + type: 'ethereumAddress', + value: customerAddress + } + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentNetworkName: 'matic', + paymentAddress: merchantAddress, + feeAddress: platformFeeAddress, + feeAmount: '50' // 5% platform fee + } + }, + contentData: { + reason: 'Invoice #INV-001', + dueDate: '2025-10-01' + } +}); +``` + +```javascript Direct Payout +// Send direct payout +const payout = await requestNetwork.createPayout({ + payoutInfo: { + currency: 'USDC-matic', + amount: '1000', + recipient: vendorAddress, + reason: 'Vendor Payment - Project ABC' + }, + paymentNetwork: { + id: 'erc20-fee-proxy-contract', + parameters: { + paymentNetworkName: 'matic' + } + } +}); +``` + +```javascript Batch Processing +// Process batch payments +const batchPayout = await requestNetwork.createBatchPayout({ + payouts: [ + { + currency: 'USDC-matic', + amount: '2000', + recipient: employee1Address, + reason: 'Salary - March 2025' + }, + { + currency: 'USDC-matic', + amount: '2500', + recipient: employee2Address, + reason: 'Salary - March 2025' + } + ], + batchSettings: { + gasOptimization: true, + atomicExecution: true + } +}); +``` + + +## Currency Support + + + + **553+ Currencies Across 10 EVM Chains** + + **Major Cryptocurrencies:** + - ETH, BTC, USDC, USDT, DAI + - MATIC, AVAX, BNB, FTM + - Hundreds of ERC-20 tokens + + **Fiat Currencies:** + - USD, EUR, GBP, JPY + - 150+ international currencies + + [View Complete List โ†’](/resources/supported-chains-and-currencies) + + + + **10 EVM-Compatible Networks:** + - Ethereum Mainnet & Sepolia + - Polygon & Mumbai + - Arbitrum One & Sepolia + - Optimism & Sepolia + - Base & Sepolia + - And more... + + [Chain Details โ†’](/resources/supported-chains-and-currencies) + + + + **Real-Time Price Feeds:** + - Chainlink price oracles + - Multiple data source aggregation + - Sub-minute price updates + - Slippage protection + + + +## What's Next? + + + + Explore webhooks, fees, and metadata capabilities + + + + Learn common integration patterns and best practices + + + + Detailed API endpoint documentation + + diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx new file mode 100644 index 0000000..05723d5 --- /dev/null +++ b/api-reference/authentication.mdx @@ -0,0 +1,218 @@ +--- +title: "Authentication" +description: "API authentication, key management, and security best practices" +--- + +## Authentication Overview + +Request Network API uses API key authentication to secure access to endpoints. This guide covers how to obtain, manage, and use your API keys securely. + +## Getting API Keys + + + + Sign up for a Request Network account at the [Request Portal](https://portal.request.network) + + + Navigate to the API Keys section and create a new API key for your project + + + Store your API key securely in environment variables + + + Make your first authenticated API call to verify setup + + + +## API Key Management + + + + **Production Environment:** + - Use separate keys for production + - Implement key rotation policies + - Monitor usage and access logs + - Set up rate limiting and alerts + + + + **Development Environment:** + - Use testnet for development + - Separate keys for each environment + - Team access management + - Testing and debugging tools + + + +## Authentication Methods + + + + **API Key in Header (Recommended):** + + ```bash + curl -X POST https://api.request.network/v2/requests \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "currency": "USD", + "expectedAmount": "100", + "payeeIdentity": "0x...", + "reason": "Test invoice" + }' + ``` + + + + **Secure Key Storage:** + + ```javascript + // .env file + REQUEST_NETWORK_API_KEY=your_api_key_here + REQUEST_NETWORK_ENVIRONMENT=testnet + + // Application code + const requestNetwork = new RequestNetwork({ + apiKey: process.env.REQUEST_NETWORK_API_KEY, + environment: process.env.REQUEST_NETWORK_ENVIRONMENT + }); + ``` + + + + **SDK Authentication:** + + ```javascript + import { RequestNetwork } from '@requestnetwork/request-client.js'; + + const requestNetwork = new RequestNetwork({ + apiKey: process.env.REQUEST_NETWORK_API_KEY, + nodeConnectionConfig: { + baseURL: 'https://api.request.network' + } + }); + ``` + + + +## Security Best Practices + + + + **Protect Your API Keys:** + - Never commit API keys to version control + - Use environment variables for key storage + - Implement key rotation policies + - Monitor for unauthorized usage + - Use different keys for different environments + + + + **Secure Communication:** + - Always use HTTPS for API calls + - Implement request signing for sensitive operations + - Use webhook signature verification + - Implement rate limiting on your endpoints + + + + **Manage Access:** + - Use principle of least privilege + - Implement role-based access control + - Regular access audits + - Immediate revocation of compromised keys + + + +## Rate Limits + + +**Rate Limiting Information** + +Current rate limits apply to API usage. Contact support for enterprise rate limit increases. + + + + + **Default Rate Limits:** + - 100 requests per minute + - 1,000 requests per hour + - 10,000 requests per day + + **Applies to:** Most API endpoints + + + + **Webhook Rate Limits:** + - 50 webhook deliveries per minute + - Exponential backoff for retries + - Maximum 5 retry attempts + + **Applies to:** Webhook delivery endpoints + + + +## Error Codes + +Common authentication error responses: + + +```json 401 Unauthorized +{ + "error": { + "code": "UNAUTHORIZED", + "message": "Invalid or missing API key", + "details": "Please provide a valid API key in the Authorization header" + } +} +``` + +```json 403 Forbidden +{ + "error": { + "code": "FORBIDDEN", + "message": "API key does not have required permissions", + "details": "This operation requires additional permissions" + } +} +``` + +```json 429 Rate Limited +{ + "error": { + "code": "RATE_LIMITED", + "message": "Rate limit exceeded", + "details": "Too many requests. Please try again later.", + "retryAfter": 60 + } +} +``` + + +## What's Next? + + + + Set up real-time event notifications + + + + Make your first API call + + + + Manage your API keys and settings + + diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b..0000000 --- a/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc8..0000000 --- a/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09e..0000000 --- a/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/api-reference/endpoint/webhook.mdx b/api-reference/endpoint/webhook.mdx deleted file mode 100644 index 3291340..0000000 --- a/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' ---- diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx deleted file mode 100644 index c835b78..0000000 --- a/api-reference/introduction.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' ---- - - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - - -## Welcome - -There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. - - - View the OpenAPI specification file - - -## Authentication - -All API endpoints are authenticated using Bearer tokens and picked up from the specification file. - -```json -"security": [ - { - "bearerAuth": [] - } -] -``` diff --git a/api-reference/openapi.json b/api-reference/openapi.json deleted file mode 100644 index da5326e..0000000 --- a/api-reference/openapi.json +++ /dev/null @@ -1,217 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "OpenAPI Plant Store", - "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", - "license": { - "name": "MIT" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://sandbox.mintlify.com" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "paths": { - "/plants": { - "get": { - "description": "Returns all plants from the system that the user has access to", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to return", - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "Plant response", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Plant" - } - } - } - } - }, - "400": { - "description": "Unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "description": "Creates a new plant in the store", - "requestBody": { - "description": "Plant to add to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "plant response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Plant" - } - } - } - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/plants/{id}": { - "delete": { - "description": "Deletes a single plant based on the ID supplied", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of plant to delete", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - "responses": { - "204": { - "description": "Plant deleted", - "content": {} - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "webhooks": { - "/plant/webhook": { - "post": { - "description": "Information about a new plant added to the store", - "requestBody": { - "description": "Plant added to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - } - }, - "responses": { - "200": { - "description": "Return a 200 status to indicate that the data was received successfully" - } - } - } - } - }, - "components": { - "schemas": { - "Plant": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "description": "The name of the plant", - "type": "string" - }, - "tag": { - "description": "Tag to specify the type", - "type": "string" - } - } - }, - "NewPlant": { - "allOf": [ - { - "$ref": "#/components/schemas/Plant" - }, - { - "required": [ - "id" - ], - "type": "object", - "properties": { - "id": { - "description": "Identification number of the plant", - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "Error": { - "required": [ - "error", - "message" - ], - "type": "object", - "properties": { - "error": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - } - } -} \ No newline at end of file diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx new file mode 100644 index 0000000..35c5c68 --- /dev/null +++ b/api-reference/webhooks.mdx @@ -0,0 +1,521 @@ +--- +title: "Webhooks" +description: "Real-time event notifications and webhook configuration guide" +--- + +## Webhook 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. + +## Webhook Events + +### 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 + + + + + + **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 + + + +### 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 + + + +### Subscription 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 + + + +## Webhook Configuration + +### 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 + + + + **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 + 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'); + } + }); + ``` + + + + **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') + ); + } + ``` + + + + **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'); + } + } + }); + ``` + + + +## Webhook Payloads + +### Payment Confirmed Event + + +```json Payment Confirmed +{ + "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" + } + } +} +``` + +```json Request Created +{ + "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" + } + } + } +} +``` + +```json Subscription Renewed +{ + "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" + } + } +} +``` + + +## Integration Examples + +### E-commerce Order Processing + + +```javascript Express.js Handler +app.post('/webhooks/payment-confirmed', async (req, res) => { + try { + // Verify webhook signature + if (!verifyWebhookSignature(req)) { + return res.status(401).send('Unauthorized'); + } + + const { eventType, data } = 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`); + } + + res.status(200).send('OK'); + + } catch (error) { + console.error('Webhook error:', error); + res.status(500).send('Error processing webhook'); + } +}); +``` + +```javascript SaaS Subscription Handler +app.post('/webhooks/subscription-events', async (req, res) => { + try { + const { eventType, data } = req.body; + + 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; + } + + res.status(200).send('OK'); + + } catch (error) { + console.error('Subscription webhook error:', error); + res.status(500).send('Error processing subscription webhook'); + } +}); +``` + + +### 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) +); +``` + +```javascript Database Handler +async function savePaymentEvent(eventData) { + const { + requestId, + eventType, + transactionHash, + blockNumber, + amount, + currency, + payerAddress, + payeeAddress, + metadata + } = eventData; + + // 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) + ]); + + return result.rows[0].id; +} +``` + + +## Testing Webhooks + +### Webhook Testing Tools + + + + **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 + + + +### Test Event Simulation + + +**Test Webhooks in Request Portal** + +Use the Request Portal to send test webhook events to your endpoint for development and testing. + + +## What's Next? + + + + Secure your API and webhook endpoints + + + + Learn more about webhook event types and handling + + + + Common webhook integration patterns and best practices + + diff --git a/api-setup/getting-started.mdx b/api-setup/getting-started.mdx new file mode 100644 index 0000000..b080180 --- /dev/null +++ b/api-setup/getting-started.mdx @@ -0,0 +1,362 @@ +--- +title: "Getting Started" +description: "Quick setup guide to get your API keys and start building with Request Network" +--- + +## Welcome to Request Network + +Get started with Request Network in just a few minutes. This guide will walk you through setting up your account, obtaining API keys, and making your first API call. + +## Quick Setup + + + + Sign up for a free Request Network account at [portal.request.network](https://portal.request.network) + + + Generate your API keys for both testnet (development) and mainnet (production) + + + Select your integration approach based on your use case + + + Test your setup with a simple API call + + + +## Account Setup + +### Request Portal Registration + + + + **For Developers:** + - Free account with generous limits + - Access to testnet for development + - API documentation and tools + - Community support + + [Sign Up โ†’](https://portal.request.network) + + + + **For Enterprises:** + - Higher rate limits + - Priority support + - Custom integrations + - SLA guarantees + + [Contact Sales โ†’](https://request.network/contact) + + + +### API Key Generation + + + + **Development Environment:** + 1. Log in to Request Portal + 2. Navigate to "API Keys" section + 3. Click "Generate New Key" + 4. Select "Testnet" environment + 5. Name your key (e.g., "Development") + 6. Copy and securely store the key + + + **Testnet vs Mainnet** + + Always start development on testnet. Testnet uses test cryptocurrencies with no real value. + + + + + **Production Environment:** + 1. Complete account verification + 2. Generate new API key + 3. Select "Mainnet" environment + 4. Configure production settings + 5. Set up monitoring and alerts + + + **Security Best Practices** + + - Store API keys in environment variables + - Never commit keys to version control + - Use different keys for different environments + - Rotate keys regularly + + + + +## Choose Your Path + +Select the integration approach that best fits your needs: + + + + **Best for:** Professional invoicing, B2B payments + + Get started with invoice creation and payment collection in under 5 minutes. + + + + **Best for:** Vendor payments, contractor payouts + + Send instant crypto payments to multiple recipients with batch processing. + + + + **Best for:** E-commerce, digital goods + + Accept crypto payments in your online store with 80+ wallet support. + + + + + + **Best for:** Employee payments, bulk processing + + Automate payroll with batch payments and recurring schedules. + + + + **Best for:** SaaS billing, recurring revenue + + Set up automated subscription billing with flexible payment cycles. + + + +## Quick Test + +Verify your setup with a simple API call: + + +```bash cURL +curl -X POST https://api.request.network/v2/requests \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "currency": "USD", + "expectedAmount": "100", + "payeeIdentity": "0x627306090abaB3A6e1400e9345bC60c78a8BEf57", + "reason": "Test invoice" + }' +``` + +```javascript Node.js +const axios = require('axios'); + +async function createTestRequest() { + try { + const response = await axios.post('https://api.request.network/v2/requests', { + currency: 'USD', + expectedAmount: '100', + payeeIdentity: '0x627306090abaB3A6e1400e9345bC60c78a8BEf57', + reason: 'Test invoice' + }, { + headers: { + 'Authorization': `Bearer ${process.env.REQUEST_NETWORK_API_KEY}`, + 'Content-Type': 'application/json' + } + }); + + console.log('Request created:', response.data.requestId); + return response.data; + + } catch (error) { + console.error('Error creating request:', error.response?.data || error.message); + } +} + +createTestRequest(); +``` + +```python Python +import requests +import os + +def create_test_request(): + url = "https://api.request.network/v2/requests" + + headers = { + "Authorization": f"Bearer {os.getenv('REQUEST_NETWORK_API_KEY')}", + "Content-Type": "application/json" + } + + data = { + "currency": "USD", + "expectedAmount": "100", + "payeeIdentity": "0x627306090abaB3A6e1400e9345bC60c78a8BEf57", + "reason": "Test invoice" + } + + try: + response = requests.post(url, json=data, headers=headers) + response.raise_for_status() + + print(f"Request created: {response.json()['requestId']}") + return response.json() + + except requests.exceptions.RequestException as e: + print(f"Error creating request: {e}") + +create_test_request() +``` + + +## Environment Configuration + +### Environment Variables + +Set up your environment variables for secure API key management: + + +```bash .env +# Request Network Configuration +REQUEST_NETWORK_API_KEY=your_api_key_here +REQUEST_NETWORK_ENVIRONMENT=testnet + +# Webhook Configuration (optional) +REQUEST_WEBHOOK_SECRET=your_webhook_secret_here +REQUEST_WEBHOOK_URL=https://your-domain.com/webhooks/request-network + +# Application Configuration +PORT=3000 +NODE_ENV=development +``` + +```javascript config.js +module.exports = { + requestNetwork: { + apiKey: process.env.REQUEST_NETWORK_API_KEY, + environment: process.env.REQUEST_NETWORK_ENVIRONMENT || 'testnet', + webhookSecret: process.env.REQUEST_WEBHOOK_SECRET, + webhookUrl: process.env.REQUEST_WEBHOOK_URL + }, + app: { + port: process.env.PORT || 3000, + environment: process.env.NODE_ENV || 'development' + } +}; +``` + + +## Development Tools + +### Request Portal Features + + + + **Interactive Testing:** + - Test API endpoints directly in browser + - Real-time response preview + - Code generation for multiple languages + - Request/response logging + + + + **Webhook Development:** + - Test webhook delivery + - Inspect webhook payloads + - Retry failed webhooks + - Webhook logs and analytics + + + + + + **Real-time Monitoring:** + - Live transaction tracking + - Payment status updates + - Error monitoring and alerts + - Performance metrics + + + + **Usage Analytics:** + - API usage statistics + - Payment volume tracking + - Success/failure rates + - Performance insights + + + +## Troubleshooting + +### Common Issues + + + + **401 Unauthorized:** + - Verify API key is correct + - Check environment (testnet vs mainnet) + - Ensure API key has required permissions + - Verify Authorization header format + + + + **429 Too Many Requests:** + - Implement exponential backoff + - Check your current rate limits + - Consider upgrading to higher limits + - Optimize API call frequency + + + + **Connection Problems:** + - Check network connectivity + - Verify API endpoint URLs + - Test with different networks + - Check firewall settings + + + +## What's Next? + +Now that you're set up, explore the features that matter most to your use case: + + + + Detailed API endpoint documentation + + + + Learn about payment types and advanced capabilities + + + + Best practices and common integration patterns + + diff --git a/development.mdx b/development.mdx deleted file mode 100644 index ac633ba..0000000 --- a/development.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: 'Development' -description: 'Preview changes locally to update your docs' ---- - - - **Prerequisites**: - - Node.js version 19 or higher - - A docs repository with a `docs.json` file - - -Follow these steps to install and run Mintlify on your operating system. - - - - -```bash -npm i -g mint -``` - - - - -Navigate to your docs directory where your `docs.json` file is located, and run the following command: - -```bash -mint dev -``` - -A local preview of your documentation will be available at `http://localhost:3000`. - - - - -## Custom ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command: - -```bash -mint dev --port 3333 -``` - -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` - -## Mintlify versions - -Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI: - -```bash -npm mint update -``` - -## Validating links - -The CLI can assist with validating links in your documentation. To identify any broken links, use the following command: - -```bash -mint broken-links -``` - -## Deployment - -If the deployment is successful, you should see the following: - - - Screenshot of a deployment confirmation message that says All checks have passed. - - -## Code formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting - - - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of the CLI: `npm remove -g mint` - 2. Upgrade to Node v19 or higher. - 3. Reinstall the CLI: `npm i -g mint` - - - - - Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again. - - - -Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions). diff --git a/docs.json b/docs.json index cf106b7..6e2b9d3 100644 --- a/docs.json +++ b/docs.json @@ -1,127 +1,210 @@ { "$schema": "https://mintlify.com/docs.json", "theme": "mint", - "name": "Mint Starter Kit", + "name": "Request Network Docs", "colors": { - "primary": "#16A34A", - "light": "#07C983", - "dark": "#15803D" + "primary": "#01B089", + "light": "#59F9D6", + "dark": "#01513B" + }, + "appearance": { + "default": "dark" + }, + "background": { + "decoration": "gradient", + "color": { + "light": "#FFFFFF", + "dark": "#001912" + } }, "favicon": "/favicon.svg", + "fonts": { + "heading": { + "family": "Montserrat" + }, + "body": { + "family": "Montserrat", + "weight": 500 + } + }, + "thumbnails": { + "appearance": "dark" + }, + "banner": { + "content": "๐Ÿš€ New: Check out our revamped documentation!", + "dismissible": true + }, "navigation": { "tabs": [ { - "tab": "Guides", + "tab": "Welcome", + "pages": ["index"] + }, + { + "tab": "Use Cases", "groups": [ { - "group": "Getting started", + "group": "๐Ÿ“„ Primary Use Cases", "pages": [ - "index", - "quickstart", - "development" + "use-cases/invoicing", + "use-cases/payouts", + "use-cases/payroll", + "use-cases/checkout", + "use-cases/subscriptions" ] - }, + } + ] + }, + { + "tab": "API", + "groups": [ { - "group": "Customization", + "group": "๐Ÿ”‘ API Setup", "pages": [ - "essentials/settings", - "essentials/navigation" + "api-setup/getting-started", + "request-network-api/api-portal-manage-api-keys-and-webhooks" ] }, { - "group": "Writing content", + "group": "โš™๏ธ API Features", "pages": [ - "essentials/markdown", - "essentials/code", - "essentials/images", - "essentials/reusable-snippets" + "api-features/payment-types", + "api-features/advanced-features", + "api-features/integration-patterns" ] }, { - "group": "AI tools", + "group": "๐Ÿ“š API Reference", "pages": [ - "ai-tools/cursor", - "ai-tools/claude-code", - "ai-tools/windsurf" + "api-reference/authentication", + "api-reference/webhooks", + { + "group": "Endpoints", + "openapi": "https://api.stage.request.network/open-api/openapi.json", + "pages": [ + "request-network-api/create-and-pay-requests" + ] + } ] } ] }, { - "tab": "API reference", + "tab": "Resources", "groups": [ { - "group": "API documentation", + "group": "๐ŸŒ Developer Resources", "pages": [ - "api-reference/introduction" + "resources/supported-chains-and-currencies", + "resources/smart-contracts", + "resources/community" ] }, { - "group": "Endpoint examples", + "group": "๐Ÿ“– Documentation", + "pages": [ + "faq", + "glossary" + ] + } + ] + }, + { + "tab": "SDK (Legacy)", + "groups": [ + { + "group": "๐Ÿ”ง SDK Documentation", + "pages": [ + "request-network-api/migrate-to-v2", + "sdk-legacy/migration-guide" + ] + } + ] + }, + { + "tab": "Release Notes", + "groups": [ + { + "group": "๐Ÿ“‹ Release Notes", "pages": [ - "api-reference/endpoint/get", - "api-reference/endpoint/create", - "api-reference/endpoint/delete", - "api-reference/endpoint/webhook" + "release-notes/index", + "release-notes/request-api", + "release-notes/easy-invoice" ] } ] } - ], - "global": { - "anchors": [ - { - "anchor": "Documentation", - "href": "https://mintlify.com/docs", - "icon": "book-open-cover" - }, - { - "anchor": "Community", - "href": "https://mintlify.com/community", - "icon": "slack" - }, - { - "anchor": "Blog", - "href": "https://mintlify.com/blog", - "icon": "newspaper" - } - ] - } + ] }, "logo": { "light": "/logo/light.svg", - "dark": "/logo/dark.svg" + "dark": "/logo/dark.svg", + "href": "https://request.network" }, "navbar": { "links": [ { "label": "Support", - "href": "mailto:hi@mintlify.com" + "href": "https://github.com/orgs/RequestNetwork/discussions" } ], - "primary": { + "primary": + { "type": "button", - "label": "Dashboard", - "href": "https://dashboard.mintlify.com" + "label": "Get your API Key", + "href": "https://portal.request.network" } }, "contextual": { "options": [ - "copy", - "view", - "chatgpt", - "claude", - "perplexity", - "mcp", - "cursor", - "vscode" - ] + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] }, "footer": { "socials": { - "x": "https://x.com/mintlify", - "github": "https://github.com/mintlify", - "linkedin": "https://linkedin.com/company/mintlify" - } + "x": "https://x.com/RequestNetwork", + "discord": "https://request.network/discord", + "github": "https://github.com/RequestNetwork", + "linkedin": "https://www.linkedin.com/company/request-network", + "bluesky": "https://bsky.app/profile/requestnetwork.bsky.social" + }, + "links": [ + { + "items": [ + { + "label": "Website", + "href": "https://request.network" + }, + { + "label": "Community", + "href": "https://discord.com/invite/FsVAR3ny3f" + }, + { + "label": "Portal", + "href": "https://portal.request.network" + }, + { + "label": "Scan", + "href": "https://scan.request.network" + }, + { + "label": "Status", + "href": "https://status.request.network" + }, + { + "label": "Blog", + "href": "https://request.network/blog" + } + ] + + } + ] } } diff --git a/essentials/code.mdx b/essentials/code.mdx deleted file mode 100644 index ae2abbf..0000000 --- a/essentials/code.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: 'Code blocks' -description: 'Display inline code and code blocks' -icon: 'code' ---- - -## Inline code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -## Code blocks - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` diff --git a/essentials/images.mdx b/essentials/images.mdx deleted file mode 100644 index 1144eb2..0000000 --- a/essentials/images.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Images and embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' ---- - - - -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code - -```md -![title](/path/image.jpg) -``` - -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using embeds - -To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images - -```html - -``` - -## Embeds and HTML elements - - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -### iFrames - -Loads another HTML page within the document. Most commonly used for embedding videos. - -```html - -``` diff --git a/essentials/markdown.mdx b/essentials/markdown.mdx deleted file mode 100644 index a45c1d5..0000000 --- a/essentials/markdown.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'Markdown syntax' -description: 'Text, title, and styling in standard markdown' -icon: 'text-size' ---- - -## Titles - -Best used for section headers. - -```md -## Titles -``` - -### Subtitles - -Best used for subsection headers. - -```md -### Subtitles -``` - - - -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. - - - -## Text formatting - -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. - -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | - -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. - -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. - -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | - -## Linking to pages - -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). - -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section. - -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. - -## Blockquotes - -### Singleline - -To create a blockquote, add a `>` in front of a paragraph. - -> Dorothy followed her through many of the beautiful rooms in her castle. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -``` - -### Multiline - -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. -``` - -### LaTeX - -Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component. - -8 x (vk x H1 - H2) = (0,1) - -```md -8 x (vk x H1 - H2) = (0,1) -``` diff --git a/essentials/navigation.mdx b/essentials/navigation.mdx deleted file mode 100644 index 60adeff..0000000 --- a/essentials/navigation.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: 'Navigation' -description: 'The navigation field in docs.json defines the pages that go in the navigation menu' -icon: 'map' ---- - -The navigation menu is the list of links on every website. - -You will likely update `docs.json` every time you add a new page. Pages do not show up automatically. - -## Navigation syntax - -Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names. - - - -```json Regular Navigation -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Getting Started", - "pages": ["quickstart"] - } - ] - } - ] -} -``` - -```json Nested Navigation -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } - ] - } - ] -} -``` - - - -## Folders - -Simply put your MDX files in folders and update the paths in `docs.json`. - -For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`. - - - -You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted. - - - -```json Navigation With Folder -"navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } - ] - } - ] -} -``` - -## Hidden pages - -MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them. diff --git a/essentials/reusable-snippets.mdx b/essentials/reusable-snippets.mdx deleted file mode 100644 index 376e27b..0000000 --- a/essentials/reusable-snippets.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Reusable snippets" -description: "Reusable, custom snippets to keep content in sync" -icon: "recycle" ---- - -import SnippetIntro from '/snippets/snippet-intro.mdx'; - - - -## Creating a custom snippet - -**Pre-condition**: You must create your snippet file in the `snippets` directory. - - - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a - component. - - -### Default export - -1. Add content to your snippet file that you want to re-use across multiple - locations. Optionally, you can add variables that can be filled in via props - when you import the snippet. - -```mdx snippets/my-snippet.mdx -Hello world! This is my content I want to reuse across pages. My keyword of the -day is {word}. -``` - - - The content that you want to reuse must be inside the `snippets` directory in - order for the import to work. - - -2. Import the snippet into your destination file. - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## Header - -Lorem impsum dolor sit amet. - - -``` - -### Reusable variables - -1. Export a variable from your snippet file: - -```mdx snippets/path/to/custom-variables.mdx -export const myName = 'my name'; - -export const myObject = { fruit: 'strawberries' }; -``` - -2. Import the snippet from your destination file and use the variable: - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; - -Hello, my name is {myName} and I like {myObject.fruit}. -``` - -### Reusable components - -1. Inside your snippet file, create a component that takes in props by exporting - your component in the form of an arrow function. - -```mdx snippets/custom-component.mdx -export const MyComponent = ({ title }) => ( -
-

{title}

-

... snippet content ...

-
-); -``` - - - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. - - -2. Import the snippet into your destination file and pass in the props - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { MyComponent } from '/snippets/custom-component.mdx'; - -Lorem ipsum dolor sit amet. - - -``` diff --git a/essentials/settings.mdx b/essentials/settings.mdx deleted file mode 100644 index 884de13..0000000 --- a/essentials/settings.mdx +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: 'Global Settings' -description: 'Mintlify gives you complete control over the look and feel of your documentation using the docs.json file' -icon: 'gear' ---- - -Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below. - -## Properties - - -Name of your project. Used for the global title. - -Example: `mintlify` - - - - - An array of groups with all the pages within that group - - - The name of the group. - - Example: `Settings` - - - - The relative paths to the markdown files that will serve as pages. - - Example: `["customization", "page"]` - - - - - - - - Path to logo image or object with path to "light" and "dark" mode logo images - - - Path to the logo in light mode - - - Path to the logo in dark mode - - - Where clicking on the logo links you to - - - - - - Path to the favicon image - - - - Hex color codes for your global theme - - - The primary color. Used for most often for highlighted content, section - headers, accents, in light mode - - - The primary color for dark mode. Used for most often for highlighted - content, section headers, accents, in dark mode - - - The primary color for important buttons - - - The color of the background in both light and dark mode - - - The hex color code of the background in light mode - - - The hex color code of the background in dark mode - - - - - - - - Array of `name`s and `url`s of links you want to include in the topbar - - - The name of the button. - - Example: `Contact us` - - - The url once you click on the button. Example: `https://mintlify.com/docs` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars. - - - If `link`: What the button links to. - - If `github`: Link to the repository to load GitHub information from. - - - Text inside the button. Only required if `type` is a `link`. - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - - - - An array of the anchors, includes the `icon`, `color`, and `url`. - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - The name of the anchor label. - - Example: `Community` - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - Used if you want to hide an anchor until the correct docs version is selected. - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. - - - The name of the top-most anchor - - - Font Awesome icon. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - An array of navigational tabs. - - - The name of the tab label. - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo). - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground/demo) - - - - - - Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. - - This behavior will soon be enabled by default, at which point this field will be deprecated. - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - - Examples: - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - ```json Relative - "openapi": "/openapi.json" - ``` - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - - - An object of social media accounts where the key:property pair represents the social media platform and the account url. - - Example: - ```json - { - "x": "https://x.com/mintlify", - "website": "https://mintlify.com" - } - ``` - - - One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news` - - Example: `x` - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - Configurations to enable feedback buttons - - - - Enables a button to allow users to suggest edits via pull requests - - - Enables a button to allow users to raise an issue about the documentation - - - - - - Customize the dark mode toggle. - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - - - - - - A background image to be displayed behind every page. See example with - [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). - diff --git a/faq.mdx b/faq.mdx new file mode 100644 index 0000000..dc42499 --- /dev/null +++ b/faq.mdx @@ -0,0 +1,109 @@ +--- +title: "FAQ" +description: "Frequently Asked Questions and Common Misconceptions" + +--- + +If your question is not answered below, please consider posting it to the [Request Network Discussions](https://github.com/orgs/RequestNetwork/discussions) page on Github. + + + + + No. Request Network is not a blockchain, smart contract platform, or scaling solution. Rather, it's a protocol for storing payment requests, facilitating on-chain payments, and reconciling those payments with the requests. It stores payment requests in [IPFS](https://www.ipfs.com/) and CID hashes on [Gnosis Chain](https://www.gnosis.io/). It uses [The Graph](https://thegraph.com/) for on-chain event indexing. It processes payments across a variety of [supported payment chains](https://docs.request.network/get-started/supported-chains). + + + + Request Network is an open-source protocol. Request Finance is a product built on top of Request Network. Request Finance has spun off from Request Network, and they are now two separate teams. + + + + No. Requests are created on Gnosis Chain (or Sepolia for testing), even if the payment will happen on a different chain. Payment(s) can occur on any of our [supported payment chains](https://docs.request.network/get-started/supported-chains#payments). + + To help builders get started quickly, the Request Network Foundation operates [Request Node Gateways](https://docs.request.network/get-started/request-node-gateways) that are free for anyone to use. These gateways offer endpoints for creating and retrieving requests. + + Requests created on Gnosis Chain are "real" and will exist forever. Requests created on Sepolia are "test" requests and will exist only as long as Sepolia continues to operate. + + + + It can be, but not necessarily. The [Signer Identity](https://docs.request.network/glossary#signer-identity) that signs to create a request is defined by the `signer` parameter. This is separate from the [Payment Recipient](https://docs.request.network/glossary#payment-recipient) which is defined by the `paymentNetwork.parameters.paymentAddress` parameter. They can be the same or different. + + This design allows for a single payee identity to have potentially multiple payment recipient addresses. + + See [Parties of a Request](https://docs.request.network/glossary#parties-of-a-request) for details. + + + + No. Request Network is a hybrid on/off-chain protocol storing the majority of request contents in IPFS. Only the content-addressable ID (CID) is stored on-chain, on Gnosis Chain. + + + + Yes. Payments are linked to requests via a [Payment Reference](https://docs.request.network/advanced/request-network-sdk/sdk-guides/request-client/payment-reference) derived from the request contents. Therefore, it is possible to calculate the `paymentReference` and execute a payment *before* creating the corresponding request. + + + + Yes and No. + + Requests can be *denominated* in fiat currencies like USD, EUR, etc. ([ISO 4217 currencies](https://en.wikipedia.org/wiki/ISO_4217)) but our payment smart contracts only support payments in cryptocurrencies. We call these [Conversion Payment](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/conversion-request)s, in which the requested fiat amount is converted to the appropriate cryptocurrency amount using on-chain price feeds at the moment of payment. + + It is possible to implement fiat payments using Declarative Requests, where the payer declares that the payment was sent and the payee declares that the payment was received. + + + + Not currently, but we're working on it. + + + + Yes. See [Single Request Forwarder](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/single-request-forwarder) + + + + No. A Request Node cannot change a request's contents before persisting it to IPFS and on-chain because doing so would invalidate the signature. This is true for private, encrypted requests as well. The Request Node cannot forge the end-user's signature. + + + + No. Today, a Request Node is required to interact with the Request Network IPFS Network. That said, it is possible to make the end-user pay the protocol fee when creating a request instead of the Request Node. To do this, inject an `HttpMetaMaskDataAccess` into the frontend `RequestNetwork` instance. + + ```javascript + const requestNetwork = new RequestNetworkBase({ + dataAccess: new HttpMetaMaskDataAccess({ + ethereumProviderUrl: 'https://eth-mainnet.g.alchemy.com/v2/demo', + }), + ... + } + ``` + + + + Yes. It is possible to request access to a user's Request Finance invoices using the [`add-stakeholder` web component](https://docs.request.network/learn-request-network/components/add-stakeholder) which is just a thin wrapper around the [Request Finance Add Stakeholders API](https://docs.request.finance/faq#i-am-integrating-the-request-network.-can-i-get-access-to-users-data-on-request-finance). They display a dialog that prompts the end-user to grant access to 1 invoice at a time. + + Details: + + - Request Finance invoices are encrypted. + - Request Network Foundation cannot grant access to encrypted requests in Request Finance. + + + + No. Request Network does not currently support cross-chain payments. All of the supported payment types involve the payer sending funds and the payee receiving funds on the same chain. + + + + Yes. See: + + - [Private Requests using Encryption](https://docs.request.network/advanced/protocol-overview/private-requests-using-encryption) + - [Encrypt with a wallet signature using Lit Protocol](https://docs.request.network/advanced/request-network-sdk/sdk-guides/encryption-and-decryption/handle-encryption-with-a-web3-wallet) + + + + Yes. See [Hinkal Private Payments](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/hinkal-private-payments) + + + + No. It is not currently possible to create a request via a smart contract call. However, [RequestNetwork/public-issues#15](https://github.com/RequestNetwork/public-issues/issues/15) is in our roadmap to make this possible. + + The recommended way to create a request is using the Request Network API. + + + + Yes. See [Single Request Forwarder](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/single-request-forwarder) + + \ No newline at end of file diff --git a/favicon.svg b/favicon.svg index b785c73..d615d18 100644 --- a/favicon.svg +++ b/favicon.svg @@ -1,19 +1 @@ - - - - - - - - - - - - - - - - - - - +icon \ No newline at end of file diff --git a/general/lifecycle-of-a-request.mdx b/general/lifecycle-of-a-request.mdx new file mode 100644 index 0000000..19c02da --- /dev/null +++ b/general/lifecycle-of-a-request.mdx @@ -0,0 +1,43 @@ +--- +title: "Lifecycle of a Request" +description: "The typical lifecycle of a request is as follows:" +--- + + +![Typical Lifecycle of a Request](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-bb17b9b51fa3361ad54d1ac2185323f707ac8766%252FLifecycle%2520of%2520a%2520Request.jpg%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=b63df9bb&sv=2) + + +## Create a request + +- The payer or payee signs the request which contains the payee, payer, currency, amount, payment details, and arbitrary content data. +- The request can be optionally encrypted such that only the payee, payer, and approved 3rd parties can view the request contents. +- The request is persisted in IPFS. +- The IPFS Content-addressable ID (CID) is stored in a smart contract on Gnosis chain + +Requests are *created* by storing their CIDs on Gnosis, but this doesn't mean *payment* must occur on Gnosis. *Payment* can occur on any of the supported chains including 20+ EVM-compatible chains or NEAR. + + +## Update a request + +- The payee can optionally cancel the request or increase/decrease the expected amount. +- The payer can optionally accept the request, indicating that they intend to pay it. +- Both payee and payer can add 3rd party stakeholders if the request is encrypted. + +## Pay a request + +- The payer derives a paymentReference from the request contents. +- The payer calls a function on the payment network smart contract, passing in the token address, to address, amount, and paymentReference. +- An event is emitted containing the token address, to address, amount, and paymentReference. + +Most requests are "reference-based" meaning that a paymentReference derived from the request contents is logged on-chain via a smart contract that emits an event. Nothing gets written back to IPFS when paying a "reference-based" request. + +The exception is when paying a "declarative" request, in which case, data *is* written back to IPFS. This includes when the payer declares that the payment was sent and the payee declares that the payment was received. + +## Retrieve a request / Detect a payment + +- The event is indexed by the payments subgraph +- An app can retrieve the request contents from IPFS and calculate the balance based on events from the payments subgraph. + +The request balance is calculated by adding up all the on-chain payment events with the same paymentReference. Partial payments are possible. + +All of these steps are facilitated by the Request Network JavaScript SDK such that the developer needs only make a few function calls. See the [Quickstart](https://docs.request.network/advanced/request-network-sdk/get-started/quickstart-browser) to learn more. \ No newline at end of file diff --git a/general/request-network-token-list.mdx b/general/request-network-token-list.mdx new file mode 100644 index 0000000..7268aa1 --- /dev/null +++ b/general/request-network-token-list.mdx @@ -0,0 +1,59 @@ +--- +title: "Request Network Token List" +description: "The [Request Network Token List](https://requestnetwork.github.io/request-token-list/latest.json) is a curated list of tokens supported by Request Network products. The token list follows a standardized format and includes essential information about each token, such as address, symbol, name, decimals, and chainId." + +--- + +## Usage + +The token list is available at: [https://requestnetwork.github.io/request-token-list/latest.json](https://requestnetwork.github.io/request-token-list/latest.json) + +You can fetch the token list directly in your application: + +```bash +const tokenList = await fetch( + "https://requestnetwork.github.io/request-token-list/latest.json" +).then((res) => res.json()); +``` + +## Token List Structure + +Each token in the list contains the following information: + +```bash +{ + "id": "TKN-mainnet" + "name": "Token Name", + "address": "0x...", + "symbol": "TKN", + "decimals": 18, + "chainId": 1, + "logoURI": "https://..." +} +``` + +## Adding a New Token + +We welcome community contributions! To add a new token to the list: + + + +Fork the [request-token-list](https://github.com/RequestNetwork/request-token-list) repository on Github + + + +Add your token information to `tokens/token-list.json` + + + +Make sure your token meets our requirements (see [CONTRIBUTING.md](https://github.com/RequestNetwork/request-token-list/blob/main/CONTRIBUTING.md)) + + + +Run tests locally: `npm test` + + + +Create a Pull Request + + diff --git a/general/request-scan.mdx b/general/request-scan.mdx new file mode 100644 index 0000000..7276dc5 --- /dev/null +++ b/general/request-scan.mdx @@ -0,0 +1,57 @@ +--- +title: "Request Scan" +description: "An explorer app for viewing requests, payments, and addresses in Request Network." +--- + + + ![Request Scan Landing + Page](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-50112fc2716ed4df557c846c8b372bf0b34e1b0b%252FScreenshot%25202024-09-05%2520at%252015.23.45.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=9d44768f&sv=2) + + + + + + + +Request Scan is an explorer for viewing requests and payments in Request Network. It enables users to explore and scrutinize requests, payments, and addresses within the Request Network ecosystem. + +## Intended Audience + +Request Scan caters to a broad audience: + +- **Accountants:** Audit and verify financial data on the request network. +- **Developers:** Easily access Request Network data for troubleshooting your applications. +- **Analysts:** Gain deep insights into network activity and trends. +- **Researchers:** Conduct in-depth studies on blockchain data. +- **Enthusiasts:** Stay informed about the latest happenings on the Request Network. + +## Usage + +### **User Interface** + +- **Search Bar:** Located at the top, allows you to search for specific requests or addresses. +- **Dashboard:** Provides an overview of network statistics and recent activity. +- **Requests:** View a list of recent requests with details like payee, payer, amount, and timestamp. +- **Payments:** View a list of recent payments with details like blockchain transactions, amounts, fees, and timestamps. +- **Address:** View information about individual addresses, including their requests and payments. +- **Request:** View information about individual requests, including their details and table with actions and payments. + +### **Searching for Data** + +- **Request:** Enter a request ID in the search bar to view its details. +- **Address:** Enter an address to see its requests and payment history. + +### Demo Video + + + + diff --git a/glossary.mdx b/glossary.mdx new file mode 100644 index 0000000..c6e9c88 --- /dev/null +++ b/glossary.mdx @@ -0,0 +1,152 @@ +--- +title: "Glossary" +--- +## Parties of a Request + +### Payee Identity + +The Payee Identity is the EVM address that uniquely identifies the payee. It can be but is not necessarily the address that will receive the payment. It is authorized to make certain updates to the request after it is created. It is one of the owners of the request data. The Payee Identity is defined by the `payee` field when creating a request. + +### Payer Identity + +The Payer Identity is the EVM address that uniquely identifies the payer. It can be but is not necessarily the address that will send the payment. It is authorized to make certain updates to the request after it is created. It is one of the owners of the request data. The Payer Identity is defined by the `payer` field when creating a request. + +### Signer Identity + +The Signer Identity is the EVM address that provides the signature to create a request. It must be either the Payee Identity or Payer Identity. + +### Payment Recipient + +The EVM address that receives the payment. It is defined by the `paymentNetwork.parameters.paymentAddress`field when creating a request. + +### Payment Sender + +The EVM address that sends the payment. Anyone can pay a given request. The payment sender address is NOT stored in the request contents. + +### Additional Stakeholder + +An EVM address that has been granted view access to an encrypted request. + +### Declarative Delegate + +An EVM address that has been granted authorization to declare payments sent and payments received on behalf of either the Payee Identity or Payer Identity of a given request. + +## Request Protocol + +### Action + +An action is signed data added by a request's stakeholder into the Request Protocol that creates or updates the state of a request. A request can be represented by a list of actions. For example, the creation of a request is an action. + +### Balance + +When using a payment network, the balance is the current amount paid for a request. The balance is determined by the payment detection method of the payment network used. + +A request with no payment network provided doesn't have a balance. + +### Confirmed/Pending action + +Request relies on other blockchain technologies to ensure data immutability. Most blockchains don't offer transaction instant finality. This means that when performing an action on the request, this action can't directly be confirmed as effective. + +As long as the action hasn't persisted and is not confirmed, the action is marked as "pending". The "pending" state helps have a fast response and a good user experience. Until the request is Confirmed, it should not be relied upon. + +### Signature Provider + +A signature provider is an abstraction of identity management and action signatures. Depending on use cases, it allows you to give your user complete control or handle some parts for them. + +### Decryption Provider + +A decryption provider is an abstraction of the mechanism that handles the decryption of a request. Depending on use cases, it allows you to give your user complete control or handle some parts for them. + +It is not used for clear requests. + +### Extension + +An extension is a set of actions that extends the feature of a request. A request without extension is a fundamental request for payment with a payee, a currency, and a requested amount. The extension allows for more advanced features. + +### Identity + +The identity defines a stakeholder of a request that allows signing or encrypting the request actions. The identity is the public data that identifies the stakeholder. + +### Request ID + +The request ID is the number that uniquely identifies a request. This number is computed from the hash of the request creation action. + +### Request Data (aka. Request Contents) + +The request data is the current state of a request, the data of the request after having applied all the confirmed actions on it. + +### Stakeholder + +A request stakeholder is a party involved with the request. Stakeholders are generally the payer and the payee of the request or any other third-party allowed to perform actions on it. For encrypted requests, stakeholders are any party interested in reading the request content. + +### Topic + +A topic is a string that is used to index a request. This topic is used for request retrieval. Several requests can share the same topic. + +Every request has its request id and payee identity as topics (and the payer identity if it is defined). Any custom topic can be appended to a request. + +## Payments + +### Payment Detection + +Payment detection is a method defined by the payment network to determine the current balance of a request. + +### Payment Network (aka Payment Extension) + +A payment network is a predefined set of rules to agree on the balance of a request. The payment network is defined during the creation of the request. + +A payment network is generally related to one currency, but it's not always the case (the Declarative payment network is currency agnostic). + +### Payment Reference + +In the Reference-based Payment Networks, Payments are linked to Requests via a `paymentReference` which is derived from the `requestId` and payment recipient address. For details see [Payment Reference](https://docs.request.network/advanced/request-network-sdk/sdk-guides/request-client/payment-reference) + +### Conversion Payment + +A "conversion" request is denominated in one currency but paid in another currency. This is facilitated by on-chain price feeds provided by oracles. The typical use case is to denominate a request in fiat like USD and pay the request in stablecoins like USDC or DAI. For details see [Conversion Payment](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/conversion-request) + +### Swap-to-pay Payment + +A "swap-to-pay" payment is where the payment sender sends one currency but the payment recipient receives a different currency. For details see [Swap-to-Pay Payment](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/swap-to-pay-request) + +### Swap-to-Conversion Payment + +A "swap-to-conversion" payment is where the request is denominated in currency A, the payer sends currency B and the payee receives currency C. For details see [Swap-to-Conversion Payment](https://docs.request.network/advanced/request-network-sdk/sdk-guides/payment/swap-to-conversion-request) + +## Ecosystem + +### Request Client + +The Request Client is a Javascript library that interacts directly with the Request Protocol. The Request Client connects to a Request Node. + +### Request Node + +Request Nodes are HTTP servers exposing an API that allows the Request Client to communicate with the Request Protocol. These servers abstract the complexity of IPFS and Ethereum used by the Request Protocol. + +### Request Protocol + +The Request Protocol is the underlying protocol that powers Request. It defines how requests are stored on a distributed ledger and how to interpret actions performed on them. + +## Blockchain, Cryptography + +### Confirmation + +Confirmation means that the network has verified the blockchain transaction. This happens through a process known as mining in a proof-of-work system (e.g., Bitcoin). Once a transaction is confirmed, it cannot be reversed. + +### Ether + +Ether is the native token of the Ethereum blockchain, which is used to pay for transaction fees, block proposer rewards, and other services on the network. + +### IPFS + +The Inter-Planetary File System (IPFS) is a protocol and a peer-to-peer network for storing and sharing data in a distributed file system. IPFS uses content-addressing to uniquely identify each file in a global namespace connecting all computing devices. + +The Request Protocol uses IPFS to ensure data accessibility. + +### Multi-signature + +Multi-signature (multisig) wallets allow multiple parties to require more than one key to authorize a transaction. The needed number of signatures is agreed upon at the creation of the wallet. Multi-signature addresses have a much greater resistance to theft. + +### Private Key + +A private key is a large number that allows you to sign or decrypt messages. Private keys can be thought of as a password; private keys must never be revealed to anyone but you, as they allow you to spend the funds from your wallet through a cryptographic signature. \ No newline at end of file diff --git a/images/checks-passed.png b/images/checks-passed.png deleted file mode 100644 index 3303c77..0000000 Binary files a/images/checks-passed.png and /dev/null differ diff --git a/images/hero-dark.png b/images/hero-dark.png deleted file mode 100644 index a61cbb1..0000000 Binary files a/images/hero-dark.png and /dev/null differ diff --git a/images/hero-light.png b/images/hero-light.png deleted file mode 100644 index 68c712d..0000000 Binary files a/images/hero-light.png and /dev/null differ diff --git a/index.mdx b/index.mdx index 15c23fb..b57fcde 100644 --- a/index.mdx +++ b/index.mdx @@ -1,97 +1,94 @@ ---- -title: "Introduction" -description: "Welcome to the new home for your documentation" ---- - -## Setting up - -Get your documentation site up and running in minutes. - - - Follow our three step quickstart guide. - - -## Make it yours - -Design a docs site that looks great and empowers your users. - - - - Edit your docs locally and preview them in real time. - - - Customize the design and colors of your site to match your brand. - - - Organize your docs to help users find what they need and succeed with your product. - - - Auto-generate API documentation from OpenAPI specifications. - - - -## Create beautiful pages - -Everything you need to create world-class documentation. - - - - Use MDX to style your docs pages. - - - Add sample code to demonstrate how to use your product. - - - Display images and other media. - - - Write once and reuse across your docs. - - - -## Need inspiration? - - - Browse our showcase of exceptional documentation sites. - +--- +title: "Request Network Docs" +description: "A protocol for creating payment requests and reconciling payments." +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 + + + Experience how creating an invoice and getting paid is better than asking someone to send you money and hoping they remember to tell you they sent it. + + *Interactive demo will be embedded here* + + +## Get Started + +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 + + + + SDK documentation and advanced implementation topics + + + + + + Supported chains, currencies, smart contracts, and community resources + + + + Stay updated with the latest features and improvements + + + +## Popular + + + + 1. [Get API Keys](/api-setup/getting-started) (2 minutes) + 2. [Create your first request](/use-cases/invoicing) (1 minute) + 3. [Test payment flow](/api-features/payment-types) (2 minutes) + + + + 1. [Try EasyInvoice Demo](/use-cases/invoicing) - See full invoicing workflow + 2. [Explore Use Cases](/use-cases/payouts) - Discover business applications + 3. [Fork & Customize](/use-cases/invoicing) - Make it your own + + + + 1. [Check Supported Chains](/resources/supported-chains-and-currencies) + 2. [Review Payment Types](/api-features/payment-types) + 3. [Explore Use Cases](/use-cases/invoicing) that match your needs + + \ No newline at end of file diff --git a/logo/dark.svg b/logo/dark.svg index 8b343cd..581b6c1 100644 --- a/logo/dark.svg +++ b/logo/dark.svg @@ -1,21 +1,59 @@ - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/logo/light.svg b/logo/light.svg index 03e62bf..99d6047 100644 --- a/logo/light.svg +++ b/logo/light.svg @@ -1,21 +1,59 @@ - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quickstart.mdx b/quickstart.mdx deleted file mode 100644 index c711458..0000000 --- a/quickstart.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Quickstart" -description: "Start building awesome documentation in minutes" ---- - -## Get started in three steps - -Get your documentation site running locally and make your first customization. - -### Step 1: Set up your local environment - - - - During the onboarding process, you created a GitHub repository with your docs content if you didn't already have one. You can find a link to this repository in your [dashboard](https://dashboard.mintlify.com). - - To clone the repository locally so that you can make and preview changes to your docs, follow the [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) guide in the GitHub docs. - - - 1. Install the Mintlify CLI: `npm i -g mint` - 2. Navigate to your docs directory and run: `mint dev` - 3. Open `http://localhost:3000` to see your docs live! - - Your preview updates automatically as you edit files. - - - -### Step 2: Deploy your changes - - - - Install the Mintlify GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app). - - Our GitHub app automatically deploys your changes to your docs site, so you don't need to manage deployments yourself. - - - For a first change, let's update the name and colors of your docs site. - - 1. Open `docs.json` in your editor. - 2. Change the `"name"` field to your project name. - 3. Update the `"colors"` to match your brand. - 4. Save and see your changes instantly at `http://localhost:3000`. - - Try changing the primary color to see an immediate difference! - - - -### Step 3: Go live - - - 1. Commit and push your changes. - 2. Your docs will update and be live in moments! - - -## Next steps - -Now that you have your docs running, explore these key features: - - - - - Learn MDX syntax and start writing your documentation. - - - - Make your docs match your brand perfectly. - - - - Include syntax-highlighted code blocks. - - - - Auto-generate API docs from OpenAPI specs. - - - - - - **Need help?** See our [full documentation](https://mintlify.com/docs) or join our [community](https://mintlify.com/community). - diff --git a/release-notes/easy-invoice.mdx b/release-notes/easy-invoice.mdx new file mode 100644 index 0000000..709ac78 --- /dev/null +++ b/release-notes/easy-invoice.mdx @@ -0,0 +1,189 @@ +--- +title: "EasyInvoice Release Notes" +description: "Track updates, new features, and improvements to EasyInvoice, the no-code invoicing solution" +--- + +# EasyInvoice Release Notes + +This page documents all updates to EasyInvoice, including new features, UI improvements, integrations, and bug fixes. + +## Version 3.2.0 - Current + + + +### ๐ŸŽ‰ New Features + +- **Multi-Currency Invoicing**: Create invoices in 50+ fiat currencies +- **Recurring Invoices**: Set up automatic recurring billing cycles +- **Custom Branding**: Upload logos and customize invoice themes +- **Payment Reminders**: Automated email reminders for overdue invoices + +### ๐Ÿš€ Improvements + +- **Mobile Experience**: Redesigned mobile interface for invoice creation +- **Performance**: 60% faster invoice generation and PDF rendering +- **Integrations**: Enhanced Stripe integration with better error handling +- **Accessibility**: Improved screen reader support and keyboard navigation + +### ๐Ÿ› Bug Fixes + +- Fixed issue with tax calculation for international transactions +- Resolved PDF generation timeout for large invoices +- Corrected date formatting for non-English locales +- Fixed duplicate payment notification edge case + + + +## Version 3.1.5 + + + +### ๐Ÿš€ Improvements + +- **Template Library**: 10 new professional invoice templates +- **Export Options**: Enhanced CSV export with custom field selection +- **Search & Filter**: Improved invoice search with advanced filters +- **Notifications**: Customizable email notification settings + +### ๐Ÿ› Bug Fixes + +- Fixed calculation error in discount percentage handling +- Resolved timezone display issues in invoice dates +- Corrected payment status sync with payment processors + + + +## Version 3.1.0 + + + +### ๐ŸŽ‰ New Features + +- **Team Collaboration**: Multi-user workspaces with role-based permissions +- **API Integration**: RESTful API for custom integrations +- **Webhook Support**: Real-time notifications for invoice events +- **Advanced Reporting**: Detailed analytics and financial reports + +### ๐Ÿš€ Improvements + +- **Invoice Editor**: Drag-and-drop interface for invoice customization +- **Payment Processing**: Support for additional payment methods +- **Client Management**: Enhanced customer information and history tracking +- **Bulk Operations**: Import/export multiple invoices at once + + + +## Version 3.0.0 - Major Release + + + +### ๐ŸŽ‰ New Features + +- **Request Network Integration**: Native support for cryptocurrency payments +- **Smart Contract Invoices**: Blockchain-verified invoice creation +- **Multi-chain Support**: Accept payments on Ethereum, Polygon, and more +- **DeFi Integrations**: Connect with popular DeFi protocols + +### ๐Ÿš€ Improvements + +- **Complete UI Redesign**: Modern, intuitive interface +- **Performance**: 5x faster loading times and operations +- **Mobile-First**: Responsive design optimized for all devices +- **Security**: Enhanced encryption and data protection + +### โš ๏ธ Breaking Changes + + +Version 3.0 includes significant changes to the user interface and some API endpoints. + + +- **New Dashboard**: Completely redesigned main interface +- **URL Structure**: Updated URLs for better organization +- **Export Format**: Enhanced CSV/PDF export formats +- **Authentication**: Improved login and session management + +**Migration Resources:** +- [V3 Migration Guide](https://docs.easyinvoice.network/migration/v3) +- [Feature Comparison](https://easyinvoice.network/features) +- [Video Tutorials](https://easyinvoice.network/tutorials) + + + +## Platform Features + +### Current Capabilities + + + + Create professional invoices with custom branding, line items, taxes, and discounts + + + + Accept payments via crypto (Request Network), credit cards (Stripe), and bank transfers + + + + Organize customer information, payment history, and communication logs + + + + Track revenue, payment trends, and business metrics with detailed reports + + + +### Integration Ecosystem + +- **Payment Processors**: Stripe, PayPal, Request Network +- **Accounting Software**: QuickBooks, Xero, FreshBooks +- **E-commerce**: Shopify, WooCommerce, Magento +- **CRM Systems**: HubSpot, Salesforce, Pipedrive + +## Upcoming Features + +### Q4 2025 Roadmap + +- **AI-Powered Insights**: Intelligent payment predictions and recommendations +- **Advanced Automation**: Workflow automation for invoice processing +- **Multi-language Support**: Interface translation for global users +- **Enterprise Features**: Advanced permissions and audit trails + +### Requested Features + +Vote on upcoming features in our [feedback portal](https://feedback.easyinvoice.network): + +1. **Subscription Management** - 847 votes +2. **Inventory Tracking** - 623 votes +3. **Time Tracking Integration** - 511 votes +4. **Mobile App** - 445 votes + +## Getting Started + + + + Sign up for a free EasyInvoice account at [easyinvoice.network](https://easyinvoice.network) + + + + Set up your business information, branding, and payment preferences + + + + Use our guided setup to create and send your first professional invoice + + + + Track payments and manage your cash flow with real-time updates + + + +## Support & Resources + +- ๐Ÿ“š [User Guide](https://docs.easyinvoice.network) +- ๐ŸŽฅ [Video Tutorials](https://easyinvoice.network/tutorials) +- ๐Ÿ’ฌ [Community Forum](https://community.easyinvoice.network) +- ๐Ÿ“ง [Support Email](mailto:support@easyinvoice.network) +- ๐Ÿ› [Bug Reports](https://github.com/RequestNetwork/easy-invoice/issues) + + +Join our [Discord community](https://request.network/discord) to connect with other users and get real-time support from our team. + diff --git a/release-notes/index.mdx b/release-notes/index.mdx new file mode 100644 index 0000000..bad2c9d --- /dev/null +++ b/release-notes/index.mdx @@ -0,0 +1,59 @@ +--- +title: "Release Notes" +description: "Stay up to date with the latest updates and improvements to Request Network products" +--- + +# Release Notes + +Stay informed about the latest features, improvements, and bug fixes across all Request Network products. Our release notes provide detailed information about what's new and what's changed in each version. + +## Product Release Notes + + + + Track updates to the Request Network API, including new endpoints, breaking changes, and performance improvements. + + + + Follow the latest features and enhancements to EasyInvoice, our no-code invoicing solution. + + + +## How to Stay Updated + + + + We follow semantic versioning and provide advance notice of breaking changes. Major version updates will be announced at least 30 days in advance with migration guides. + + + + - **Critical Updates**: Subscribe to our status page for system-wide notifications + - **Feature Updates**: Follow our blog for detailed feature announcements + - **Developer Updates**: Join our Discord community for real-time discussions + + + + - **Current Version**: Full support with regular updates + - **Previous Version**: Security updates and critical bug fixes for 6 months + - **Legacy Versions**: Limited support, migration assistance available + + + +## Quick Links + +- [API Status Page](https://status.request.network) - Real-time system status +- [Developer Blog](https://request.network/blog) - In-depth feature explanations +- [Discord Community](https://request.network/discord) - Ask questions and get support +- [GitHub Repository](https://github.com/RequestNetwork) - Source code and issue tracking + +## Release Schedule + +We typically release updates on the following schedule: + +- **Patch releases** (bug fixes): As needed +- **Minor releases** (new features): Monthly +- **Major releases** (breaking changes): Quarterly + + +Sign up for our developer newsletter to receive release notes directly in your inbox. + diff --git a/release-notes/request-api.mdx b/release-notes/request-api.mdx new file mode 100644 index 0000000..e906b40 --- /dev/null +++ b/release-notes/request-api.mdx @@ -0,0 +1,143 @@ +--- +title: "Request API Release Notes" +description: "Track updates, new features, and changes to the Request Network API" +--- + +# Request API Release Notes + +This page documents all updates to the Request Network API, including new features, improvements, bug fixes, and breaking changes. + +## Version 2.1.0 - Current + + + +### ๐ŸŽ‰ New Features + +- **Enhanced Payment Status Tracking**: New webhook events for granular payment status updates +- **Bulk Request Creation**: Create multiple payment requests in a single API call +- **Advanced Filtering**: Extended query parameters for request listing endpoints +- **Payment Intent Support**: Integration with Stripe Payment Intents for card payments + +### ๐Ÿš€ Improvements + +- **Performance**: 40% faster response times for request creation +- **Rate Limiting**: Increased rate limits for authenticated requests (1000/minute โ†’ 2000/minute) +- **Error Messages**: More descriptive error responses with actionable suggestions +- **Documentation**: Interactive API explorer with live examples + +### ๐Ÿ› Bug Fixes + +- Fixed timestamp formatting inconsistencies in webhook payloads +- Resolved issue with currency conversion precision for small amounts +- Fixed pagination edge case in request listing endpoint +- Corrected decimal handling for Japanese Yen transactions + +### โš ๏ธ Breaking Changes + +None in this release. + + + +## Version 2.0.5 + + + +### ๐Ÿš€ Improvements + +- **Security**: Enhanced API key validation and rotation capabilities +- **Monitoring**: Improved request tracing for better debugging +- **Webhooks**: Retry mechanism with exponential backoff for failed deliveries + +### ๐Ÿ› Bug Fixes + +- Fixed rare concurrency issue in payment processing +- Resolved webhook delivery order for high-volume scenarios +- Corrected timezone handling in request expiration dates + + + +## Version 2.0.0 - Major Release + + + +### ๐ŸŽ‰ New Features + +- **Multi-chain Support**: Native support for Ethereum, Polygon, Arbitrum, and more +- **Payment Methods**: Credit card payments via Stripe integration +- **Request Templates**: Reusable templates for recurring payment scenarios +- **Advanced Webhooks**: Configurable event filtering and custom headers + +### ๐Ÿš€ Improvements + +- **RESTful Design**: Complete API redesign following REST principles +- **OpenAPI Specification**: Comprehensive API documentation with interactive examples +- **SDK Support**: Official SDKs for JavaScript, Python, and PHP +- **Performance**: 10x improvement in request processing speed + +### โš ๏ธ Breaking Changes + + +This is a major version upgrade with significant breaking changes. Please review the migration guide carefully. + + +- **Endpoint Structure**: All endpoints have been restructured +- **Authentication**: New API key format and authentication method +- **Response Format**: Standardized response structure across all endpoints +- **Field Names**: Several field names have been updated for consistency + +**Migration Resources:** +- [Migration Guide](/request-network-api/migrate-to-v2) +- [V1 to V2 Comparison Tool](https://portal.request.network/migration) +- [Support Channel](https://request.network/discord) for migration assistance + + + +## API Versioning + +### Current Version Support + +- **v2.1.x**: Current stable version with full support +- **v2.0.x**: Maintenance mode, security updates only +- **v1.x**: **Deprecated** - End of life: December 2025 + +### Version Headers + +Always specify the API version in your requests: + +```bash +curl -H "API-Version: 2.1" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + https://api.request.network/requests +``` + +### Breaking Change Policy + + +We follow semantic versioning and provide advance notice for breaking changes: + +- **Major versions** (2.0.0): May include breaking changes +- **Minor versions** (2.1.0): New features, backward compatible +- **Patch versions** (2.1.1): Bug fixes, backward compatible + + +## Upcoming Features + +### Q4 2025 Roadmap + +- **GraphQL API**: Alternative query interface for complex data retrieval +- **Batch Operations**: Bulk operations for high-volume use cases +- **Advanced Analytics**: Detailed payment and request analytics +- **Mobile SDKs**: Native iOS and Android SDK support + + +Follow our [GitHub repository](https://github.com/RequestNetwork/request-api) to track development progress and provide feedback on upcoming features. + + +## Getting Help + +If you have questions about any release or need migration assistance: + +- ๐Ÿ“š [API Documentation](/api-reference/authentication) +- ๐Ÿ’ฌ [Discord Community](https://request.network/discord) +- ๐Ÿ“ง [Support Email](mailto:support@request.network) +- ๐Ÿ› [Bug Reports](https://github.com/RequestNetwork/request-api/issues) diff --git a/request-network-api/api-portal-manage-api-keys-and-webhooks.mdx b/request-network-api/api-portal-manage-api-keys-and-webhooks.mdx new file mode 100644 index 0000000..9330cee --- /dev/null +++ b/request-network-api/api-portal-manage-api-keys-and-webhooks.mdx @@ -0,0 +1,79 @@ +--- +title: "API Portal: Manage API Keys and Webhooks" +description: "An app for managing Request Network API keys and webhooks." +--- + + + + + + + +## Overview + +The Request Network API Portal provides app developers with a platform to securely manage their API keys and webhook endpoints. + +## Key Features + +### API Key Management + +- **Create and Manage API Keys:** Users can create new API keys for authentication. +- **Toggle and Delete API Keys:** API keys can be toggled on and off, or deleted if no longer needed, enhancing control over API access. +- **Security Guidelines:** API keys are sensitive and should never be shared publicly. In case of compromise, users are advised to create a new key, update their code, and delete the compromised key. +- **Multiple Keys:** Allows the creation of multiple API keys for different environments or applications. + +### Webhook Management + +- **Create and Manage Webhooks:** App developers can configure webhook endpoints to receive real-time notifications for payment events. +- **Security Guidelines:** Each webhook request includes a signature in the \`x-request-network-signature\` header to ensure authenticity. +- **Signature Verification:** The signature is a SHA-256 HMAC of the request body, signed using the webhook secret. + +Example Verification Code: + +```bash expandable +import express from 'express'; +import crypto from 'node:crypto'; + +const app = express(); +const WEBHOOK_SECRET = 'your_webhook_secret'; + +app.post('/payment', async (req, res) => { + 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({ + success: false, + message: 'Invalid signature' + }); + } + + // Business logic here + return res.status(200).json({ success: true }); +}); +``` + +## Usage + +### Creating API Keys + +- Navigate to the "API Keys" section. +- Click on "Create new key." +- Store the key securely and never share it publicly. + +### Configuring Webhooks + +- Navigate to the "Webhooks" section. +- Click on "Add webhook." +- Enter the endpoint URL and ensure the endpoint is secure and can handle incoming JSON payloads. + +## Security Considerations + +- **Keep API keys and webhook secrets secure.** Never expose them in public repositories or client-side code. +- **Verify all webhook signatures** to ensure authenticity and integrity. +- **Use HTTPS** for all endpoints to encrypt communication. diff --git a/request-network-api/create-and-pay-requests.mdx b/request-network-api/create-and-pay-requests.mdx new file mode 100644 index 0000000..09a32a9 --- /dev/null +++ b/request-network-api/create-and-pay-requests.mdx @@ -0,0 +1,29 @@ +--- +title: "Create and Pay Requests " +sidebarTitle: "Overview" +description: "The Request Network API provides an interface for creating and paying requests within your application." +--- + + +**Talk to an expert** + +Discover how Request Network API can enhance your app's features - [book a call](https://calendly.com/mariana-rn/request-network-demo-docs) with us. + + +## **Core Functionality** + +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. +- **Fee Collection:** When paying a request, you can specify a fee percentage (between 0 and 100) and a fee address, which will add the fee on top of the payment amount - meaning the payer will pay the original amount plus the fee percentage, with the fee portion being sent to the specified fee address. +- **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. + +### Supported Chains and Currencies + +See [Supported Chains and Currencies](https://docs.request.network/request-network-api/supported-chains-and-currencies#request-network-api-supported-currencies) diff --git a/request-network-api/create-anew-request.mdx b/request-network-api/create-anew-request.mdx new file mode 100644 index 0000000..d09b921 --- /dev/null +++ b/request-network-api/create-anew-request.mdx @@ -0,0 +1,124 @@ +--- +title: "Create a New Request" +description: "Create a new payment request" +api: POST https://api.request.network/v2/request +contentType: application/json +--- + + + + +## Headers + + + API key for authentication + + +## Body + + + The wallet address of the payer + + + + The wallet address of the payee. Required for all requests except crypto-to-fiat + + + + The payable amount of the invoice, in human readable format + + + + Invoice Currency ID, from the [Request Network Token List](/general/request-network-token-list) e.g: USD + + + + Payment currency ID, from the [Request Network Token List](/general/request-network-token-list) e.g: ETH-sepolia-sepolia + + + + Whether crypto-to-fiat payment is available for this request + + + + + The recurrence of the invoice + + + + The start date of the invoice + + + + The frequency of the invoice + + Possible values: `DAILY` `WEEKLY` `MONTHLY` `YEARLY` + + + + +## Response + +### 201 Request created successfully + + + +Unique identifier of the request, used to pay the request as well as check the status of the request + +Example: `0xb3581f0b0f74cc61` + + + +Unique identifier of the request, commonly used to look up a request in Request Scan + +Example: `01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb` + + + + + + + +```bash 201 Request created successfully +{ + "paymentReference": "0xb3581f0b0f74cc61", + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb" +} +``` + +```bash 400 Validation failed +No content +``` + +```bash 401 Unauthorized +No content +``` + +```bash 404 Wallet not found +No content +``` + +```bash 429 Too Many Requests +No content +``` + + + + +## Error Responses + + + Validation failed - check your request parameters + + + + Unauthorized - invalid API key + + + + Wallet not found + + + + Too Many Requests - rate limit exceeded + \ No newline at end of file diff --git a/request-network-api/easyinvoice-api-demo-app.mdx b/request-network-api/easyinvoice-api-demo-app.mdx new file mode 100644 index 0000000..e53ba36 --- /dev/null +++ b/request-network-api/easyinvoice-api-demo-app.mdx @@ -0,0 +1,185 @@ +--- +title: "EasyInvoice: API Demo App" +description: "An app for creating and paying requests using the Request Network API." +--- + +EasyInvoice is a web application built with Next.js that allows users to create and manage invoices, and accept crypto payments via the Request Network API. It mimics Web2 apps in its functionalities, providing a user-friendly experience with Google login and real-time updates. + + +**Talk to an expert** + +Discover how your app can have its own EasyInvoice features - [book a call](https://calendly.com/mariana-rn/request-network-demo-docs) with us. + + + + + + + +## Key Features + +### Overall Supported Currencies and Chains + +15 stablecoins: USDC/USDT/DAI on 5 chains (Ethereum, Polygon, Arbitrum One, Base, OP Mainnet) + 4 testnet tokens on Sepolia + USD fiat for Conversion and Crypto-to-fiat payments. + +### **Invoice Creation** + +- **Invoice Creation**: A simple form to create invoices. + - Client name and email fields. + - Items, amounts, and notes fields. + - Invoice currency and payment currency options, supporting currency conversion via the Request Network API. +- **Currency Conversion**: uses on-chain price feeds to calculate the exact payment currency amount based on the invoice currency at the moment of payment so you always receive the correct amount. + + +### **Dashboard** + +- **Dashboard**: View key metrics and a table of your invoices. + + +### Invoice Payment + +- **Invoice Payment:** + - View invoice details and initiate payment using transaction calldata provided by the Request Network API. + - Compatible with 80+ different crypto wallets via Reown AppKit +- **Real-time Updates**: The app receives webhooks from the Request Network API to update the invoice status in real-time. + +
+ + ![EasyInvoice supports 80+ wallets via Reown + AppKit](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-aa6eba6e357825684e36735b00922664fc6c43bd%252Fimage%2520%281%29.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=f019f5c4&sv=2) + + +### Invoice Crosschain Payment + + + ![](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-48739d507550f8489d876ba298ef0ee94cc5ede4%252FScreenshot%25202025-04-01%2520at%25204.07.30%25E2%2580%25AFPM.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e1eaea42&sv=2) + + + + + +#### Crosschain Payment Supported Currencies + +For Crosschain (and Samechain) Payments, EasyInvoice supports 12 stablecoins: USDC/USDT/DAI on 4 chains (Ethereum, Arbitrum One, Base, OP Mainnet) + +### Crypto-to-fiat Payment + + + + + +#### Crypto-to-fiat Payment Supported Currencies + +For Crypto-to-fiat Payments, EasyInvoice supports USDC on Sepolia. + +### Batch Pay Invoices + + + + +### Recurring Invoices + +- **Recurring Invoice**: Automatically create new invoices based on the selected start date and frequency + + ![Create New Invoice page - Recurring Invoice + Enabled](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-b0761801ebbfd42f807425721a07ae688b2205c5%252FScreenshot%25202025-04-02%2520at%25204.03.45%25E2%2580%25AFPM.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=ab9524e0&sv=2) + +
+ + ![Invoice Dashboard - Recurring + Invoice](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-1b49f707f277973d2a3d2ca1a6c5729cdb6f8dc3%252FScreenshot%25202025-04-02%2520at%25204.08.57%25E2%2580%25AFPM.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=cbb4869&sv=2) + + +### Payout + +- **Payout**: Send a payment without having to create a request first. + + ![EasyInvoice Direct Payment page](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-9d8b59fc962c49a59bedec3a10c0128ea7c5ee46%252Fimage%2520%286%29.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=75abda0e&sv=2) + + +### Batch Payout + + + + + +### InvoiceMe Link + +- **InvoiceMe Link**: Prompt clients to send you an invoice prefilled with your name and email address. + + ![Create InvoiceMe Link + page](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-633e8cd81e5cfbf71d0c911a31be57b15429b0c6%252Fimage9.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=34532bc2&sv=2) + +
+ + ![Create Invoice via InvoiceMe + Link](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-7cd1e7e68a5520effb952d1d1054e684e0b68d6d%252Fimage7.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5a2ea20d&sv=2) + + +### Subscriptions + + + + + +### Login + +- **Google Login**: Securely log in to your account using Google OAuth. + + ![EasyInvoice Login + Page](https://docs.request.network/~gitbook/image?url=https%3A%2F%2F1914277788-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fei6UAiSK3iAAi0mFH667%252Fuploads%252Fgit-blob-ea25fd7becc61ac6c2b839899c854a1fe8e81dd4%252Fimage.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=a9079f7&sv=2) + diff --git a/request-network-api/get-payment-calldata.mdx b/request-network-api/get-payment-calldata.mdx new file mode 100644 index 0000000..f28b130 --- /dev/null +++ b/request-network-api/get-payment-calldata.mdx @@ -0,0 +1,124 @@ +--- +title: "Get Payment Calldata" +description: "Get the calldata needed to pay a request. For same-chain payments, returns transaction calldata that can be directly executed. For crosschain payments (when chain and token parameters are provided and differ from the request's native chain), returns a payment intent that needs to be signed and processed through the crosschain bridge. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected." +api: GET https://api.request.network/v2/request/{requestId}/pay +contentType: application/json +--- + + + +## Path Parameters + + + The requestId of the request Example: + `01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb` + + +## Query Parameters + + + The wallet address of the payer Example: + `0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7` + + + + The source chain of the crosschain payment + + - `ethereum` - `arbitrum-one` - `base` - `op-mainnet` + + + + + The source token of the crosschain payment + - `USDC` - `USDT` - `DAI` + + + + The amount to pay, in human readable format + + + + Optional client user ID for off-ramp payments Example: `user-123` + + + + Optional payment details ID for off-ramp payments Example: + `fa898aec-519c-46be-9b4c-e76ef4ff99d9` + + + + Fee percentage to apply at payment time (e.g., '2.5' for 2.5%) Example: `0.02` + + + + Address to receive the fee Example: + `0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7` + + +## Headers parameters + + + API key for authentication + + +## Response + +### 200 Payment calldata retrieved successfully + + + + + + + Array of transactions to execute for the payment + + + Metadata about the payment requirements + + + + + + + + Unique identifier for the payment intent + + + + EIP-712 typed data for payment intent signature + + + + Metadata about the payment requirements + + + + Transaction calldata for token approval (for non-EIP-2612 tokens) + + + + Metadata about the crosschain payment + + + + + + + +## Error Responses + + + Validation failed - check your request parameters + + + + Unauthorized - invalid API key + + + + Request not found + + + + Too Many Requests - rate limit exceeded + diff --git a/request-network-api/get-request-status.mdx b/request-network-api/get-request-status.mdx new file mode 100644 index 0000000..a5d9113 --- /dev/null +++ b/request-network-api/get-request-status.mdx @@ -0,0 +1,117 @@ +--- +title: "Get Request Status" +description: "Get the status of a payment request" +api: GET https://api.request.network/v2/request/{requestId} +contentType: application/json +--- + + + + + + +## Path Parameters + + + The requestId for the request + + Example: `01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb` + + +## Headers parameters + + + API key for authentication + + +## Response + +### 200 Request status retrieved successfully + + + +Whether the request has been paid + + +Unique identifier used for payments and status checks + + + +Unique identifier of the request + + + +Whether the system is actively listening for payments on this request + + + +Transaction hash of the payment, null if not yet paid + + + +Recurrence configuration for recurring requests + + + +Original request ID for recurring requests + + + +Current status of the request + + + +Payment reference of the original request for recurring payments + + + +Array of payments made to this request + + + +Whether recurrence has been stopped for this request + + + + + + + +## Error Responses + + + Unauthorized - invalid API key + + + + Request not found + + + + Too Many Requests - rate limit exceeded + + + + +```bash 200 Request status retrieved successfully +{ + "hasBeenPaid": true, + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "isListening": false, + "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" +} +``` + +```bash 401 Unauthorized +No content +``` + +```bash 404 Request not found +No content +``` + +```bash 429 Too Many Requests +No content +``` + + \ No newline at end of file diff --git a/request-network-api/initiate-a-payment.mdx b/request-network-api/initiate-a-payment.mdx new file mode 100644 index 0000000..e58f11e --- /dev/null +++ b/request-network-api/initiate-a-payment.mdx @@ -0,0 +1,131 @@ +--- +title: "Initiate a Payment" +description: "Initiate a payment without having to create a request first. Supports both one-time and recurring payments. For recurring payments, specify the recurrence object with start date, frequency, total executions, and payer address. The system will create a recurring payment schedule and return the necessary transactions for allowance approval and signature submission." +api: POST https://api.request.network/v2/payouts +contentType: application/json +--- + + + +## Headers parameters + + + API key for authentication + + +## Body + + + The wallet address of the payee + + + + The payable amount of the invoice, in human readable format + + + + Invoice Currency ID, from the [Request Network Token List](/general/request-network-token-list) e.g: USD + + + + Payment currency ID, from the [Request Network Token List](/general/request-network-token-list) e.g: ETH-sepolia-sepolia + + + + Fee percentage to apply at payment time (e.g., '2.5' for 2.5%) + + + + Address to receive the fee + + + + The wallet address of the payer, use to check if payer approval exists + + + + Recurring payment configuration (optional) + + + + The start date of the payment, cannot be in the past + + + + The frequency of the payment + + Possible values: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY` + + + + The total number of times the payment will be executed (max 256). + + + + The wallet address of the payer + + + + +## Response + +### 201 Request created and payment initiated successfully + + + + + + +## Error Responses + + + Unauthorized - invalid API key + + + + Wallet not found + + + + Too Many Requests - rate limit exceeded + + + + + +```bash 201 Request created and payment initiated successfully +{ + "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb", + "paymentReference": "0xb3581f0b0f74cc61", + "transactions": [ + { + "data": "0xb868980b...00", + "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687", + "value": { + "type": "BigNumber", + "hex": "0x038d7ea4c68000" + } + } + ], + "metadata": { + "stepsRequired": 1, + "needsApproval": false, + "approvalTransactionIndex": null, + "hasEnoughBalance": true, + "hasEnoughGas": true + } +} +``` + +```bash 401 Unauthorized +No content +``` + +```bash 404 Wallet not found +No content +``` + +```bash 429 Too Many Requests +No content +``` + \ No newline at end of file diff --git a/request-network-api/migrate-to-v2.mdx b/request-network-api/migrate-to-v2.mdx new file mode 100644 index 0000000..b845171 --- /dev/null +++ b/request-network-api/migrate-to-v2.mdx @@ -0,0 +1,241 @@ +--- +title: "Migrate to V2" +description: "A comprehensive guide to help you transition from V1 to V2 of the Request Network API" +--- + + +The Request Network API V2 introduces significant improvements while maintaining backward compatibility. This guide provides a comprehensive overview of the breaking changes between V1 and V2, along with a step-by-step migration guide. + +**V1 API Deprecation Notice** + +V1 of the Request Network API is deprecated and in security-fixes-only mode. This means: + +- **Deprecated**: We strongly recommend upgrading to V2 +- **Security-fixes-only**: V1 will only receive critical security patches, no new features, enhancements, or non-security bug fixes + +Please migrate to V2 as soon as possible to ensure continued support and access to the latest features. + + + +**Important**: V2 is designed to coexist with V1. You can migrate incrementally and don't need to migrate all endpoints at once. See the [Full API Reference](https://api.request.network/open-api) for documentation of the V1 endpoints. + +## Breaking Changes from V1 to V2 + +### Core Architectural Changes + +**Path Parameter Changes** + +- **V1**: Uses `paymentReference` as the path parameter +- **V2**: Uses `requestId` as the path parameter + +**Response Schema Standardization** + +- **V1**: Returns `requestID` (uppercase D) in create responses +- **V2**: Returns `requestId` (lowercase d) in create responses + +**Enhanced Validation** + +- **V2**: Stricter type checking and validation schemas +- **V1**: More permissive validation + +## API Interface Differences + +### Endpoint Structure Changes + +#### Request Endpoints + +| Feature | V1 Endpoint | V2 Endpoint | +|---------|-------------|-------------| +| Create Request | `POST /v1/request` | `POST /v2/request` | +| Get Request | `GET /v1/request/{paymentReference}` | `GET /v2/request/{requestId}` | +| Get Request Status | `GET /v1/request/{paymentReference}/status` | `GET /v2/request/{requestId}/status` | + +#### Payment Endpoints + +| Feature | V1 Endpoint | V2 Endpoint | +|---------|-------------|-------------| +| Get Payment Calldata | `GET /v1/request/{paymentReference}/pay` | `GET /v2/request/{requestId}/pay` | +| Get Payment Routes | `GET /v1/request/{paymentReference}/routes` | `GET /v2/request/{requestId}/routes` | + +### Request Schema Differences + +#### Create Request Schema + +**V1 Schema:** + +```json +{ + "amount": "string", + "payee": "string", + "invoiceCurrency": "string", + "paymentCurrency": "string" +} +``` + +**V2 Schema:** + +```json +{ + "amount": "string", + "payee": "string", + "invoiceCurrency": "string", + "paymentCurrency": "string" + // V2 accepts additional optional fields for extended functionality +} +``` + +#### Create Response Schema + +**V1 Response:** + +```json +{ + "requestID": "string", // Note: uppercase D + "paymentReference": "string" +} +``` + +**V2 Response:** + +```json +{ + "requestId": "string", // Note: lowercase d + "paymentReference": "string" +} +``` + +### Payment Query Parameter Differences + +#### Pay Request Query Parameters + +**V1 Query Parameters:** + +```typescript +interface PayRequestQueryV1 { + payerAddress?: string; + routeId?: string; +} +``` + +**V2 Query Parameters:** + +```typescript +interface PayRequestQueryV2 { + payerAddress?: string; + routeId?: string; + // Enhanced validation with stricter type checking +} +``` + +## Step-by-Step Migration Guide + +### Phase 1: Assessment and Planning + +1. **Audit Your Current Integration** + - List all V1 endpoints you're currently using + - Identify which features you need (basic payments vs advanced features) +2. **Choose Migration Strategy** + - **Incremental**: Migrate endpoints one by one (recommended) + - **Full Migration**: Switch all endpoints at once + - **Parallel**: Run V1 and V2 side by side + +### Phase 2: Update Path Parameters + +#### Before (V1): + +```javascript +// Get request status +const response = await fetch(`/v1/request/${paymentReference}/status`); + +// Get payment calldata +const payData = await fetch(`/v1/request/${paymentReference}/pay?payerAddress=${address}`); +``` + +#### After (V2): + +```javascript +// Get request status +const response = await fetch(`/v2/request/${requestId}/status`); + +// Get payment calldata +const payData = await fetch(`/v2/request/${requestId}/pay?payerAddress=${address}`); +``` + +### Phase 3: Update Response Handling + +#### Before (V1): + +```javascript +const createResponse = await fetch('/v1/request', { + method: 'POST', + body: JSON.stringify(requestData) +}); + +const { requestID, paymentReference } = await createResponse.json(); +// Note: requestID with uppercase D +``` + +#### After (V2): + +```javascript +const createResponse = await fetch('/v2/request', { + method: 'POST', + body: JSON.stringify(requestData) +}); + +const { requestId, paymentReference } = await createResponse.json(); +// Note: requestId with lowercase d +``` + +### Phase 4: Update Error Handling + +V2 has enhanced error responses with more specific error codes: + +```javascript +try { + const response = await fetch('/v2/request', { + method: 'POST', + body: JSON.stringify(requestData) + }); + + if (!response.ok) { + const error = await response.json(); + + // V2 provides more detailed error information + console.error('Error:', error.message); + console.error('Status Code:', error.statusCode); + console.error('Error Code:', error.error); + } +} catch (error) { + console.error('Request failed:', error); +} +``` + +### Phase 5: Testing and Validation + +1. **Test Core Functionality** + - Create requests using V2 endpoints + - Verify payment flows work correctly + - Check response formats match expectations +2. **Enhanced Validation Testing** + - Test stricter type checking + - Verify improved error responses +3. **Performance Testing** + - Compare response times between V1 and V2 + - Test with realistic data volumes + +## Support and Resources + +- **Migration Support**: [Book a call](https://calendly.com/mariana-rn/request-network-demo-docs) with our team for migration assistance +- **GitHub Examples**: Check the `easy-invoice` repository for V2 implementation examples + +## Backward Compatibility + +V1 endpoints will continue to work during the migration period. However, we recommend migrating to V2 to access improvements and future features: + +- Enhanced security and validation +- Better error handling and debugging +- Improved webhook events +- Access to new features as they are released + +V2 is the foundation for all future Request Network API features and improvements. \ No newline at end of file diff --git a/request-network-api/payment-detection.mdx b/request-network-api/payment-detection.mdx new file mode 100644 index 0000000..8506c97 --- /dev/null +++ b/request-network-api/payment-detection.mdx @@ -0,0 +1,61 @@ +--- +title: "Payment Detection" +description: "A high level overview on how our API does payment detection" +--- + +## Payment Detection in Request API + +### Overview + +The Request API uses a [**reference-based payment detection system**](https://docs.request.network/advanced/protocol-overview/how-payment-networks-work#reference-based-payment-networks-recommended) that automatically monitors blockchain transactions to detect when payments are made to your requests. This system works across [multiple blockchains](https://docs.request.network/general/supported-chains) and handles various payment scenarios. + +### How It Works + +#### 1. Payment Reference Generation + +When you create a payment request, the API automatically generates a unique [**payment reference**](https://docs.request.network/advanced/request-network-sdk/sdk-guides/request-client/payment-reference)**,** a 16-character identifier that acts as a fingerprint for your request. This reference is what connects blockchain transactions back to your specific request. + +#### 2. Blockchain Monitoring + +The API continuously monitors supported blockchains using subgraphs that scan for transactions containing payment references. This happens automatically in the background, no action required from you. + +#### 3. Automatic Detection + +When someone makes a payment and includes the payment reference in their transaction, our system: + +- Detects the transaction within minutes +- Validates the payment details (amount, currency, recipient) +- Updates the request status (partially paid, fully paid, etc.) +- Triggers your configured webhooks + +#### 4. Real-time Updates + +Once a payment is detected, your request status is immediately updated and you can get the latest information via: + +- GET requests to check payment status using the request's id +- Automatically receive updates to your [webhooks](https://docs.request.network/request-network-api/api-portal-manage-api-keys-and-webhooks) + +### Crosschain Support + +All crosschain payments done using the [Request Network API](https://docs.request.network/request-network-api/crosschain-payments) use our [ERC 20 Fee proxy contract](https://docs.request.network/advanced/protocol-overview/how-payment-networks-work#erc20-fee-proxy-contract) as the last leg of payment, so payment detection works out of the box. + +### Webhook Notifications + +For real-time integration, you can configure webhooks to be notified for the following events: + +- **Payment Confirmed**: Full payment received +- **Payment Partial**: Partial payment received +- **Payment Failed**: Transaction failed +- **Payment Refunded**: Payment was refunded + +This allows your application to react immediately to payment events without constantly polling the API. + +### Integration Benefits + +- **Zero Configuration**: Payment detection happens automatically +- **Multi-blockchain**: Works across all supported networks +- **Real-time**: Fast detection and status updates +- **Flexible**: Handles various payment scenarios +- **Reliable**: Built on proven blockchain indexing infrastructure + +The system is designed to be completely transparent to your application, simply create requests and let the API handle all the complexity of monitoring blockchains for payments. \ No newline at end of file diff --git a/request-network-api/request-network-token-list.mdx b/request-network-api/request-network-token-list.mdx new file mode 100644 index 0000000..22ec48b --- /dev/null +++ b/request-network-api/request-network-token-list.mdx @@ -0,0 +1,86 @@ +--- +title: "Request Network Token List | Request Network Docs" +source: "https://docs.request.network/request-network-api/request-network-token-list" +author: "Request Network Team" +published: 2025-05-21 +created: 2025-09-08 +description: "Comprehensive list of supported tokens and currencies for the Request Network API" +tags: + - "clippings" +--- + +# Request Network Token List + +This document provides a comprehensive list of all supported tokens and currencies for the Request Network API. + +## Supported Currencies + +The Request Network API supports a wide variety of cryptocurrencies and fiat currencies for creating payment requests and processing payments. + +### Cryptocurrencies + +#### Ethereum Mainnet +- **ETH**: `ETH-mainnet-mainnet` +- **USDC**: `USDC-mainnet-mainnet` +- **USDT**: `USDT-mainnet-mainnet` +- **DAI**: `DAI-mainnet-mainnet` + +#### Arbitrum One +- **USDC**: `USDC-arbitrum-one-arbitrum-one` +- **USDT**: `USDT-arbitrum-one-arbitrum-one` +- **DAI**: `DAI-arbitrum-one-arbitrum-one` + +#### Base +- **USDC**: `USDC-base-base` +- **USDT**: `USDT-base-base` +- **DAI**: `DAI-base-base` + +#### OP Mainnet +- **USDC**: `USDC-op-mainnet-op-mainnet` +- **USDT**: `USDT-op-mainnet-op-mainnet` +- **DAI**: `DAI-op-mainnet-op-mainnet` + +#### Sepolia Testnet +- **ETH**: `ETH-sepolia-sepolia` +- **USDC**: `USDC-sepolia-sepolia` +- **USDT**: `USDT-sepolia-sepolia` +- **DAI**: `DAI-sepolia-sepolia` + +### Fiat Currencies + +The Request Network API supports fiat currency denominations for conversion payments: +- **USD**: `USD` +- **EUR**: `EUR` +- **GBP**: `GBP` +- **JPY**: `JPY` +- And other ISO 4217 currencies + +## Currency ID Format + +Currency IDs follow the pattern: `{TOKEN}-{CHAIN}-{CHAIN}` + +For example: +- `USDC-mainnet-mainnet` for USDC on Ethereum mainnet +- `USDC-base-base` for USDC on Base +- `USD` for USD fiat currency + +## Usage in API + +When creating requests or initiating payments, use the currency IDs from this list in the `invoiceCurrency` and `paymentCurrency` fields. + +## Crosschain Payments + +For crosschain payments, the following stablecoins are supported: +- USDC, USDT, DAI on Ethereum, Arbitrum One, Base, and OP Mainnet + +## Crypto-to-Fiat Payments + +For crypto-to-fiat payments, USDC on Sepolia testnet is currently supported. + +## Updates + +This token list is regularly updated. For the most current list, refer to the API documentation or contact the Request Network team. + + + + diff --git a/request-network-api/update-a-recurring-request.mdx b/request-network-api/update-a-recurring-request.mdx new file mode 100644 index 0000000..2e0a9be --- /dev/null +++ b/request-network-api/update-a-recurring-request.mdx @@ -0,0 +1,60 @@ +--- +title: "Update a Recurring Request" +api: PATCH https://api.request.network/v2/request/{requestId} +contentType: application/json +--- + +## Update a Recurring Request + + + +## Path Parameters + + + The requestId for the recurring request + + Example: `01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb` + + +## Headers parameters + + + API key for authentication + + + +## Response + +Returns `204 No Content` on successful update. + +## Error Responses + + + Unauthorized - invalid API key + + + + Request not found + + + + Too Many Requests - rate limit exceeded + + + +```bash 200 Recurrence updated successfully +No content +``` + +```bash 401 Unauthorized +No content +``` + +```bash 404 Request not found +No content +``` + +```bash 429 Too Many Requests +No content +``` + \ No newline at end of file diff --git a/resources/community.mdx b/resources/community.mdx new file mode 100644 index 0000000..7209cac --- /dev/null +++ b/resources/community.mdx @@ -0,0 +1,331 @@ +--- +title: "Community" +description: "Join the Request Network community, get support, and stay updated with the latest developments" +--- + +## Request Network Community + +Connect with developers, integrators, and the Request Network team across our community channels. Get help, share your projects, and stay updated with the latest developments. + +## Community Channels + + + + **Join our Discord server** + + - Developer support and Q&A + - Integration help and guidance + - Community showcases and demos + - Real-time discussions with the team + - Beta testing and feedback opportunities + + + + **Follow @RequestNetwork** + + - Product announcements and updates + - Feature releases and roadmap + - Community highlights and showcases + - Industry news and insights + - Developer spotlights + + + + + + **Connect on LinkedIn** + + - Professional network updates + - Business use case discussions + - Partnership announcements + - Industry thought leadership + - Career opportunities + + + + **Follow on Bluesky** + + - Alternative social platform + - Community discussions + - Technical updates + - Decentralized social presence + + + +## Developer Resources + +### GitHub Organization + + + + **RequestNetwork Core** + + - Protocol implementation + - Smart contracts + - SDK packages + - Issue tracking and contributions + + + + **Request API** + + - API server implementation + - Documentation and examples + - Bug reports and feature requests + - API development updates + + + +### Documentation & Guides + + + + **Comprehensive Guides:** + - [API Reference](/api-reference/authentication) - Complete API documentation + - [Integration Patterns](/api-features/integration-patterns) - Best practices and examples + - [Use Case Guides](/use-cases/invoicing) - Specific implementation scenarios + - [Smart Contracts](/resources/smart-contracts) - Contract addresses and ABIs + + + + **Learning Resources:** + - Getting started with Request Network API + - Building your first invoice application + - Implementing webhook notifications + - Advanced payment flow patterns + + *Video content available on our YouTube channel and documentation* + + + + **Educational Content:** + - [Request Network Blog](https://request.network/blog) - Latest updates and insights + - Technical deep dives and tutorials + - Industry analysis and trends + - Developer success stories and case studies + + + +## Support Options + +### Developer Support + + + + **Free Community Help:** + + **Discord #dev-support Channel:** + - Quick questions and troubleshooting + - Integration guidance + - Code reviews and feedback + - Community-driven solutions + + **GitHub Issues:** + - Bug reports and feature requests + - Technical discussions + - Documentation improvements + - Open source contributions + + + + **Enterprise & Business Support:** + + **Direct Access:** + - Priority support channels + - Dedicated technical account management + - Custom integration consultation + - SLA-backed response times + + **Contact:** [enterprise@request.network](mailto:enterprise@request.network) + + + + **Expert Consultation:** + + **Services Available:** + - Architecture review and planning + - Custom integration development + - Performance optimization + - Security audit and recommendations + + **Contact:** [consulting@request.network](mailto:consulting@request.network) + + + +## Community Guidelines + +### Code of Conduct + + +**Respectful Community** + +Request Network is committed to fostering a welcoming, inclusive, and respectful community for all developers and users. + + +**Community Standards:** +- Be respectful and constructive in all interactions +- Help newcomers and share knowledge freely +- Stay on-topic and avoid spam or self-promotion +- Report issues or concerns to community moderators +- Follow platform-specific rules and guidelines + +### Contributing + + + + **Help Improve Documentation:** + - Fix typos and clarify explanations + - Add examples and use cases + - Translate content to other languages + - Suggest new topics and guides + + **How to Contribute:** Submit pull requests to our documentation repositories + + + + **Report Issues Effectively:** + - Provide clear reproduction steps + - Include relevant code snippets + - Specify environment and version details + - Search existing issues before creating new ones + + **Where to Report:** GitHub Issues on relevant repositories + + + + **Suggest New Features:** + - Describe the use case and problem + - Explain the proposed solution + - Consider backwards compatibility + - Engage in community discussion + + **Process:** GitHub Discussions or Discord feature-requests channel + + + +## Events & Meetups + +### Regular Events + + + + **Monthly Community Calls** + + - Direct access to the development team + - Q&A sessions and technical discussions + - Product roadmap updates + - Community showcase presentations + + **Schedule:** First Thursday of each month + + + + **Community Challenges** + + - Regular hackathons and building competitions + - Prize pools for innovative integrations + - Mentorship from Request Network team + - Showcase opportunities for winners + + **Updates:** Announced via Discord and social media + + + +### Conference Presence + +**Industry Events:** +- ETHGlobal events and hackathons +- Blockchain developer conferences +- Fintech and payments industry events +- Web3 developer workshops and meetups + +## Community Showcase + + + + **Community Built Solutions:** + + - Innovative payment applications + - Creative use case implementations + - Open source tools and libraries + - Educational content and tutorials + + **Submit Your Project:** Share in Discord #showcase channel + + + + **Success Stories:** + + - Business transformation case studies + - Technical implementation deep dives + - Performance and scalability achievements + - Developer journey narratives + + **Share Your Story:** Contact us for feature opportunities + + + + **Developer-Built Resources:** + + - SDK extensions and wrappers + - Integration templates and boilerplates + - Testing and development tools + - Analytics and monitoring solutions + + + +## Stay Updated + +### Newsletter & Updates + + + + **Monthly Technical Updates** + + - New feature announcements + - Integration guides and tutorials + - Community highlights + - Technical best practices + + [Subscribe to Newsletter โ†’](https://request.network/newsletter) + + + + **Real-time Updates** + + - API updates and new endpoints + - Breaking changes and migrations + - Security updates and patches + - Documentation improvements + + **Follow:** GitHub releases and Discord announcements + + + +## What's Next? + + + + Start building with Request Network today + + + + Connect with the developer community + + + + Discover what you can build + + diff --git a/resources/smart-contracts.mdx b/resources/smart-contracts.mdx new file mode 100644 index 0000000..079b319 --- /dev/null +++ b/resources/smart-contracts.mdx @@ -0,0 +1,453 @@ +--- +title: "Smart Contracts" +description: "Smart contract addresses, ABIs, and technical details for Request Network protocol" +--- + +## Overview + +Request Network operates through a set of smart contracts deployed across multiple blockchain networks. These contracts handle payment processing, fee collection, and request lifecycle management. This page provides contract addresses, ABIs, and integration details for developers. + +## Core Contract Architecture + + + + **Core Protocol Contract** + + **Purpose:** Request creation, updates, and lifecycle management + **Features:** + - Request creation and validation + - Metadata storage and retrieval + - Request status management + - Event emission for indexing + + + + **Payment Execution Contract** + + **Purpose:** Handle actual payment processing + **Features:** + - Multi-currency payment support + - Fee collection and distribution + - Payment verification + - Cross-chain payment routing + + + + + + **Fee Collection Contract** + + **Purpose:** Platform and integration fee management + **Features:** + - Configurable fee structures + - Multi-party fee distribution + - Fee rate management + - Revenue sharing automation + + + + **Supported Currency Contract** + + **Purpose:** Manage supported currencies and tokens + **Features:** + - Currency whitelist management + - Token metadata storage + - Price oracle integration + - Currency validation + + + +## Contract Addresses by Network + +### Ethereum Mainnet + + + + **Primary Contract Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0x123...abc` | Core request management | + | Payment Processor | `0x456...def` | Payment execution | + | Fee Manager | `0x789...ghi` | Fee collection | + | Currency Registry | `0xabc...123` | Supported currencies | + + **Network ID:** 1 + **Explorer:** [Etherscan](https://etherscan.io) + + + + **Payment Processing Contracts:** + + | Payment Type | Contract Address | Version | + |--------------|------------------|---------| + | ERC20 Fee Proxy | `0xdef...456` | v2.1.0 | + | ETH Fee Proxy | `0xghi...789` | v2.1.0 | + | ERC20 Swap | `0xjkl...012` | v2.0.0 | + | Batch Payments | `0xmno...345` | v2.1.0 | + + + + **Sepolia Testnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xtest...001` | Core request management | + | Payment Processor | `0xtest...002` | Payment execution | + | Fee Manager | `0xtest...003` | Fee collection | + + **Network ID:** 11155111 + **Explorer:** [Sepolia Etherscan](https://sepolia.etherscan.io) + + + +### Polygon + + + + **Polygon Mainnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xpoly...001` | Core request management | + | Payment Processor | `0xpoly...002` | Payment execution | + | Fee Manager | `0xpoly...003` | Fee collection | + | Currency Registry | `0xpoly...004` | Supported currencies | + + **Network ID:** 137 + **Explorer:** [PolygonScan](https://polygonscan.com) + + + + **Mumbai Testnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xmumb...001` | Core request management | + | Payment Processor | `0xmumb...002` | Payment execution | + | Fee Manager | `0xmumb...003` | Fee collection | + + **Network ID:** 80001 + **Explorer:** [Mumbai PolygonScan](https://mumbai.polygonscan.com) + + + +### Layer 2 Networks + + + + **Arbitrum Mainnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xarb1...001` | Core request management | + | Payment Processor | `0xarb1...002` | Payment execution | + | Fee Manager | `0xarb1...003` | Fee collection | + + **Network ID:** 42161 + **Explorer:** [Arbiscan](https://arbiscan.io) + + + + **Optimism Mainnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xopt...001` | Core request management | + | Payment Processor | `0xopt...002` | Payment execution | + | Fee Manager | `0xopt...003` | Fee collection | + + **Network ID:** 10 + **Explorer:** [Optimistic Etherscan](https://optimistic.etherscan.io) + + + + **Base Mainnet Addresses:** + + | Contract | Address | Purpose | + |----------|---------|---------| + | Request Manager | `0xbase...001` | Core request management | + | Payment Processor | `0xbase...002` | Payment execution | + | Fee Manager | `0xbase...003` | Fee collection | + + **Network ID:** 8453 + **Explorer:** [BaseScan](https://basescan.org) + + + +## Contract ABIs + +### Request Manager ABI + + +```json Core Functions +[ + { + "type": "function", + "name": "createRequest", + "inputs": [ + { + "name": "_requestData", + "type": "tuple", + "components": [ + {"name": "payee", "type": "address"}, + {"name": "payer", "type": "address"}, + {"name": "expectedAmount", "type": "uint256"}, + {"name": "currency", "type": "address"}, + {"name": "deadline", "type": "uint256"} + ] + } + ], + "outputs": [ + {"name": "requestId", "type": "bytes32"} + ] + }, + { + "type": "event", + "name": "RequestCreated", + "inputs": [ + {"name": "requestId", "type": "bytes32", "indexed": true}, + {"name": "payee", "type": "address", "indexed": true}, + {"name": "payer", "type": "address", "indexed": true} + ] + } +] +``` + +```json Payment Functions +[ + { + "type": "function", + "name": "payRequest", + "inputs": [ + {"name": "_requestId", "type": "bytes32"}, + {"name": "_amount", "type": "uint256"}, + {"name": "_feeAmount", "type": "uint256"} + ], + "outputs": [] + }, + { + "type": "event", + "name": "PaymentReceived", + "inputs": [ + {"name": "requestId", "type": "bytes32", "indexed": true}, + {"name": "amount", "type": "uint256"}, + {"name": "payer", "type": "address", "indexed": true} + ] + } +] +``` + + +### Integration Examples + + +```javascript Web3.js Integration +const Web3 = require('web3'); +const web3 = new Web3('https://polygon-rpc.com'); + +// Contract instance +const requestManager = new web3.eth.Contract( + REQUEST_MANAGER_ABI, + '0xpoly...001' +); + +// Create a payment request +async function createRequest(payeeAddress, payerAddress, amount, tokenAddress) { + const requestData = { + payee: payeeAddress, + payer: payerAddress, + expectedAmount: web3.utils.toWei(amount.toString(), 'ether'), + currency: tokenAddress, + deadline: Math.floor(Date.now() / 1000) + 86400 // 24 hours + }; + + const tx = await requestManager.methods + .createRequest(requestData) + .send({ from: payeeAddress }); + + return tx.events.RequestCreated.returnValues.requestId; +} +``` + +```javascript Ethers.js Integration +const { ethers } = require('ethers'); + +// Provider and contract setup +const provider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com'); +const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); +const requestManager = new ethers.Contract( + '0xpoly...001', + REQUEST_MANAGER_ABI, + wallet +); + +// Listen for payment events +requestManager.on('PaymentReceived', (requestId, amount, payer, event) => { + console.log(`Payment received: ${requestId}`); + console.log(`Amount: ${ethers.utils.formatEther(amount)}`); + console.log(`From: ${payer}`); + + // Handle payment confirmation + handlePaymentReceived(requestId, amount, payer); +}); + +// Pay a request +async function payRequest(requestId, amount, feeAmount) { + const tx = await requestManager.payRequest( + requestId, + ethers.utils.parseEther(amount.toString()), + ethers.utils.parseEther(feeAmount.toString()) + ); + + await tx.wait(); + return tx.hash; +} +``` + + +## Gas Usage Estimates + +### Transaction Gas Costs + + + + **Gas Usage for Request Management:** + + | Operation | Estimated Gas | Cost on Polygon | Cost on Ethereum | + |-----------|---------------|-----------------|------------------| + | Create Request | 150,000 | $0.01 | $3-30 | + | Update Request | 80,000 | $0.005 | $2-20 | + | Cancel Request | 60,000 | $0.003 | $1-15 | + + **Optimization Tips:** + - Batch multiple operations when possible + - Use Layer 2 networks for frequent operations + - Optimize metadata to reduce gas usage + + + + **Gas Usage for Payments:** + + | Payment Type | Estimated Gas | Cost on Polygon | Cost on Ethereum | + |--------------|---------------|-----------------|------------------| + | ERC20 Payment | 120,000 | $0.008 | $2-25 | + | ETH Payment | 80,000 | $0.005 | $2-20 | + | Batch Payment (5x) | 400,000 | $0.025 | $8-80 | + | Cross-chain Payment | 200,000 | $0.012 | $4-40 | + + + + **Gas Usage for Fee Management:** + + | Operation | Estimated Gas | Notes | + |-----------|---------------|-------| + | Collect Platform Fee | 45,000 | Additional to payment gas | + | Distribute Revenue Share | 80,000 | Per additional recipient | + | Update Fee Structure | 60,000 | Admin operation | + + + +## Security Considerations + +### Contract Security + + + + **Security Audits:** + - Audited by leading security firms + - Formal verification of critical functions + - Bug bounty program for ongoing security + - Regular security reviews and updates + + **Audit Reports:** + - [Audit Report v2.1.0] - ConsenSys Diligence + - [Audit Report v2.0.0] - Trail of Bits + - [Formal Verification] - Certora + + + + **Integration Security:** + - Always validate contract addresses + - Use latest contract versions + - Implement proper error handling + - Monitor for unusual activity + - Use multi-signature wallets for admin functions + + **Common Pitfalls to Avoid:** + - Don't hardcode contract addresses across networks + - Always check function return values + - Implement proper access controls + - Validate all input parameters + + + + **Contract Upgrades:** + - Proxy pattern for upgradeable contracts + - Timelock for critical parameter changes + - Multi-signature governance for upgrades + - Emergency pause functionality for critical issues + + **Incident Response:** + - Real-time monitoring and alerting + - Coordinated disclosure for vulnerabilities + - Rapid response team for critical issues + - Communication channels for status updates + + + +## Version History + + + + **Release Date:** September 2025 + + **New Features:** + - Enhanced batch payment processing + - Improved gas optimization + - Cross-chain payment routing + - Advanced fee distribution + + **Deployments:** All supported networks + + + + **Release Date:** June 2025 + + **Major Changes:** + - Complete protocol redesign + - Multi-chain support + - Enhanced security model + - Improved user experience + + **Status:** Legacy support until v3.0.0 + + + +## What's Next? + + + + View all supported currencies and their contract addresses + + + + Learn how to integrate with Request Network contracts + + + + Start building with Request Network API and contracts + + diff --git a/resources/supported-chains-and-currencies.mdx b/resources/supported-chains-and-currencies.mdx new file mode 100644 index 0000000..fa4e9d1 --- /dev/null +++ b/resources/supported-chains-and-currencies.mdx @@ -0,0 +1,383 @@ +--- +title: "Supported Chains and Currencies" +description: "Complete list of supported blockchain networks and currencies for Request Network" +--- + +## Overview + +Request Network supports payments across **10 EVM-compatible blockchain networks** with **553+ currencies** including major cryptocurrencies, stablecoins, and fiat currencies. This comprehensive coverage ensures global accessibility and flexibility for all payment scenarios. + +## Supported Blockchain Networks + + + + **Mainnet & Sepolia Testnet** + + **Native Token:** ETH + **Popular Tokens:** USDC, USDT, DAI, LINK, UNI + **Network ID:** 1 (mainnet), 11155111 (sepolia) + + **Best For:** High-value transactions, DeFi integration + + + + **Mainnet & Mumbai Testnet** + + **Native Token:** MATIC + **Popular Tokens:** USDC, USDT, DAI, WETH + **Network ID:** 137 (mainnet), 80001 (mumbai) + + **Best For:** Low-cost transactions, high throughput + + + + + + **One & Sepolia Testnet** + + **Native Token:** ETH + **Popular Tokens:** USDC, USDT, ARB, GMX + **Network ID:** 42161 (one), 421614 (sepolia) + + **Best For:** Lower fees with Ethereum security + + + + **Mainnet & Sepolia Testnet** + + **Native Token:** ETH + **Popular Tokens:** USDC, USDT, OP, SNX + **Network ID:** 10 (mainnet), 11155420 (sepolia) + + **Best For:** Fast transactions, Ethereum compatibility + + + + + + **Mainnet & Sepolia Testnet** + + **Native Token:** ETH + **Popular Tokens:** USDC, cbETH, DAI + **Network ID:** 8453 (mainnet), 84532 (sepolia) + + **Best For:** Coinbase ecosystem integration + + + + **More Networks Available:** + - BSC (Binance Smart Chain) + - Avalanche C-Chain + - Fantom Opera + - Gnosis Chain + - Celo + + + +## Currency Categories + +### Major Cryptocurrencies + + + + **Blockchain Native Currencies:** + + | Currency | Symbol | Chains Available | + |----------|--------|------------------| + | Ethereum | ETH | Ethereum, Arbitrum, Optimism, Base | + | Polygon | MATIC | Polygon | + | Binance Coin | BNB | BSC | + | Avalanche | AVAX | Avalanche | + | Fantom | FTM | Fantom | + + + + **USD-Pegged Stablecoins:** + + | Currency | Symbol | Chains Available | + |----------|--------|------------------| + | USD Coin | USDC | All supported chains | + | Tether | USDT | Ethereum, Polygon, BSC, Avalanche | + | DAI | DAI | Ethereum, Polygon, Arbitrum, Optimism | + | BUSD | BUSD | BSC, Ethereum | + | FRAX | FRAX | Ethereum, Polygon, Arbitrum | + + **Other Stablecoins:** + - USDC.e (bridged USDC on various chains) + - sUSD (Synthetix USD) + - LUSD (Liquity USD) + - And many more... + + + + **DeFi & Ecosystem Tokens:** + + | Currency | Symbol | Primary Chains | + |----------|--------|----------------| + | Chainlink | LINK | Ethereum, Polygon, Arbitrum | + | Uniswap | UNI | Ethereum, Polygon, Arbitrum | + | Aave | AAVE | Ethereum, Polygon | + | Compound | COMP | Ethereum | + | Curve DAO | CRV | Ethereum, Polygon | + | 1inch | 1INCH | Ethereum, BSC | + + + +### Fiat Currencies + + + + **G7 & Major Global Currencies:** + + | Currency | Code | Region | + |----------|------|--------| + | US Dollar | USD | United States | + | Euro | EUR | European Union | + | British Pound | GBP | United Kingdom | + | Japanese Yen | JPY | Japan | + | Canadian Dollar | CAD | Canada | + | Australian Dollar | AUD | Australia | + | Swiss Franc | CHF | Switzerland | + | Chinese Yuan | CNY | China | + + **Note:** Fiat currencies are used for pricing and conversion. Actual payments settle in cryptocurrency. + + + + **Regional Currencies:** + + | Currency | Code | Region | + |----------|------|--------| + | Brazilian Real | BRL | Brazil | + | Indian Rupee | INR | India | + | Mexican Peso | MXN | Mexico | + | South African Rand | ZAR | South Africa | + | Turkish Lira | TRY | Turkey | + | Russian Ruble | RUB | Russia | + | Korean Won | KRW | South Korea | + | Thai Baht | THB | Thailand | + + **Total Coverage:** 150+ international fiat currencies + + + +## Currency Selection Guide + +### For Different Use Cases + + + + **Recommended Currencies:** + - **Pricing:** USD, EUR, GBP (familiar fiat terms) + - **Settlement:** USDC, USDT, DAI (stable value) + - **Networks:** Polygon, Arbitrum (lower fees) + + [Learn More โ†’](/use-cases/invoicing) + + + + **Recommended Currencies:** + - **High Volume:** USDC on Polygon (lowest fees) + - **Cross-border:** USDC, USDT (global acceptance) + - **Flexibility:** Native tokens for local markets + + [Learn More โ†’](/use-cases/payouts) + + + + + + **Recommended Currencies:** + - **Customer Choice:** Multiple payment options + - **Conversion:** USD pricing, crypto settlement + - **Popular:** ETH, USDC, MATIC, BNB + + [Learn More โ†’](/use-cases/checkout) + + + + **Recommended Currencies:** + - **Stability:** USDC, DAI (predictable values) + - **Low Fees:** Polygon, Arbitrum networks + - **Reliability:** Established stablecoins + + [Learn More โ†’](/use-cases/subscriptions) + + + +## Network Selection Criteria + +### Cost Optimization + + + + **Average Transaction Costs (2025):** + + | Network | Native Transfer | ERC-20 Transfer | Typical Use | + |---------|----------------|-----------------|-------------| + | Polygon | $0.001-0.01 | $0.01-0.03 | High volume, frequent transactions | + | Arbitrum | $0.10-0.50 | $0.20-1.00 | Ethereum ecosystem, medium volume | + | Optimism | $0.10-0.50 | $0.20-1.00 | Ethereum ecosystem, medium volume | + | Base | $0.05-0.25 | $0.10-0.50 | Coinbase integration | + | Ethereum | $2-20 | $5-50 | High value, infrequent transactions | + + + **Fee Optimization Tips** + + - Use Polygon for high-frequency, low-value transactions + - Use Ethereum for high-value, security-critical transactions + - Consider L2 solutions (Arbitrum, Optimism) for balanced cost/security + + + + + **Transaction Confirmation Times:** + + | Network | Block Time | Practical Finality | Best For | + |---------|------------|-------------------|----------| + | Polygon | 2 seconds | 30-60 seconds | Real-time applications | + | Base | 2 seconds | 30-60 seconds | Fast user experiences | + | Arbitrum | 1 second | 5-15 minutes | Balanced speed/security | + | Optimism | 2 seconds | 5-15 minutes | Balanced speed/security | + | Ethereum | 12 seconds | 5-15 minutes | Maximum security | + + + + **Network Ecosystem Maturity:** + + | Network | TVL | DEX Liquidity | Ecosystem | Adoption | + |---------|-----|---------------|-----------|----------| + | Ethereum | Highest | Highest | Most mature | Universal | + | Polygon | High | High | Very mature | High | + | Arbitrum | High | High | Mature | High | + | Optimism | Medium | Medium | Growing | Medium | + | Base | Growing | Growing | New but strong | Growing | + + + +## Currency Codes and Formats + +### Standard Format + +Request Network uses standardized currency codes: + + +```javascript Native Tokens +// Format: {SYMBOL}-{NETWORK} +"ETH-mainnet" // Ethereum on Ethereum mainnet +"MATIC-matic" // MATIC on Polygon mainnet +"ETH-arbitrum-one" // ETH on Arbitrum One +"ETH-optimism" // ETH on Optimism +"BNB-bsc" // BNB on BSC +``` + +```javascript ERC-20 Tokens +// Format: {SYMBOL}-{NETWORK}-{OPTIONAL_SUFFIX} +"USDC-mainnet" // USDC on Ethereum +"USDC-matic" // USDC on Polygon +"USDC-arbitrum-one" // USDC on Arbitrum +"USDC-optimism" // USDC on Optimism +"USDT-mainnet" // USDT on Ethereum +"DAI-mainnet" // DAI on Ethereum +``` + +```javascript Fiat Currencies +// Format: {ISO_CODE} +"USD" // US Dollar +"EUR" // Euro +"GBP" // British Pound +"JPY" // Japanese Yen +"CAD" // Canadian Dollar +``` + + +### Currency Validation + + +```javascript Validate Currency +import { validateCurrency } from '@requestnetwork/request-client.js'; + +// Check if currency is supported +const isValid = validateCurrency('USDC-matic'); +console.log(isValid); // true + +// Get currency details +const currencyInfo = getCurrencyInfo('USDC-matic'); +console.log(currencyInfo); +// { +// symbol: 'USDC', +// network: 'matic', +// type: 'ERC20', +// decimals: 6, +// address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174' +// } +``` + +```javascript API Currency Check +// Check supported currencies via API +const response = await fetch('https://api.request.network/v2/currencies', { + headers: { + 'Authorization': `Bearer ${apiKey}` + } +}); + +const currencies = await response.json(); +console.log(currencies.supported); +``` + + +## Real-Time Price Data + +Request Network uses multiple price feed sources for accurate conversions: + + + + **Primary Data Sources:** + - Chainlink Price Feeds (on-chain) + - CoinGecko API (market aggregation) + - CoinMarketCap API (market data) + - DEX aggregators (real-time trading data) + + **Update Frequency:** Sub-minute updates for major pairs + + + + **Fiat to Crypto:** + - Any fiat currency โ†’ Any supported cryptocurrency + - Real-time exchange rate calculation + - Slippage protection for large amounts + + **Crypto to Crypto:** + - Cross-chain token conversions + - Optimal routing through DEX aggregators + - Minimal slippage and MEV protection + + + +## What's Next? + + + + View smart contract addresses for all supported networks + + + + Learn about different payment types and currency options + + + + Start building with your preferred currencies and networks + + diff --git a/sdk-legacy/migration-guide.mdx b/sdk-legacy/migration-guide.mdx new file mode 100644 index 0000000..0efca7f --- /dev/null +++ b/sdk-legacy/migration-guide.mdx @@ -0,0 +1,272 @@ +--- +title: "Migration Guide" +description: "Simple migration guidance from deprecated SDK packages to Request Network API" +--- + +## Migration Overview + +The Request Network SDK has been deprecated in favor of the more robust and feature-rich Request Network API. This guide provides a straightforward migration path for the few existing SDK users. + + +**SDK Deprecation Notice** + +The Request Network SDK had near-zero adoption and is no longer maintained. All new development should use the Request Network API. + + +## Quick Migration Summary + +**From SDK to API:** +- Replace direct blockchain interactions with API calls +- Simplified authentication using API keys +- Enhanced features including webhooks and advanced payment types +- Better error handling and rate limiting +- Comprehensive documentation and support + +## Migration Steps + + + + Sign up for Request Network API access at [portal.request.network](https://portal.request.network) + + + Convert SDK function calls to equivalent API endpoints + + + Implement proper API error handling and retry logic + + + Set up webhooks for real-time payment notifications + + + +## Code Comparison + +### Request Creation + + +```javascript SDK (Deprecated) +import { RequestNetwork } from '@requestnetwork/request-client.js'; + +// SDK approach - deprecated +const requestNetwork = new RequestNetwork({ + nodeConnectionConfig: { + baseURL: 'https://goerli.gateway.request.network/' + } +}); + +const request = await requestNetwork.createRequest({ + requestInfo: { + currency: 'ETH', + expectedAmount: '1000000000000000000', + payee: { + type: 'ethereumAddress', + value: '0x...' + } + } +}); +``` + +```javascript API (Recommended) +// API approach - current and supported +const response = await fetch('https://api.request.network/v2/requests', { + method: 'POST', + headers: { + 'Authorization': `Bearer ${process.env.REQUEST_NETWORK_API_KEY}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + currency: 'ETH-sepolia', + expectedAmount: '1', + payeeIdentity: '0x...', + reason: 'Payment for services' + }) +}); + +const request = await response.json(); +``` + + +### Payment Processing + + +```javascript SDK (Deprecated) +// SDK payment processing +const paymentTx = await request.payWithWallet(wallet); +await paymentTx.wait(); +``` + +```javascript API (Recommended) +// API payment processing with webhook +const payment = await fetch('https://api.request.network/v2/payments', { + method: 'POST', + headers: { + 'Authorization': `Bearer ${process.env.REQUEST_NETWORK_API_KEY}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + requestId: request.requestId, + amount: '1', + currency: 'ETH-sepolia' + }) +}); + +// Webhook will notify you when payment is confirmed +``` + + +## Benefits of API Migration + + + + **Easier Development:** + - No blockchain wallet management required + - Standard REST API calls + - Comprehensive error responses + - Built-in rate limiting and retry logic + + + + **Enhanced Monitoring:** + - Webhook notifications for all events + - Real-time payment confirmations + - Automatic retry for failed webhooks + - Comprehensive event logging + + + + + + **New Capabilities:** + - Cross-chain payments + - Batch processing + - Recurring payments + - Platform fee collection + - Multi-currency support + + + + **Production Features:** + - High availability and uptime + - Scalable infrastructure + - Professional support + - Security audits and compliance + + + +## Common Migration Patterns + +### Replace SDK Initialization + + +```javascript Before (SDK) +import { RequestNetwork } from '@requestnetwork/request-client.js'; +import { Web3SignatureProvider } from '@requestnetwork/web3-signature'; + +const web3SignatureProvider = new Web3SignatureProvider(web3.currentProvider); +const requestNetwork = new RequestNetwork({ + nodeConnectionConfig: { + baseURL: 'https://goerli.gateway.request.network/' + }, + signatureProvider: web3SignatureProvider +}); +``` + +```javascript After (API) +// Simple API configuration +const config = { + apiKey: process.env.REQUEST_NETWORK_API_KEY, + baseURL: 'https://api.request.network', + environment: 'testnet' // or 'mainnet' +}; + +// No complex initialization required +``` + + +### Replace Event Listening + + +```javascript Before (SDK) +// SDK event listening +request.on('payment', (payment) => { + console.log('Payment received:', payment); + updateOrderStatus(payment.requestId, 'paid'); +}); +``` + +```javascript After (API) +// Webhook endpoint for payment events +app.post('/webhooks/payment-events', (req, res) => { + const { eventType, data } = req.body; + + if (eventType === 'payment_confirmed') { + console.log('Payment received:', data); + updateOrderStatus(data.requestId, 'paid'); + } + + res.status(200).send('OK'); +}); +``` + + +## Migration Checklist + + + + **Before You Start:** + - [ ] Review current SDK usage in your application + - [ ] Identify all SDK function calls and event listeners + - [ ] Sign up for Request Network API access + - [ ] Generate API keys for development and production + - [ ] Review API documentation for equivalent endpoints + + + + **Update Your Code:** + - [ ] Replace SDK initialization with API configuration + - [ ] Convert request creation to API calls + - [ ] Replace payment processing with API endpoints + - [ ] Set up webhook endpoints for event handling + - [ ] Update error handling for API responses + - [ ] Test all functionality with API integration + + + + **Verify Migration:** + - [ ] Test request creation and payment flows + - [ ] Verify webhook event handling + - [ ] Test error scenarios and edge cases + - [ ] Performance test with expected load + - [ ] Deploy to staging environment + - [ ] Run end-to-end tests + - [ ] Deploy to production with monitoring + + + +## Need Help? + + +**Limited SDK Support** + +Since the SDK had minimal adoption, migration support is available on a case-by-case basis. Most users will find the API migration straightforward and beneficial. + + + + + Comprehensive API documentation with examples and best practices + + + + Quick setup guide to get your API integration running + + + + + + Explore specific business scenarios and implementation patterns + + + + Common integration patterns and architectural guidance + + diff --git a/snippets/snippet-intro.mdx b/snippets/snippet-intro.mdx index e20fbb6..9774dc9 100644 --- a/snippets/snippet-intro.mdx +++ b/snippets/snippet-intro.mdx @@ -1,4 +1,10 @@ -One of the core principles of software development is DRY (Don't Repeat -Yourself). This is a principle that applies to documentation as -well. If you find yourself repeating the same content in multiple places, you -should consider creating a custom snippet to keep your content in sync. +--- +title: "Snippet Introduction | Request Network Docs" +description: "Introduction to using snippets in documentation" +tags: + - "snippets" +--- + +# Snippet Introduction + +One of the core principles of software development is DRY (Don't Repeat Yourself). This is a principle that applies to documentation as well. If you find yourself repeating the same content in multiple places, you should consider creating a custom snippet to keep your content in sync. diff --git a/use-cases/checkout.mdx b/use-cases/checkout.mdx new file mode 100644 index 0000000..c97bfcf --- /dev/null +++ b/use-cases/checkout.mdx @@ -0,0 +1,284 @@ +--- +title: "๐Ÿ›’ Checkout" +description: "Integrate crypto payments into your e-commerce with 80+ wallet support and seamless UX" +--- + +## Overview + +Transform your e-commerce checkout with Request Network's payment infrastructure. Accept crypto payments with support for 80+ wallets, enable cross-chain transactions, and provide customers with a seamless payment experience that rivals traditional payment processors. + +## ๐Ÿš€ Quickstart: Integrate Your First Checkout Payment + + +**Integrate your first checkout payment in under 1 minute** + +*Interactive quickstart experience coming soon* + + + + + Embed the Request Network payment widget in your checkout + + + Set accepted payment currencies and conversion rates + + + Listen for payment confirmations and update order status + + + Automatically match payments to orders with zero manual work + + + +## EasyInvoice Demo + +Experience checkout payment flows through our demo: + + + + See the payment widget with wallet connection and direct payment forms + + + + Experience the complete customer payment journey + + + +**Demo Features:** +- 80+ wallet connection support (MetaMask, WalletConnect, Coinbase, etc.) +- Direct payment forms with QR codes +- Real-time payment status updates +- Cross-chain payment options +- Mobile-optimized payment experience + +## Integration Options + + + + **Best for:** Quick e-commerce integration, existing payment forms + + Embed payout functionality in existing e-commerce: + - Drop-in payment widget + - Hosted payment pages + - Minimal integration required + + [Get Embed Code โ†’](#) + + + + **Best for:** Custom checkout experience, brand matching + + Tailor checkout flow to match brand/UX requirements: + - Custom payment UI components + - Branded checkout experience + - Advanced payment flow customization + + [Fork Repository โ†’](#) | [Checkout Customization Guide โ†’](#) + + + + **Best for:** Complete control, enterprise integration + + Build checkout with full control over user experience: + - Custom payment logic and validation + - Advanced fraud prevention + - Deep e-commerce platform integration + + [Checkout API Documentation โ†’](/api-features/payment-types) + + + +## Key API Features for Checkout + + + + Drop-in payment component with 80+ wallet support + + + + Accept payments from any supported blockchain + + + + Collect marketplace or processing fees automatically + + + + Robust error handling for failed or partial payments + + + + Optimize payment paths for best rates and speed + + + + Instant payment confirmation and order updates + + + +## E-commerce Integration Patterns + + + + Integrate with existing e-commerce platforms: + - Shopify, WooCommerce, Magento plugins + - Payment gateway replacement + - Inventory management integration + - Order fulfillment automation + + + + Perfect for digital product sales: + - Instant payment confirmation + - Automated delivery for digital products + - Subscription and recurring billing + - Global payment acceptance without banking restrictions + + + + Enable multi-vendor marketplaces: + - Automatic vendor payout splitting + - Marketplace fee collection + - Escrow and dispute resolution + - Multi-party payment flows + + + + Handle high-volume event sales: + - Instant ticket delivery + - Anti-fraud protection + - High-throughput payment processing + - Global accessibility without regional payment restrictions + + + +## Customer Experience Benefits + + + + **80+ Supported Wallets:** + - MetaMask, WalletConnect, Coinbase Wallet + - Hardware wallets (Ledger, Trezor) + - Mobile wallets (Trust Wallet, Rainbow) + - Exchange wallets and DeFi wallets + + + + **Multiple Payment Options:** + - Direct wallet payments + - QR code scanning for mobile + - Cross-chain payment routing + - Multiple currency options + + + + **Enhanced Security:** + - No stored payment credentials + - Transparent blockchain transactions + - Real-time payment verification + - Immutable payment records + + + +## Technical Implementation + + +```javascript React Component +import { PaymentWidget } from '@requestnetwork/payment-widget'; + +function CheckoutPage({ orderTotal, orderId }) { + return ( + { + // Handle successful payment + updateOrderStatus(orderId, 'paid'); + }} + onPaymentError={(error) => { + // Handle payment errors + console.error('Payment failed:', error); + }} + /> + ); +} +``` + +```javascript Webhook Handler +app.post('/webhook/payment', (req, res) => { + const { eventType, request } = req.body; + + if (eventType === 'payment_confirmed') { + // Update order status + updateOrder(request.orderId, { + status: 'paid', + paymentHash: request.paymentHash, + paidAt: new Date() + }); + } + + res.status(200).send('OK'); +}); +``` + + +## What's Next? + + + + Enable recurring billing for subscription products + + + + Explore advanced payment options and routing + + + + Set up your account and start integrating + + diff --git a/use-cases/invoicing.mdx b/use-cases/invoicing.mdx new file mode 100644 index 0000000..f517ed7 --- /dev/null +++ b/use-cases/invoicing.mdx @@ -0,0 +1,180 @@ +--- +title: "๐Ÿ“„ Invoicing" +description: "Create professional invoices and get paid in crypto with 100% payment reconciliation" +--- + +## Overview + +Transform your invoicing workflow with Request Network. Create professional invoices, accept payments in 553+ currencies across 10 EVM chains, and maintain perfect payment records with zero reconciliation errors. + +## ๐Ÿš€ Quickstart: Create Your First Invoice + + +**Get your first invoice paid in under 1 minute** + +*Interactive quickstart experience coming soon* + + + + + Generate a payment request with amount, recipient, and payment terms + + + Send the secure payment link to your customer + + + Customer pays with their preferred wallet and currency + + + Real-time payment detection and automatic reconciliation + + + +## EasyInvoice Demo + +See the complete invoicing workflow in action with our demo application: + + + + Complete invoicing workflow with Google login, dashboard metrics, and real-time updates + + + + Experience the full EasyInvoice application + + + +**Demo Features:** +- Google authentication and user management +- Professional invoice creation with custom branding +- Real-time payment tracking and notifications +- Dashboard with payment analytics and metrics +- Multi-currency support (USD invoicing, crypto settlement) + +## Integration Options + +Choose the approach that best fits your needs: + + + + **Best for:** Quick deployment, immediate invoicing capabilities + + Deploy EasyInvoice directly for your business: + - Ready-to-use invoicing interface + - No development required + - Hosted solution with custom domain support + + [Deploy EasyInvoice โ†’](#) + + + + **Best for:** Custom branding, workflow modifications + + Customize EasyInvoice for your specific needs: + - Clone the repository + - Modify UI/UX to match your brand + - Add custom business logic + - Requires API key setup + + [Fork Repository โ†’](#) | [Setup Guide โ†’](#) + + + + **Best for:** White-label solutions, full control + + Build your own invoicing system using Request Network API: + - Complete customization freedom + - Integrate with existing systems + - Pure API integration + + [API Documentation โ†’](/api-features/payment-types) + + + +## Key API Features for Invoicing + + + + Generate payment requests with flexible parameters and metadata + + + + Invoice in USD, get paid in crypto with automatic conversion + + + + Set up subscription billing and automated recurring invoices + + + + Real-time payment notifications for instant reconciliation + + + + Accept installment payments and partial settlements + + + + Add invoice numbers, tax info, and business data + + + +## What's Next? + + + + Set up your account and get API credentials + + + + Learn about payment types and advanced capabilities + + + + Review supported chains and currencies + + diff --git a/use-cases/payouts.mdx b/use-cases/payouts.mdx new file mode 100644 index 0000000..540fa8a --- /dev/null +++ b/use-cases/payouts.mdx @@ -0,0 +1,217 @@ +--- +title: "๐Ÿ’ฐ Payouts" +description: "Send instant crypto payouts to vendors, contractors, and partners with full transparency" +--- + +## Overview + +Streamline your payment operations with Request Network payouts. Send instant payments to multiple recipients, maintain complete payment records, and eliminate the complexity of manual crypto transfers. + +## ๐Ÿš€ Quickstart: Send Your First Payout + + +**Send your first payout in under 1 minute** + +*Interactive quickstart experience coming soon* + + + + + Add payee addresses and payment amounts + + + Select from 553+ supported currencies + + + Send payments instantly with one transaction + + + Monitor payment status and maintain records + + + +## EasyInvoice Demo + +Experience payout functionality through our demo application: + + + + See individual payout processing and tracking + + + + Watch batch payment processing for multiple recipients + + + + + Experience both single and batch payout functionality + + +**Demo Features:** +- Single and batch payout interfaces +- Multi-currency payment support +- Real-time transaction tracking +- Payment history and analytics +- Cross-chain payment capabilities + +## Integration Options + + + + **Best for:** Immediate payout capabilities, simple payment operations + + Use the existing payout dashboard: + - Ready-to-use payout interface + - Single and batch payment support + - Built-in payment tracking + + [Access Payout Dashboard โ†’](#) + + + + **Best for:** Custom payout workflows, business integration + + Integrate payout flows into existing business workflows: + - Customize payout forms and approval processes + - Add business logic and validation rules + - Integrate with existing vendor management systems + + [Fork Repository โ†’](#) | [Payout Setup Guide โ†’](#) + + + + **Best for:** Automated payouts, full programmatic control + + Build automated payout systems: + - API-driven payout automation + - Integration with payroll and vendor systems + - Custom approval workflows and compliance + + [Payout API Documentation โ†’](/api-features/payment-types) + + + +## Key API Features for Payouts + + + + Send instant payments without creating requests first + + + + Process multiple payments in a single transaction + + + + Automate regular payments to vendors and contractors + + + + Collect platform fees automatically from each payout + + + + Send payments across different blockchain networks + + + + Optimize payment paths for lowest fees and fastest settlement + + + +## Common Payout Use Cases + + + + Pay suppliers and service providers instantly: + - Net payment terms elimination + - Real-time payment confirmation + - Automated vendor onboarding + + + + Streamline freelancer and contractor payments: + - Project-based milestone payments + - Recurring retainer payments + - Multi-currency global payments + + + + Automate affiliate and partner payouts: + - Performance-based commission payments + - Tiered commission structures + - Real-time payout tracking + + + + Distribute profits to stakeholders: + - Automated profit distribution + - Multi-stakeholder payments + - Transparent payment records + + + +## What's Next? + + + + Scale up to batch payroll processing + + + + Learn about efficient batch payment processing + + + + Set up your account for payout operations + + diff --git a/use-cases/payroll.mdx b/use-cases/payroll.mdx new file mode 100644 index 0000000..5f20cd8 --- /dev/null +++ b/use-cases/payroll.mdx @@ -0,0 +1,241 @@ +--- +title: "๐Ÿ’ผ Payroll" +description: "Process batch payroll payments with automated recurring schedules and full compliance tracking" +--- + +## Overview + +Revolutionize payroll processing with Request Network's batch payment capabilities. Process multiple employee payments simultaneously, automate recurring payroll schedules, and maintain comprehensive payment records for compliance and reporting. + +## ๐Ÿš€ Quickstart: Process Your First Batch Payroll + + +**Process your first batch payroll in under 1 minute** + +*Interactive quickstart experience coming soon* + + + + + Import employee addresses and salary amounts + + + Set up weekly, bi-weekly, or monthly payment schedules + + + Process all payments in a single transaction + + + Download payment records for compliance and accounting + + + +## EasyInvoice Demo + +See batch payroll processing in action: + + + + Watch batch payout functionality handling multiple recipients and recurring schedules + + + + Experience batch payment processing interface + + + +**Demo Features:** +- Multi-recipient batch payment interface +- CSV upload for employee data +- Recurring payment schedule setup +- Real-time batch processing status +- Payment history and reporting dashboard + +## Integration Options + + + + **Best for:** Small teams, manual payroll management + + Use the existing batch payment interface: + - Manual batch payout management + - CSV upload for employee data + - Basic recurring payment setup + + [Access Payroll Dashboard โ†’](#) + + + + **Best for:** Integration with existing payroll systems + + Integrate with existing payroll systems: + - Connect to HR management systems + - Custom approval workflows + - Advanced compliance and reporting features + + [Fork Repository โ†’](#) | [Payroll Integration Guide โ†’](#) + + + + **Best for:** Enterprise payroll automation + + Build automated payroll with full API control: + - Automated payroll processing from HR systems + - Advanced compliance and audit trails + - Integration with accounting and tax systems + + [Payroll API Documentation โ†’](/api-features/payment-types) + + + +## Key API Features for Payroll + + + + Process hundreds of employee payments in a single transaction + + + + Automate weekly, bi-weekly, and monthly payroll schedules + + + + Pay employees across different blockchain networks + + + + Handle tax withholdings and benefit deductions automatically + + + + Maintain comprehensive audit trails for regulatory compliance + + + + Include employee IDs, pay periods, and tax information + + + +## Payroll Scenarios + + + + Replace traditional payroll processing: + - Instant salary payments (no waiting for bank transfers) + - Automatic tax withholding and reporting + - Real-time payment confirmation for employees + - Reduced payroll processing costs + + + + Pay international employees without banking complications: + - No international wire transfer fees + - Same-day payment regardless of location + - Multi-currency salary support + - Simplified tax compliance across jurisdictions + + + + Handle variable compensation structures: + - Commission-based payments + - Bonus distributions + - Profit-sharing allocations + - Merit-based salary adjustments + + + + Manage mixed workforce payments: + - Different payment schedules for contractors vs employees + - Project-based milestone payments + - Hourly vs fixed-rate compensation + - 1099 vs W-2 payment tracking + + + +## Compliance & Reporting + + + + **Automated Tax Handling:** + - Automatic withholding calculations + - Real-time tax payment to authorities + - Year-end tax document generation + - Multi-jurisdiction tax compliance + + + + **Complete Payment Records:** + - Immutable blockchain payment records + - Employee payment history tracking + - Compliance report generation + - Real-time audit access + + + + **Comprehensive Analytics:** + - Payroll cost analysis + - Payment timing optimization + - Employee payment trends + - Cross-chain fee optimization + + + +## What's Next? + + + + Begin with simple vendor payouts before scaling to payroll + + + + Learn about efficient batch payment implementation + + + + Get API keys and configure payroll processing + + diff --git a/use-cases/subscriptions.mdx b/use-cases/subscriptions.mdx new file mode 100644 index 0000000..1ec8e54 --- /dev/null +++ b/use-cases/subscriptions.mdx @@ -0,0 +1,334 @@ +--- +title: "๐Ÿ”„ Subscriptions" +description: "Automate recurring payments with flexible billing cycles and transparent subscription management" +--- + +## Overview + +Build robust subscription businesses with Request Network's recurring payment infrastructure. Automate billing cycles, handle subscription upgrades and downgrades, and provide customers with transparent subscription managementโ€”all while maintaining perfect payment records. + +## ๐Ÿš€ Quickstart: Set Up Your First Recurring Subscription + + +**Set up your first recurring subscription in under 1 minute** + +*Interactive quickstart experience coming soon* + + + + + Set billing amount, frequency, and subscription terms + + + Customer approves recurring payment authorization + + + Payments are automatically processed according to schedule + + + Handle upgrades, downgrades, and cancellations transparently + + + +## EasyInvoice Demo + +Experience subscription management through our demo application: + + + + Watch UI-driven recurring invoice setup and subscription management + + + + Experience the subscription dashboard and management interface + + + +**Demo Features:** +- Subscription plan creation and management +- Customer subscription dashboard +- Automated billing cycle processing +- Upgrade/downgrade workflow +- Subscription analytics and reporting +- Payment failure handling and retry logic + +## Integration Options + + + + **Best for:** Simple subscription management, basic billing needs + + Simple subscription management interface: + - Pre-built subscription dashboard + - Basic plan management + - Customer self-service portal + + [Access Subscription Dashboard โ†’](#) + + + + **Best for:** Custom subscription workflows, existing platform integration + + Integrate with existing subscription platforms: + - Custom billing logic and pricing models + - Integration with CRM and customer management + - Advanced subscription analytics and reporting + + [Fork Repository โ†’](#) | [Subscription Integration Guide โ†’](#) + + + + **Best for:** Complex subscription models, enterprise requirements + + API-driven recurring payment automation: + - Advanced subscription lifecycle management + - Custom pricing models and billing logic + - Integration with existing business systems + + [Subscription API Documentation โ†’](/api-features/payment-types) + + + +## Key API Features for Subscriptions + + + + Automate billing cycles with flexible scheduling options + + + + Generate subscription invoices automatically + + + + Real-time notifications for billing events and payment updates + + + + Handle pro-rated billing and partial period charges + + + + Automatically retry failed payments with configurable schedules + + + + Track subscription plans, customer IDs, and billing periods + + + +## Subscription Models + + + + Power software-as-a-service billing: + - Monthly/annual subscription billing + - Usage-based pricing models + - Seat-based licensing + - Free trial and freemium conversions + + + + Monetize content and media platforms: + - Premium content subscriptions + - Ad-free viewing tiers + - Creator revenue sharing + - Multi-tier membership models + + + + Handle gaming and entertainment subscriptions: + - Battle pass and season pass billing + - Premium game access + - In-game currency subscriptions + - Tournament and league fees + + + + Manage business service subscriptions: + - Professional service retainers + - API access and usage billing + - Consulting and support contracts + - Enterprise license management + + + +## Subscription Lifecycle Management + + + + **Flexible Pricing Models:** + - Fixed monthly/annual pricing + - Usage-based billing + - Tiered pricing structures + - Custom enterprise pricing + + + + **Seamless Experience:** + - Frictionless subscription signup + - Transparent billing notifications + - Easy upgrade/downgrade processes + - Self-service cancellation options + + + + **Operational Excellence:** + - Automated revenue recognition + - Churn analysis and prevention + - Customer lifetime value tracking + - Subscription health monitoring + + + +## Advanced Subscription Features + + +```javascript Subscription Creation +import { RequestNetwork } from '@requestnetwork/request-client.js'; + +async function createSubscription(customer, plan) { + const subscription = await requestNetwork.createRequest({ + requestInfo: { + currency: plan.currency, + expectedAmount: plan.amount, + payee: { + type: 'ethereumAddress', + value: merchantAddress + }, + payer: { + type: 'ethereumAddress', + value: customer.address + } + }, + contentData: { + reason: `${plan.name} Subscription`, + dueDate: plan.nextBillingDate, + recurring: { + frequency: plan.billingCycle, // 'monthly', 'yearly' + occurrences: plan.maxOccurrences + } + } + }); + + return subscription; +} +``` + +```javascript Webhook Handling +app.post('/webhook/subscription', (req, res) => { + const { eventType, request } = req.body; + + switch(eventType) { + case 'recurring_payment_success': + // Extend subscription period + extendSubscription(request.customerId); + break; + + case 'recurring_payment_failed': + // Handle failed payment + handleFailedPayment(request.customerId); + break; + + case 'subscription_cancelled': + // Process cancellation + cancelSubscription(request.customerId); + break; + } + + res.status(200).send('OK'); +}); +``` + + +## Analytics & Insights + + + + Track MRR, ARR, churn rate, and customer lifetime value + + + + Monitor payment success rates and failure patterns + + + + Analyze subscription behavior and engagement patterns + + + + Identify churn risks and retention opportunities + + + +## What's Next? + + + + Begin with one-time invoices before adding subscriptions + + + + Learn about recurring payment implementation details + + + + Get API keys and configure subscription processing + +