API Documentation (v1.0.0) OpenAPI (Swagger)

Crypto Payment API Documentation

This is the complete REST API reference for the VisualPay crypto payment gateway. Use it to create transactions, accept USDT, USDC, ETH, BNB and TON payments on any supported network, monitor status on-chain and receive webhooks - all from your own backend, with no hosted checkout in between.

Every endpoint below is authenticated with a single merchant API key, returns JSON, and can be called from any language or framework. There is no SDK to install and no plugin to maintain.

Get Started

Integrating a crypto payment gateway with VisualPay takes one POST request. You send the order amount in USD together with the coin and network you want to be paid in, and the API responds with the payment address, the exact USDT (or other coin) amount and a tracking code you can store against your order.

Easily accept cryptocurrency payments for your business by integrating with VisualPay. To process a payment, create a new transaction and redirect your user to the hosted payment page returned in the response. VisualPay handles blockchain monitoring, and you can poll status or use your merchant panel for reconciliation.

Optionally pass callback_url when creating a transaction to send the payer back to your site after payment completes or fails. VisualPay appends order_id (when provided), status, and tracking_code as query parameters to that single URL.

BASE URL https://visualpay.net/

Callback Redirect

When you provide an optional callback_url on Create transaction, the hosted payment page redirects the payer's browser to your URL after the payment reaches a final state. Use one URL for all outcomes - success and failure are distinguished by the status query parameter.

Query parameters appended to your URL

The gateway appends the parameters in the table below to your callback URL so your application can identify the order and its final outcome without another API call.

Parameter Description
order_id Your order ID from Create transaction, when provided.
status Final payment state: confirmed, expired, or cancelled (same values as the Check transaction API).
tracking_code VisualPay transaction UUID for verification.

Example redirect

url 
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
Important: Callback redirect is for browser UX only. Your backend must still use webhooks or the Check transaction endpoint to confirm payment before fulfilling orders. If callback_url is omitted, the payer stays on the VisualPay hosted page.

Redirect timing: confirmed payments show a success message for 3 seconds before redirect; expired or cancelled payments redirect immediately.

Authentication

To interact with the VisualPay Merchant API, authenticate every request with your merchant API key. Create a merchant in the VisualPay panel and copy the API key from the merchant settings.

Security note: Store your API key securely. It is shown when generated and should not be exposed in client-side code.

Merchant API key required on every request.

Include your merchant API key in the x-api-key HTTP header for all API requests.

http 
x-api-key: YOUR_MERCHANT_API_KEY
GET /api/v1/merchant/currencies/list

List supported currencies

Returns currencies and networks enabled for the authenticated merchant.

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

Response Example

json 
{
    "status": 200,
    "data": [
        {
            "currency_name": "Tether",
            "currency_symbol": "USDT",
            "currency_type": "stable",
            "price_in_usdt": 1,
            "icon": "",
            "supported_networks": [
                {
                    "network_name": "TRON (TRC20)",
                    "network_symbol": "TRX",
                    "network_code": "trc20",
                    "network_fee": 1,
                    "minimum_pay_usd": 5,
                    "maximum_pay_usd": 10000,
                    "max_ttl": 30,
                    "icon": ""
                }
            ]
        }
    ],
    "message": "success"
}
GET /api/v1/merchant/transaction/list

List transactions

Paginated merchant transactions. Optional filters: status enum, date range (max 30 days).

Request Parameters

Field Required Type Description
limit No integer Items per page (1–50)
page No integer Page number
from_date No string (date) Start date (Y-m-d). Required with to_date. Max range 30 days.
to_date No string (date) End date (Y-m-d). Required with from_date. Max range 30 days.
status No enum Optional. Supported values: pending, confirmed, expired, cancelled.

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

Response Example

