भुगतान और निकासी/Payment API

Payment API

2328.io Payment API के साथ क्रिप्टोकरेंसी भुगतान session बनाएँ और प्रबंधित करें।

Payment API आपको भुगतान session बनाने, customer को hosted checkout पर redirect करने, और भुगतान status track करने की सुविधा देता है।

भुगतान बनाएँ

एक भुगतान session बनाता है और customer को pay करने के लिए एक URL लौटाता है।

Request parameters

Field	Type	आवश्यक	Description
`amount`	decimal	हाँ	currency में भुगतान राशि, जैसे `100.00`
`currency`	string	हाँ	Fiat currency (USD, EUR, RUB, …) या क्रिप्टोकरेंसी (USDT, TRX, BTC, …)
`order_id`	string	हाँ	आपका order ID, जैसे `ORDER-12345` (अधिकतम 128 chars)
`to_currency`	string	नहीं	पहले से चुनी हुई क्रिप्टोकरेंसी
`network`	string	नहीं*	Network code (आवश्यक यदि `to_currency` set है या `currency` एक क्रिप्टोकरेंसी है)
`url_return`	string	नहीं	भुगतान के बाद redirect URL, जैसे `https://your-site.com/return`
`url_success`	string	नहीं	`url_return` का विकल्प
`url_callback`	string	हाँ	webhook notifications के लिए URL, जैसे `https://your-site.com/webhook`
`invite_code`	string	नहीं	Referrer code
`fee_split`	decimal	नहीं	Merchant fee का वह हिस्सा जो payer पर डाला गया है, 0–100 (%)। 0 = merchant पूरी तरह भरता है, 100 = payer पूरी तरह भरता है। Project-level setting को override करता है। उदाहरण: `30` (payer fee का 30% कवर करता है)।
`price_markup`	decimal	नहीं	Invoice राशि पर markup या discount, −99 से 100 (%)। Project-level setting को override करता है। उदाहरण: `5` (+5%) या `-10` (10% discount)।
`description`	string	नहीं	वैकल्पिक invoice description (अधिकतम 200 chars)। भुगतान page पर payer को दिखाया जाता है। उदाहरण: `Premium plan — Order #12345`।
`ttl_seconds`	int	नहीं	Invoice की वैधता seconds में, `300` (5 मिनट) से `86400` (24 घंटे) तक। इस अवधि के बाद invoice expire हो जाता है और इसका भुगतान नहीं किया जा सकता। Default: `3600` (1 घंटा)। उदाहरण: `3600`।

Response

JSON

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

भुगतान पूरा करने के लिए customer को result.url पर redirect करें।
tg_deeplink — Telegram MiniApp के माध्यम से भुगतान के लिए Telegram bot deeplink।
qr — deposit address का Base64-encoded QR code (data URI)। तब उपस्थित रहता है जब address पहले से assigned हो (जब network, to_currency के साथ set हो, या जब currency एक क्रिप्टोकरेंसी हो); अन्यथा null।
txid, payment_amount — customer के pay करने तक null रहते हैं। On-chain transaction detect होने पर भर जाते हैं। यह कब हुआ जानने के लिए payment_status: paid webhook को सुनें।
exchange_rate — null यदि conversion अभी लागू नहीं है (जैसे fiat → crypto rate अभी lock नहीं हुआ है)। Payer currency चुने जाने पर भर जाता है।

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

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

Response

Click Try it to see the response here.

होस्टेड चेकआउट, H2H, और सही क्रिप्टो राशि

एक ही एंडपॉइंट तीन अलग-अलग इनवॉइस रूपों का समर्थन करता है। जानबूझकर एक चुनें; उनकी राशि की अर्थव्यवस्था को मिलाएं नहीं।

होस्टेड चेकआउट के साथ भुगतानकर्ता का चयन

amount, currency, order_id, और url_callback भेजें, लेकिन to_currency और network छोड़ दें। प्रतिक्रिया में result.url शामिल है; address, qr, और कभी-कभी भुगतानकर्ता फ़ील्ड null रहते हैं जब तक कि भुगतानकर्ता होस्टेड पेज पर दिशा का चयन नहीं करता।

JSON

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

डायरेक्ट-एड्रेस H2H इनवॉइस

दोनों to_currency और network भेजें। 2328.io API कॉल के दौरान ब्लॉकचेन चालान बनाता है, इसलिए सफल प्रतिक्रिया को ग्राहक को रीडायरेक्ट किए बिना आपके चेकआउट में प्रस्तुत किया जा सकता है।

JSON

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

इन मानों को ठीक वैसे ही प्रस्तुत करें जैसा कि लौटाया गया है:

payer_amount और payer_currency — भुगतान निर्देश;
network और address — इस चालान के लिए एकमात्र गंतव्य;
qr — उसी पते के लिए एक डेटा URI;
expires_at — चालान की समय सीमा;
url — एक उपयोगी होस्टेड फॉलबैक जब कस्टम चेकआउट पूरा नहीं हो पाता।

कभी भी कोई पता न बनाएं या उसका स्थान न लें, किसी अन्य चालान से कोई पता पुन: उपयोग न करें, या सार्वजनिक स्पॉट मूल्य से payer_amount की गणना न करें। API प्रतिक्रिया अधिकारकारी है।

सटीक क्रिप्टो राशि के लिए चालान

जब चालान स्वयं क्रिप्टो में हो, तब क्रिप्टोकरेंसी को currency में डालें:

JSON

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

अनुरोधित क्रिप्टो मूल्य payer_currency / payer_amount में संरक्षित है। सेवा आंतरिक रूप से खाता और दर क्षेत्रों के लिए USD मूल्य भी रख सकती है; उस सटीक क्रिप्टो निर्देश को उस मूल्य से बदलें नहीं। लौटाए गए दशमलव स्ट्रिंग्स को बनाए रखें, जिसमें अंतिम सटीकता शामिल है।

