API Integration Guide

VirtexGate Payment Gateway · REST API · v1

Overview

VirtexGate is a cloud-native crypto payment gateway. Integrate our API to create invoices from your server — VirtexGate calculates the crypto amount, assigns a unique payment address, verifies the payment, and notifies your endpoint via webhook the moment it's confirmed.

Base URL

https://<your-host>/api

Supported Coins

BTC ETH USDT/Tron USDT/Polygon

Integration Flow

API Key → Create Invoice → Buyer pays via Checkout → Webhook confirms

Your Server

→

POST /invoices

→

checkoutUrl

→

Buyer pays

→

Webhook invoice.paid

Authentication

X-Api-Key Store API Key

All integration endpoints use your store's API key. Set it as the X-Api-Key header on every request. Format: vgk_ + base64url(32 bytes). Keys are generated once and shown only once — store yours in an environment variable.

X-Api-Key: vgk_abc123...

Where to get it: Gateway Dashboard → Store → Settings → Rotate API Key. The previous key is immediately invalidated on rotation.

Quick Start

Phase 1 — Dashboard Setup Do this once in the Gateway UI

Create your account at the Gateway dashboard. Check your inbox for the verification email and click the confirmation link before logging in.

Create a store

A store holds your wallets, API key, and settings. You can have multiple stores (one per website or product line).

Sidebar → Stores → + New Store

Fill in the store name and optionally set a default currency, invoice expiry, and webhook URL. Save — you'll be taken to the store overview.

After saving, copy the Store ID from the store overview page — you'll need it for API calls.

Add a wallet

A wallet tells VirtexGate which coin(s) you want to accept. Generate a secure wallet directly from the dashboard — one per coin type. Setup takes seconds.

Store → Wallets tab → + Add Wallet → Select coin type → Save

BTC ETH USDT / Tron USDT / Polygon

Add one wallet per coin you wish to accept. You can add more later without re-generating the API key.

Generate your API key

The API key authorises your backend to create invoices for this store. It is shown once — copy it immediately into your server's environment variables.

Store → Settings tab → Rotate API Key → Copy key

The key is displayed only once. If you close the dialog without copying it, you must rotate again — the old key is immediately invalidated. Store it in an environment variable, never in source code.

VirtexGate_API_KEY=vgk_••••••••••••••••••••••••

Phase 2 — API Integration Add these two calls to your backend

Create an invoice server-side

Call POST /invoices from your backend when a customer checks out. Pass your storeId, amount, and currency.

POST /api/invoices → { id, checkoutUrl, expiresAt }

Redirect the buyer to checkout frontend

Send the buyer to the checkoutUrl returned in step 5. They select a coin, scan the QR code, and pay. Your webhook fires when payment is confirmed.

window.location = invoice.checkoutUrl

Minimal integration (curl)

# Create invoice from your server (steps 5-6)
curl -s -X POST https://your-host/api/invoices \
  -H "X-Api-Key: vgk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId":         "YOUR_STORE_ID",
    "amount":          25.00,
    "fiatCurrency":    "USD",
    "externalOrderId": "order-42",
    "redirectUrl":     "https://myshop.com/thank-you"
  }'

# Returns:
# { "id": "3fa85f64...", "checkoutUrl": "https://your-host/checkout/3fa85f64...", "expiresAt": "..." }

# Redirect the buyer to checkoutUrl — they scan the QR and pay

Create Invoice

The single server-side call your backend makes. Requires X-Api-Key.

Create a payment invoice. Returns a checkout URL to redirect the buyer to. The buyer scans a QR code and pays in their chosen coin.

Request

Field	Type	Notes
storeId	guid	required — your store ID
amount	decimal	required — fiat amount ≥ 0.01
fiatCurrency	string	required — e.g. USD, EUR (max 10 chars)
externalOrderId	string?	your order reference — echoed in webhooks
buyerEmail	string?	optional — for receipt
buyerName	string?	optional
description	string?	optional — shown on checkout page
redirectUrl	string?	where to send the buyer after payment completes

Response 201

{ id, checkoutUrl, expiresAt, amount, fiatCurrency }

Errors

404 — store not found | 409 — idempotency key conflict | 422 — invalid amount

Idempotent retries

Add an Idempotency-Key header to prevent duplicate invoices on network retries. The same key + same body replays the original 201 response. A different body with the same key returns 409.

POST /api/invoices
X-Api-Key: vgk_YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Keys are enforced for 24 hours. Omit the header to skip replay protection.

Payment Flow

After you create an invoice, the checkoutUrl in the response is a fully hosted payment page served by VirtexGate. Redirect the buyer there — VirtexGate handles everything: coin selection, QR code generation, confirmation countdown, and post-payment redirect.

Your backend

POST /invoices

→

checkoutUrl

in response

→

Redirect buyer

your frontend

→

VirtexGate checkout UI

coin · QR · payment

→

Webhook fired

invoice.paid

What VirtexGate's checkout page handles for you

