Skip to main content

​
Overview

Request creation forms the foundation of Request Network operations, enabling structured payment collection through invoice generation and payment request workflows.

​
What You Can Do

At its core, the Request Network API empowers you to:
  • Create Requests: Define payment requests with information such as payee, payer (optional), amount, currency, and recurrence (optional).
  • Facilitate Payments: Return transaction calldata, ready to be signed by end-users and sent to the blockchain for secure and transparent value transfer.
  • Deliver Webhook Notifications: Receive instant updates on payment status changes, enabling your application to react dynamically to completed transactions.
  • Partial Payment Support: Pay a portion of a request instead of the full amount at once. This unlocks powerful use cases such as:
    • Split payment: Split a payment 50% USDC on Base and 50% with USDT on Optimism.
    • Gradual payment plans: Allow users to pay large invoices in smaller chunks.
    • Risk mitigation: Test with small amounts before completing large payments.
The API automatically tracks payment progress, showing partially_paid status until the request is fully paid, and prevents overpayment by capping amounts to the remaining balance.

​
Workflows

​
Invoice-first Workflow

Create a payment request first, then allow customers to pay at their convenience. Flow:
  1. Create request with payee, amount, and currency
  2. Share request ID or payment reference with customer
  3. Customer retrieves payment calldata
  4. Customer executes transaction
  5. Receive webhook confirmation
Use Cases: Professional invoicing, B2B payments, subscription billing

​
Payment-first Workflow

Send payments directly without creating a request first using the /payouts endpoint. Flow:
  1. Call /payouts with payee and amount
  2. Receive transaction calldata immediately
  3. Execute transaction
  4. Request is created and paid in one step
Use Cases: Vendor payments, contractor payouts, immediate transfers

​
How It Works

The following diagram illustrates the typical flow for creating and paying requests using the Request Network API:

​
Request Properties

​
Core Information

  • Payee: The wallet address of the payee (Ethereum 0x… or TRON T…). Required for all requests except crypto-to-fiat.
  • Payer: The wallet address of the payer (optional)
  • Amount: The payable amount of the invoice, in human readable format
  • Invoice Currency: Invoice Currency ID, from the Request Network Token List e.g: USD
  • Payment Currency: Payment currency ID, from the Request Network Token List e.g: ETH-sepolia-sepolia

​
Optional Configuration

  • Recurrence: For recurring payments, specify start date and frequency (DAILY, WEEKLY, MONTHLY, YEARLY)
  • Fee Settings: Specify fee percentage and fee address for platform fee collection

​
Supported Chains and Currencies

See Supported Chains and Currencies for the complete list of available networks and tokens.

​
Quick Example

Here’s a simple example of creating a request: 
const response = await fetch('https://api.request.network/v2/request', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.RN_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payee: '0x...',
    amount: '100',
    invoiceCurrency: 'USD',
    paymentCurrency: 'USDC-base-base'
  })
});

const { requestId, paymentReference } = await response.json();
Then get the payment calldata: 
const payResponse = await fetch(
  `https://api.request.network/v2/request/${paymentReference}/pay`,
  {
    headers: { 'X-Api-Key': process.env.RN_API_KEY }
  }
);

const { transactions, metadata } = await payResponse.json();
// Execute transactions with your wallet...
For a complete working example, see the Integration Tutorial.

​
Used In

Invoicing

Business invoice generation

Checkout

Payment collection at checkout

Integration Tutorial

Complete implementation example

Recurring Payments

Subscription and billing workflows

​
Key Features

  • Human-readable amounts: Send amounts in standard format (e.g., “0.1”), no BigNumber conversions needed
  • Automatic payment tracking: Real-time status updates via webhooks
  • Flexible currencies: Request in one currency, pay in another with automatic conversion
  • Partial payments: Track multiple payments against a single request
See API Reference for complete technical documentation with OpenAPI specs.