### API Key Authentication Example

Source: https://docs.request.network/api-reference/authentication

Use API keys for backend calls. This example shows how to make a GET request to retrieve a specific request using an API key.

```bash
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
  -H 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Fastify Server Setup

Source: https://docs.request.network/api-setup/integration-tutorial

Sets up a basic Fastify server with CORS enabled and a root endpoint. It logs server start and handles errors.

```typescript
// src/index.ts
import 'dotenv/config';
import Fastify, { FastifyRequest, FastifyReply } from 'fastify';

const fastify = Fastify({
  logger: true
});

fastify.get('/', async (request: FastifyRequest, reply: FastifyReply) => {
  return { message: 'Hello World!' };
});

const start = async () => {
  try {
    const port =  3000;
    const host = 'localhost';
    
    await fastify.register(require('@fastify/cors'), {
      origin: true, // change to your frontend URL in production
      methods: ['GET', 'POST', 'PATCH'],
    });
    await fastify.listen({ port, host });
    console.log(`Server listening on http://${host}:${port}`);
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

```

--------------------------------

### API Key Authentication Example

Source: https://docs.request.network/api-reference/authentication

Use API keys for backend calls. This example shows how to authenticate a GET request to retrieve a request by its ID.

```APIDOC
## API Key Authentication Example

### Description
Use API keys for backend calls. This example shows how to authenticate a GET request to retrieve a request by its ID.

### Method
GET

### Endpoint
`https://api.request.network/v2/request/{requestId}`

### Headers
- `x-api-key`: YOUR_API_KEY

### Request Example
```bash
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
  -H 'x-api-key: YOUR_API_KEY'
```
```

--------------------------------

### Client ID Authentication Example

Source: https://docs.request.network/api-reference/authentication

Use Client ID for browser-side authentication. This example demonstrates a GET request requiring both a Client ID and the Origin header.

```bash
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'Origin: https://your-app.example'
```

--------------------------------

### Install Dependencies for Request Network Demo

Source: https://docs.request.network/api-setup/getting-started

Install the dotenv package to manage environment variables for your API integration.

```bash
mkdir request-api-demo
cd request-api-demo
npm init -y
npm install dotenv
```

--------------------------------

### Request with Customer Information and Reference Example

Source: https://docs.request.network/api-reference/request/create-a-new-request

Use this example when you need to include detailed customer information and a merchant reference for tracking. It supports address details and contact information.

```json
{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "50.00",
  "invoiceCurrency": "USD",
  "paymentCurrency": "USDC-sepolia",
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "reference": "ORDER-2024-001234"
}
```

--------------------------------

### Recurring Payment Example

Source: https://docs.request.network/api-reference/pay/initiate-a-payment

Configure and initiate a recurring payment. This requires specifying start date, frequency, total number of payments, and the payer's wallet address.

```json
{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia",
  "feePercentage": "0.02",
  "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "recurrence": {
    "startDate": "2030-01-01",
    "frequency": "DAILY",
    "totalPayments": 30,
    "payer": "0x2e2E5C79F571ef1658d4C2d3684a1FE97DD30570"
  }
}
```

--------------------------------

### Frontend Redirect Examples

Source: https://docs.request.network/api-features/secure-payment-integration-guide

These examples show how to redirect the payer to the secure payment URL. One redirects in the same tab, and the other opens the URL in a new tab.

```javascript
window.location.href = securePaymentUrl;
```

```javascript
window.open(securePaymentUrl, "_blank", "noopener,noreferrer");
```

--------------------------------

### GET /v2/request/{requestId}/pay with Platform Fees

Source: https://docs.request.network/api-features/platform-fees

This example shows how to add platform fees as query parameters when initiating a request-based payment.

```APIDOC
## GET /v2/request/{requestId}/pay

### Description
Initiates a payment for a given request, with optional platform fees.

### Method
GET

### Endpoint
`/v2/request/{requestId}/pay`

### Parameters
#### Query Parameters
- **feePercentage** (string) - Optional - Fee percentage to apply at payment time (e.g., "2.5" for 2.5%).
- **feeAddress** (string) - Optional - Wallet address that receives the platform fee.

### Request Example
```bash
curl -X GET 'https://api.request.network/v2/request/{requestId}/pay?feePercentage=2.5&feeAddress=0x742d35CC6634c0532925a3B844BC9e7595f8fA40' \
  -H 'x-api-key: YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **paymentPayload** (object) - The payload required to execute the payment, including fee handling.

#### Response Example
```json
{
  "example": "payment payload details"
}
```
```

--------------------------------

### ERC20 Token Payment Example

Source: https://docs.request.network/api-reference/pay/initiate-a-payment

Initiate a payment using an ERC20 token. This example demonstrates how to specify custom token currencies like 'FAU-sepolia'.

```json
{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "100",
  "invoiceCurrency": "FAU-sepolia",
  "paymentCurrency": "FAU-sepolia",
  "feePercentage": "0.01",
  "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
}
```

--------------------------------

### One-Time Payment Example

Source: https://docs.request.network/api-reference/pay/initiate-a-payment

Use this example to initiate a standard one-time payment. Ensure the payee, amount, invoice currency, and payment currency are correctly specified.

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

--------------------------------

### Request Status Examples

Source: https://docs.request.network/api-reference/request/get-request-status

Examples of the response structure for different request statuses.

```APIDOC
## Get Request Status

### Description
Retrieve the status of a payment request.

### Method
GET

### Endpoint
`/requests/{requestId}/status`

### Parameters
#### Path Parameters
- **requestId** (string) - Required - The unique identifier of the request.

### Response
#### Success Response (200)
- **hasBeenPaid** (boolean) - Indicates if the request has been fully paid.
- **requestId** (string) - The unique identifier of the request.
- **isListening** (boolean) - Indicates if the system is actively listening for payments related to this request.
- **txHash** (string | null) - The transaction hash if the request has been paid on-chain, otherwise null.
- **paymentReference** (string | null) - A reference to the payment transaction.
- **amountInUsd** (string | null) - The total amount of the request in USD.
- **conversionRate** (string | null) - The conversion rate used for the payment in USD.
- **rateSource** (string | null) - The source of the conversion rate.
- **conversionBreakdown** (object | null) - Detailed breakdown of the conversion if applicable.
- **fees** (array) - An array of fee objects associated with the request.
  - **type** (string) - The type of fee (e.g., platform, gas).
  - **provider** (string) - The provider of the fee.
  - **amount** (string) - The amount of the fee.
  - **currency** (string) - The currency of the fee.
- **customerInfo** (object | null) - Information about the customer.
  - **firstName** (string)
  - **lastName** (string)
  - **email** (string)
  - **address** (object)
    - **street** (string)
    - **city** (string)
    - **state** (string)
    - **postalCode** (string)
    - **country** (string)
- **reference** (string | null) - A customer-facing reference for the request.

### Response Example (Paid)
```json
{
  "hasBeenPaid": true,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "isListening": false,
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "paymentReference": null,
  "amountInUsd": null,
  "conversionRate": null,
  "rateSource": null,
  "conversionBreakdown": null,
  "fees": [],
  "customerInfo": null,
  "reference": null
}
```

### Response Example (Not Paid)
```json
{
  "hasBeenPaid": false,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "isListening": false,
  "txHash": null,
  "paymentReference": null,
  "amountInUsd": null,
  "conversionRate": null,
  "rateSource": null,
  "conversionBreakdown": null,
  "fees": [],
  "customerInfo": null,
  "reference": null
}
```

### Response Example (With Customer Info)
```json
{
  "hasBeenPaid": false,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "isListening": true,
  "txHash": null,
  "paymentReference": null,
  "amountInUsd": null,
  "conversionRate": null,
  "rateSource": null,
  "conversionBreakdown": null,
  "fees": [],
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "reference": "ORDER-2024-001234"
}
```

### Response Example (Paid with USD Info)
```json
{
  "hasBeenPaid": true,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "paymentReference": "0xb3581f0b0f74cc61",
  "amountInUsd": "100.00",
  "conversionRate": "2487.52",
  "rateSource": "coingecko",
  "fees": [
    {
      "type": "platform",
      "provider": "request-network",
      "amount": "2.00",
      "currency": "USDC"
    },
    {
      "type": "gas",
      "provider": "sepolia",
      "amount": "0.002",
      "currency": "ETH"
    }
  ],
  "isListening": false,
  "txHash": null,
  "conversionBreakdown": null,
  "customerInfo": null,
  "reference": null
}
```

### Response Example (Partially Paid with Breakdown)
```json
{
  "hasBeenPaid": false,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "paymentReference": "0xb3581f0b0f74cc61",
  "amountInUsd": "100.12",
  "conversionRate": null,
  "rateSource": "mixed",
  "conversionBreakdown": {
    "paidAmount": "75.00",
    "paidAmountInUsd": "75.00",
    "remainingAmount": "25.00",
    "remainingAmountInUsd": "25.12",
    "currentMarketRate": "2501.23",
    "currentMarketRateSource": "coingecko",
    "payments": [
      {
        "amount": "75.00",
        "amountInUsd": "75.00",
        "conversionRate": "2487.52",
        "rateSource": "chainlink",
        "timestamp": "2025-01-01T10:00:00Z"
      }
    ]
  },
  "fees": [
    {
      "type": "platform",
      "provider": "request-network",
      "amount": "1.50",
      "currency": "USDC"
    },
    {
      "type": "gas",
      "provider": "sepolia",
      "amount": "0.0015",
      "currency": "ETH"
    }
  ],
  "isListening": false,
  "txHash": null,
  "customerInfo": null,
  "reference": null
}
```

### Response Example (Unpaid Request with Market Rates)
```json
{
  "hasBeenPaid": false,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "paymentReference": "0xb3581f0b0f74cc61",
  "amountInUsd": "100.25",
  "conversionRate": "2501.23",
  "rateSource": "coingecko",
  "fees": [],
  "isListening": false,
  "txHash": null,
  "conversionBreakdown": null,
  "customerInfo": null,
  "reference": null
}
```

### Response Example (Multiple Payments)
```json
{
  "hasBeenPaid": true,
  "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
  "paymentReference": "0xb3581f0b0f74cc61",
  "amountInUsd": null,
  "conversionRate": null,
  "rateSource": null,
  "fees": [],
  "isListening": false,
  "txHash": null,
  "conversionBreakdown": null,
  "customerInfo": null,
  "reference": null
}
```
```

--------------------------------

### Example Routes Response

Source: https://docs.request.network/api-features/crosschain-payments

This JSON object shows an example response when fetching available payment routes. It includes same-chain and cross-chain options with details on fees and estimated speed.

```json
{
  "routes": [
    {
      "id": "REQUEST_NETWORK_PAYMENT",
      "fee": 0,
      "feeBreakdown": [],
      "speed": "FAST",
      "chain": "BASE",
      "token": "USDC"
    },
    {
      "id": "ARBITRUM_BASE_USDT_USDC",
      "fee": 0.001,
      "feeBreakdown": [
        {
          "type": "crosschain",
          "stage": "sending",
          "provider": "lifi",
          "amount": "0.001",
          "amountInUSD": "0.001",
          "currency": "USDT"
        }
      ],
      "speed": 300,
      "chain": "ARBITRUM",
      "token": "USDT"
    }
  ]
}
```

--------------------------------

### Example Response for Supported Currencies

Source: https://docs.request.network/api-features/secure-payment-supported-networks-and-currencies

This is an example JSON response when querying for supported currencies on the 'sepolia' network. It lists currency details including ID, name, symbol, decimals, network, type, and chain ID.

```json
[
  {
    "id": "FAU-sepolia",
    "name": "FAU",
    "symbol": "FAU",
    "decimals": 18,
    "network": "sepolia",
    "type": "ERC20",
    "chainId": 11155111
  }
]
```

--------------------------------

### Payer Endpoint Examples

Source: https://docs.request.network/api-features/crypto-to-fiat-payments

These examples show how to use the `clientUserId` path parameter with various payer-related API endpoints. Replace `{clientUserId}` with your platform's unique identifier for the user.

```bash
GET /v2/payer/{clientUserId}
```

```bash
PATCH /v2/payer/{clientUserId}
```

```bash
POST /v2/payer/{clientUserId}/payment-details
```

```bash
GET  /v2/payer/{clientUserId}/payment-details
```

--------------------------------

### Backend Example: Create Secure Payment Link (Node.js/Express)

Source: https://docs.request.network/api-features/secure-payment-integration-guide

This Node.js/Express backend example demonstrates how to call the /v2/secure-payments API to create a secure payment link. It handles the API request and response, and includes comments for persisting data.

```javascript
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/checkout/secure-payment", async (req, res) => {
  const { orderId, payee, amount, currencyId } = req.body;

  const apiResponse = await fetch("https://api.request.network/v2/secure-payments", {
    method: "POST",
    headers: {
      "x-api-key": process.env.REQUEST_API_KEY,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      requests: [
        {
          payee,
          amount,
          invoiceCurrency: currencyId,
          paymentCurrency: currencyId,
        },
      ],
    }),
  });

  if (!apiResponse.ok) {
    const errorBody = await apiResponse.text();
    return res.status(apiResponse.status).json({ error: errorBody });
  }

  const securePayment = await apiResponse.json();

  // Persist in your DB
  // Example payload:
  // {
  //   orderId,
  //   requestIds: securePayment.requestIds,
  //   token: securePayment.token,
  //   securePaymentUrl: securePayment.securePaymentUrl,
  //   status: "pending"
  // }

  return res.status(200).json({
    orderId,
    securePaymentUrl: securePayment.securePaymentUrl,
  });
});
```

--------------------------------

### Individual Beneficiary Compliance Data Example

Source: https://docs.request.network/api-reference/payer/create-compliance-data-for-a-user

This example demonstrates how to structure the request body to create compliance data for an individual beneficiary. Ensure all required fields are accurately provided.

```json
{
  "clientUserId": "user-123",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "beneficiaryType": "individual",
  "dateOfBirth": "1985-12-12"
}
```

--------------------------------

### TRON USDT Payment Example

Source: https://docs.request.network/api-reference/pay/initiate-a-payment

Initiate a payment using USDT on the TRON network. This example shows the specific currency format required for TRON-based USDT payments.

```json
{
  "payee": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW",
  "amount": "10",
  "invoiceCurrency": "USDT-tron",
  "paymentCurrency": "USDT-tron"
}
```

--------------------------------

### Regular Payment Request Example

Source: https://docs.request.network/api-reference/request/create-a-new-request

Use this example for standard payment requests. It specifies the payee, amount, and currencies for the invoice and payment.

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

--------------------------------

### Signature Verification Example

Source: https://docs.request.network/api-reference/webhooks

Example code demonstrating how to verify the HMAC SHA-256 signature of incoming webhooks using Node.js.

```APIDOC
## Signature Verification

Every webhook includes an HMAC SHA-256 signature in the `x-request-network-signature` header.

```javascript theme={null}
import crypto from "node:crypto";

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  } catch {
    return false;
  }
}

