Create and Pay Requests

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

Reach out

For more details on how to start accepting crypto payments, get in touch and we will reach out.

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.

Supported Chains and Currencies

See Supported Chains and Currencies

Create a new request

post

https://api.request.networkhttps://api.stage.request.networkhttp://127.0.0.1:8080

/v2/request

Create a new payment request

Header parameters

x-api-keystringOptional

API key for authentication (optional if using Client ID)

x-client-idstringOptional

Client ID for frontend authentication (optional if using API key)

OriginstringOptional

Origin header (required for Client ID auth, automatically set by browser)

Body

application/json

payerstringOptional

The wallet address of the payer

payeestringOptional

The wallet address of the payee. Required for all requests except crypto-to-fiat

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

referencestring · min: 1 · max: 255Optional

Merchant reference for receipt tracking and identification

originalRequestIdstring · min: 1Optional

ID of the original request for recurring payments

originalRequestPaymentReferencestring · min: 1Optional

Payment reference of the original request for recurring payments

Responses

201

Request created successfully

application/json

400

Validation failed

404

Wallet not found

429

Too Many Requests

post

/v2/request

HTTPcURLJavaScriptPython

POST /v2/request HTTP/1.1
Host: api.request.network
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia"
}

Regular payment requestCrypto-to-fiat payment requestRequest with customer information and referenceRecurring invoice

{
  "paymentReference": "0xb3581f0b0f74cc61",
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"
}

Get request status

get

https://api.request.networkhttps://api.stage.request.networkhttp://127.0.0.1:8080

/v2/request/{requestId}

Get the status of a payment request

Path parameters

requestIdstringRequired

The requestId for the request

Example: 01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb

Header parameters

x-api-keystringOptional

API key for authentication (optional if using Client ID)

x-client-idstringOptional

Client ID for frontend authentication (optional if using API key)

OriginstringOptional

Origin header (required for Client ID auth, automatically set by browser)

Responses

200

Request status retrieved successfully

application/json

404

Request not found

429

Too Many Requests

get

/v2/request/{requestId}

HTTPcURLJavaScriptPython

GET /v2/request/{requestId} HTTP/1.1
Host: api.request.network
Accept: */*

{
  "hasBeenPaid": true,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "isListening": false,
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Update a recurring request

patch

https://api.request.networkhttps://api.stage.request.networkhttp://127.0.0.1:8080

/v2/request/{requestId}

Update a recurring request

Path parameters

requestIdstringRequired

The requestId for the request

Example: 01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb

Header parameters

x-api-keystringOptional

API key for authentication (optional if using Client ID)

x-client-idstringOptional

Client ID for frontend authentication (optional if using API key)

OriginstringOptional

Origin header (required for Client ID auth, automatically set by browser)

Body

application/json

isRecurrenceStoppedbooleanRequired

Whether the recurrence is stopped

Responses

200

Recurrence updated successfully

No content

404

Request not found

429

Too Many Requests

patch

/v2/request/{requestId}

HTTPcURLJavaScriptPython

PATCH /v2/request/{requestId} HTTP/1.1
Host: api.request.network
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "isRecurrenceStopped": true
}

Stop recurring invoiceResume recurring invoice

No content

Get payment calldata

get

https://api.request.networkhttps://api.stage.request.networkhttp://127.0.0.1:8080

/v2/request/{requestId}/pay

Get the calldata needed to pay a request. For same-chain payments, returns transaction calldata that can be directly executed. For crosschain payments (when chain and token parameters are provided and differ from the request's native chain), returns a payment intent that needs to be signed and processed through the crosschain bridge. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected.

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 crosschain payment

Possible values:

tokenstring · enumOptional

The source token of the crosschain 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-keystringOptional

API key for authentication (optional if using Client ID)

x-client-idstringOptional

Client ID for frontend authentication (optional if using API key)

OriginstringOptional

Origin header (required for Client ID auth, automatically set by browser)

Responses

200

Payment calldata retrieved successfully

application/json

Responseany of

or

400

Validation failed

application/json

404

Request not found

429

Too Many Requests

get

/v2/request/{requestId}/pay

HTTPcURLJavaScriptPython

GET /v2/request/{requestId}/pay HTTP/1.1
Host: api.request.network
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

https://api.request.networkhttps://api.stage.request.networkhttp://127.0.0.1:8080

/v2/payouts

Initiate a payment without having to create a request first. Supports both one-time and recurring payments. For recurring payments, specify the recurrence object with start date, frequency, total executions, and payer address. The system will create a recurring payment schedule and return the necessary transactions for allowance approval and signature submission. Optionally includes customer information (firstName, lastName, email, address) and a merchant reference field for checkout widget implementations and receipt tracking.

Header parameters

x-api-keystringOptional

API key for authentication (optional if using Client ID)

x-client-idstringOptional

Client ID for frontend authentication (optional if using API key)

OriginstringOptional

Origin header (required for Client ID auth, automatically set by browser)

Body

application/json

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

payerWalletstringOptional

The wallet address of the payer, use to check if payer approval exists

referencestring · min: 1 · max: 255Optional

Merchant reference for receipt tracking and identification

Responses

201

Request created and payment initiated successfully

application/json

404

Wallet not found

429

Too Many Requests

post

/v2/payouts

HTTPcURLJavaScriptPython

POST /v2/payouts HTTP/1.1
Host: api.request.network
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia",
  "feePercentage": "0.02",
  "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
}

One-time payment exampleRecurring payment exampleERC20 token payment exampleCheckout widget payment with customer info and reference

{
  "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: