Skip to content

Commit 13a7a13

Browse files
MantisClonegitbook-bot
MantisClone
authored and
gitbook-bot
committed
GITBOOK-156: feat: add Request API Batch Payments
1 parent b53817d commit 13a7a13

File tree

2 files changed

+221
-0
lines changed

2 files changed

+221
-0
lines changed

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
* [Create and Pay Requests](request-network-api/create-and-pay-requests.md)
88
* [Crosschain Payments](request-network-api/crosschain-payments.md)
99
* [Crypto-to-fiat Payments](request-network-api/crypto-to-fiat-payments.md)
10+
* [Batch Payments](request-network-api/batch-payments.md)
1011
* [EasyInvoice: API Demo App](request-network-api/easyinvoice-api-demo-app.md)
1112
* [API Portal: Manage API Keys and Webhooks](request-network-api/api-portal-manage-api-keys-and-webhooks.md)
1213
* [Full API Reference](https://api.request.network/open-api)

‎docs/request-network-api/batch-payments.md

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
description: >-
3+
Process multiple payment requests or payouts efficiently in a single
4+
blockchain transaction
5+
---
6+
7+
# Batch Payments
8+
9+
{% hint style="info" %}
10+
**Talk to an expert**
11+
12+
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.
13+
{% endhint %}
14+
15+
## Overview
16+
17+
Batch payments enable you to process multiple payment requests efficiently in a single blockchain transaction, reducing gas costs and simplifying multi-recipient workflows.
18+
19+
**Two Types of Batch Payments:**
20+
21+
### **Batch Pay Invoices**
22+
23+
Process previously created requests using their request IDs and receive payment calldata that can be executed on-chain to pay multiple requests simultaneously.
24+
25+
### **Batch Payouts**
26+
27+
Submit new payment requests that are immediately processed, creating requests and returning payment calldata in a single API call for instant multi-recipient payments.
28+
29+
## Key Benefits
30+
31+
* **Gas Efficiency**: Significantly reduce transaction costs by batching multiple payments
32+
* **Simplified UX**: Process up to 200 payments in a single transaction
33+
* **Mixed Payment Types**: Support ERC20, native tokens, and conversion payments in the same batch
34+
* **Atomic Execution**: All payments succeed or fail together, ensuring consistency
35+
36+
{% hint style="warning" %}
37+
**Single Network Limitation**: All requests in a batch must be on the same blockchain network. Need multi-network batch payments? [Book a call](https://calendly.com/mariana-rn/request-network-demo-docs) to discuss this feature.
38+
{% endhint %}
39+
40+
## Batch Processing Limits
41+
42+
The theoretical limit for batch payments is **100-200 payments per transaction**, depending on:
43+
44+
* Payment complexity (ERC20 vs native tokens vs conversions)
45+
* Available block gas limit on the target network
46+
* Smart contract computational requirements
47+
48+
For optimal performance, we recommend starting with smaller batches (10-50 payments) and scaling based on your network conditions.
49+
50+
## Batch Payment Workflow
51+
52+
```mermaid
53+
---
54+
config:
55+
fontSize: 10
56+
sequence:
57+
wrap: true
58+
actorMargin: 90
59+
width: 100
60+
height: 30
61+
---
62+
sequenceDiagram
63+
participant Payer
64+
participant App
65+
participant Request Network API
66+
participant Blockchain
67+
68+
Payer->>App: Initiate Batch Payment
69+
App->>Request Network API: POST /v2/payouts/batch {requests or requestIds}
70+
Request Network API-->>App: 200 OK {batchPaymentTransaction, ERC20ApprovalTransactions}
71+
Request Network API-)Request Network API: Start listening for batch payments
72+
73+
opt if needs ERC20 approvals
74+
App->>Payer: Prompt for approval signatures
75+
Payer-->>App: Sign approval transactions
76+
App->>Blockchain: Submit approval transactions
77+
end
78+
79+
App->>Payer: Prompt for batch payment signature
80+
Payer-->>App: Sign batch payment transaction
81+
App->>Blockchain: Submit batch payment transaction
82+
83+
Request Network API->>Request Network API: Batch payments detected
84+
Request Network API->>App: POST <webhook url> {"payment.confirmed" events for each request}
85+
App-->>Payer: Batch Payment Complete
86+
```
87+
88+
## Endpoints
89+
90+
{% openapi-operation spec="request-api" path="/v2/payouts/batch" method="post" %}
91+
[Broken link](broken-reference)
92+
{% endopenapi-operation %}
93+
94+
## Implementation Examples
95+
96+
The following examples demonstrate how to implement batch payment calldata execution in your application. **Note**: The API returns unsigned transaction calldata - your application must handle sending these transactions to the blockchain.
97+
98+
#### Batch Pay Invoices Example
99+
100+
```typescript
101+
import { ethers } from 'ethers';
102+
103+
// Get unsigned calldata to pay existing requests by their IDs
104+
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
105+
method: 'POST',
106+
headers: {
107+
'Content-Type': 'application/json',
108+
'x-api-key': 'your-api-key',
109+
'x-platform-id': 'your-platform-id'
110+
},
111+
body: JSON.stringify({
112+
requestIds: [
113+
"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
114+
"02f384fdd39e5c627e04b1f2e6fd60593783b8863c3c789197f5bd381527b8ecd"
115+
],
116+
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
117+
})
118+
});
119+
120+
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
121+
122+
// Your app must implement sending these transactions to the blockchain
123+
const provider = new ethers.providers.Web3Provider(window.ethereum);
124+
const signer = provider.getSigner();
125+
126+
// 1. Handle ERC20 approvals if needed
127+
for (const approval of ERC20ApprovalTransactions) {
128+
const tx = await signer.sendTransaction(approval);
129+
await tx.wait();
130+
}
131+
132+
// 2. Send the batch payment transaction
133+
const batchTx = await signer.sendTransaction(batchPaymentTransaction);
134+
await batchTx.wait();
135+
```
136+
137+
#### Batch Payouts Example
138+
139+
```typescript
140+
// Create new requests and process them immediately
141+
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
142+
method: 'POST',
143+
headers: {
144+
'Content-Type': 'application/json',
145+
'x-api-key': 'your-api-key',
146+
'x-platform-id': 'your-platform-id'
147+
},
148+
body: JSON.stringify({
149+
requests: [
150+
{
151+
payee: "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
152+
amount: "10",
153+
invoiceCurrency: "USD",
154+
paymentCurrency: "USDC-sepolia"
155+
},
156+
{
157+
payee: "0xb07D2398d2004378cad234DA0EF14f1c94A530e4",
158+
amount: "25.50",
159+
invoiceCurrency: "EUR",
160+
paymentCurrency: "DAI-sepolia"
161+
}
162+
],
163+
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
164+
})
165+
});
166+
167+
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
168+
169+
// Your app must implement the blockchain transaction execution
170+
// (same pattern as Batch Pay Invoices example above)
171+
```
172+
173+
## Supported Payment Types
174+
175+
Batch payments support mixing different payment types in a single transaction:
176+
177+
* **ERC20 Token Payments**: Standard token transfers
178+
* **Native Token Payments**: ETH, MATIC, etc.
179+
* [**Conversion Payments**](https://vscode-file/vscode-app/Applications/Visual%20Studio%20Code.app/Contents/Resources/app/out/vs/code/electron-sandbox/workbench/workbench.html): Requests denominated in one currency but paid in another (e.g., USD invoices paid with USDC)
180+
181+
## Key Implementation Notes
182+
183+
### Your Responsibility
184+
185+
* **API Call**: Your application calls the Request Network API to get transaction data
186+
* **Blockchain Execution**: Your application executes the returned transaction data on the blockchain
187+
* **Error Handling**: Your application handles transaction failures and retries
188+
189+
### Best Practices
190+
191+
1. **Validate Addresses**: Always validate recipient addresses before submitting batch payments
192+
2. **Test on Testnets**: Start with small batches on test networks before production deployment
193+
3. **Handle Failures Gracefully**: Implement proper error handling for transaction failures
194+
4. **Gas Estimation**: Consider gas costs when determining optimal batch sizes
195+
5. **User Experience**: Provide clear progress indicators for multi-step approval processes
196+
197+
### Error Handling
198+
199+
Common error scenarios and their solutions:
200+
201+
* **Network Mismatch**: Ensure all requests use the same blockchain network
202+
* **Insufficient Funds**: Verify payer has sufficient balance for all payments plus gas
203+
* **Invalid Addresses**: Validate all payee addresses before batch submission
204+
* **Gas Limit Exceeded**: Reduce batch size if hitting network gas limits
205+
206+
## Demo Application
207+
208+
See the batch payment feature in action in our EasyInvoice demo application:
209+
210+
### EasyInvoice Batch Pay Invoices
211+
212+
{% embed url="https://youtu.be/BsbENNP00AI" %}
213+
214+
### EasyInvoice: Batch Payouts
215+
216+
{% embed url="https://youtu.be/craVMSj8PRs" %}
217+
218+
For detailed information on all available endpoints and their parameters, please refer to the full [Request Network API Reference](https://vscode-file/vscode-app/Applications/Visual%20Studio%20Code.app/Contents/Resources/app/out/vs/code/electron-sandbox/workbench/workbench.html).
219+
220+
For more implementation details, explore the [EasyInvoice source code](https://github.com/RequestNetwork/easy-invoice).

0 commit comments

Comments
 (0)