// Usage in your webhook handler
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-request-network-signature"];
  
  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  
  // Parse JSON after verification
  const body = JSON.parse(req.rawBody.toString("utf8"));
  
  // Process webhook...
  res.status(200).json({ success: true });
});
```
```

--------------------------------

### Crypto-to-Fiat Payment Request Example

Source: https://docs.request.network/api-reference/request/create-a-new-request

This example is for payment requests where the customer pays in cryptocurrency, and the merchant receives fiat. It includes the `isCryptoToFiatAvailable` flag.

```json
{
  "amount": "25.50",
  "invoiceCurrency": "USD",
  "paymentCurrency": "USDC-sepolia",
  "isCryptoToFiatAvailable": true
}
```

--------------------------------

### Create Client ID with Fees

Source: https://docs.request.network/api-reference/client-ids/create-a-new-client-id

This example demonstrates creating a client ID with fee configuration. The 'feePercentage' and 'feeAddress' are required when setting up fees. Multiple domains can be specified.

```json
{
  "label": "My Client ID with Fees",
  "allowedDomains": [
    "https://example.com",
    "https://app.example.com"
  ],
  "feePercentage": "2.5",
  "feeAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7"
}
```

--------------------------------

### Create Client ID (Basic)

Source: https://docs.request.network/api-reference/client-ids/create-a-new-client-id

