API Documentation (v1.0.0) OpenAPI (Swagger)

API Documentation

Integrate VisualPay into your application to accept cryptocurrency payments globally. Create transactions, monitor status, and manage withdrawals through a simple REST API.

Get Started

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

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 JWT API key

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
network_code Yes string
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)
comment No string
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' \
--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":"[email protected]","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

Request Example

bash 
curl --location 'https://visualpay.net/api/v1/merchant/transaction/cancel' \
--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.