Crypto Payment Gateway - Merchant Dashboard API

Overview

This document specifies all REST API endpoints needed for the merchant dashboard to manage crypto payment gateway operations. These endpoints allow merchants to view payment sessions, monitor crypto addresses, track balances, manage withdrawals, and access detailed transaction information.

---

Authentication

All dashboard API requests require authentication using your API Key:

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

API Key Types:

• Test Key (test_sk_...) - Access test mode data only
• Production Key (live_sk_...) - Access production data only

---

1. Payment Sessions Management

1.1 List All Payment Sessions

Get a paginated list of all checkout sessions created by the merchant.

Endpoint: GET /api/v1/dashboard/sessions

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
status	string	all	Filter by status: all, pending, paid, failed, expired
network	string	all	Filter by network: all, BSC, ETH, POL, TRX, SOL
currency	string	all	Filter by currency: all, USDT, USDC
start_date	string		Filter from date (ISO 8601)
end_date	string		Filter to date (ISO 8601)
search	string		Search by reference, customer email, or session ID
sort_by	string	created_at	Sort field: created_at, amount, paid_at
sort_order	string	desc	Sort order: asc, desc

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
        "reference": "ORDER-12345",
        "amount": 100.00,
        "currency": "USDT",
        "network": "BSC",
        "status": "paid",
        "payment_method": "crypto",
        "customer_email": "customer@example.com",
        "customer_name": "John Doe",
        "description": "Product purchase",
        "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "blockchain_tx_hash": "0xabc123def456...",
        "paid_amount": 100.00,
        "paid_at": "2026-01-30T18:10:23Z",
        "created_at": "2026-01-30T18:00:00Z",
        "expires_at": "2026-01-30T18:15:00Z",
        "payment_url": "https://payments-api-dev.../pay/11fec830-..."
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 98,
      "items_per_page": 20,
      "has_next": true,
      "has_prev": false
    },
    "summary": {
      "total_sessions": 98,
      "total_paid": 75,
      "total_pending": 12,
      "total_failed": 8,
      "total_expired": 3
    }
  }
}

1.2 Get Session Details

Get comprehensive details for a specific payment session.

Endpoint: GET /api/v1/dashboard/sessions/:sessionId

Response:

{
  "success": true,
  "data": {
    "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
    "reference": "ORDER-12345",
    "amount": 100.00,
    "currency": "USDT",
    "network": "BSC",
    "status": "paid",
    "payment_method": "crypto",
    
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    
    "description": "Product purchase",
    "callback_url": "https://yoursite.com/payment/callback",
    "metadata": {
      "order_id": "12345",
      "product_sku": "PROD-ABC"
    },
    
    "payment_details": {
      "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "deposit_address_id": 42,
      "blockchain_tx_hash": "0xabc123def456...",
      "blockchain_explorer_url": "https://bscscan.com/tx/0xabc123def456...",
      "paid_amount": 100.00,
      "expected_amount": 100.00,
      "confirmations": 15,
      "required_confirmations": 12,
      "paid_at": "2026-01-30T18:10:23Z"
    },
    
    "timeline": [
      {
        "event": "session_created",
        "timestamp": "2026-01-30T18:00:00Z",
        "details": "Checkout session created"
      },
      {
        "event": "address_assigned",
        "timestamp": "2026-01-30T18:00:01Z",
        "details": "Deposit address assigned"
      },
      {
        "event": "payment_received",
        "timestamp": "2026-01-30T18:10:23Z",
        "details": "Payment received (100 USDT)"
      },
      {
        "event": "payment_confirmed",
        "timestamp": "2026-01-30T18:12:00Z",
        "details": "Payment confirmed on blockchain"
      },
      {
        "event": "webhook_sent",
        "timestamp": "2026-01-30T18:12:02Z",
        "details": "Webhook notification sent"
      },
      {
        "event": "funds_swept",
        "timestamp": "2026-01-30T18:15:00Z",
        "details": "Funds swept to hot wallet"
      }
    ],
    
    "created_at": "2026-01-30T18:00:00Z",
    "updated_at": "2026-01-30T18:12:02Z",
    "expires_at": "2026-01-30T18:15:00Z",
    "payment_url": "https://payments-api-dev.../pay/11fec830-..."
  }
}