Use this example to create a client ID without any fee configuration. Ensure the 'label' and 'allowedDomains' are provided.

```json
{
  "label": "My Client ID",
  "allowedDomains": [
    "https://example.com"
  ]
}
```

--------------------------------

### Client ID Authentication Example

Source: https://docs.request.network/api-reference/authentication

Use Client ID when your integration needs browser-side authentication flow. This example shows how to authenticate a GET request to retrieve a request by its ID, including the required Origin header.

```APIDOC
## Client ID Authentication Example

### Description
Use Client ID when your integration needs browser-side authentication flow. This example shows how to authenticate a GET request to retrieve a request by its ID, including the required Origin header.

### Method
GET

### Endpoint
`https://api.request.network/v2/request/{requestId}`

### Headers
- `x-client-id`: YOUR_CLIENT_ID
- `Origin`: https://your-app.example

### Request Example
```bash
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'Origin: https://your-app.example'
```
```

--------------------------------

### Configure Environment Variables for API

Source: https://docs.request.network/api-setup/getting-started

Set up your Client ID and API URL in a .env file for secure access.

```bash
RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2
```

--------------------------------

### GET /v2/secure-payments/:token

Source: https://docs.request.network/api-reference/secure-payments

Get payment metadata for a given payment token.

```APIDOC
## GET /v2/secure-payments/:token

