Skip to content

Commit decc77c

Browse files
MantisCloneMantisClone
authored
docs: clean up Payment Detection use case page (#32)
1 parent df371b8 commit decc77c

1 file changed

Lines changed: 87 additions & 222 deletions

File tree

‎use-cases/payment-detection.mdx‎

Lines changed: 87 additions & 222 deletions
Original file line numberDiff line numberDiff line change
@@ -4,280 +4,145 @@ icon: "credit-card"
44
description: "Automatically detect and verify crypto payments with real-time blockchain monitoring and webhooks"
55
---
66

7-
<Warning>
8-
**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).
9-
</Warning>
10-
117
## Overview
128

13-
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.
9+
Traditional crypto payments lack business context. You receive a <Tooltip tip="Unique identifier of a transaction recorded on the blockchain">transaction hash,</Tooltip> but don't know which customer, invoice, or order it's for. Manual reconciliation is error-prone and doesn't scale.
10+
11+
Request IDs solve this by attaching business context to every payment. Each request gets a unique Request ID that connects payments back to your specific invoice, order, or subscription with cryptographic certainty.
12+
13+
**What you get:**
14+
- **Automatic attribution** - Every payment linked to its request via Request ID
15+
- **Multi-chain monitoring** - Track payments across 9 EVM chains in 150+ currencies
16+
- **Real-time notifications** - <Tooltip tip="HTTP callbacks that notify your server when payment events occur">Webhooks</Tooltip> for instant payment confirmations
17+
- **Zero manual work** - No spreadsheets, no guessing, no payment collisions
18+
19+
[See how Request IDs prevent payment collisions (welcome page demo) →](/use-cases/welcome)
1420

1521
## When to Use Payment Detection
1622

1723
<CardGroup cols={2}>
18-
<Card title="Existing Business Logic" icon="building">
19-
You already have invoicing, billing, or business systems and just need crypto payment acceptance
24+
<Card title="Payment Collisions" icon="triangle-exclamation">
25+
Multiple payments of the same amount create attribution problems - you can't tell which customer paid
2026
</Card>
2127

22-
<Card title="Single Wallet, Many Payments" icon="wallet">
23-
Collect payments at scale to one wallet address and automatically attribute each payment
28+
<Card title="High Payment Volume" icon="chart-line">
29+
Processing hundreds or thousands of crypto payments where manual tracking doesn't scale
2430
</Card>
2531

26-
<Card title="Real-time Verification" icon="clock">
27-
Need instant payment confirmation without manual blockchain checking
32+
<Card title="Wallet Management Overhead" icon="key">
33+
Managing separate wallets for each customer or transaction creates operational complexity
2834
</Card>
2935

30-
<Card title="Multi-chain Support" icon="link">
31-
Accept payments across Ethereum, Polygon, BSC, and 10+ EVM chains
36+
<Card title="Cross-chain Payments" icon="link">
37+
Accepting payments across multiple blockchains and need unified detection without managing multiple APIs
3238
</Card>
3339
</CardGroup>
3440

3541
## Common Scenarios
3642

37-
### Donations with Attribution
38-
Accept crypto donations to a single wallet and automatically attribute each to the correct donor, campaign, or cause.
39-
40-
**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.
41-
42-
### SaaS Adding Crypto Payments
43-
Existing subscription or billing platform adds crypto as a payment option alongside credit cards.
43+
### E-commerce Checkout
44+
Accept crypto payments at scale without generating unique addresses for each customer.
4445

45-
**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.
46+
**Example:** An e-commerce platform processes 10,000+ crypto orders per day. Each order gets a unique Request ID - customers pay to a single wallet address, and every payment is automatically attributed to the correct order.
4647

47-
### Manual Invoices + Crypto Detection
48-
Send invoices through existing channels (email, PDF) and let customers pay in crypto with automatic detection.
48+
### SaaS Subscriptions
49+
Add crypto as a payment option for recurring billing alongside traditional payment methods.
4950