---

2. Crypto Addresses Management

2.1 List All Deposit Addresses

View all generated crypto deposit addresses with complete details.

Endpoint: GET /api/v1/dashboard/addresses

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
network	string	all	Filter by network
currency	string	all	Filter by currency
status	string	all	Filter: all, active, assigned, unassigned, inactive
has_balance	boolean		Only show addresses with balance > 0
sweep_status	string	all	Filter: all, pending, swept, failed
sort_by	string	created_at	Sort field
sort_order	string	desc	Sort order

Response:

{
  "success": true,
  "data": {
    "addresses": [
      {
        "id": 42,
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "network": "BSC",
        "currency": "USDT",
        "is_active": true,
        "is_assigned": true,
        "assigned_to_session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
        "assigned_to_reference": "ORDER-12345",
        
        "balance": {
          "current": "0.00000000",
          "total_received": "100.00000000",
          "total_swept": "100.00000000"
        },
        
        "sweep_info": {
          "status": "swept",
          "last_swept_at": "2026-01-30T18:15:00Z",
          "sweep_tx_hash": "0xdef789ghi012...",
          "sweep_explorer_url": "https://bscscan.com/tx/0xdef789ghi012..."
        },
        
        "usage": {
          "times_reused": 3,
          "last_used_at": "2026-01-30T18:00:01Z",
          "first_used_at": "2026-01-20T10:00:00Z"
        },
        
        "gas_funding": {
          "funded_at": "2026-01-20T10:00:00Z",
          "funding_tx_hash": "0xgas123...",
          "funding_amount": "0.01000000"
        },
        
        "last_checked_at": "2026-01-30T18:20:00Z",
        "created_at": "2026-01-20T09:59:00Z",
        "updated_at": "2026-01-30T18:15:05Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "total_items": 56,
      "items_per_page": 20
    },
    "summary": {
      "total_addresses": 56,
      "active_addresses": 50,
      "assigned_addresses": 15,
      "addresses_with_balance": 5,
      "total_balance_across_all": "250.50000000"
    }
  }
}

2.2 Get Address Details

Get comprehensive details for a specific deposit address including all associated sessions.

Endpoint: GET /api/v1/dashboard/addresses/:addressId

Response:

{
  "success": true,
  "data": {
    "id": 42,
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "BSC",
    "currency": "USDT",
    "is_active": true,
    "is_assigned": false,
    
    "balance": {
      "current": "0.00000000",
      "current_usd": 0.00,
      "total_received": "350.00000000",
      "total_received_usd": 350.00,
      "total_swept": "350.00000000",
      "total_swept_usd": 350.00
    },
    
    "sweep_history": [
      {
        "swept_at": "2026-01-30T18:15:00Z",
        "amount": "100.00000000",
        "tx_hash": "0xdef789ghi012...",
        "explorer_url": "https://bscscan.com/tx/0xdef789ghi012...",
        "status": "confirmed"
      },
      {
        "swept_at": "2026-01-25T12:30:00Z",
        "amount": "250.00000000",
        "tx_hash": "0xabc456def789...",
        "explorer_url": "https://bscscan.com/tx/0xabc456def789...",
        "status": "confirmed"
      }
    ],
    
    "sessions": [
      {
        "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
        "reference": "ORDER-12345",
        "amount": 100.00,
        "status": "paid",
        "paid_at": "2026-01-30T18:10:23Z",
        "created_at": "2026-01-30T18:00:00Z"
      },
      {
        "session_id": "22abc123-...",
        "reference": "ORDER-12340",
        "amount": 250.00,
        "status": "paid",
        "paid_at": "2026-01-25T12:15:00Z",
        "created_at": "2026-01-25T12:00:00Z"
      }
    ],
    
    "blockchain_transactions": [
      {
        "tx_hash": "0xabc123def456...",
        "type": "incoming",
        "amount": "100.00000000",
        "from": "0x1234...",
        "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "timestamp": "2026-01-30T18:10:23Z",
        "confirmations": 150,
        "explorer_url": "https://bscscan.com/tx/0xabc123def456..."
      }
    ],
    
    "usage": {
      "times_reused": 2,
      "last_used_at": "2026-01-30T18:00:01Z",
      "first_used_at": "2026-01-25T12:00:00Z"
    },
    
    "created_at": "2026-01-20T09:59:00Z",
    "updated_at": "2026-01-30T18:15:05Z"
  }
}

2.3 Check Address Balance (Real-time)

Trigger a real-time blockchain balance check for an address.

Endpoint: POST /api/v1/dashboard/addresses/:addressId/check-balance

Response:

{
  "success": true,
  "data": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "BSC",
    "currency": "USDT",
    "balance": "0.00000000",
    "balance_usd": 0.00,
    "last_checked_at": "2026-01-31T17:30:00Z",
    "blockchain_confirmed": true
  }
}

