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.

Store ID

Every invoice creation request also requires your storeId — the UUID of the store the API key belongs to. This is a deliberate security check: the server validates that the key and the storeId match, preventing a leaked key from being used against a different store.

Where to find it: Gateway Dashboard → Store → the Store ID is displayed on the store overview page. Copy and store it alongside your API key in your environment variables.

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 — found on the store overview page in the dashboard. Must match the store the API key belongs to.
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 every webhook URL registered under your store whenever an invoice changes state. Add endpoints in Store → Settings → Webhook Endpoints.

Events

invoice.created invoice.waiting invoice.payment_received invoice.payment_settled invoice.processing invoice.paid invoice.overpaid invoice.partially_paid invoice.expired invoice.cancelled invoice.invalid

Payload

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

Signature Verification (required)

Every delivery includes an X-Signature header containing an HMAC-SHA256 of the raw request body. Always verify this before trusting the payload — reject any request whose signature does not match.

Algorithm HMAC-SHA256

Header X-Signature: sha256=<lowercase hex>

Key The signing secret shown once when you add the webhook endpoint in the dashboard. If you left the field blank the gateway auto-generated one.

Input The raw UTF-8 request body — read the stream before parsing JSON.

Formula "sha256=" + hex( HMAC‑SHA256(secret, rawBody) )

Webhook handler examples

const crypto = require('crypto');
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; // from Store Settings

// Use express.raw() — req.body must be a Buffer for signature verification
app.post('/webhook/payment', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Verify signature (timing-safe comparison)
  const sig      = req.headers['x-signature'] ?? '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401); // reject — do not process
  }

  // 2. Parse and handle
  const { event, invoiceId, externalOrderId } = JSON.parse(req.body);
  if (event === 'invoice.paid') {
    fulfillOrder(externalOrderId);
  }
  res.sendStatus(200);
});

<?php
$secret = getenv('WEBHOOK_SECRET'); // from Store Settings
$body   = file_get_contents('php://input'); // raw — read before json_decode

// 1. Verify signature (timing-safe comparison)
$sig      = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Unauthorized');
}

// 2. Parse and handle
$data  = json_decode($body, true);
$event = $data['event'];

if ($event === 'invoice.paid') {
    fulfillOrder($data['externalOrderId']);
}
http_response_code(200);
echo 'OK';

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']  # from Store Settings

@app.route('/webhook/payment', methods=['POST'])
def webhook():
    # 1. Read raw body BEFORE any parsing
    body = request.get_data()

    # 2. Verify signature (timing-safe comparison)
    sig      = request.headers.get('X-Signature', '')
    expected = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig):
        abort(401)  # reject — do not process

    # 3. Parse and handle
    data = request.get_json()
    if data.get('event') == 'invoice.paid':
        fulfill_order(data['externalOrderId'])
    return 'OK', 200

using System.Security.Cryptography;
using System.Text;

// Minimal API — appsettings.json: { "Webhooks": { "Secret": "..." } }
app.MapPost("/webhook/payment", async (HttpRequest req, IConfiguration cfg) =>
{
    // 1. Read raw body BEFORE deserialization
    req.EnableBuffering();
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var rawBody = Encoding.UTF8.GetString(ms.ToArray());

    // 2. Verify signature (constant-time comparison)
    var secret   = cfg["Webhooks:Secret"]!; // from Store Settings
    var sig      = req.Headers["X-Signature"].ToString();
    var hash     = HMACSHA256.HashData(
                       Encoding.UTF8.GetBytes(secret),
                       Encoding.UTF8.GetBytes(rawBody));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();

    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(sig),
            Encoding.UTF8.GetBytes(expected)))
        return Results.Unauthorized();

    // 3. Parse and handle
    using var doc = JsonDocument.Parse(rawBody);
    if (doc.RootElement.GetProperty("event").GetString() == "invoice.paid")
    {
        var orderId = doc.RootElement.GetProperty("externalOrderId").GetString();
        await FulfillOrderAsync(orderId!);
    }
    return Results.Ok();
});

# Simulate a signed webhook delivery for local testing
BODY='{"event":"invoice.paid","invoiceId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","storeId":"9b2e1c3d-8f4a-4b2e-bc4a-1d2e3f4a5b6c","status":"Paid","amount":25.00,"currency":"USD","externalOrderId":"order-42","createdAt":"2026-05-16T10:00:00Z","timestamp":1747390800}'
SECRET="your-64-char-hex-signing-secret"

SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')"

curl -s -X POST https://yourapp.com/webhook/payment \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event: invoice.paid" \
  -H "X-Invoice-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

Timing attacks: always use a constant-time comparison function (crypto.timingSafeEqual, hash_equals, hmac.compare_digest, CryptographicOperations.FixedTimeEquals) — never a plain string equality check.

Always respond 200 OK quickly — the gateway retries up to 3 times with 5 s / 10 s backoff on any non-2xx response or timeout.

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 — GET /stores/self

id name defaultFiatCurrency coins[]

The id field is your Store ID — save it alongside your API key. You'll pass it as storeId in every invoice request. You can also find it on the store overview page in the dashboard.

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:"..."}

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/checkout/*: 60  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)
  res : 200 { ping:"pong", status:"healthy", timestamp:ISO8601, isAuthenticated:bool }
  note: isAuthenticated reflects whether the request carries a valid credential — useful for verifying your API key is working

══ CREATE INVOICE ════════════════════════════════════════════════════════════
POST /invoices  ►X-Api-Key  [Idempotency-Key optional]
  req : {
    storeId(guid,required)   ← UUID of the store — shown on store overview page in dashboard.
                               Server validates storeId matches the API key's store (security check).
                               Store in env var alongside API key. Never hard-code.
    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 or storeId/key mismatch | 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  : Content-Type:application/json
           X-Webhook-Event: {event}
           X-Invoice-Id: {invoiceId}
           X-Signature: sha256={lowercase-hex-hmac}
Events   : invoice.created | invoice.waiting | invoice.payment_received
           | invoice.payment_settled | invoice.processing | invoice.paid
           | invoice.overpaid | invoice.partially_paid
           | invoice.expired | invoice.cancelled | invoice.invalid
Payload  : {
  event, invoiceId(guid), storeId(guid),
  status(InvoiceStatus), amount(decimal), currency(string),
  externalOrderId?, orderId?, createdAt(ISO8601),
  timestamp(unix-seconds)
}
Payment events (payment_received, payment_settled) add:
  payment: { coinType, address, txId?, amountPaid, amountDue,
             confirmations, requiredConfirmations,
             afterExpiration?(payment_received) | settled?(payment_settled) }
Retries  : 3 attempts — immediately, +5 s, +10 s. No retries if 2xx received.

SIGNING (HMAC-SHA256) ────────────────────────────────────────────────────────
Algorithm : HMAC-SHA256
Input     : raw UTF-8 request body (before any JSON parsing)
Key       : signing secret (64-char hex) — shown once at webhook creation
Header    : X-Signature: sha256={lowercase-hex-digest}
Required  : MUST verify before processing. Reject if missing or invalid.
Timing    : use constant-time comparison (crypto.timingSafeEqual / FixedTimeEquals)
Secret    : set per-webhook in dashboard → Webhooks → copy on creation (not shown again)

══ 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