Convert API

Convert API आपको आपके मर्चेंट बैलेंस में मौजूद करेंसी के बीच वर्तमान मार्केट प्राइस पर एक्सचेंज करने देता है — वही इंजन जो मर्चेंट डैशबोर्ड के Swap टैब को चलाता है, अब आपके बैकएंड से कॉल किया जा सकता है।

कन्वर्जन प्राइस पाना

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

कन्वर्ट एक्ज़िक्यूट करना

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

एरर

विफल होने पर, रिस्पॉन्स में state: 1 और एक error_code होता है — /v1/convert/price और /v1/convert दोनों में समान:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

आगमन भुगतान का स्वचालित रूपांतरण

स्वचलित रूपांतरण इनकमिंग इनवॉइस और स्टेटिक-वॉलेट क्रेडिट्स के लिए एक परियोजना सेटिंग है। इसे मर्चेंट डैशबोर्ड में कॉन्फ़िगर किया जाता है, न कि /v1/payment में फ़ील्ड जोड़कर। प्रत्येक नियम एक या अधिक स्रोत मुद्राओं और एक लक्ष्य मुद्रा का चयन करता है।

जब रूपांतरण पूरा हो जाता है, तो भुगतान जानकारी और मर्चेंट वेबहुक्स में शामिल किया जा सकता है:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

राशि डोमेन जानबूझकर अलग हैं:

• payment_amount — स्रोत भुगतान मुद्रा में ऑन-चेन क्या पता चला;
• merchant_amount — रूपांतरण से पहले मर्चेंट को सौंपी गई शुद्ध स्रोत राशि;
• convert.amount — convert.to_currency में क्रेडिट की गई राशि;
• convert.rate और convert.commission — निष्पादित रूपांतरण परिणाम, कोई मूल्य नहीं जिसे आपको स्थानीय रूप से पुनः गणना करनी चाहिए।

ऑटो-कन्वर्ट विफलता और फॉलबैक

रूपांतरण ब्लॉकचेन भुगतान प्राप्त करने के बाद डाउनस्ट्रीम होता है। बाजार की उपलब्धता, न्यूनतम आदेश आकार, सटीकता सीमा, एक्सचेंज समय समाप्ति और अपर्याप्त निष्पादन योग्य तरलता रूपांतरण को विलंबित या अवरुद्ध कर सकते हैं।

• वैश्विक/परियोजना न्यूनतम से कम जमा राशि रूपांतरण पाइपलाइन को बाइपास करती है और स्रोत मुद्रा को क्रेडिट करती है।
• अल्पकालिक असफलताओं को असिंक्रोनस रूप से दोबारा प्रयास किया जा सकता है।
• बड़ी या गैर-व्यापारी योग्य जमा राशि को दोबारा प्रयास नीति समाप्त होने के बाद स्रोत-मुद्रा क्रेडिट में बदल दिया जा सकता है।
• इसलिए एक भुगतान मान्य हो सकता है भले ही इच्छित लक्ष्य-मुद्रा रूपांतरण नहीं हुआ हो।

आपका एकीकरण पहले सत्यापित भुगतान को सुरक्षित रूप से रखे, फिर भुगतान जानकारी, वैकल्पिक convert ब्लॉक, और व्यापारी बैलेंस से वास्तविक क्रेडिट की गई मुद्रा का मिलान करे। अपने खुद के विश्लेषण या सूचना प्रणालियों पर इंतजार करते समय भुगतान वेबहुक की स्वीकृति को अवरुद्ध न करें।

ऑटो-कन्वर्ट स्वीकृति परीक्षण

कम से कम परीक्षण करें: सफल डायरेक्ट कन्वर्शन, ब्रिज/मल्टी-हॉप कन्वर्शन, न्यूनतम से नीचे धूल, अस्थायी पुनः प्रयास, स्रोत मुद्रा पर फॉलबैक, अत्यल्प भुगतान, अधिक भुगतान, डुप्लिकेट वेबहुक, गायब convert, और अस्पष्ट टाइमआउट के बाद सामंजस्य।

मैनुअल कन्वर्शन एज केस

• /v1/convert/price एक संकेतक पूर्वावलोकन है; बाजार की गति निष्पादन परिणाम बदल सकती है।
• amount_type: from स्रोत-पक्ष का अनुरोध ठीक करता है, जबकि amount_type: to लक्ष्य-पक्ष की राशि का अनुरोध करता है। पुष्टि UI प्रस्तुत करते समय अर्थ को बदलें नहीं।
• एक जोड़ी जिसके पास डायरेक्ट मार्केट नहीं है, उसे मध्यवर्ती मुद्रा के माध्यम से मार्गित किया जा सकता है। यदि केवल एक लेग पूरा होता है, तो partially_completed मध्यवर्ती क्रेडिट की रिपोर्ट करता है।
• यदि एक execute कॉल समय समाप्त हो जाता है, तो पुनः प्रयास करने से पहले मेल करें। एक मार्केट ऑर्डर तब भी निष्पादित हो सकता है जब इसका HTTP उत्तर खो गया हो।
• failed को मिलान करने की स्थिति के रूप में मानें, स्थानीय मुआवजा बैलेंस एंट्री लागू करने की अनुमति के रूप में नहीं; प्लेटफ़ॉर्म डेबिट/रिफंड लेखांकन का स्वामित्व रखता है।