---

3. Merchant Balance & Earnings

3.1 Get Crypto Payment Gateway Balance

View total balance and earnings from crypto payment gateway.

Endpoint: GET /api/v1/dashboard/balance/crypto

Response:

{
  "success": true,
  "data": {
    "available_balance": {
      "amount": "9850.50000000",
      "usd_value": 9850.50,
      "breakdown": [
        {
          "currency": "USDT",
          "amount": "7500.00000000",
          "usd_value": 7500.00,
          "networks": [
            { "network": "BSC", "amount": "5000.00000000" },
            { "network": "ETH", "amount": "1500.00000000" },
            { "network": "POL", "amount": "1000.00000000" }
          ]
        },
        {
          "currency": "USDC",
          "amount": "2350.50000000",
          "usd_value": 2350.50,
          "networks": [
            { "network": "SOL", "amount": "1350.50000000" },
            { "network": "ETH", "amount": "1000.00000000" }
          ]
        }
      ]
    },
    
    "pending_balance": {
      "amount": "150.00000000",
      "usd_value": 150.00,
      "description": "Awaiting blockchain confirmations"
    },
    
    "total_earnings": {
      "all_time": "25500.75000000",
      "this_month": "3250.00000000",
      "this_week": "750.00000000",
      "today": "100.00000000"
    },
    
    "total_withdrawn": {
      "all_time": "15500.00000000",
      "this_month": "2000.00000000"
    },
    
    "platform_fees_paid": {
      "all_time": "255.00750000",
      "this_month": "32.50000000"
    },
    
    "last_updated": "2026-01-31T17:30:00Z"
  }
}

3.2 Get Balance Breakdown by Network

Get detailed balance information for each blockchain network.

Endpoint: GET /api/v1/dashboard/balance/networks

Response:

{
  "success": true,
  "data": {
    "networks": [
      {
        "network": "BSC",
        "total_balance": "5000.00000000",
        "currencies": [
          {
            "currency": "USDT",
            "balance": "5000.00000000",
            "addresses_count": 15,
            "addresses_with_balance": 3
          }
        ],
        "hot_wallet": "0xHOTWALLET123...",
        "total_swept": "45000.00000000",
        "last_sweep": "2026-01-30T18:15:00Z"
      },
      {
        "network": "ETH",
        "total_balance": "2500.00000000",
        "currencies": [
          {
            "currency": "USDT",
            "balance": "1500.00000000",
            "addresses_count": 10,
            "addresses_with_balance": 2
          },
          {
            "currency": "USDC",
            "balance": "1000.00000000",
            "addresses_count": 8,
            "addresses_with_balance": 1
          }
        ],
        "hot_wallet": "0xHOTWALLET456...",
        "total_swept": "18000.00000000",
        "last_sweep": "2026-01-30T15:20:00Z"
      }
    ]
  }
}

---

4. Transaction History

4.1 List All Blockchain Transactions

View all incoming and outgoing blockchain transactions.