50-
**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.
51+
**Example:** A SaaS company uses Stripe for card payments but offers USDC for monthly subscriptions. Payment Detection automatically confirms renewals and updates subscription status without manual tracking.
5152

52-
### High-Volume Payment Collection
53-
Collect thousands of payments without creating new wallet addresses for each transaction.
53+
### Manual Invoices with Crypto Settlement
54+
Send invoices through existing channels (email, PDF) and accept crypto payments with automatic reconciliation.
5455

55-
**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.
56+
**Example:** A freelancer emails invoices as PDFs with a Request ID. When clients pay in crypto, the accounting software automatically marks invoices as paid via <Tooltip tip="HTTP callbacks that notify your server when payment events occur">webhook</Tooltip> - no manual checking required.
5657

57-
---
58+
<Info>
59+
These scenarios all use automatic payment detection. [See technical details on detection methods and configuration →](/api-features/payment-detection)
60+
</Info>
5861

5962
## How Payment Detection Works
6063

6164
<Steps>
62-
<Step title="Payment Initiated">
63-
Customer sends crypto payment including the Request ID in the transaction reference
64-
</Step>
65-
66-
<Step title="Blockchain Monitoring">
67-
Request Network continuously scans supported blockchains for transactions matching your requests
65+
<Step title="Create Request">
66+
When you create a request, it gets a unique Request ID for tracking
6867
</Step>
6968

70-
<Step title="Payment Detected">
71-
When a matching payment is found, Request Network verifies amount, currency, and confirmations
69+
<Step title="Customer Pays">
70+
Customer sends payment to your wallet address - the Request ID is connected to the transaction
7271
</Step>
7372

74-
<Step title="Webhook Notification">
75-
Your system receives a real-time webhook with payment details and status
73+
<Step title="Automatic Detection">
74+
Request Network monitors <Tooltip tip="Decentralized networks where cryptocurrency transactions are recorded">blockchains</Tooltip> and matches payments to your requests
7675
</Step>
7776

78-
<Step title="Automatic Reconciliation">
79-
Your business logic updates invoice status, triggers fulfillment, or sends receipts
77+
<Step title="Get Notified">
78+
When a payment is detected, you receive a <Tooltip tip="HTTP callback that notifies your server when payment events occur">webhook</Tooltip> notification with payment details
8079
</Step>
8180
</Steps>
8281

83-
---
84-
85-
## Detection Features
86-
87-
### Real-time Blockchain Scanning
88-
- **Multi-chain monitoring:** Ethereum, Polygon, Arbitrum, Optimism, BSC, Gnosis, Fantom, Avalanche, and more
89-
- **Sub-minute detection:** Typically detect payments within seconds of blockchain confirmation
90-
- **Confirmation tracking:** Configurable confirmation thresholds for different security requirements
82+
<Info>
83+
Payment Detection powers all Request Network use cases: [invoicing](/use-cases/invoicing), [payouts](/use-cases/payouts), [payroll](/use-cases/payroll), [checkout](/use-cases/checkout), and [subscriptions](/use-cases/subscriptions). [See technical details on detection methods, confirmation thresholds, and implementation →](/api-features/payment-detection)
84+
</Info>
9185

92-
### Payment Verification
93-
- **Amount matching:** Verify exact payment amount or accept partial payments
94-
- **Currency validation:** Support for 553+ tokens across all supported chains
95-
- **Smart contract verification:** Detect payments through ERC20, native tokens, and conversion proxies
96-
97-
### Webhook Integration
98-
- **Event notifications:** `payment.detected`, `payment.confirmed`, `payment.failed`
99-
- **Retry logic:** Automatic webhook retries with exponential backoff
100-
- **Signature verification:** Cryptographically signed webhooks for security
101-
102-
---
103-
104-
## API Integration
86+
## Key API Features for Payment Detection
10587