json 
{
    "status": 200,
    "data": {
        "items": [
            {
                "order_id": 1001,
                "status": "pending",
                "tracking_code": "AbC12XyZ",
                "payment_url": "https://pay.visualpay.net/AbC12XyZ",
                "currency_code": "usdt_trc20",
                "currency_name": "Tether",
                "network_code": "trc20",
                "network_name": "TRON (TRC20)",
                "pay_amount": "10.00000000",
                "amount_usd": "10.00000000",
                "platform_share": "0.20000000",
                "merchant_share": "9.80000000",
                "payment_fee_percent": 1,
                "payment_tolerance_percent": 1,
                "paid_amount": "",
                "is_canceled_by_user": false,
                "tx_id": "",
                "tx_explorer_url": "",
                "email": "",
                "comment": "",
                "paid_at": 0,
                "created_at": 0,
                "expired_at": 0
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 50,
            "total": 120,
            "last_page": 3
        }
    },
    "message": "success"
}
POST /api/v1/merchant/transaction/create

Create transaction

Creates a new crypto payment.

amount_usd: Payable Amount in USD/USDT. The value you send must be greater than or equal to minimum_pay_usd and less than or equal to maximum_pay_usd.

ttl: Time To Live in minutes for monitoring the transaction. The value you enter must not be greater than max_ttl.

order_id: Optional. If you send this parameter, it must be a 6-digit number.

email: Optional.

comment: Optional.

callback_url: Optional. Public HTTPS URL on your site. When provided, the hosted payment page redirects the payer back after a terminal status (confirmed, expired, or cancelled) with order_id (when provided), status, and tracking_code query parameters appended.

Example:
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000

Request Parameters

Field Required Type Description
currency_symbol Yes string Currency symbol enabled for your merchant (e.g. USDT, ETH).
network_code Yes string Network code for the selected currency (e.g. TRC20, ERC20, BEP20).
amount_usd Yes number Amount in USD/USDT
ttl Yes integer Time To Live in minutes for monitoring this transaction. Must not exceed the currency max_ttl.
order_id No integer Optional. If provided, must be a 6-digit number.
email No string (email) Optional payer email.
comment No string Optional payer comment.
callback_url No string (uri) Optional. After the payer completes or fails payment on the hosted page, VisualPay redirects their browser to this HTTPS URL with query parameters order_id (when provided on create), status, and tracking_code. Use a single URL for all outcomes; distinguish results via the status parameter. Always verify payment state server-side via webhook or the Check transaction endpoint — do not rely on redirect alone.

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/create?currency_symbol=value&network_code=value&amount_usd=value&ttl=value&order_id=value&email=value&comment=value&callback_url=value' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"currency_symbol":"USDT","network_code":"trc20","amount_usd":25.5,"ttl":15,"order_id":100001,"email":"payer@example.com","comment":"Invoice #1001","callback_url":"https://example.com/order"}'

Response Example

json 
{
    "status": 200,
    "data": {
        "payment_url": "http://127.0.0.1:6131/payment/AbC12XyZ",
        "tracking_code": "AbC12XyZ",
        "status": "pending",
        "order_id": 1001,
        "currency_name": "Tether",
        "currency_symbol": "USDT",
        "network": "tron",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "amount_usd": "25.50000000",
        "pay_amount": "25.50000000",
        "platform_share": "0.51000000",
        "merchant_share": "24.99000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "wallet_address": "TXyz...",
        "qr_code": "",
        "expired_at": 0
    },
    "message": "success"
}
GET /api/v1/merchant/transaction/status

Check transaction

Lookup by tracking_code. Only transactions belonging to the authenticated merchant are returned.

Request Parameters

Field Required Type Description
tracking_code Yes string Gateway tracking code returned when the transaction was created

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

Response Example

json 
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "success"
}
GET /api/v1/merchant/transaction/recheck

Recheck transaction

Re-verifies an on-chain payment for an expired or cancelled transaction owned by the authenticated merchant. Lookup by tracking_code.

Request Parameters

Field Required Type Description
tracking_code Yes string Gateway tracking code returned when the transaction was created

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

Response Example

json 
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "Transaction confirmed successfully."
}
POST /api/v1/merchant/transaction/cancel

Cancel transaction

Only transactions with status pending can be cancelled.

Request Parameters

Field Required Type Description
tracking_code Yes string Gateway tracking code of the pending transaction to cancel.

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/cancel?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"tracking_code":"AbC12XyZ"}'

Response Example

json 
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "Transaction cancelled successfully."
}
GET /api/v1/merchant/withdrawals/list

List withdrawals

Paginated withdrawal history. Optional filters: status enum, date range (max 30 days).

Request Parameters

Field Required Type Description
limit No integer Items per page (1–50)
page No integer Page number
from_date No string (date) Start date (Y-m-d). Required with to_date. Max range 30 days.
to_date No string (date) End date (Y-m-d). Required with from_date. Max range 30 days.
status No enum Optional. Supported values: pending, processing, confirmed.

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/withdrawals/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

Response Example

json 
{
    "status": 200,
    "data": {
        "items": [
            {
                "tracking_code": "49e9f567-8c2a-4b1d-9f3e-2a1b0c9d8e7f",
                "currency_name": "Tether",
                "network_name": "TRON (TRC20)",
                "destination_address": "TXyz...",
                "amount_usd": "$98.50",
                "status": "Processing",
                "tx_id": "",
                "tx_explorer_url": "",
                "created_at": 0
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 50,
            "total": 120,
            "last_page": 3
        }
    },
    "message": "success"
}

Transaction Statuses

The transaction status indicates the current state of a payment. Possible values include:

pending

Waiting for on-chain payment.

confirmed

Payment completed successfully.

expired

Payment window elapsed without completion.

cancelled

Transaction was cancelled.

Best practice: After a payer returns to your site, call the Check transaction endpoint to confirm the final payment state before fulfilling the order.