Skip to main content

​
Welcome to Request Network

Get started with Request Network in just a few minutes. This guide will walk you through setting up your account, obtaining API keys, and making your first payment.

​
Quick Setup

1

Create Account

Sign up for a free Request Network account at dashboard.request.network
2

Get API Keys

Generate your Client ID from the Dashboard
3

Create Your First Request

Use the API to create a payment request
4

Process Payment

Get payment calldata and execute the transaction

​
Account Setup

​
Request Dashboard Registration

Create Your Account

Sign up at dashboard.request.network to get started. All accounts include:
  • Free API access with generous limits
  • API documentation and tools
  • Community support

​
Client ID Generation

  1. Log in to Request Dashboard
  2. Create a payment destination first if you haven’t — the Client IDs section is only available once a destination exists. From the Home page, click Set up payment destination and pick the chain + token you want to receive on.
  3. Open Manage Destination → Client IDs
  4. Click Generate your first Client ID (or Generate New Client ID if you already have one)
  5. Copy and securely store the Client ID
Security Best Practices
  • Store API keys in environment variables
  • Never commit keys to version control
  • Rotate keys regularly

​
Your First Integration

Let’s create a simple Node.js server that integrates with the Request Network API to create payments and track their status.

​
Project Setup

Create a new project and install dependencies: 
mkdir request-api-demo
cd request-api-demo
npm init -y
npm install dotenv
Create a .env file: 
RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2

​
Create a Payment

Create an index.js file: 
require('dotenv').config();

async function createPayment() {
  try {
    const response = await fetch(`${process.env.RN_API_URL}/payouts`, {
      method: 'POST',
      headers: {
        'x-client-id': process.env.RN_CLIENT_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        payee: '0x...', // Your wallet address
        amount: '0.1',
        invoiceCurrency: 'ETH-sepolia-sepolia',
        paymentCurrency: 'ETH-sepolia-sepolia'
      })
    });

    if (!response.ok) {
      const errorText = await response.text();
      console.error('API Error:', errorText);
      return;
    }

    const data = await response.json();
    console.log('Payment created:', {
      requestId: data.requestId,
      paymentReference: data.paymentReference,
      transactions: data.transactions,
      metadata: data.metadata
    });
    
    return data;
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createPayment();
Run it: 
node index.js
The response will include:
  • requestId — Unique identifier for the request
  • paymentReference — Used to track the payment
  • transactions — Array of transaction calldata to execute
  • metadata — Additional info like stepsRequired and needsApproval

​
Understanding the Response

{
  "requestId": "011d9f76e07a678b8321ccfaa300efd4d80832652b8bbc07ea4069ca71006210b5",
  "paymentReference": "0xe23a6b02059c2b30",
  "transactions": [
    {
      "data": "0xb868980b000000000000000000000000...",
      "to": "0xe11BF2fDA23bF0A98365e1A4c04A87C9339e8687",
      "value": {
        "type": "BigNumber",
        "hex": "0x02c68af0bb140000"
      }
    }
  ],
  "metadata": {
    "stepsRequired": 1,
    "needsApproval": false,
    "paymentTransactionIndex": 0
  }
}
Note: The amount is in human-readable format. No BigNumber conversions needed!

​
Setting Up Webhooks

To track payment status in real-time, set up a webhook endpoint: 
const crypto = require('crypto');
const express = require('express');

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

// Webhook handler
app.post('/webhooks', async (req, res) => {
  const signature = req.headers['x-request-network-signature'];
  const webhookSecret = process.env.RN_WEBHOOK_SECRET;

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send({ error: 'Invalid signature' });
  }

  const { requestId, event } = req.body;
  console.log(`Webhook: ${event} for request ${requestId}`);
  
  // Handle different events
  switch (event) {
    case 'payment.confirmed':
      console.log('Payment confirmed!');
      // Update your database, send email, etc.
      break;
    case 'payment.pending':
      console.log('Payment pending...');
      break;
  }

  res.send({ code: 200, message: 'Webhook received' });
});

​
Testing Webhooks Locally

Since webhooks can’t reach your local server directly, use ngrok: 
ngrok http 3000
Copy the HTTPS URL (e.g., https://abc123.ngrok.io/webhooks) and register it via the Auth API: 
curl -X POST "https://auth.request.network/v1/webhook" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $RN_CLIENT_ID" \
  -d '{ "url": "https://abc123.ngrok.io/webhooks" }'
The response includes a one-time secret — copy it to your .env: 
RN_WEBHOOK_SECRET=your_webhook_secret_here

​
Environment Configuration

Set up environment variables for secure API key management: 
# Request Network Configuration
RN_CLIENT_ID=your_client_id_here
RN_API_URL=https://api.request.network/v2

# Webhook Configuration (optional)
RN_WEBHOOK_SECRET=your_webhook_secret_here

module.exports = {
  requestNetwork: {
    clientId: process.env.RN_CLIENT_ID,
    apiUrl: process.env.RN_API_URL || 'https://api.request.network/v2',
    webhookSecret: process.env.RN_WEBHOOK_SECRET,
  }
};

​
What’s Next?

Now that you’ve made your first API call, explore more features:

📚 API Features

Learn about different payment types and features

🔍 Payment Detection

Understand how payments are tracked

⚡ Integration Tutorial

Complete tutorial with backend + frontend

​
Troubleshooting

​
Common Issues

  • Verify Client ID is correct
  • Check that you’re using the right header: x-client-id
  • Ensure the Client ID hasn’t been revoked
  • Check required fields: payee, amount, invoiceCurrency, paymentCurrency
  • Ensure amount is a string (e.g., “0.1”)
  • Verify currency IDs are valid
  • Verify webhook URL is publicly accessible
  • Check webhook signature verification
  • Ensure the webhook is active (toggle via PUT /v1/webhook/:id on the Auth API)
You’re all set! You’ve created your first payment request with Request Network. For a complete working example with frontend, check out the Integration Tutorial.