Skip to content

payment-detection.mdx

Latest commit

 

History

History
138 lines (101 loc) · 4.13 KB

payment-detection.mdx

File metadata and controls

138 lines (101 loc) · 4.13 KB
title Payment Detection
description Automatic reference-based payment detection system for blockchain transactions

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 works across supported blockchains and handles payment matching automatically.

How It Works

graph TD
    A[Create Request] --> B[Payment Reference Generated]
    B --> C[Payer Sends Payment with Reference]
    C --> D[Subgraph Detects Transaction]
    D --> E[Validate Payment Details]
    E --> F[Update Request Status]
    F --> G[Trigger Webhook]
Loading

1. Payment Reference Generation

When you create a request, the API automatically generates a unique payment reference (16-character identifier). This reference is what links on-chain payment transactions to your 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.

Monitoring includes:

  • transaction scanning
  • 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
  • Validates payment details (amount, currency, recipient)
  • Updates request status (for example partially paid or fully paid)
  • Triggers your configured webhooks

4. Real-time Status Updates

Once a payment is detected, your request status is updated and you can retrieve the latest information via:

  • API Queries: GET /v2/request/{requestId}
  • Webhooks: receive updates on your configured endpoints

For the latest chain and currency support, see Supported Chains and Currencies.

Crosschain Payment Detection

All crosschain payments using Request Network API use the ERC-20 Fee Proxy contract as the last payment leg, so payment detection works out of the box.

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:

Full payment received and confirmed on blockchain Partial payment received (less than expected amount) Payment transaction failed or reverted Payment was refunded to the payer

This allows your application to react immediately to payment events without constantly polling the API.

Integration Benefits

Payment detection happens automatically Works across supported chains Fast detection and status updates Built on blockchain indexing infrastructure

What's Next?

Configure webhook notifications for payment events

<Card title="Query Payments" href="/api-features/query-payments" icon="magnifying-glass"

Manually check payment status via API

<Card title="Supported Chains" href="/resources/supported-chains-and-currencies" icon="globe"

View all supported networks and currencies