Endpoint: GET /api/v1/dashboard/transactions

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page
type	string	all	Filter: all, incoming, outgoing, sweep
network	string	all	Filter by network
currency	string	all	Filter by currency
start_date	string		From date
end_date	string		To date
min_amount	number		Minimum amount
max_amount	number		Maximum amount

Response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": 1234,
        "tx_hash": "0xabc123def456...",
        "type": "incoming",
        "network": "BSC",
        "currency": "USDT",
        "amount": "100.00000000",
        "amount_usd": 100.00,
        "from_address": "0xcustomer123...",
        "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "confirmations": 150,
        "status": "confirmed",
        "explorer_url": "https://bscscan.com/tx/0xabc123def456...",
        "timestamp": "2026-01-30T18:10:23Z",
        "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
        "reference": "ORDER-12345"
      },
      {
        "id": 1235,
        "tx_hash": "0xdef789ghi012...",
        "type": "sweep",
        "network": "BSC",
        "currency": "USDT",
        "amount": "100.00000000",
        "amount_usd": 100.00,
        "from_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "to_address": "0xHOTWALLET123...",
        "confirmations": 120,
        "status": "confirmed",
        "explorer_url": "https://bscscan.com/tx/0xdef789ghi012...",
        "timestamp": "2026-01-30T18:15:00Z",
        "gas_fee": "0.00050000"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 15,
      "total_items": 298
    },
    "summary": {
      "total_transactions": 298,
      "total_incoming": 250,
      "total_outgoing": 48,
      "total_volume": "25500.75000000"
    }
  }
}

4.2 Get Transaction Details

Get comprehensive details for a specific blockchain transaction.

Endpoint: GET /api/v1/dashboard/transactions/:txHash

Response:

