شروع

یکپارچه‌سازی درگاه با VisualPay یک درخواست POST می‌خواهد. مبلغ سفارش به USD و کوین و شبکه پرداخت را می‌فرستید؛ API آدرس پرداخت، مبلغ دقیق USDT (یا کوین دیگر) و tracking code برمی‌گرداند.

با VisualPay به‌راحتی پرداخت رمزارزی بپذیرید. برای پردازش، تراکنش جدید بسازید و کاربر را به صفحه پرداخت میزبانی‌شده در پاسخ هدایت کنید. VisualPay زنجیره را پایش می‌کند و شما می‌توانید وضعیت را poll کنید یا از پنل مرچنت استفاده کنید.

اختیاری callback_url هنگام ساخت تراکنش بفرستید تا پس از موفق یا ناموفق بودن پرداخت، پرداخت‌کننده به سایت شما برگردد. VisualPay order_id (در صورت ارسال)، status و tracking_code را به همان URL اضافه می‌کند.

BASE URL https://visualpay.net/

بازگشت Callback

با ارسال اختیاری callback_url هنگام Create transaction، پس از رسیدن پرداخت به وضعیت نهایی، صفحه میزبانی‌شده مرورگر پرداخت‌کننده را به URL شما هدایت می‌کند. یک URL برای همه نتایج - موفق و ناموفق با پارامتر queryی status تفکیک می‌شوند.

پارامترهای query اضافه‌شده به URL شما

درگاه پارامترهای جدول زیر را به callback_url اضافه می‌کند تا بدون فراخوانی API دیگر، سفارش و نتیجه نهایی را بشناسید.

پارامتر	توضیح
`order_id`	شناسه سفارش شما از Create transaction، در صورت ارسال.
`status`	وضعیت نهایی پرداخت: `confirmed`، `expired` یا `cancelled` (همان مقادیر API Check transaction).
`tracking_code`	UUID تراکنش VisualPay برای تأیید.

نمونه redirect

url

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

مهم: redirect callback فقط برای UX مرورگر است. بک‌اند شما همچنان باید قبل از تحویل سفارش از webhook یا endpoint Check transaction استفاده کند. اگر callback_url نباشد، پرداخت‌کننده روی صفحه میزبانی VisualPay می‌ماند.

زمان‌بندی redirect: پرداخت تأییدشده ۳ ثانیه پیام موفقیت نشان می‌دهد سپس redirect؛ expired یا cancelled فوراً redirect می‌شوند.

احراز هویت

برای Merchant API VisualPay، هر درخواست را با کلید API مرچنت احراز کنید. مرچنت در پنل VisualPay بسازید و کلید را از تنظیمات مرچنت کپی کنید.

نکته امنیتی: کلید API را امن نگه دارید. هنگام ساخت نمایش داده می‌شود و نباید در کد سمت کلاینت باشد.

کلید API مرچنت برای هر درخواست الزامی است.

کلید API مرچنت را در هدر HTTP x-api-key برای همه درخواست‌ها بفرستید.

http

x-api-key: YOUR_MERCHANT_API_KEY

GET /api/v1/merchant/currencies/list

لیست ارزهای پشتیبانی‌شده

ارزها و شبکه‌های فعال برای مرچنت احراز هویت‌شده را برمی‌گرداند.

نمونه درخواست

bash

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

نمونه پاسخ

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

لیست تراکنش‌ها

لیست صفحه‌بندی‌شده تراکنش‌های مرچنت. فیلترهای اختیاری: enum مربوط به status و بازه تاریخ (حداکثر ۳۰ روز).

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`limit`	خیر	integer	تعداد آیتم در هر صفحه (۱ تا ۵۰)
`page`	خیر	integer	شماره صفحه
`from_date`	خیر	string (date)	تاریخ شروع (Y-m-d). همراه با to_date الزامی است. حداکثر بازه ۳۰ روز.
`to_date`	خیر	string (date)	تاریخ پایان (Y-m-d). همراه با from_date الزامی است. حداکثر بازه ۳۰ روز.
`status`	خیر	enum	اختیاری. مقادیر مجاز: `pending`، `confirmed`، `expired`، `cancelled`.

نمونه درخواست

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'

نمونه پاسخ

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

ساخت تراکنش

یک پرداخت رمزارزی جدید می‌سازد.

amount_usd: مبلغ قابل پرداخت به USD/USDT. مقدار ارسالی باید بزرگ‌تر یا مساوی minimum_pay_usd و کوچک‌تر یا مساوی maximum_pay_usd باشد.

ttl: مدت اعتبار به دقیقه برای پایش تراکنش. مقدار واردشده نباید از max_ttl بیشتر باشد.

order_id: اختیاری. در صورت ارسال باید یک عدد ۶ رقمی باشد.

email: اختیاری.

comment: اختیاری.

