API दस्तावेज़ (v1.0.0) OpenAPI (Swagger)

क्रिप्टो पेमेंट API दस्तावेज़

यह VisualPay क्रिप्टो पेमेंट गेटवे का पूरा REST API रेफ़रेंस है। इससे आप ट्रांज़ैक्शन बना सकते हैं, किसी भी समर्थित नेटवर्क पर USDT, USDC, ETH, BNB और TON में भुगतान ले सकते हैं, ऑन-चेन स्टेटस देख सकते हैं और वेबहुक पा सकते हैं। यह सब आपके अपने बैकएंड से होता है, बीच में कोई होस्टेड चेकआउट नहीं आता।

नीचे दिया गया हर एंडपॉइंट एक ही मर्चेंट API कुंजी से प्रमाणित होता है, JSON लौटाता है और किसी भी भाषा या फ़्रेमवर्क से कॉल किया जा सकता है। न कोई SDK इंस्टॉल करना है, न कोई प्लगइन संभालना है।

शुरुआत करें

VisualPay के साथ क्रिप्टो पेमेंट गेटवे इंटीग्रेट करने के लिए सिर्फ़ एक POST रिक्वेस्ट चाहिए। आप ऑर्डर की राशि USD में भेजते हैं, साथ में वह कॉइन और नेटवर्क जिसमें आपको भुगतान चाहिए। API जवाब में पेमेंट एड्रेस, USDT (या दूसरे कॉइन) की सटीक राशि और एक ट्रैकिंग कोड देता है, जिसे आप अपने ऑर्डर के साथ सेव कर सकते हैं।

VisualPay से इंटीग्रेट करके अपने कारोबार के लिए क्रिप्टोकरेंसी भुगतान आसानी से स्वीकार करें। भुगतान प्रोसेस करने के लिए नया ट्रांज़ैक्शन बनाएँ और अपने उपयोगकर्ता को रिस्पॉन्स में मिले होस्टेड पेमेंट पेज पर भेजें। ब्लॉकचेन की निगरानी VisualPay संभालता है। आप स्टेटस पोल कर सकते हैं या मिलान के लिए मर्चेंट पैनल देख सकते हैं।

ट्रांज़ैक्शन बनाते समय आप चाहें तो callback_url भेज सकते हैं, ताकि भुगतान पूरा होने या विफल होने के बाद भुगतानकर्ता आपकी साइट पर लौट आए। VisualPay उसी एक URL में order_id (अगर दिया गया हो), status और tracking_code क्वेरी पैरामीटर के रूप में जोड़ देता है।

बेस URL https://visualpay.net/

कॉलबैक रीडायरेक्ट

अगर आप "ट्रांज़ैक्शन बनाएँ" में वैकल्पिक callback_url देते हैं, तो भुगतान के अंतिम स्थिति में पहुँचने के बाद होस्टेड पेमेंट पेज भुगतानकर्ता के ब्राउज़र को आपके URL पर भेज देता है। सभी नतीजों के लिए एक ही URL इस्तेमाल करें। सफलता और विफलता का फ़र्क status क्वेरी पैरामीटर से पता चलता है।

आपके URL में जोड़े जाने वाले क्वेरी पैरामीटर

गेटवे नीचे की तालिका के पैरामीटर आपके कॉलबैक URL में जोड़ता है, ताकि आपका एप्लिकेशन बिना एक और API कॉल के ऑर्डर और उसके अंतिम नतीजे को पहचान सके।

पैरामीटर विवरण
order_id "ट्रांज़ैक्शन बनाएँ" में दी गई आपकी ऑर्डर ID, अगर दी गई हो।
status भुगतान की अंतिम स्थिति: confirmed, expired या cancelled ("ट्रांज़ैक्शन जाँचें" API जैसे ही मान)।
tracking_code सत्यापन के लिए VisualPay ट्रांज़ैक्शन UUID।

रीडायरेक्ट का उदाहरण

url
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
महत्वपूर्ण: कॉलबैक रीडायरेक्ट सिर्फ़ ब्राउज़र के अनुभव के लिए है। ऑर्डर पूरा करने से पहले आपके बैकएंड को वेबहुक या "ट्रांज़ैक्शन जाँचें" एंडपॉइंट से भुगतान की पुष्टि करनी ही होगी। अगर callback_url नहीं दिया गया है, तो भुगतानकर्ता VisualPay के होस्टेड पेज पर ही रहता है।

