Skip to content

payment-detection.mdx

Latest commit

 

History

History
283 lines (207 loc) · 9.54 KB

payment-detection.mdx

File metadata and controls

283 lines (207 loc) · 9.54 KB
title Payment Detection
icon credit-card
description Automatically detect and verify crypto payments with real-time blockchain monitoring and webhooks
**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions).

Overview

Payment Detection monitors blockchain networks to automatically identify and verify when payments are completed. Add crypto payment acceptance to your existing systems without rebuilding your entire infrastructure.

When to Use Payment Detection

You already have invoicing, billing, or business systems and just need crypto payment acceptance Collect payments at scale to one wallet address and automatically attribute each payment Need instant payment confirmation without manual blockchain checking Accept payments across Ethereum, Polygon, BSC, and 10+ EVM chains

Common Scenarios

Donations with Attribution

Accept crypto donations to a single wallet and automatically attribute each to the correct donor, campaign, or cause.

Example: A nonprofit collects donations from hundreds of donors to one Ethereum address. Each donation includes a Request ID, enabling automatic attribution and thank-you emails.

SaaS Adding Crypto Payments

Existing subscription or billing platform adds crypto as a payment option alongside credit cards.

Example: A SaaS company uses Stripe for card payments but wants to offer USDC payments. Payment Detection monitors for crypto payments and updates subscription status automatically.

Manual Invoices + Crypto Detection

Send invoices through existing channels (email, PDF) and let customers pay in crypto with automatic detection.

Example: A freelancer emails invoices as PDFs with a Request ID. Clients pay in crypto, and the freelancer's accounting software automatically marks invoices as paid via webhook.

High-Volume Payment Collection

Collect thousands of payments without creating new wallet addresses for each transaction.

Example: An e-commerce platform processes 10,000+ crypto orders per day. Instead of generating unique addresses, each order gets a Request ID for attribution.

How Payment Detection Works

Customer sends crypto payment including the Request ID in the transaction reference Request Network continuously scans supported blockchains for transactions matching your requests When a matching payment is found, Request Network verifies amount, currency, and confirmations Your system receives a real-time webhook with payment details and status Your business logic updates invoice status, triggers fulfillment, or sends receipts

Detection Features

Real-time Blockchain Scanning

  • Multi-chain monitoring: Ethereum, Polygon, Arbitrum, Optimism, BSC, Gnosis, Fantom, Avalanche, and more
  • Sub-minute detection: Typically detect payments within seconds of blockchain confirmation
  • Confirmation tracking: Configurable confirmation thresholds for different security requirements

Payment Verification

  • Amount matching: Verify exact payment amount or accept partial payments
  • Currency validation: Support for 553+ tokens across all supported chains
  • Smart contract verification: Detect payments through ERC20, native tokens, and conversion proxies

Webhook Integration

  • Event notifications: payment.detected, payment.confirmed, payment.failed
  • Retry logic: Automatic webhook retries with exponential backoff
  • Signature verification: Cryptographically signed webhooks for security

API Integration

Real-time payment notifications sent to your server Poll for payment status on demand Technical details on detection methods and configuration Check request status including payment state

Detection-Only vs Full Workflows

Understanding when to use standalone payment detection versus integrated workflows:

**Best for:** Existing systems that just need crypto payment acceptance 
**What you handle:**
- Create invoices/requests in your existing system
- Generate Request IDs via API
- Include Request ID in payment instructions
- Receive webhooks when payments are detected
- Update your system based on payment status

**What Request Network handles:**
- Blockchain monitoring across all chains
- Payment verification and confirmation tracking
- Webhook delivery with retry logic
- Permanent on-chain payment records

**Example:** QuickBooks + crypto payments via Request Network detection
**Best for:** Building new invoicing systems from scratch 
**What Request Network handles:**
- Invoice creation with structured data
- Payment link generation
- Payment processing
- Payment detection
- Complete payment lifecycle management

**What you handle:**
- User interface and experience
- Customer management
- Business logic and workflows

**Example:** [EasyInvoice](/use-cases/invoicing) - full-stack invoicing application

[Learn more →](/use-cases/invoicing)
**Payment detection powers all Request Network use cases:** 
- **[Payouts](/use-cases/payouts):** Detection confirms batch payment completion
- **[Payroll](/use-cases/payroll):** Detection verifies salary payments
- **[Checkout](/use-cases/checkout):** Detection triggers order fulfillment
- **[Subscriptions](/use-cases/subscriptions):** Detection handles recurring payments

Each use case combines request creation with payment detection for specific workflows.

Implementation Example

Here's a minimal example of using payment detection with webhooks:

```javascript Node.js - Create Request const response = await fetch('https://api.request.network/requests', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ currency: 'USDC-matic', expectedAmount: '100.00', paymentAddress: '0x...your-wallet', reason: 'Invoice #12345' }) });

const { requestId } = await response.json(); // Include requestId in payment instructions to customer


```javascript Node.js - Webhook Handler
app.post('/webhooks/request', (req, res) => {
  const { eventType, requestId, paymentAmount, status } = req.body;
  
  if (eventType === 'payment.detected') {
    // Payment detected on blockchain
    console.log(`Payment detected for ${requestId}: ${paymentAmount}`);
    
    // Update your system
    await updateInvoiceStatus(requestId, 'PAID');
    await sendReceiptEmail(requestId);
  }
  
  res.status(200).send('OK');
});

from flask import Flask, request

@app.route('/webhooks/request', methods=['POST'])
def handle_webhook():
    data = request.json
    
    if data['eventType'] == 'payment.detected':
        request_id = data['requestId']
        payment_amount = data['paymentAmount']
        
        # Update your system
        update_invoice_status(request_id, 'PAID')
        send_receipt_email(request_id)
    
    return '', 200

Supported Networks & Currencies

Mainnet Networks

  • Ethereum: ETH, USDC, USDT, DAI, and 200+ ERC20 tokens
  • Polygon: MATIC, USDC, USDT, DAI, and 150+ tokens
  • Arbitrum, Optimism, BSC, Gnosis, Fantom, Avalanche: Full ERC20 support

Detection Speed

  • Ethereum: ~15 seconds per confirmation
  • Polygon: ~2 seconds per confirmation
  • Layer 2s: Sub-second to ~2 seconds

Testnet Support

Available on Sepolia, Mumbai, and other testnets for development

View all supported chains and currencies →

Next Steps

Set up authentication and create your first request Set up real-time payment notifications Learn how to check payment status programmatically Manage API keys and monitor requests in real-time