### Description
Get payment metadata

### Method
GET

### Endpoint
/v2/secure-payments/:token

### Parameters
#### Path Parameters
- **token** (string) - Required - The unique token of the payment.

### Response
(Response details are not explicitly provided in the source. Refer to general API documentation for expected response structure.)

### Error responses
(Error responses are not explicitly detailed for this endpoint in the provided source. Refer to general API documentation for common error codes.)
```

--------------------------------

### All Networks Conversion Routes

Source: https://docs.request.network/api-reference/currencies/get-conversion-routes-for-a-specific-currency

Example response showing conversion routes for USD across all available networks. This response includes routes for both mainnet and sepolia networks.

```json
{
  "currencyId": "USD",
  "network": null,
  "conversionRoutes": [
    {
      "id": "USDT-mainnet",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "network": "mainnet",
      "type": "ERC20",
      "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "chainId": 1
    },
    {
      "id": "FAU-sepolia",
      "name": "FAU",
      "symbol": "FAU",
      "decimals": 18,
      "address": "0x370DE27fdb7D1Ff1e1BaA7D11c5820a324Cf623C",
      "network": "sepolia",
      "type": "ERC20"
    }
  ]
}
```

--------------------------------

### Tron Destination Example

Source: https://docs.request.network/use-cases/programmatic-payment-links

Example of a destination ID for the Tron network, specifically USDT on Tron.

```json
{
  "requests": [
    {
      "destinationId": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8@eip155:728126428#5F89A3B2:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "amount": "100"
    }
  ]
}
```

--------------------------------

### EVM Destination Example

Source: https://docs.request.network/use-cases/programmatic-payment-links

Example of a destination ID for an EVM network, specifically USDC on Base.

```json
{
  "requests": [
    {
      "destinationId": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:8453#ABCD1234:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "100"
    }
  ]
}
```

--------------------------------

### GET /v2/secure-payments/:token/pay

Source: https://docs.request.network/api-reference/secure-payments

Get executable calldata for a payment, allowing for direct on-chain interaction.

```APIDOC
## GET /v2/secure-payments/:token/pay