callback_url: اختیاری. آدرس عمومی HTTPS روی سایت شما. در صورت ارسال، صفحه پرداخت میزبانی‌شده پس از وضعیت نهایی (confirmed، expired یا cancelled) پرداخت‌کننده را برمی‌گرداند و پارامترهای query مربوط به order_id (در صورت ارسال)، status و tracking_code را اضافه می‌کند.

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

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`currency_symbol`	بله	string	نماد ارزی فعال برای مرچنت شما (مثلاً USDT، ETH).
`network_code`	بله	string	کد شبکه برای ارز انتخاب‌شده (مثلاً TRC20، ERC20، BEP20).
`amount_usd`	بله	number	مبلغ به USD/USDT
`ttl`	بله	integer	مدت اعتبار به دقیقه برای پایش این تراکنش. نباید از max_ttl ارز بیشتر باشد.
`order_id`	خیر	integer	اختیاری. در صورت ارسال باید یک عدد ۶ رقمی باشد.
`email`	خیر	string (email)	ایمیل اختیاری پرداخت‌کننده.
`comment`	خیر	string	توضیح اختیاری پرداخت‌کننده.
`callback_url`	خیر	string (uri)	اختیاری. پس از تکمیل یا ناموفق بودن پرداخت در صفحه میزبانی‌شده، VisualPay مرورگر پرداخت‌کننده را به این URL از نوع HTTPS هدایت می‌کند و پارامترهای queryی `order_id` (در صورت ارسال هنگام ساخت)، `status` و `tracking_code` را اضافه می‌کند. برای همه نتایج یک URL استفاده کنید و نتیجه را با `status` تشخیص دهید. همیشه وضعیت پرداخت را در سمت سرور با webhook یا endpoint بررسی تراکنش تأیید کنید — فقط به redirect اکتفا نکنید.

نمونه درخواست

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"}'

نمونه پاسخ

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

بررسی تراکنش

جستجو با tracking_code. فقط تراکنش‌های متعلق به مرچنت احراز هویت‌شده برگردانده می‌شوند.

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`tracking_code`	بله	string	کد پیگیری درگاه که هنگام ساخت تراکنش برگردانده شده است

نمونه درخواست

bash

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

نمونه پاسخ

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

بررسی مجدد تراکنش

پرداخت روی زنجیره را برای تراکنش منقضی یا لغو‌شده متعلق به مرچنت احراز هویت‌شده دوباره بررسی می‌کند. جستجو با tracking_code.

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`tracking_code`	بله	string	کد پیگیری درگاه که هنگام ساخت تراکنش برگردانده شده است

نمونه درخواست

bash

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

نمونه پاسخ

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

لغو تراکنش

فقط تراکنش‌هایی با وضعیت pending قابل لغو هستند.

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`tracking_code`	بله	string	کد پیگیری درگاه برای تراکنش pending که باید لغو شود.

نمونه درخواست

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"}'

نمونه پاسخ

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

لیست برداشت‌ها

تاریخچه صفحه‌بندی‌شده برداشت‌ها. فیلترهای اختیاری: enum مربوط به status و بازه تاریخ (حداکثر ۳۰ روز).

پارامترهای درخواست

فیلد	الزامی	نوع	توضیح
`limit`	خیر	integer	تعداد آیتم در هر صفحه (۱ تا ۵۰)
`page`	خیر	integer	شماره صفحه
`from_date`	خیر	string (date)	تاریخ شروع (Y-m-d). همراه با to_date الزامی است. حداکثر بازه ۳۰ روز.
`to_date`	خیر	string (date)	تاریخ پایان (Y-m-d). همراه با from_date الزامی است. حداکثر بازه ۳۰ روز.
`status`	خیر	enum	اختیاری. مقادیر مجاز: `pending`، `processing`، `confirmed`.

نمونه درخواست

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'

نمونه پاسخ

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

وضعیت‌های تراکنش

وضعیت تراکنش حالت فعلی پرداخت را نشان می‌دهد. مقادیر ممکن:

pending

در انتظار پرداخت روی زنجیره.

confirmed

پرداخت با موفقیت تکمیل شد.

expired

مهلت پرداخت بدون تکمیل به پایان رسید.

cancelled

تراکنش لغو شد.

بهترین روش: پس از بازگشت پرداخت‌کننده به سایت، endpoint Check transaction را برای تأیید وضعیت نهایی قبل از تحویل سفارش فراخوانی کنید.

مستندات API پرداخت رمزارزی

شروع

بازگشت Callback

پارامترهای query اضافه‌شده به URL شما

نمونه redirect

احراز هویت

لیست ارزهای پشتیبانی‌شده

نمونه درخواست

نمونه پاسخ

لیست تراکنش‌ها

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

ساخت تراکنش

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

بررسی تراکنش

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

بررسی مجدد تراکنش

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

لغو تراکنش

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

لیست برداشت‌ها

پارامترهای درخواست

نمونه درخواست

نمونه پاسخ

وضعیت‌های تراکنش