Guides
Gateway Server

DeroPay Gateway Server

The gateway server is a standalone HTTP server that wraps the dero-pay SDK into a clean REST API. It connects to your DERO wallet, creates invoices, monitors payments, fires webhooks, and manages escrow — all accessible via standard HTTP endpoints.

This is the same architecture as BTCPay Server: the gateway is the engine, and everything else (plugins, widgets, payment links) is a thin client.

Architecture

┌─────────────────────────────────────────┐
│           YOUR INFRASTRUCTURE            │
│                                          │
│  ┌──────────┐    ┌──────────┐           │
│  │ DERO     │    │ DERO     │           │
│  │ Daemon   │    │ Wallet   │           │
│  │ :10102   │    │ :10103   │           │
│  └────┬─────┘    └────┬─────┘           │
│       └──────┬────────┘                  │
│              │                           │
│       ┌──────▼──────┐                    │
│       │  DeroPay    │                    │
│       │  Gateway    │ ← your API key     │
│       │  :3080      │                    │
│       └──────┬──────┘                    │
│              │                           │
└──────────────┼───────────────────────────┘
               │ REST API
    ┌──────────┼──────────────┐
    │          │              │
┌───▼───┐ ┌───▼────┐ ┌──────▼─────┐
│Widget │ │WooCom  │ │Payment     │
│       │ │Plugin  │ │Links       │
└───────┘ └────────┘ └────────────┘

Everything runs on your own infrastructure. You control the wallet, the daemon, the gateway, and the data.

Install and Configure

git clone https://github.com/DHEBP/DeroPay.git
cd DeroPay/apps/gateway
cp .env.example .env

Edit .env with your wallet details:

DEROPAY_WALLET_RPC_URL=http://127.0.0.1:10103/json_rpc
DEROPAY_DAEMON_RPC_URL=http://127.0.0.1:10102/json_rpc
DEROPAY_API_KEY=your-secret-api-key
DEROPAY_WEBHOOK_URL=https://yourstore.com/webhook
DEROPAY_WEBHOOK_SECRET=your-webhook-secret

Generate an API Key

bun run src/generate-key.ts

Start the Server

bun install
bun run start

Verify It's Running

curl http://localhost:3080/health
{
  "status": "ok",
  "wallet": "connected",
  "balance": "125.00000"
}

API Endpoints

Public (no API key)

MethodRoutePurpose
GET/healthWallet connectivity + balance
GET/status?invoiceId=xInvoice status (for checkout widgets)
GET/priceCurrent DERO price (USD, BTC)
GET/convert?amount=9.99&currency=usdFiat → DERO conversion

Authenticated (requires x-api-key header)

MethodRoutePurpose
POST/invoicesCreate an invoice
GET/invoices/:idGet invoice details
GET/invoicesList/filter invoices
GET/statsAggregate payment stats
POST/escrow/:id/:actionEscrow operations
GET/escrowsList escrow invoices

Creating an Invoice

curl -X POST http://localhost:3080/invoices \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "Order #1234",
    "amount": 150000,
    "ttl": 900
  }'

With fiat pricing (auto-converts to DERO):

curl -X POST http://localhost:3080/invoices \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "T-Shirt",
    "fiatAmount": 29.99,
    "currency": "usd"
  }'

The gateway fetches live DERO prices from CoinGecko and TradeOgre (with fallback). Merchants price products in fiat; the gateway converts at checkout time.

Webhooks

The gateway sends HMAC-SHA256 signed HTTP POST notifications on every invoice state change:

{
  "invoiceId": "inv_abc123",
  "status": "completed",
  "amount": "150000",
  "amountReceived": "150000",
  "payments": [{ "txHash": "...", "amount": "150000" }]
}

Verify the signature:

import { verifyWebhookSignature } from "dero-pay/server";
 
const isValid = verifyWebhookSignature(
  rawBody,
  request.headers["x-deropay-signature"],
  process.env.WEBHOOK_SECRET
);

What's Next

The gateway is the foundation. Connect it to:

PrerequisitesPayment Links