Skip to content

docs(batch-payments): add comprehensive implementation guide with examples, workflow diagrams, and demo videos #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aimensahnoun wants to merge 1 commit into
base: 03-02-docs_api-features_align_crosschain-payments_page_with_legacy_docs_flow_update_api-features_crosschain-payments.mdx_to_follow_legacy_content_structure_and_sequencing_while_keeping_mintlify-compatible_formatting._-_replaced_mixed_
Choose a base branch
from
+196 −38
Open

docs(batch-payments): add comprehensive implementation guide with examples, workflow diagrams, and demo videos #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 196 additions & 38 deletions api-features/batch-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,58 +3,216 @@ title: "Batch Payments"
description: "Process multiple payments in a single transaction for gas optimization"
---

## Overview

Batch payments enable you to process multiple payment requests efficiently in a single blockchain transaction, reducing gas costs and simplifying multi-recipient workflows.

**Two Types of Batch Payments:**

### Batch Pay Invoices

Process previously created requests using their request IDs and receive payment calldata that can be executed on-chain to pay multiple requests simultaneously.

### Batch Payouts

Submit new payment requests that are immediately processed, creating requests and returning payment calldata in a single API call for instant multi-recipient payments.

## Key Benefits

- **Gas Efficiency**: Significantly reduce transaction costs by batching multiple payments
- **Simplified UX**: Process up to 200 payments in a single transaction
- **Mixed Payment Types**: Support ERC20, native tokens, and conversion payments in the same batch
- **Atomic Execution**: All payments succeed or fail together, ensuring consistency

<Warning>
**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).
**Single Network Limitation**: All requests in a batch must be on the same blockchain network.
</Warning>

## Overview
## Batch Processing Limits

The theoretical limit for batch payments is **100-200 payments per transaction**, depending on:

Batch payments allow you to process multiple direct or conversion payments in a single blockchain transaction, significantly reducing gas costs and simplifying payment operations.
- Payment complexity (ERC20 vs native tokens vs conversions)
- Available block gas limit on the target network
- Smart contract computational requirements

## How It Works
For optimal performance, we recommend starting with smaller batches (10-50 payments) and scaling based on your network conditions.

## Batch Payment Workflow

```mermaid
graph TD
A[Multiple Recipients] --> B[Single Transaction]
B --> C[Atomic Execution]
C --> D[All Succeed or All Fail]
sequenceDiagram
participant Payer
participant App
participant RequestAPI as Request Network API
participant Blockchain

Payer->>App: Initiate Batch Payment
App->>RequestAPI: POST /v2/payouts/batch {requests or requestIds}
RequestAPI-->>App: 200 OK {batchPaymentTransaction, ERC20ApprovalTransactions}
RequestAPI-)RequestAPI: Start listening for batch payments

opt if needs ERC20 approvals
App->>Payer: Prompt for approval signatures
Payer-->>App: Sign approval transactions
App->>Blockchain: Submit approval transactions
end

App->>Payer: Prompt for batch payment signature
Payer-->>App: Sign batch payment transaction
App->>Blockchain: Submit batch payment transaction

RequestAPI->>RequestAPI: Batch payments detected
RequestAPI->>App: POST <webhook url> {"payment.confirmed" events for each request}
App-->>Payer: Batch Payment Complete
```

## Endpoints

### Pay multiple requests in one transaction

Pays multiple payment requests in one transaction by either creating new requests or using existing request IDs. All requests must be on the same network. Supports mixed ERC20, native, and conversion requests.

Endpoint reference: [POST /v2/payouts/batch](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts/batch)

## Implementation Examples

The following examples demonstrate how to implement batch payment calldata execution in your application. The API returns unsigned transaction calldata, and your application sends those transactions on-chain.

#### Batch Pay Invoices Example

```typescript
import { ethers } from 'ethers';

// Get unsigned calldata to pay existing requests by their IDs
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requestIds: [
"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
"02f384fdd39e5c627e04b1f2e6fd60593783b8863c3c789197f5bd381527b8ecd"
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});

const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
Comment on lines +88 to +104
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add error handling for the API fetch call. The current example doesn't check if the response was successful before destructuring the JSON.

Suggested change
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requestIds: [
"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
"02f384fdd39e5c627e04b1f2e6fd60593783b8863c3c789197f5bd381527b8ecd"
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requestIds: [
"01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
"02f384fdd39e5c627e04b1f2e6fd60593783b8863c3c789197f5bd381527b8ecd"
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});
if (!batchPayResponse.ok) {
throw new Error(`API error: ${batchPayResponse.status}`);
}
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();


// Your app must implement sending these transactions to the blockchain
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

// 1. Handle ERC20 approvals if needed
for (const approval of ERC20ApprovalTransactions) {
const tx = await signer.sendTransaction(approval);
await tx.wait();
}

// 2. Send the batch payment transaction
const batchTx = await signer.sendTransaction(batchPaymentTransaction);
await batchTx.wait();
```