केवल एक समर्थित नेटवर्क वाली क्रिप्टोकरेंसी के लिए, नेटवर्क स्वचालित रूप से चुना जा सकता है। निर्णायक एकीकरण के लिए स्पष्ट रूप से network प्रदान करना फिर भी अनुशंसित है। स्थिरकॉइन जैसी बहु-नेटवर्क संपत्तियों के लिए, इसे हमेशा भेजें।

इडेम्पोटेंसी और पुनः प्रयास

order_id प्रमाणित व्यापारी परियोजना तक सीमित है और निर्माण इडेम्पोटेंसी कुंजी के रूप में कार्य करता है। यदि कोई भुगतान पहले से मौजूद है, तो API उस सत्र को state: 0 के साथ लौटाता है।

एक ही order_id के साथ पुनः प्रयास not का मतलब “इस चालान को अपडेट करें” है। बदली गई राशि, मुद्रा, कॉलबैक, मार्कअप, TTL, या दिशा फ़ील्ड को अनदेखा किया जा सकता है क्योंकि मौजूदा सत्र लौटाया जाता है। पहले अनुरोध को स्थायी बनाएं और अपने स्वयं के एप्लिकेशन में विरोधाभासी पुनः प्रयासों को अस्वीकार करें।

सिफारिश की गई निर्माण एल्गोरिदम:

अपने स्थानीय भुगतान प्रयास और अद्वितीय order_id को एक डेटाबेस लेन-देन में डालें।
हस्ताक्षरित API अनुरोध भेजें।
वापसी हुई uuid और पूरा उत्तर स्थायी रूप से सहेजें।
यदि HTTP परिणाम खो गया है, तो समान अनुरोध दोबारा प्रयास करें या /v1/payment/info को order_id द्वारा प्राप्त करें।
केवल इसलिए कि अपस्ट्रीम अनुरोध समय समाप्त हो गया, कभी भी दूसरा स्थानीय आदेश न बनाएं।

भुगतान किनारे मामले

स्थिति	सही संचालन
`address` / `qr` है `null`	भुगतानकर्ता दिशा आरंभ नहीं की गई है। `url` पर पुनर्निर्देशित करें, या नए `order_id` के साथ सही तरीके से निर्दिष्ट नया H2H इनवॉइस बनाएं।
HTTP `400` सत्यापन त्रुटि	फील्ड-लेवल `errors` पढ़ें; बिना बदले इनपुट को फिर से प्रयास न करें।
HTTP `429`	जिटर वाले घातीय बैकऑफ के साथ पुनः प्रयास करें और वही `order_id` रखें।
HTTP `503` / `direction_disabled`	`/v1/directions` ताज़ा करें; दिशा को अस्थायी रूप से छिपाएं या बाद में पुनः प्रयास करें।
क्लाइंट अनुरोध समय समाप्त	परिणाम को अज्ञात माना जाए। कुछ भी बनाने से पहले `order_id` द्वारा क्वेरी करें।
`underpaid_check`	आंशिक घटना को सहेजें और टॉप-अप या बाद की स्थिति का इंतजार करें। जब अधिक txids आएं तो दो बार क्रेडिट न करें।
`underpaid`	अंतिम अधूरे भुगतान की स्थिति। वास्तविक क्रेडिट राशि पर अपने कॉन्फ़िगर किए गए फुलफिलमेंट/मैनुअल-रिव्यु पॉलिसी लागू करें।
`overpaid`	अधिक धन के साथ सफल भुगतान। प्रतिलिपि रहित ढंग से पूरा करें और मिलान/रिफंड पॉलिसी के लिए वास्तविक राशि को सुरक्षित रखें।
`aml_lock`	स्वतः फंड्स जारी या पूरा न करें; इसे अनुपालन/सपोर्ट वर्कफ़्लो में रूट करें।
`cancel`	चालान की अवधि समाप्त या रद्द कर दी गई। यह न समझें कि देर से ऑन-चेन ट्रांसफर असंभव है; किसी भी बाद की घटना को सपोर्ट के साथ मिलाकर मिलान करें।

ब्राउज़र रिटर्न URL केवल नेविगेशन के लिए है। एक ग्राहक इसे बिना भुगतान किए खोल सकता है, भुगतान करने के बाद इसे बंद कर सकता है, या बाद में फिर से चला सकता है। केवल सत्यापित API/वेबहुक स्थिति ही व्यापारी आदेश को निपटा सकती है।

भुगतान की जानकारी

uuid या order_id से वर्तमान भुगतान status प्राप्त करें।

Request parameters

Field	Type	आवश्यक	Description	Values
`uuid`	string	हाँ*	Payment UUID (creation पर `result.uuid` से)
`order_id`	string	हाँ*	आपका order ID

uuid या order_id में से कम से कम एक आवश्यक है।

RequestPOST/v1/payment/info

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

Response

Click Try it to see the response here.

भुगतान सूची

filtering और pagination के साथ सभी भुगतानों की सूची प्राप्त करें।

Request parameters

Field	Type	आवश्यक	Description
`status`	string	नहीं	भुगतान status के अनुसार filter (देखें References)
`date_from`	date	नहीं	प्रारंभिक तिथि (YYYY-MM-DD), जैसे `2026-01-01`
`date_to`	date	नहीं	अंतिम तिथि (YYYY-MM-DD), जैसे `2026-01-31`
`page`	int	नहीं	Page संख्या, default `1`
`per_page`	int	नहीं	प्रति page items, default `15`, अधिकतम `5000`

RequestPOST/v1/payment/list

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

Response

Click Try it to see the response here.