✓Coin selection (shows only the coins your store has wallets for)

✓QR code generation and payment address display

✓Fiat → crypto conversion and amount calculation

✓Real-time confirmation countdown and status updates

✓Post-payment redirect to your redirectUrl

Redirect to checkout

// After POST /invoices, redirect the buyer:
const invoice = await createInvoice({ amount: 25.00, fiatCurrency: 'USD', ... });

// Option A – full-page redirect (recommended)
window.location.href = invoice.checkoutUrl;

// Option B – open in new tab
window.open(invoice.checkoutUrl, '_blank');

// Option C – embed in an iframe (same-origin only)
// <iframe src="{invoice.checkoutUrl}" width="480" height="620" />

Optional Server-side status check

If you need to verify payment status programmatically without waiting for a webhook (e.g. from a background job or an order management page), you can poll this endpoint from your server.

Field	Type	Notes
invoiceId	guid	path param — the id from POST /invoices

Webhooks

The gateway POSTs to your store's webhookUrl whenever an invoice changes state. Configure the URL in your store settings on the dashboard.

Events

invoice.created invoice.waiting invoice.processing invoice.paid invoice.expired

Payload

{
  "event":           "invoice.paid",
  "invoiceId":       "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "storeId":         "9b2e1c3d-8f4a-4b2e-bc4a-1d2e3f4a5b6c",
  "status":          "Paid",
  "amount":          25.00,
  "fiatCurrency":    "USD",
  "externalOrderId": "order-42",
  "createdAt":       "2026-05-06T10:00:00Z",
  "paidAt":          "2026-05-06T10:12:44Z"
}

Handler example (Node.js / Express)

app.post('/webhook/payment', express.json(), (req, res) => {
  const { event, invoiceId, externalOrderId, status } = req.body;

  if (event === 'invoice.paid') {
    fulfillOrder(externalOrderId); // release your product/service
  }

  res.sendStatus(200); // always return 200 to acknowledge
});

Always respond 200 OK quickly. Failed deliveries are retried automatically. The gateway sends these headers with every POST: X-Webhook-Event, X-Invoice-Id, X-Signature.

Error Reference

All errors follow: {"{ \"error\": \"description\" }"}

Code	Meaning	Notes
400	Bad Request	Validation failure, malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key is valid but not permitted for this store
404	Not Found	Invoice or resource does not exist
409	Conflict	Invoice already paid / expired / cancelled — or Idempotency-Key reused with a different payload
422	Unprocessable	Amount too small, missing field
429	Too Many Requests	Rate-limit hit. Returns `{ error, status, timestamp }`. Back off and retry.
500	Server Error	Unexpected failure

Status Codes

Invoice Status Flow

New Waiting Processing Paid Expired Underpaid Overpaid Cancelled Invalid

Status	Meaning
New	Invoice created, no coin selected yet
Waiting	Coin selected, payment address shown — awaiting transaction
Processing	Transaction detected, waiting for required confirmations
Paid	Fully confirmed — fulfil the order
Expired	Timer elapsed before payment arrived
Underpaid	Less than the required amount was received
Overpaid	More than the required amount was received

Payment (Transaction) Status

Status	Meaning
Pending	Address generated, no transaction seen yet
Detected	Payment received, awaiting confirmation
Confirmed	Required confirmations reached
Expired	Invoice timer elapsed

Status Response Shape