### Description
Get payment calldata

### Method
GET

### Endpoint
/v2/secure-payments/:token/pay

### Parameters
#### Path Parameters
- **token** (string) - Required - The unique token of the payment.

### Response
(Response details are not explicitly provided in the source. Refer to general API documentation for expected response structure.)

### Error responses
(Error responses are not explicitly detailed for this endpoint in the provided source. Refer to general API documentation for common error codes.)
```

--------------------------------

### Example Webhook Received Output

Source: https://docs.request.network/api-setup/integration-tutorial

This is an example of the log output you should expect to see on your server when a webhook event is received and processed.

```log
Webhook received: payment.confirmed for request req_test123456789abcdef {
  webhookData: {
    event: 'payment.confirmed',
    requestId: 'req_test123456789abcdef',
    requestID: 'req_test123456789abcdef',
    paymentReference: '0x1234567890abcdef1234567890abcdef12345678',
    explorer: 'https://scan.request.network/request/req_test123456789abcdef',
    amount: '100.0',
    totalAmountPaid: '100.0',
    expectedAmount: '100.0',
    timestamp: '2025-08-28T12:25:45.995Z',
    txHash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
    network: 'ethereum',
    currency: 'USDC',
    paymentCurrency: 'USDC',
    isCryptoToFiat: false,
    subStatus: '',
    paymentProcessor: 'request-network',
    fees: [ [Object] ]
  }
}
Webhook event: payment.confirmed
Full webhook data: {
  "event": "payment.confirmed",
  "requestId": "req_test123456789abcdef",
  "requestID": "req_test123456789abcdef",
  "paymentReference": "0x1234567890abcdef1234567890abcdef12345678",
  "explorer": "https://scan.request.network/request/req_test123456789abcdef",
  "amount": "100.0",
  "totalAmountPaid": "100.0",
  "expectedAmount": "100.0",
  "timestamp": "2025-08-28T12:25:45.995Z",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "network": "ethereum",
  "currency": "USDC",
  "paymentCurrency": "USDC",
  "isCryptoToFiat": false,
  "subStatus": "",
  "paymentProcessor": "request-network",
  "fees": [
    {
      "type": "network",
      "amount": "0.02",
      "currency": "ETH"
    }
  ]
}
```

--------------------------------

### Search Payments by Wallet and Date Range

Source: https://docs.request.network/api-reference/v2payments/search-payments-with-advanced-filtering

This example shows how to filter payments by a wallet address within a specified date range. It includes details on fees and associated requests.

```json
{
  "payments": [
    {
      "id": "01HXAMPLE1111222233334444",
      "amount": "50000000",
      "sourceNetwork": "base",
      "destinationNetwork": "base",
      "sourceTxHash": "0x1111222233334444555566667777888899990000aaaabbbbccccddddeeeeffff",
      "destinationTxHash": null,
      "timestamp": "2024-01-14T16:20:00.000Z",
      "type": "conversion",
      "currency": "USD",
      "paymentCurrency": "USDC",
      "fees": [
        {
          "type": "platform",
          "amount": "500000",
          "currency": "USDC",
          "provider": "request-network"
        }
      ],
      "request": {
        "requestId": "01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb",
        "paymentReference": "0xe1f2a3b4c5d67890",
        "hasBeenPaid": true,
        "reference": "SERVICE-2024-789"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
```

--------------------------------

### Recurring Invoice Request Example

Source: https://docs.request.network/api-reference/request/create-a-new-request

This example demonstrates how to set up a recurring invoice. It includes the `recurrence` object with `startDate` and `frequency`.

```json
{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "10",
  "invoiceCurrency": "USD",
  "paymentCurrency": "ETH-sepolia-sepolia",
  "recurrence": {
    "startDate": "2030-01-01",
    "frequency": "YEARLY"
  }
}
```

--------------------------------

### Example ERC-7828 Address Format

Source: https://docs.request.network/api-features/payee-destinations

An example of an ERC-7828 interop address format, which encodes wallet, chain, checksum, and token.

```text
0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:8453#ABCD1234:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

--------------------------------

### POST /v2/payouts with Platform Fees

Source: https://docs.request.network/api-features/platform-fees

This example demonstrates how to include platform fees as body parameters when creating a direct payout.

```APIDOC
## POST /v2/payouts

### Description
Creates a direct payout with optional platform fees.

### Method
POST

### Endpoint
`/v2/payouts`

### Parameters
#### Request Body
- **payee** (string) - Required - The wallet address of the payee.
- **amount** (string) - Required - The amount to be paid.
- **invoiceCurrency** (string) - Required - The currency of the invoice.
- **paymentCurrency** (string) - Required - The currency for the payment.
- **feePercentage** (string) - Optional - Fee percentage to apply at payment time (e.g., "2.5" for 2.5%).
- **feeAddress** (string) - Optional - Wallet address that receives the platform fee.

### Request Example
```json
{
  "payee": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "amount": "100",
  "invoiceCurrency": "USD",
  "paymentCurrency": "USDC-base",
  "feePercentage": "2.5",
  "feeAddress": "0x742d35CC6634c0532925a3B844BC9e7595f8fA40"
}
```

### Response
#### Success Response (200)
- **payoutDetails** (object) - Details of the created payout.

#### Response Example
```json
{
  "example": "payout details"
}
```
```

--------------------------------

### Viem Client Setup for Transaction Execution

Source: https://docs.request.network/api-features/crosschain-payments

This TypeScript code initializes Viem clients for interacting with the Arbitrum network. It sets up both a wallet client for signing transactions and a public client for reading blockchain data.

```typescript
import { createWalletClient, createPublicClient, custom, http } from "viem";
import { arbitrum } from "viem/chains";

const walletClient = createWalletClient({
  chain: arbitrum,
  transport: custom(window.ethereum),
});

const publicClient = createPublicClient({
  chain: arbitrum,
  transport: http(),
});

const [account] = await walletClient.getAddresses();

```

--------------------------------

### Example Payout Response

Source: https://docs.request.network/api-setup/integration-tutorial

This is an example of the JSON response you should expect after successfully creating a payout. It includes a `requestId`, `paymentReference`, transaction details, and metadata about the payment process.

```json
{
  "requestId": "011d9f76e07a678b8321ccfaa300efd4d80832652b8bbc07ea4069ca71006210b5",
  "paymentReference": "0xe23a6b02059c2b30",
  "transactions": [
    {
      "data": "0xb868980b00000000000000000000000029eab540117632a112ea29ba8be686a1b66467a700000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000dead0000000000000000000000000000000000000000000000000000000000000008e23a6b02059c2b30000000000000000000000000000000000000000000000000",
      "to": "0xe11BF2fDA23bF0A98365e1A4c04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x02c68af0bb140000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "paymentTransactionIndex": 0
  }
}
```

--------------------------------

### Currency Codes and Examples

Source: https://docs.request.network/resources/supported-chains-and-currencies

Examples of currency identifiers used across different networks and types, including native tokens, ERC20 tokens, and fiat currencies.

```javascript
"ETH-mainnet"
"USDC-mainnet"
"USDC-base"
"USDT-arbitrum-one"
"USDT0-arbitrum-one"
```

```javascript
"USDT-tron"
"USDC-tron"
```

```javascript
"USD"
"EUR"
"GBP"
```

--------------------------------

### USD Conversion Routes on Mainnet

Source: https://docs.request.network/api-reference/currencies/get-conversion-routes-for-a-specific-currency

Example response showing conversion routes for USD on the mainnet. Includes details like currency ID, symbol, decimals, address, network, type, and chain ID for each route.

```json
{
  "currencyId": "USD",
  "network": "mainnet",
  "conversionRoutes": [
    {
      "id": "USDT-mainnet",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "network": "mainnet",
      "type": "ERC20",
      "hash": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "chainId": 1
    },
    {
      "id": "ETH-mainnet",
      "name": "Ether",
      "symbol": "ETH",
      "decimals": 18,
      "address": "0xf5af88e117747e87fc5929f2ff87221b1447652e",
      "network": "mainnet",
      "type": "ETH",
      "hash": "0xf5af88e117747e87fc5929f2ff87221b1447652e",
      "chainId": 1
    }
  ]
}
```