10688
<CardGroup cols={2}>
107-
<Card title="Webhooks" href="/api-features/webhooks-events" icon="webhook">
108-
Real-time payment notifications sent to your server
89+
<Card
90+
title="Payment Detection"
91+
href="/api-features/payment-detection"
92+
icon="radar"
93+
>
94+
Monitor <Tooltip tip="Decentralized networks where cryptocurrency transactions are recorded">blockchain</Tooltip> transactions and match payments to requests automatically
10995
</Card>
11096

111-
<Card title="Query Payments" href="/api-features/query-payments" icon="magnifying-glass">
112-
Poll for payment status on demand
97+
<Card
98+
title="Webhooks"
99+
href="/api-features/webhooks-events"
100+
icon="webhook"
101+
>
102+
Real-time notifications when payments are detected, confirmed, or failed
113103
</Card>
114104

115-
<Card title="Payment Detection API" href="/api-features/payment-detection" icon="code">
116-
Technical details on detection methods and configuration
105+
<Card
106+
title="Query Requests"
107+
href="/api-features/query-requests"
108+
icon="magnifying-glass"
109+
>
110+
Check request status and payment history on demand
117111
</Card>
118112

119-
<Card title="Request Status" href="/api-features/query-requests" icon="circle-check">
120-
Check request status including payment state
113+
<Card
114+
title="Query Payments"
115+
href="/api-features/query-payments"
116+
icon="circle-check"
117+
>
118+
Retrieve detailed payment information including confirmations and amounts
121119
</Card>
122120
</CardGroup>
123121

124-
---
125-
126-
## Detection-Only vs Full Workflows
127-
128-
Understanding when to use standalone payment detection versus integrated workflows:
129-
130-
<Tabs>
131-
<Tab title="Payment Detection Only">
132-
**Best for:** Existing systems that just need crypto payment acceptance
133-
134-
**What you handle:**
135-
- Create invoices/requests in your existing system
136-
- Generate Request IDs via API
137-
- Include Request ID in payment instructions
138-
- Receive webhooks when payments are detected
139-
- Update your system based on payment status
140-
141-
**What Request Network handles:**
142-
- Blockchain monitoring across all chains
143-
- Payment verification and confirmation tracking
144-
- Webhook delivery with retry logic
145-
- Permanent on-chain payment records
146-
147-
**Example:** QuickBooks + crypto payments via Request Network detection
148-
</Tab>
149-
150-
<Tab title="Full Invoicing Workflow">
151-
**Best for:** Building new invoicing systems from scratch
152-
153-
**What Request Network handles:**
154-
- Invoice creation with structured data
155-
- Payment link generation
156-
- Payment processing
157-
- Payment detection
158-
- Complete payment lifecycle management
159-
160-
**What you handle:**
161-
- User interface and experience
162-
- Customer management
163-
- Business logic and workflows
164-
165-
**Example:** [EasyInvoice](/use-cases/invoicing) - full-stack invoicing application
166-
167-
[Learn more →](/use-cases/invoicing)
168-
</Tab>
169-
170-
<Tab title="Other Use Cases">
171-
**Payment detection powers all Request Network use cases:**
172-
173-
- **[Payouts](/use-cases/payouts):** Detection confirms batch payment completion
174-
- **[Payroll](/use-cases/payroll):** Detection verifies salary payments
175-
- **[Checkout](/use-cases/checkout):** Detection triggers order fulfillment
176-
- **[Subscriptions](/use-cases/subscriptions):** Detection handles recurring payments
177-
178-
Each use case combines request creation with payment detection for specific workflows.
179-
</Tab>
180-
</Tabs>
181-
182-
---
183-
184-
## Implementation Example
185-
186-
Here's a minimal example of using payment detection with webhooks:
187-
188-
<CodeGroup>
189-
```javascript Node.js - Create Request
190-
const response = await fetch('https://api.request.network/requests', {
191-
method: 'POST',
192-
headers: {
193-
'Authorization': `Bearer ${API_KEY}`,
194-
'Content-Type': 'application/json'
195-
},
196-
body: JSON.stringify({
197-
currency: 'USDC-matic',
198-
expectedAmount: '100.00',
199-
paymentAddress: '0x...your-wallet',
200-
reason: 'Invoice #12345'
201-
})
202-
});
203-
204-
const { requestId } = await response.json();
205-
// Include requestId in payment instructions to customer
206-
```
207-
208-
```javascript Node.js - Webhook Handler
209-
app.post('/webhooks/request', (req, res) => {
210-
const { eventType, requestId, paymentAmount, status } = req.body;
211-
212-
if (eventType === 'payment.detected') {
213-
// Payment detected on blockchain
214-
console.log(`Payment detected for ${requestId}: ${paymentAmount}`);
215-
216-
// Update your system
217-
await updateInvoiceStatus(requestId, 'PAID');
218-
await sendReceiptEmail(requestId);
219-
}
220-
221-
res.status(200).send('OK');
222-
});
223-
```
224-
225-
```python Python - Webhook Handler
226-
from flask import Flask, request
227-
228-
@app.route('/webhooks/request', methods=['POST'])
229-
def handle_webhook():
230-
data = request.json
231-
232-
if data['eventType'] == 'payment.detected':
233-
request_id = data['requestId']
234-
payment_amount = data['paymentAmount']
235-
236-
# Update your system
237-
update_invoice_status(request_id, 'PAID')
238-
send_receipt_email(request_id)
239-
240-
return '', 200
241-
```
242-
</CodeGroup>
243-
244-
---
122+
## What's Next?
245123

