# Create and Pay Requests

{% hint style="info" %}
**Reach out**

For more details on how to start accepting crypto payments, [get in touch](https://2deywy.share-eu1.hsforms.com/2b92phs9LR_eJdeZoxzmoMA?utm_source=request.network\&utm_medium=docs\&utm_campaign=evergreen\&utm_content=get_in_touch) and we will reach out.
{% endhint %}

## **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 [#request-network-api-supported-currencies](https://docs.request.network/supported-chains-and-currencies#request-network-api-supported-currencies "mention")

## Create a new request

> Create a new payment request

```json
{"openapi":"3.0.0","info":{"title":"Request Network API","version":"0.18.0"},"tags":[{"name":"V2/Request","description":"Core payment request operations (V2)"}],"servers":[{"url":"https://api.request.network","description":"Production server"},{"url":"https://api.stage.request.network","description":"Staging server"},{"url":"http://127.0.0.1:8080","description":"Local development server"}],"paths":{"/v2/request":{"post":{"description":"Create a new payment request","operationId":"RequestControllerV2_createRequest_v2","parameters":[{"name":"x-api-key","in":"header","description":"API key for authentication (optional if using Client ID)","required":false,"schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"Client ID for frontend authentication (optional if using API key)","required":false,"schema":{"type":"string"}},{"name":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payer":{"type":"string","description":"The wallet address of the payer"},"payee":{"type":"string","description":"The wallet address of the payee (Ethereum 0x... or TRON T...). Optional when using client ID authentication with a configured payee destination."},"amount":{"type":"string","description":"The payable amount of the invoice, in human readable format"},"invoiceCurrency":{"type":"string","description":"Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD"},"paymentCurrency":{"type":"string","description":"Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia"},"recurrence":{"type":"object","properties":{"startDate":{"type":"string","description":"The start date of the invoice, cannot be in the past"},"frequency":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"The frequency of the invoice"}},"required":["startDate","frequency"],"description":"The recurrence of the invoice"},"isCryptoToFiatAvailable":{"type":"boolean","description":"Whether crypto-to-fiat payment is available for this request"},"customerInfo":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name"},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name"},"email":{"type":"string","maxLength":255,"format":"email","description":"Customer's email address"},"address":{"type":"object","properties":{"street":{"type":"string","maxLength":255,"description":"Street address"},"city":{"type":"string","maxLength":100,"description":"City"},"state":{"type":"string","maxLength":100,"description":"State or province"},"postalCode":{"type":"string","maxLength":20,"description":"Postal or ZIP code"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Country code (ISO 3166-1 alpha-2)"}},"description":"Customer's address"}},"description":"Optional customer information for merchant receipt tracking"},"reference":{"type":"string","minLength":1,"maxLength":255,"description":"Merchant reference for receipt tracking and identification"},"originalRequestId":{"type":"string","minLength":1,"description":"ID of the original request for recurring payments"},"originalRequestPaymentReference":{"type":"string","minLength":1,"description":"Payment reference of the original request for recurring payments"}},"required":["amount","invoiceCurrency","paymentCurrency"]}}}},"responses":{"201":{"description":"Request created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"paymentReference":{"type":"string","description":"Unique identifier of the request, used to pay the request as well as check the status of the request"},"requestId":{"type":"string","description":"Unique identifier of the request, commonly used to look up a request in Request Scan"}}}}}},"400":{"description":"Validation failed or no active payee destination for client ID"},"403":{"description":"Client ID has been revoked"},"429":{"description":"Too Many Requests"}},"summary":"Create a new request","tags":["Request","V2/Request"]}}}}
```

## Get request status

> Get the status of a payment request

```json
{"openapi":"3.0.0","info":{"title":"Request Network API","version":"0.18.0"},"tags":[{"name":"V2/Request","description":"Core payment request operations (V2)"}],"servers":[{"url":"https://api.request.network","description":"Production server"},{"url":"https://api.stage.request.network","description":"Staging server"},{"url":"http://127.0.0.1:8080","description":"Local development server"}],"paths":{"/v2/request/{requestId}":{"get":{"description":"Get the status of a payment request","operationId":"RequestControllerV2_getRequestStatus_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The requestId for the request","schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication (optional if using Client ID or session)","required":false,"schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"Client ID for frontend authentication (optional if using API key or session)","required":false,"schema":{"type":"string"}},{"name":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"hasBeenPaid":{"type":"boolean","description":"Whether the request has been paid"},"paymentReference":{"type":"string","description":"Unique identifier used for payments and status checks"},"requestId":{"type":"string","description":"Unique identifier of the request"},"payee":{"type":"string","nullable":true,"description":"The payee wallet address for this request"},"isListening":{"type":"boolean","description":"Whether the system is actively listening for payments on this request"},"recurrence":{"type":"object","description":"Recurrence configuration for recurring requests"},"originalRequestId":{"type":"string","description":"Original request ID for recurring requests"},"status":{"type":"string","description":"Current status of the request"},"isCryptoToFiatAvailable":{"type":"boolean","description":"Whether crypto-to-fiat conversion is available for this request"},"originalRequestPaymentReference":{"type":"string","description":"Payment reference of the original request for recurring payments"},"payments":{"type":"array","description":"Array of payments made to this request. Use each payment's sourceTxHash and destinationTxHash as the source of truth for transaction hashes.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the payment"},"amount":{"type":"string","description":"Payment amount as a human-readable decimal string"},"sourceNetwork":{"type":"string","description":"Network where the payment originated"},"destinationNetwork":{"type":"string","description":"Network where the payment was received"},"sourceTxHash":{"type":"string","nullable":true,"description":"Transaction hash on the source network"},"destinationTxHash":{"type":"string","nullable":true,"description":"Transaction hash on the destination network"},"timestamp":{"type":"string","format":"date-time","description":"When the payment was recorded"},"type":{"type":"string","description":"Payment type"},"conversionRateSource":{"type":"string","nullable":true,"description":"Conversion rate used on the source side"},"conversionRateDestination":{"type":"string","nullable":true,"description":"Conversion rate used on the destination side"},"currency":{"type":"string","description":"Invoice currency symbol"},"paymentCurrency":{"type":"string","description":"Payment currency symbol"},"detectionSource":{"type":"string","enum":["lifi","request-network"],"nullable":true,"description":"How this payment was confirmed"},"note":{"type":"string","nullable":true,"description":"Additional context for fallback or non-standard settlement cases"}}}},"isRecurrenceStopped":{"type":"boolean","description":"Whether recurrence has been stopped for this request"},"reference":{"type":"string","nullable":true,"description":"Merchant reference for receipt tracking and identification"},"requestAmount":{"type":"string","nullable":true,"description":"Original requested amount in invoice currency"},"amountInUsd":{"type":"string","nullable":true,"description":"Request amount in USD (actual if paid, current market rate if unpaid)"},"conversionRate":{"type":"string","nullable":true,"description":"Conversion rate. Available for: unpaid requests and fully paid requests with single payment. Null for: partially paid requests and fully paid requests with multiple payments."},"rateSource":{"type":"string","enum":["lifi","chainlink","coingecko","unknown","mixed"],"description":"Source of the conversion rate"},"conversionBreakdown":{"type":"object","nullable":true,"description":"Detailed breakdown for partial payments or multiple payments. Provides individual payment rates when top-level rate is null.","properties":{"paidAmount":{"type":"string"},"paidAmountInUsd":{"type":"string"},"remainingAmount":{"type":"string"},"remainingAmountInUsd":{"type":"string"},"currentMarketRate":{"type":"string","nullable":true},"currentMarketRateSource":{"type":"string","enum":["lifi","chainlink","coingecko","unknown"],"nullable":true},"payments":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string"},"amountInUsd":{"type":"string"},"conversionRate":{"type":"string"},"rateSource":{"type":"string","enum":["lifi","chainlink","coingecko","unknown"]},"timestamp":{"type":"string"}}}}}},"fees":{"type":"array","nullable":true,"description":"Associated fees (actual if paid, empty if unpaid)","items":{"type":"object","properties":{"type":{"type":"string","enum":["gas","platform","crosschain","crypto-to-fiat","offramp"],"description":"Type of fee"},"provider":{"type":"string","description":"Fee provider"},"amount":{"type":"string","description":"Fee amount in human-readable format (formatted with token decimals)"},"currency":{"type":"string","description":"Fee currency"}}}}}}}}},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Get request status","tags":["Request","V2/Request"]}}}}
```

## Update a recurring request

> Update a recurring request

```json
{"openapi":"3.0.0","info":{"title":"Request Network API","version":"0.18.0"},"tags":[{"name":"V2/Request","description":"Core payment request operations (V2)"}],"servers":[{"url":"https://api.request.network","description":"Production server"},{"url":"https://api.stage.request.network","description":"Staging server"},{"url":"http://127.0.0.1:8080","description":"Local development server"}],"paths":{"/v2/request/{requestId}":{"patch":{"description":"Update a recurring request","operationId":"RequestControllerV2_updateRequest_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The requestId for the request","schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication (optional if using Client ID)","required":false,"schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"Client ID for frontend authentication (optional if using API key)","required":false,"schema":{"type":"string"}},{"name":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isRecurrenceStopped":{"type":"boolean","description":"Whether the recurrence is stopped"}},"required":["isRecurrenceStopped"]}}}},"responses":{"200":{"description":"Recurrence updated successfully"},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Update a recurring request","tags":["Request","V2/Request"]}}}}
```

## Get payment calldata

> 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 executable transaction calldata for the route, including any required approval transaction before the LiFi transaction. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected.

```json
{"openapi":"3.0.0","info":{"title":"Request Network API","version":"0.18.0"},"tags":[{"name":"V2/Request","description":"Core payment request operations (V2)"}],"servers":[{"url":"https://api.request.network","description":"Production server"},{"url":"https://api.stage.request.network","description":"Staging server"},{"url":"http://127.0.0.1:8080","description":"Local development server"}],"paths":{"/v2/request/{requestId}/pay":{"get":{"description":"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 executable transaction calldata for the route, including any required approval transaction before the LiFi transaction. For off-ramp payments, use the query parameters clientUserId and paymentDetailsId. Note: Crosschain requests with an expectedAmount less than 1 are rejected.","operationId":"RequestControllerV2_getPaymentCalldata_v2","parameters":[{"name":"requestId","required":true,"in":"path","description":"The requestId of the request","schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication (optional if using Client ID)","required":false,"schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"Client ID for frontend authentication (optional if using API key)","required":false,"schema":{"type":"string"}},{"name":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}},{"name":"wallet","required":false,"in":"query","description":"The wallet address of the payer.","schema":{"type":"string"}},{"name":"chain","required":false,"in":"query","description":"The source chain of the crosschain payment","schema":{"enum":["BASE","OPTIMISM","ARBITRUM","ETHEREUM"],"type":"string"}},{"name":"token","required":false,"in":"query","description":"The source token of the crosschain payment","schema":{"enum":["USDC","USDT"],"type":"string"}},{"name":"amount","required":false,"in":"query","description":"The amount to pay, in human readable format","schema":{"type":"string"}},{"name":"clientUserId","required":false,"in":"query","description":"Optional client user ID for off-ramp payments","schema":{"type":"string"}},{"name":"paymentDetailsId","required":false,"in":"query","description":"Optional payment details ID for off-ramp payments","schema":{"type":"string"}},{"name":"feePercentage","required":false,"in":"query","description":"Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)","schema":{"type":"string"}},{"name":"feeAddress","required":false,"in":"query","description":"Address to receive the fee","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment calldata retrieved successfully","content":{"application/json":{"schema":{"anyOf":[{"type":"object","title":"Same-chain Payment Response","description":"Response for same-chain payments with transaction calldata","properties":{"transactions":{"type":"array","description":"Array of transactions to execute for the payment","items":{"type":"object","properties":{"data":{"type":"string","description":"Transaction calldata"},"to":{"type":"string","description":"Target contract address"},"value":{"type":"object","description":"Payment amount in EVM-compatible format","properties":{"type":{"type":"string","enum":["BigNumber"]},"hex":{"type":"string","description":"Amount encoded in hex"}}}},"required":["data","to","value"]}},"metadata":{"type":"object","description":"Metadata about the payment requirements","properties":{"stepsRequired":{"type":"number","description":"Number of transactions required"},"needsApproval":{"type":"boolean","description":"Whether token approval is needed"},"approvalTransactionIndex":{"type":"number","nullable":true,"description":"Index of the approval transaction if needed"},"hasEnoughBalance":{"type":"boolean","description":"Whether payer has sufficient balance"},"hasEnoughGas":{"type":"boolean","description":"Whether payer has sufficient gas"}},"required":["stepsRequired","needsApproval","hasEnoughBalance","hasEnoughGas"]}},"required":["transactions","metadata"]},{"type":"object","title":"Crosschain Payment Response","description":"Response for crosschain payments with executable transaction calldata","properties":{"transactions":{"type":"array","description":"Array of transactions to execute for the selected route","items":{"type":"object","properties":{"data":{"type":"string","description":"Transaction calldata"},"to":{"type":"string","description":"Target contract address"},"value":{"oneOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","enum":["BigNumber"]},"hex":{"type":"string"}}}],"description":"Transaction value"},"chainType":{"type":"string","enum":["evm","tron"],"nullable":true}},"required":["data","to","value"]}},"metadata":{"type":"object","description":"Metadata about the crosschain payment","properties":{"stepsRequired":{"type":"number","description":"Number of transactions required"},"needsApproval":{"type":"boolean","description":"Whether token approval is needed"},"approvalTransactionIndex":{"type":"number","nullable":true,"description":"Index of the approval transaction if needed"},"paymentTransactionIndex":{"type":"number","description":"Index of the executable crosschain transaction"},"hasEnoughBalance":{"type":"boolean","description":"Whether payer has sufficient token balance"},"routeType":{"type":"string","enum":["crosschain","samechain"]},"quoteExpiresAt":{"type":"number","description":"Route quote expiry timestamp"}},"required":["stepsRequired","needsApproval","paymentTransactionIndex","hasEnoughBalance","routeType"]}},"required":["transactions","metadata"]}]}}}},"400":{"description":"Validation failed","content":{"application/json":{}}},"404":{"description":"Request not found"},"429":{"description":"Too Many Requests"}},"summary":"Get payment calldata","tags":["Request","V2/Request"]}}}}
```

## Initiate a payment

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

```json
{"openapi":"3.0.0","info":{"title":"Request Network API","version":"0.18.0"},"tags":[{"name":"V2/Payouts","description":"Pay a request without creating one first (V2)"}],"servers":[{"url":"https://api.request.network","description":"Production server"},{"url":"https://api.stage.request.network","description":"Staging server"},{"url":"http://127.0.0.1:8080","description":"Local development server"}],"paths":{"/v2/payouts":{"post":{"description":"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.","operationId":"PayoutV2Controller_payRequest_v2","parameters":[{"name":"x-api-key","in":"header","description":"API key for authentication (optional if using Client ID)","required":false,"schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"Client ID for frontend authentication (optional if using API key)","required":false,"schema":{"type":"string"}},{"name":"Origin","in":"header","description":"Origin header (required for Client ID auth, automatically set by browser)","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payee":{"type":"string","description":"The wallet address of the payee (Ethereum 0x... or TRON T...)"},"amount":{"type":"string","description":"The payable amount of the invoice, in human readable format"},"invoiceCurrency":{"type":"string","description":"Invoice Currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: USD"},"paymentCurrency":{"type":"string","description":"Payment currency ID, from the [Request Network Token List](https://docs.request.network/general/request-network-token-list) e.g: ETH-sepolia-sepolia"},"feePercentage":{"type":"string","description":"Fee percentage to apply at payment time (e.g., '2.5' for 2.5%)"},"feeAddress":{"type":"string","description":"Address to receive the fee (Ethereum 0x... or TRON T...)"},"recurrence":{"type":"object","properties":{"startDate":{"type":"string","description":"The start date of the payment, cannot be in the past"},"frequency":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"The frequency of the payment"},"totalPayments":{"type":"number","minimum":2,"maximum":256,"description":"The total number of times the payment will be executed (max 256)."},"payer":{"type":"string","description":"The wallet address of the payer. Cannot be the same as the payee address."}},"required":["startDate","frequency","totalPayments","payer"],"description":"Configuration details for recurring payments"},"payerWallet":{"type":"string","description":"The wallet address of the payer, use to check if payer approval exists"},"payerAddress":{"type":"string","description":"The wallet address of the payer (alias for payerWallet)"},"customerInfo":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name"},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name"},"email":{"type":"string","maxLength":255,"format":"email","description":"Customer's email address"},"address":{"type":"object","properties":{"street":{"type":"string","maxLength":255,"description":"Street address"},"city":{"type":"string","maxLength":100,"description":"City"},"state":{"type":"string","maxLength":100,"description":"State or province"},"postalCode":{"type":"string","maxLength":20,"description":"Postal or ZIP code"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Country code (ISO 3166-1 alpha-2)"}},"description":"Customer's address"}},"description":"Optional customer information for merchant receipt tracking"},"reference":{"type":"string","minLength":1,"maxLength":255,"description":"Merchant reference for receipt tracking and identification"}},"required":["payee","amount","invoiceCurrency","paymentCurrency"]}}}},"responses":{"201":{"description":"Request created and payment initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string"}},"required":["requestId"]}}}},"404":{"description":"Wallet not found"},"429":{"description":"Too Many Requests"}},"summary":"Initiate a payment","tags":["Pay","V2/Payouts"]}}}}
```

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

## Create and Pay Request Workflow

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

{% @mermaid/diagram content="---
config:
fontSize: 10
sequence:
wrap: true
actorMargin: 90
width: 100
height: 50
----------

sequenceDiagram
actor User
participant App
participant Request Network API
participant Blockchain

```
User->>App: Create Request
App->>Request Network API: POST /request {apiKey, payee, payer?, amount, invoiceCurrency, paymentCurrency}
Request Network API-->>App: 201 Created {requestId, paymentReference}

User->>App: Pay Request
App->>Request Network API: GET /request/{paymentReference}/pay {apiKey}
Request Network API-->>App: 200 OK {transactions[calldata], metadata{stepsRequired, needsApproval, approvalTransactionIndex}}
Request Network API-)Request Network API: Start listening {paymentReference}

opt if needs approval 
    App->>User: Prompt for approval signature
    User-->>App: Sign approval transaction
    App->>Blockchain: Submit approval transaction
end

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

Request Network API->>Request Network API: Payment detected, stop listening {paymentReference}
Request Network API->>App: POST <webhook url> {"payment.confirmed", requestId, paymentReference, request scan link, timestamp}
App-->>User: Payment Complete" fullWidth="false" %}
```