**Benefits:**
- **Gas Savings:** Up to 60% reduction in total gas costs
- **Atomic Operations:** All payments succeed or fail together
- **Simplified Management:** One transaction to monitor
#### Batch Payouts Example

```typescript
// Create new requests and process them immediately
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requests: [
{
payee: "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
amount: "10",
invoiceCurrency: "USD",
paymentCurrency: "USDC-sepolia"
},
{
payee: "0xb07D2398d2004378cad234DA0EF14f1c94A530e4",
amount: "25.50",
invoiceCurrency: "EUR",
paymentCurrency: "DAI-sepolia"
}
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});

const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
Comment on lines +125 to +151
Copy link

@greptile-apps greptile-apps bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add error handling for the API fetch call (same issue as Batch Pay Invoices example).

Suggested change
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requests: [
{
payee: "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
amount: "10",
invoiceCurrency: "USD",
paymentCurrency: "USDC-sepolia"
},
{
payee: "0xb07D2398d2004378cad234DA0EF14f1c94A530e4",
amount: "25.50",
invoiceCurrency: "EUR",
paymentCurrency: "DAI-sepolia"
}
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();
const batchPayResponse = await fetch('https://api.request.network/v2/payouts/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'your-api-key',
'x-platform-id': 'your-platform-id'
},
body: JSON.stringify({
requests: [
{
payee: "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
amount: "10",
invoiceCurrency: "USD",
paymentCurrency: "USDC-sepolia"
},
{
payee: "0xb07D2398d2004378cad234DA0EF14f1c94A530e4",
amount: "25.50",
invoiceCurrency: "EUR",
paymentCurrency: "DAI-sepolia"
}
],
payer: "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
})
});
if (!batchPayResponse.ok) {
throw new Error(`API error: ${batchPayResponse.status}`);
}
const { batchPaymentTransaction, ERC20ApprovalTransactions } = await batchPayResponse.json();


// Your app must implement the blockchain transaction execution
// (same pattern as Batch Pay Invoices example above)
```

## Supported Payment Types

Batch payments support mixing different payment types in a single transaction:

- **ERC20 Token Payments**: Standard token transfers
- **Native Token Payments**: ETH, MATIC, etc.
- [**Conversion Payments**](/api-features/conversion-payments): Requests denominated in one currency but paid in another (e.g., USD invoices paid with USDC)

## Key Implementation Notes

### Your Responsibility

- **API Call**: Your application calls the Request Network API to get transaction data
- **Blockchain Execution**: Your application executes the returned transaction data on the blockchain
- **Error Handling**: Your application handles transaction failures and retries

### Best Practices

1. **Validate Addresses**: Always validate recipient addresses before submitting batch payments
2. **Test on Testnets**: Start with small batches on test networks before production deployment
3. **Handle Failures Gracefully**: Implement proper error handling for transaction failures
4. **Gas Estimation**: Consider gas costs when determining optimal batch sizes
5. **User Experience**: Provide clear progress indicators for multi-step approval processes

### Error Handling

Common error scenarios and their solutions:

- **Network Mismatch**: Ensure all requests use the same blockchain network
- **Insufficient Funds**: Verify payer has sufficient balance for all payments plus gas
- **Invalid Addresses**: Validate all payee addresses before batch submission
- **Gas Limit Exceeded**: Reduce batch size if hitting network gas limits

## Requirements
## Demo Application

- All payments must be on the same network
- Supports Native, ERC20, and Conversion payments
- Maximum batch size limited by block gas limit
See the batch payment feature in action in our EasyInvoice demo application:

## Use Cases
### EasyInvoice Batch Pay Invoices

<CardGroup cols={2}>
<Card title="Payroll Processing" icon="users">
Pay multiple employees simultaneously
</Card>

<Card title="Vendor Payments" icon="building">
Process multiple supplier invoices
</Card>
</CardGroup>
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/BsbENNP00AI"
title="EasyInvoice Batch Pay Invoices"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>

## Used In
### EasyInvoice: Batch Payouts

<CardGroup cols={2}>
<Card title="Payroll" href="/use-cases/payroll">
Efficient employee payments
</Card>

<Card title="Payouts" href="/use-cases/payouts">
Bulk vendor payments
</Card>
</CardGroup>
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/craVMSj8PRs"
title="EasyInvoice Batch Payouts"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>

## Implementation Details
For detailed information on all available endpoints and their parameters, see the full [Request Network API Reference](https://api.request.network/open-api).

See [API Reference - Batch Payments](/api-reference/batch-payments) for complete technical documentation.
For implementation details, see the [EasyInvoice source code](https://github.com/RequestNetwork/easy-invoice).