{
  "success": true,
  "data": {
    "tx_hash": "0xabc123def456...",
    "type": "incoming",
    "network": "BSC",
    "currency": "USDT",
    "amount": "100.00000000",
    "amount_usd": 100.00,
    
    "addresses": {
      "from": "0xcustomer123...",
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    
    "blockchain_info": {
      "block_number": 12345678,
      "block_hash": "0xblock123...",
      "confirmations": 150,
      "gas_used": "65000",
      "gas_price": "5000000000",
      "gas_fee": "0.00032500",
      "timestamp": "2026-01-30T18:10:23Z"
    },
    
    "status": "confirmed",
    "explorer_url": "https://bscscan.com/tx/0xabc123def456...",
    
    "related_session": {
      "session_id": "11fec830-6b48-4e1e-b504-eef2ad0bbc01",
      "reference": "ORDER-12345",
      "customer_email": "customer@example.com",
      "status": "paid"
    },
    
    "created_at": "2026-01-30T18:10:23Z",
    "confirmed_at": "2026-01-30T18:11:00Z"
  }
}

---

5. Withdrawals Management

5.1 List Withdrawal Requests

View all withdrawal requests and their status.

Endpoint: GET /api/v1/dashboard/withdrawals

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page
status	string	all	Filter: all, pending, processing, completed, failed
method	string	all	Filter: all, crypto, fiat

Response:

{
  "success": true,
  "data": {
    "withdrawals": [
      {
        "id": 789,
        "amount": "5000.00000000",
        "currency": "USDT",
        "method": "crypto",
        "status": "completed",
        
        "crypto_details": {
          "network": "BSC",
          "address": "0xmerchant_wallet...",
          "tx_hash": "0xwithdrawal123...",
          "explorer_url": "https://bscscan.com/tx/0xwithdrawal123..."
        },
        
        "fees": {
          "fee_amount": "5.00000000",
          "fee_percentage": "0.1",
          "net_amount": "4995.00000000"
        },
        
        "created_at": "2026-01-28T10:00:00Z",
        "processed_at": "2026-01-28T10:05:00Z",
        "completed_at": "2026-01-28T10:10:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 2,
      "total_items": 25
    },
    "summary": {
      "total_withdrawn": "50000.00000000",
      "pending_withdrawals": "1500.00000000",
      "this_month": "8000.00000000"
    }
  }
}

5.2 Create Withdrawal Request

Request a withdrawal of available balance.

Endpoint: POST /api/v1/dashboard/withdrawals/create

Request:

{
  "amount": 5000.00,
  "method": "crypto",
  "crypto_network": "BSC",
  "crypto_address": "0xmerchant_wallet...",
  "note": "Monthly settlement"
}

Response:

{
  "success": true,
  "data": {
    "withdrawal_id": 790,
    "amount": "5000.00000000",
    "fee_amount": "5.00000000",
    "net_amount": "4995.00000000",
    "status": "pending",
    "estimated_completion": "2026-01-31T18:00:00Z",
    "created_at": "2026-01-31T17:30:00Z"
  }
}

5.3 Get Withdrawal Details

Endpoint: GET /api/v1/dashboard/withdrawals/:withdrawalId

Response: Similar to withdrawal list item with additional timeline.

---

6. Analytics & Reports

6.1 Payment Analytics

Get comprehensive payment analytics for crypto gateway.

Endpoint: GET /api/v1/dashboard/analytics/payments

Query Parameters:

Parameter	Type	Default	Description
period	string	30d	Time period: 24h, 7d, 30d, 90d, 1y, all
start_date	string		Custom start date
end_date	string		Custom end date
group_by	string	day	Group by: hour, day, week, month

Response:

{
  "success": true,
  "data": {
    "period": "30d",
    "start_date": "2026-01-01T00:00:00Z",
    "end_date": "2026-01-31T23:59:59Z",
    
    "overview": {
      "total_sessions": 245,
      "successful_sessions": 198,
      "failed_sessions": 32,
      "expired_sessions": 15,
      "success_rate": 80.82,
      "total_volume": "19800.00000000",
      "total_volume_usd": 19800.00,
      "average_transaction": "100.00000000",
      "platform_fees": "198.00000000"
    },
    
    "by_network": [
      {
        "network": "BSC",
        "sessions": 120,
        "volume": "12000.00000000",
        "percentage": 60.61
      },
      {
        "network": "ETH",
        "sessions": 45,
        "volume": "4500.00000000",
        "percentage": 22.73
      },
      {
        "network": "POL",
        "sessions": 20,
        "volume": "2000.00000000",
        "percentage": 10.10
      },
      {
        "network": "SOL",
        "sessions": 10,
        "volume": "1000.00000000",
        "percentage": 5.05
      },
      {
        "network": "TRX",
        "sessions": 3,
        "volume": "300.00000000",
        "percentage": 1.52
      }
    ],
    
    "by_currency": [
      {
        "currency": "USDT",
        "sessions": 150,
        "volume": "15000.00000000",
        "percentage": 75.76
      },
      {
        "currency": "USDC",
        "sessions": 48,
        "volume": "4800.00000000",
        "percentage": 24.24
      }
    ],
    
    "timeline": [
      {
        "date": "2026-01-01",
        "sessions": 8,
        "successful": 6,
        "volume": "600.00000000"
      },
      {
        "date": "2026-01-02",
        "sessions": 10,
        "successful": 8,
        "volume": "800.00000000"
      }
      // ... more days
    ],
    
    "top_hours": [
      { "hour": 14, "sessions": 35, "label": "2:00 PM" },
      { "hour": 15, "sessions": 30, "label": "3:00 PM" },
      { "hour": 10, "sessions": 25, "label": "10:00 AM" }
    ],
    
    "top_amounts": [
      { "amount": "100.00", "count": 85 },
      { "amount": "50.00", "count": 42 },
      { "amount": "200.00", "count": 28 }
    ]
  }
}

6.2 Export Transactions

Export transaction data in various formats.

Endpoint: GET /api/v1/dashboard/analytics/export

Query Parameters:

Parameter	Type	Required	Description
format	string	Yes	Format: csv, xlsx, json, pdf
type	string	Yes	Data type: sessions, transactions, addresses
start_date	string	Yes	Start date
end_date	string	Yes	End date
filters	object	No	Additional filters

Response:

{
  "success": true,
  "data": {
    "export_id": "exp_123456",
    "download_url": "https://api.../exports/exp_123456.csv",
    "expires_at": "2026-02-01T17:30:00Z",
    "file_size": "245KB",
    "record_count": 198
  }
}

---

7. Webhook Configuration

7.1 Get Webhook Settings

Endpoint: GET /api/v1/dashboard/webhooks/config

Response:

{
  "success": true,
  "data": {
    "webhook_url": "https://yoursite.com/webhooks/payment",
    "webhook_secret": "whsec_123456...",
    "enabled": true,
    "events": [
      "payment.confirmed",
      "payment.failed",
      "session.expired"
    ],
    "retry_config": {
      "max_retries": 3,
      "retry_interval": 300
    }
  }
}

7.2 Update Webhook Settings

Endpoint: PUT /api/v1/dashboard/webhooks/config

Request:

{
  "webhook_url": "https://yoursite.com/webhooks/payment",
  "enabled": true,
  "events": ["payment.confirmed", "payment.failed"]
}

7.3 Test Webhook

Send a test webhook event.

Endpoint: POST /api/v1/dashboard/webhooks/test

Response:

{
  "success": true,
  "data": {
    "test_sent": true,
    "response_status": 200,
    "response_time_ms": 125,
    "webhook_url": "https://yoursite.com/webhooks/payment"
  }
}

---

8. Statistics & Summaries

8.1 Dashboard Overview

Get high-level dashboard statistics.

Endpoint: GET /api/v1/dashboard/overview

Response:

{
  "success": true,
  "data": {
    "balance": {
      "available": "9850.50000000",
      "pending": "150.00000000"
    },
    
    "today": {
      "sessions": 12,
      "successful": 10,
      "volume": "1000.00000000",
      "revenue": "990.00000000"
    },
    
    "this_week": {
      "sessions": 75,
      "successful": 62,
      "volume": "6200.00000000",
      "revenue": "6138.00000000"
    },
    
    "this_month": {
      "sessions": 245,
      "successful": 198,
      "volume": "19800.00000000",
      "revenue": "19602.00000000"
    },
    
    "recent_sessions": [
      {
        "session_id": "11fec830-...",
        "reference": "ORDER-12345",
        "amount": 100.00,
        "status": "paid",
        "created_at": "2026-01-31T17:00:00Z"
      }
      // ... 4 more recent sessions
    ],
    
    "pending_actions": {
      "pending_sessions": 5,
      "addresses_needing_sweep": 3,
      "pending_withdrawals": 1
    }
  }
}

---

Error Responses

All endpoints follow a consistent error response format:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid network specified",
    "details": {
      "parameter": "network",
      "allowed_values": ["BSC", "ETH", "POL", "TRX", "SOL"]
    }
  }
}

