Create and Pay Requests

The Request Network API provides an interface for creating and paying requests within your application.

Talk to an expert

Discover how Request Network API can enhance your app's features - book a call with us.

Core Functionality

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.

  • Fee Collection: When paying a request, you can specify a fee percentage (between 0 and 100) and a fee address, which will add the fee on top of the payment amount - meaning the payer will pay the original amount plus the fee percentage, with the fee portion being sent to the specified fee address.

  • 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.

Create a new request

post

Create a new payment request

Header parameters
x-api-keystringRequired

API key for authentication

Body
payerstringOptional

The wallet address of the payer

payeestringRequired

The wallet address of the payee

amountstringRequired

The payable amount of the invoice, in human readable format

invoiceCurrencystringRequired

Invoice Currency ID, from the Request Network Token List e.g: USD

paymentCurrencystringRequired

Payment currency ID, from the Request Network Token List e.g: ETH-sepolia-sepolia

isCryptoToFiatAvailablebooleanOptional

Whether crypto-to-fiat payment is available for this request

Responses
201
Request created successfully
application/json
post
POST /v2/request HTTP/1.1
Host: api.request.network
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 238

{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia",
  "isCryptoToFiatAvailable": false,
  "recurrence": {
    "startDate": "2025-01-01T00:00:00.000Z",
    "frequency": "DAILY"
  }
}
{
  "paymentReference": "0xb3581f0b0f74cc61",
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"
}

Get request status

get

Get the status of a payment request

Path parameters
requestIdstringRequired

The requestId for the request

Example: 01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb
Header parameters
x-api-keystringRequired

API key for authentication

Responses
200
Request status retrieved successfully
application/json
Responseany
get
GET /v2/request/{requestId} HTTP/1.1
Host: api.request.network
x-api-key: text
Accept: */*
{
  "hasBeenPaid": true,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "isListening": false,
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Update a recurring request

patch

Update a recurring request

Path parameters
requestIdstringRequired

The requestId for the request

Example: 01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb
Header parameters
x-api-keystringRequired

API key for authentication

Responses
200
Recurrence updated successfully
patch
PATCH /v2/request/{requestId} HTTP/1.1
Host: api.request.network
x-api-key: text
Accept: */*

No content

Get payment calldata

get

Get the calldata needed to pay a request. For cross-chain payments, returns a payment intent that needs to be signed. For same-chain payments, returns transaction calldata. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId.

Path parameters
requestIdstringRequired

The requestId of the request

Example: 01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb
Query parameters
walletstringOptional

The wallet address of the payer.

Example: 0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7
chainstring · enumOptional

The source chain of the cross chain payment

Possible values:
tokenstring · enumOptional

The source token of the cross chain payment

Possible values:
amountstringOptional

The amount to pay, in human readable format

clientUserIdstringOptional

Optional client user ID for off-ramp payments

Example: user-123
paymentDetailsIdstringOptional

Optional payment details ID for off-ramp payments

Example: fa898aec-519c-46be-9b4c-e76ef4ff99d9
feePercentagestringOptional

Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)

Example: 0.02
feeAddressstringOptional

Address to receive the fee

Example: 0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7
Header parameters
x-api-keystringRequired

API key for authentication

Responses
200
Payment calldata retrieved successfully
application/json
get
GET /v2/request/{requestId}/pay HTTP/1.1
Host: api.request.network
x-api-key: text
Accept: */*
{
  "transactions": [
    {
      "data": "0xb868980b...00",
      "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x038d7ea4c68000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "approvalTransactionIndex": null,
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}

Initiate a payment

post

Initiate a payment without having to create a request first

Header parameters
x-api-keystringRequired

API key for authentication

Body
payeestringRequired

The wallet address of the payee

amountstringRequired

The payable amount of the invoice, in human readable format

invoiceCurrencystringRequired

Invoice Currency ID, from the Request Network Token List e.g: USD

paymentCurrencystringRequired

Payment currency ID, from the Request Network Token List e.g: ETH-sepolia-sepolia

feePercentagestringOptional

Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)

feeAddressstringOptional

Address to receive the fee

Responses
201
Request created and payment initiated successfully
application/json
Responseany
post
POST /v2/payouts HTTP/1.1
Host: api.request.network
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia",
  "feePercentage": "0.02",
  "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
}
{
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "paymentReference": "0xb3581f0b0f74cc61",
  "transactions": [
    {
      "data": "0xb868980b...00",
      "to": "0x11BF2fDA23bF0A98365e1A4e04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x038d7ea4c68000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "approvalTransactionIndex": null,
    "hasEnoughBalance": true,
    "hasEnoughGas": true
  }
}

For detailed information on all available endpoints and their parameters, please refer to the full Request Network API Reference

Create and Pay Request Workflow

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

Last updated

Was this helpful?