Crypto payments in Xboard and V2Board: accept USDT for VPN subscriptions step by step

Xboard and V2Board are popular panels for selling VPN and proxy subscriptions. Out of the box the customer pays by card or through a gateway you host yourself. This guide shows how to add crypto: the customer pays in USDT on TRC20, ERC20 or BEP20 or in another coin, and the panel opens the order by itself. You don't run a wallet, a node or a self-hosted gateway — the money lands in your SnapEX Pay merchant balance.

How a payment goes

customer → panel checkout → SnapEX Pay page
SnapEX Pay → signed webhook → panel
plugin → GET invoice from the API → paid?
panel → order opened

1. At checkout the plugin creates a SnapEX Pay invoice for the order (the panel's trade_no is the invoice external_id) and sends the customer to the payment page.
2. The customer chooses a coin and pays. When the invoice is paid, SnapEX Pay sends a signed webhook to the panel.
3. The plugin checks the signature, asks the SnapEX Pay API for the invoice and marks the order paid only if the status there is paid.

What you need

• Xboard with the plugin system (PHP 8.2+), or V2Board / an older Xboard that loads gateways from app/Payments (PHP 7.3+).
• The PHP cURL extension.
• The panel reachable from the internet over HTTPS: SnapEX Pay delivers webhooks only to public HTTPS addresses.
• A SnapEX Pay merchant account: sign up at pay.snapex.pro.

Step 1. Install the plugin

Download the archive snapexpay-xboard-1.2.0.zip (MIT, free).

Xboard. Admin → Plugins → upload the ZIP → Install → Enable "SnapEX Pay". Or unpack the archive into the panel folder:

cd /path/to/Xboard
curl -fsSLO https://pay.snapex.pro/downloads/xboard/snapexpay-xboard-1.2.0.zip
unzip snapexpay-xboard-1.2.0.zip
mv snapexpay-xboard-1.2.0 plugins/Snapexpay

The folder must be named exactly plugins/Snapexpay — on Linux the name is case-sensitive. Then Plugins → Install → Enable.

V2Board and older Xboard. Copy one file from the archive into the panel:

unzip -p snapexpay-xboard-1.2.0.zip \
  snapexpay-xboard-1.2.0/app/Payments/SnapexPay.php \
  > /path/to/v2board/app/Payments/SnapexPay.php

If you use OPcache or Octane, restart PHP-FPM or Octane. Check that Site URL (app_url) is filled in the V2Board settings: without it the plugin can't send the customer back to the order page after payment.

Step 2. Get an API key

In the SnapEX Pay merchant cabinet open Developers and issue an API key. It is shown once — copy it right away. A key issued in the cabinet gets every Merchant API permission, including the invoices.read and invoices.write the plugin needs. Reissuing a key immediately revokes the old one, so update the panel at the same moment.

Step 3. Add the payment method

Panel admin → Payment configuration → Add payment method → gateway SnapexPay. The fields:

• API key — the key from step 2.
• Webhook secret — fill in at step 4.
• Network fee paid by — merchant (default): the customer pays exactly the order total; customer: the network fee is added on top. More on this: Who pays the fees on a crypto invoice.
• Payment window, minutes — how long the invoice stays payable. Xboard: 60 by default, at most 120; V2Board: 20 by default, at most 30. The cap is below the panel's own timeout for unpaid orders, so a customer can't pay an order the panel has already cancelled.
• USD per 1 shop currency — 1 if prices are in USD. Panels keep totals in cents, and the plugin sends total / 100 × usd_rate. For a shop in CNY that is about 0.14. The rate is fixed: update it yourself when the exchange rate moves.
• Environment — live or test (see step 5).
• Partner ID — leave empty if you set this up yourself; an integrator who connected you puts their ID here.
• API URL — leave the default https://snapex.pro/api/v1/merchant.

The minimum invoice is 0.50 USD: a smaller order, after conversion, fails at checkout with an error.

Step 4. Set up the webhook

Each payment method in the panel has its own notify URL:

https://your-panel.example/api/v1/guest/payment/notify/SnapexPay/{uuid}

Xboard shows the full address in the list of payment methods. In the cabinet, on the Developers page, paste it as the webhook URL and save. The signing secret whsec_… is shown only once, right after the first save — copy it into Webhook secret of the payment method.

The cabinet has one webhook URL per account, and every event goes to it. The plugin opens an order only for a paid invoice; for other events the panel replies with an error (422 on Xboard, 500 on V2Board). In the delivery log that looks like a failed delivery — that's expected.

How the plugin checks a notification:

• the Webhook-Signature header: HMAC-SHA256 over {Webhook-Timestamp}.{raw request body} with your secret;
• Webhook-Timestamp within 5 minutes of the server clock — keep NTP running;
• the invoice itself, re-read from the SnapEX Pay API with your key: the order is paid only if the status there is paid.

More about signatures and retries: Crypto payment webhooks.

Step 5. A test order without real money

1. Set Environment to test and save.
2. Create an order in the panel and go to payment.
3. The SnapEX Pay page shows a Test badge. Pick any coin and network: the page shows a test address, and about 10 seconds later the payment confirms by itself. Nothing has to be sent.
4. The order should switch to paid within seconds. If it doesn't, look at the delivery log on the Developers page and the panel log (storage/logs).
5. Switch Environment back to live.

While the method is in test, any order paid with it opens without money — so keep the test short. Once the method is back to live, the plugin rejects test invoices, and a test payment can't open a real order. More: How to test crypto payments without real money.

What the customer sees

The SnapEX Pay page with a choice of coins: USDT on TRC20, ERC20 and BEP20 and other coins (50+ in total) when SnapEX Pay offers them for the invoice amount. If the customer presses "Pay" again, the same invoice opens while it is still valid; if it has expired, a new one is created for the same order (external_id {trade_no}-1, -2 and so on).

If the customer sends less than the total, the order does not open: the received amount goes to your SnapEX Pay balance, and you settle the rest with the customer. How underpayments work: The customer sent less than the invoice.

If something doesn't work

• SnapexPay is not in the gateway list (Xboard). The folder must be exactly plugins/Snapexpay, and the plugin both installed and enabled.
• "A valid merchant API key is required" or "This source IP is not allowed" at checkout. The key is wrong or revoked, or its IP allowlist doesn't include the panel server's outgoing IP.
• "Amount is below the … USD minimum". After conversion the order is below 0.50 USD — check USD per 1 shop currency.
• The customer paid, the order is still unpaid. Look at the delivery log in the cabinet. Usually the webhook secret doesn't match, the server clock is off by more than 5 minutes, the URL points to another method's UUID, a reverse proxy changes the request body, or the panel can't reach the SnapEX Pay API. A failed delivery can be replayed from the log.

Cost

1% per payment, no setup fee and no monthly fee. The plugin is free.

Plugin page: Xboard / V2Board. Overview for VPN services: Crypto payments for VPN services. Sign-up: pay.snapex.pro.