246-
## Supported Networks & Currencies
247-
248-
### Mainnet Networks
249-
- **Ethereum:** ETH, USDC, USDT, DAI, and 200+ ERC20 tokens
250-
- **Polygon:** MATIC, USDC, USDT, DAI, and 150+ tokens
251-
- **Arbitrum, Optimism, BSC, Gnosis, Fantom, Avalanche:** Full ERC20 support
252-
253-
### Detection Speed
254-
- **Ethereum:** ~15 seconds per confirmation
255-
- **Polygon:** ~2 seconds per confirmation
256-
- **Layer 2s:** Sub-second to ~2 seconds
257-
258-
### Testnet Support
259-
Available on Sepolia, Mumbai, and other testnets for development
260-
261-
[View all supported chains and currencies →](/resources/supported-chains-and-currencies)
262-
263-
---
264-
265-
## Next Steps
266-
267-
<CardGroup cols={2}>
268-
<Card title="Get API Keys" href="/api-setup/getting-started" icon="key">
269-
Set up authentication and create your first request
270-
</Card>
271-
272-
<Card title="Configure Webhooks" href="/api-reference/webhooks" icon="webhook">
273-
Set up real-time payment notifications
124+
<CardGroup cols={3}>
125+
<Card
126+
title="Get API Keys"
127+
href="/api-setup/getting-started"
128+
icon="key"
129+
>
130+
Set up your account and get API credentials
274131
</Card>
275132

276-
<Card title="Query API" href="/api-features/query-payments" icon="code">
277-
Learn how to check payment status programmatically
133+
<Card
134+
title="Payment Detection Details"
135+
href="/api-features/payment-detection"
136+
icon="code"
137+
>
138+
Technical deep dive on detection methods and configuration
278139
</Card>
279140

280-
<Card title="View Portal" href="https://portal.request.network" icon="external-link">
281-
Manage API keys and monitor requests in real-time
141+
<Card
142+
title="Supported Chains & Currencies"
143+
href="/resources/supported-chains-and-currencies"
144+
icon="globe"
145+
>
146+
See which networks and tokens you can use
282147
</Card>
283148
</CardGroup>

0 commit comments

Comments
 (0)