{
  "status": "Processing",
  "expiresAt": "2026-05-06T12:30:00Z",
  "secondsRemaining": 1543,
  "payment": {
    "coinType": "BTC",
    "amountDue": 0.00032541,
    "amountPaid": 0.00032541,
    "status": "Detected",
    "txId": "4a5e1e4baab89f3a32518a88c31bc87f...",
    "confirmations": 1,
    "requiredConfirmations": 1,
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}

Click Auto-play to watch the full integration walkthrough

Authenticate

Every request to create invoices uses your Store API Key. Pass it as the X-Api-Key header. To verify the key is working, call GET /stores/self.

→Get your API key from Gateway Dashboard → Store → Rotate API Key

→Store it in an environment variable — never commit it to source code

→Response includes your store's accepted coins and default currency

Expected response

id name defaultFiatCurrency coins[]

Language:

Request

← Response 200 OK

Step 1 of 4

AI-Optimized API Spec

Integration endpoints only — copy into your AI context for payment integration assistance.

VirtexGate INTEGRATION API SPEC v1.1
==================================
BASE: https://{host}/api
FORMAT: JSON, UTF-8, UTC timestamps (ISO8601+Z), enums as strings
ERRORS: {error:string} — HTTP 400|401|403|404|409|422|429|500
UNKNOWN ROUTES: 404 {error:"Not Found",status:404,message:"The requested endpoint does not exist.",docs:"..."}
GET /           → redirect to GET /status

AUTH: X-Api-Key: {key}   — format: vgk_+base64url(32bytes)
      Per-store key. Generated once, shown once. Rotate via dashboard.

══ RATE LIMITING ════════════════════════════════════════════════════════════
Partitioned by userId (if auth'd) or IP address (X-Forwarded-For respected).
  global         : 300 req / 1 min   (all endpoints)
  /api/auth/*    : 12  req / 1 min
  /api/checkout/*: 60  req / 1 min
  GET /status    : 30  req / 1 min
429 response: {error:"Too many requests. Please slow down and try again shortly.", status:429, timestamp:ISO8601}

══ IDEMPOTENCY ══════════════════════════════════════════════════════════════
POST /invoices supports Idempotency-Key header.
  - Same key + same body → replays cached 201 (no duplicate invoice)
  - Same key + diff body → 409 Conflict
  - Key enforced for 24 hours; omit header to skip replay protection
  Header: Idempotency-Key: {uuid-or-any-string}

══ ENUMS ════════════════════════════════════════════════════════════════════
CoinType      : BTC | ETH | USDT_TRON | USDT_POLYGON
InvoiceStatus : New | Waiting | Processing | Paid | Expired | Underpaid | Overpaid | Cancelled | Invalid
PaymentStatus : Pending | Detected | Confirmed | Expired

══ INTEGRATION FLOW ══════════════════════════════════════════════════════════
1. POST /invoices [X-Api-Key] → {id, checkoutUrl, expiresAt}
2. Redirect buyer to checkoutUrl — VirtexGate's hosted UI handles everything
   (coin selection, QR code, crypto conversion, confirmation countdown)
3. Buyer completes payment → redirected to your redirectUrl
4. Your webhook endpoint receives invoice.paid → fulfil the order
   (Optional: GET /checkout/{id}/status for server-side status checks)

══ HEALTH CHECK ══════════════════════════════════════════════════════════════
GET  /status  ►none (public, rate-limited 30/min)
  res : 200 {
    ping:"pong", status:"healthy", timestamp:ISO8601,
    request:{ traceId, ipAddress, method, path, scheme, host,
              userAgent, isAuthenticated, userId?, userEmail? }
  }
  note: isAuthenticated/userId/userEmail reflect caller's auth — useful for debugging key issues

══ CREATE INVOICE ════════════════════════════════════════════════════════════
POST /invoices  ►X-Api-Key  [Idempotency-Key optional]
  req : {
    storeId(guid,required),
    amount(decimal,>=0.01,required),
    fiatCurrency(string,max10,required),
    externalOrderId?,
    buyerEmail?, buyerName?, description?,
    redirectUrl?   ← buyer sent here after payment
  }
  res : 201 {id(guid), checkoutUrl(string), expiresAt(ISO8601), amount, fiatCurrency}
  err : 404 store not found | 409 idempotency key conflict | 422 invalid amount

══ PAYMENT STATUS (optional server-side check) ═══════════════════════════════
GET  /checkout/{invoiceId}/status  ►none (public)
  res : 200 {
    status:InvoiceStatus, expiresAt, secondsRemaining,
    payment?:{
      coinType, amountDue, amountPaid,
      status:PaymentStatus, txId?, confirmations, requiredConfirmations
    }
  }
  note: webhooks are preferred; use this for on-demand server-side status checks

══ VERIFY API KEY ════════════════════════════════════════════════════════════
GET  /stores/self  ►X-Api-Key
  res : 200 {id, name, defaultFiatCurrency, invoiceExpiryMinutes, webhookUrl, coins:CoinType[]}
  err : 401 invalid key

══ WEBHOOKS ══════════════════════════════════════════════════════════════════
Delivery : POST to store.webhookUrl (set in dashboard)
Headers  : X-Webhook-Event, X-Invoice-Id, X-Signature
Events   : invoice.created | invoice.waiting | invoice.processing | invoice.paid | invoice.expired
Payload  : {
  event, invoiceId(guid), storeId(guid),
  status(InvoiceStatus), amount(decimal), fiatCurrency,
  externalOrderId?, createdAt(ISO8601), paidAt?(ISO8601)
}

══ KEY SCHEMAS ═══════════════════════════════════════════════════════════════
Invoice : {
  id, storeId, amount, fiatCurrency, status:InvoiceStatus,
  expiresAt, externalOrderId?, buyerEmail?, buyerName?,
  description?, redirectUrl?, createdAt, updatedAt
}

PaymentRequest : {
  id, invoiceId, coinType, chain, address,
  amountDue, amountPaid, exchangeRateUsed,
  serviceCharge, estimatedGasFee,
  status:PaymentStatus, txId?, confirmations, createdAt
}

══ STATUS FLOW ═══════════════════════════════════════════════════════════════
New → (buyer selects coin) → Waiting → (tx detected) → Processing → (confirmed) → Paid
                                                                               ↘ Underpaid | Overpaid
                                                                   (timer)  → Expired

API Integration Guide

Overview

Authentication

Quick Start

Create Invoice

Payment Flow

Webhooks

Error Reference

Status Codes

Authenticate

Create Invoice

Redirect to Checkout

Handle Payment Status