Common Error Codes:

• UNAUTHORIZED - Invalid or missing API key
• FORBIDDEN - Action not allowed for your account
• NOT_FOUND - Resource not found
• INVALID_PARAMETER - Invalid request parameter
• INSUFFICIENT_BALANCE - Not enough balance for withdrawal
• RATE_LIMIT_EXCEEDED - Too many requests
• SERVER_ERROR - Internal server error

HTTP Status Codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Rate Limit Exceeded
• 500 - Server Error

---

Rate Limiting

Dashboard API endpoints are rate limited:

• Standard endpoints: 100 requests per minute
• Analytics endpoints: 20 requests per minute
• Export endpoints: 5 requests per hour

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1672531200

---

Pagination

All list endpoints support pagination with consistent response format:

{
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "total_items": 195,
    "items_per_page": 20,
    "has_next": true,
    "has_prev": false
  }
}

---

Best Practices

1. Cache Dashboard Data - Don't refresh balance every second
2. Use Webhooks - Don't poll for payment updates
3. Handle Pagination - Don't fetch all records at once
4. Respect Rate Limits - Implement exponential backoff
5. Store Export Files - Download exports promptly (24h expiry)
6. Monitor Webhook Health - Check webhook delivery status
7. Use Filters - Filter data on server-side for performance

---

Support

For technical support:

• Email: hi@rach.finance
• Dashboard: https://payments.rach.finance/dashboard
• Documentation: https://payments.rach.finance/docs