रीडायरेक्ट का समय: पुष्टि हुए भुगतान में रीडायरेक्ट से पहले 3 सेकंड तक सफलता का संदेश दिखता है। समाप्त या रद्द हुए भुगतान में तुरंत रीडायरेक्ट होता है।

प्रमाणीकरण

VisualPay मर्चेंट API इस्तेमाल करने के लिए हर रिक्वेस्ट को अपनी मर्चेंट API कुंजी से प्रमाणित करें। VisualPay पैनल में मर्चेंट बनाएँ और मर्चेंट सेटिंग से API कुंजी कॉपी करें।

सुरक्षा नोट: अपनी API कुंजी सुरक्षित रखें। यह बनाते समय दिखाई जाती है और इसे क्लाइंट-साइड कोड में नहीं रखना चाहिए।

हर रिक्वेस्ट पर मर्चेंट API कुंजी ज़रूरी है।

सभी API रिक्वेस्ट में x-api-key HTTP हेडर के साथ अपनी मर्चेंट API कुंजी भेजें।

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

ट्रांज़ैक्शन की सूची

मर्चेंट के ट्रांज़ैक्शन पेज-दर-पेज लौटाता है। वैकल्पिक फ़िल्टर: status enum, तारीख़ की सीमा (अधिकतम 30 दिन)।

रिक्वेस्ट पैरामीटर

फ़ील्ड अनिवार्य टाइप विवरण
limit नहीं integer प्रति पेज आइटम (1–50)
page नहीं integer पेज संख्या
from_date नहीं string (date) शुरू की तारीख़ (Y-m-d)। to_date के साथ ज़रूरी। अधिकतम सीमा 30 दिन।
to_date नहीं string (date) अंत की तारीख़ (Y-m-d)। from_date के साथ ज़रूरी। अधिकतम सीमा 30 दिन।
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: वैकल्पिक। अगर आप यह पैरामीटर भेजते हैं, तो यह 6 अंकों की संख्या होनी चाहिए।

email: वैकल्पिक।

comment: वैकल्पिक।

callback_url: वैकल्पिक। आपकी साइट का सार्वजनिक HTTPS URL। यह देने पर होस्टेड पेमेंट पेज अंतिम स्थिति (confirmed, expired या cancelled) के बाद भुगतानकर्ता को वापस भेजता है और 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 वैकल्पिक। अगर दिया जाए, तो 6 अंकों की संख्या होनी चाहिए।
email नहीं string (email) वैकल्पिक। भुगतानकर्ता का ईमेल।
comment नहीं string वैकल्पिक। भुगतानकर्ता की टिप्पणी।
callback_url नहीं string (uri) वैकल्पिक। भुगतानकर्ता होस्टेड पेज पर भुगतान पूरा करे या विफल हो, उसके बाद VisualPay उसके ब्राउज़र को इस HTTPS URL पर भेजता है और order_id (अगर बनाते समय दिया गया हो), status और tracking_code क्वेरी पैरामीटर जोड़ता है। सभी नतीजों के लिए एक ही URL रखें और नतीजे status पैरामीटर से पहचानें। भुगतान की स्थिति हमेशा सर्वर पर वेबहुक या "ट्रांज़ैक्शन जाँचें" एंडपॉइंट से सत्यापित करें। सिर्फ़ रीडायरेक्ट पर भरोसा न करें।

रिक्वेस्ट का उदाहरण

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 रद्द किए जाने वाले लंबित ट्रांज़ैक्शन का गेटवे ट्रैकिंग कोड।

रिक्वेस्ट का उदाहरण

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

निकासी की सूची

निकासी का इतिहास पेज-दर-पेज लौटाता है। वैकल्पिक फ़िल्टर: status enum, तारीख़ की सीमा (अधिकतम 30 दिन)।

रिक्वेस्ट पैरामीटर

फ़ील्ड अनिवार्य टाइप विवरण
limit नहीं integer प्रति पेज आइटम (1–50)
page नहीं integer पेज संख्या
from_date नहीं string (date) शुरू की तारीख़ (Y-m-d)। to_date के साथ ज़रूरी। अधिकतम सीमा 30 दिन।
to_date नहीं string (date) अंत की तारीख़ (Y-m-d)। from_date के साथ ज़रूरी। अधिकतम सीमा 30 दिन।
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

ट्रांज़ैक्शन रद्द कर दिया गया।

सुझाव: भुगतानकर्ता के आपकी साइट पर लौटने के बाद, ऑर्डर पूरा करने से पहले "ट्रांज़ैक्शन जाँचें" एंडपॉइंट को कॉल करके भुगतान की अंतिम स्थिति की पुष्टि करें।