Skip to main content
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 or contact support.

​
Overview

The Request Network API uses a reference-based payment detection system that automatically monitors blockchain transactions to detect when payments are made to your requests. This system works across multiple blockchains and handles various payment scenarios with zero configuration required.

​
How It Works

​
1. Payment Reference Generation

When you create a payment request, the API automatically generates a unique 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. Example: 0x1234567890abcdef

​
2. Blockchain Monitoring

The API continuously monitors supported blockchains using subgraphs that scan for transactions containing payment references. This happens automatically in the background with no action required from you. Monitoring includes:
  • Real-time transaction scanning
  • Multi-network support
  • Payment reference matching
  • Amount and currency validation

​
3. Automatic Detection

When someone makes a payment and includes the payment reference in their transaction, the system:
  • Detects the transaction within minutes
  • Validates payment details (amount, currency, recipient)
  • Updates request status (pending → partially paid → fully paid)
  • Triggers your configured webhooks

​
4. Real-time Status Updates

Once a payment is detected, your request status is immediately updated and you can get the latest information via:
  • API Queries: GET requests to check payment status using the request ID
  • Webhooks: Automatically receive updates to your configured webhook endpoints

​
Supported Networks

Payment detection works across all Request Network supported chains:

​
Mainnet Networks

  • Ethereum, Polygon (Matic), Arbitrum One, Optimism, Base
  • Gnosis Chain, BSC, Fantom, Avalanche, Celo

​
Testnet Networks

  • Sepolia, Base Sepolia, Arbitrum Sepolia, Optimism Sepolia

​
Crosschain Payment Detection

All crosschain payments using the Request Network API use the ERC-20 Fee Proxy contract as the final payment leg, ensuring payment detection works seamlessly across chains. How it works:
  1. Payer initiates payment on source chain (e.g., Polygon)
  2. Crosschain bridge transfers funds to destination chain (e.g., Base)
  3. Final payment uses ERC-20 Fee Proxy with payment reference
  4. Payment detection system identifies the transaction
  5. Request status updated automatically

​
Webhook Notifications

Configure webhooks to receive real-time notifications for payment events:

Payment Confirmed

Full payment received and confirmed on blockchain

Payment Partial

Partial payment received (less than expected amount)

Payment Failed

Payment transaction failed or reverted

Payment Refunded

Payment was refunded to the payer
This allows your application to react immediately to payment events without constantly polling the API.

​
Integration Benefits

Zero Configuration

Payment detection happens automatically — no setup required

Multi-blockchain

Works across all 10+ supported EVM networks

Real-time Updates

Fast detection and status updates within minutes

Reliable Infrastructure

Built on proven blockchain indexing infrastructure

​
Payment States

Requests progress through the following payment states:
  • created - Request created, awaiting payment
  • pending - Payment transaction detected, awaiting confirmations
  • partially_paid - Partial payment received
  • paid - Full payment received and confirmed
  • overpaid - Payment exceeds expected amount
  • refunded - Payment was refunded

​
What’s Next?

Webhooks

Configure webhook notifications for payment events

Query Payments

Manually check payment status via API

Supported Chains

View all supported networks and currencies