क्रिप्टो मास पेमेन्ट एपीआई: गैर-निगरानी तरीके से पेमेन्ट स्वचालित करें

क्रिप्टो मास पेमेन्ट एपीआई वास्तव में क्या करता है

एकल POST /v1/payout कॉल पूरे बैच के लिए फंड आरक्षित करता है, प्रत्येक प्राप्तकर्ता को मान्य करता है, और एक पेमेन्ट बैच बनाता है जिसे आप ट्रैक कर सकते हैं। यह एक क्रिप्टो मास पेमेन्ट एपीआई पर एक गेटवे के साथ आंतरिक Payora बैलेंस: एपीआई सबमिशन, मान्यता, स्थिति और वेबहुक्स, जबकि रिलीज स्वीकृति, हस्ताक्षर या रिलीज प्रवाह के अनुसार होती है जो खाते के लिए कॉन्फ़िगर की गई है। एक बनाया गया बैच ऑन-चेन पेमेन्ट की पुष्टि के समान नहीं है, और प्राप्तकर्ताओं को तब तक भुगतान नहीं किया गया माना जाना चाहिए जब तक कि स्थिति और लेनदेन के प्रमाण इसे साबित न करें। यदि यह व्यापारिक समझौता स्वीकार्य लगता है, तो एपीआई एक मैनुअल पेरोल या सहयोगी रन को दो या तीन कोड की पंक्तियों में बदल देता है।

यह एक डेवलपर गाइड है। यह ठीक उसी अनुबंध की नकल करता है जो API दस्तावेज़ से सटीक अनुबंध की नकल करता है ताकि आप आज इसके खिलाफ शिप कर सकें: एंडपॉइंट्स, HMAC साइनिंग, Idempotency-Key, कड़ा 422 सत्यापन, payout.sent वेबहुक, और कैसे रद्द करना रोके गए संतुलन को मुक्त करता है। यदि आप पहले उत्पाद अवलोकन चाहते हैं, तो पढ़ें मास भुगतान पृष्ठ।

क्यों सबमिशन और रिलीज अलग हैं

जब आप एक बैच सबमिट करते हैं — कैबिनेट से या API के माध्यम से — Payora रिजर्व करता है कुल के साथ-साथ प्रति-आइटम मूव शुल्क आपके आंतरिक संतुलन, इसलिए बैच अधिक खर्च नहीं किया जा सकता। बैच फिर खाते के लिए कॉन्फ़िगर किए गए अनुमोदन, हस्ताक्षर या रिलीज़ प्रवाह का पालन करता है। इसे एक समीक्षा की गई भुगतान कार्यप्रवाह के रूप में मानें, न कि इस प्रमाण के रूप में कि पैसे पहले से ही हर प्राप्तकर्ता के पास पहुँच चुके हैं।

आपका सुरक्षा मॉडल सरल है: "API कॉल, सिक्के तुरंत चले गए" को अपने मानसिक मॉडल के रूप में न बनाएं जब तक कि यह स्पष्ट रूप से वह उत्पाद न हो जिसे आपने चुना है। पूरी तरह से स्वचालित हॉट-वॉलेट-शैली के भुगतान उत्पाद तेजी से हो सकते हैं, लेकिन वे एक खाते या सर्वर के समझौते के विस्फोट क्षेत्र को भी बढ़ाते हैं। Payora के वर्तमान संचालन के चरणों की जांच उत्पाद दस्तावेज़ों और खाता सेटिंग्स में की जानी चाहिए इससे पहले कि आप एक बैच को जारी के रूप में मानें।

प्रमाणीकरण और अनुरोध हस्ताक्षर

क्रिप्टो मास भुगतान API Payora के बाकी हिस्सों के समान प्रमाणीकरण का उपयोग करता है। प्रत्येक अनुरोध में तीन हेडर होते हैं: X-Payora-Key, X-Payora-Timestamp (यूनिक्स सेकंड, ±120s स्क्यू), और X-Payora-Signature। हस्ताक्षर एक HMAC-SHA256 है जो टाइमस्टैम्प, एक शाब्दिक बिंदु, और सटीक कच्चा अनुरोध शरीर पर है:

X-Payora-Signature = hex(HMAC-SHA256(api_secret, timestamp + "." + raw_body))

आप वास्तव में जो बाइट्स भेजते हैं, उन्हें हस्ताक्षरित करें, किसी भी पुनः-सीरियलाइजेशन से पहले। यदि आपका HTTP क्लाइंट JSON को फिर से एन्कोड करता है, तो पहले कच्चे शरीर को कैप्चर करें और उसे हैश करें। यह वही योजना है जिसका उपयोग इनबाउंड वेबहुक्स को सत्यापित करने के लिए किया जाता है, जो कि HMAC-SHA256 वेबहुक हस्ताक्षर सत्यापन.

POST /v1/payout: एक बैच सबमिट करें

एक मुद्रा भेजें, 500 आइटम तक, और एक वैकल्पिक नोट। प्रत्येक आइटम एक पता, एक राशि के रूप में एक स्ट्रिंग, और एक वैकल्पिक tag — जब संपत्ति को एक की आवश्यकता होती है तो XRP गंतव्य टैग या XLM मेमो।

curl -X POST https://api.payora.money/v1/payout \
  -H "X-Payora-Key: pk_live_9f3c8a12" \
  -H "X-Payora-Timestamp: 1753280400" \
  -H "X-Payora-Signature: 7b1e0c4d9a55f2..." \
  -H "Idempotency-Key: payroll-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "items": [
      {"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "250.00"},
      {"address": "TXk9mP2v7wQ3nR5tYb1cD8eF4gH6jK0lMn", "amount": "1800.00", "tag": ""}
    ],
    "note": "July contractors"
  }'

सफलता पर आपको मिलता है 201 एक बैच जिसे आप ट्रैक कर सकते हैं। total यह राशियों का योग है, fee यह आपके योजना का मूव शुल्क है (फ्री पर 1.5%) और सिक्के का नेटवर्क शुल्क, और दोनों पहले से ही आपके बैलेंस के खिलाफ रखे गए हैं:

{
  "batch_id": "po_7Qd2K8xM4b",
  "status": "pending",
  "currency": "USDT",
  "item_count": 2,
  "total": "2050.00",
  "fee": "20.50",
  "items": [
    {"index": 0, "address": "TR7NHqjeKQ...", "amount": "250.00", "status": "pending"},
    {"index": 1, "address": "TXk9mP2v7w...", "amount": "1800.00", "status": "pending"}
  ]
}

भुगतान स्वीकार करना अभी भी 0% है; मूव शुल्क केवल तब लागू होता है जब पैसा बाहर जाता है। नेटवर्क शुल्क अलग होते हैं और प्रसारण समय पर ऑन-चेन भुगतान किए जाते हैं।

कठोर सत्यापन: कोई चुपचाप गिराया गया प्राप्तकर्ता नहीं

सत्यापन जानबूझकर सब या कुछ नहीं है। यदि कोई पता चुने गए नेटवर्क के लिए गलत है, या कोई राशि सिक्के द्वारा समर्थित दशमलव स्थानों से अधिक है, तो पूरा बैच को 422 और दोषपूर्ण अनुक्रमांक के साथ अस्वीकृत कर दिया जाता है। कुछ भी कतारबद्ध नहीं होता, कुछ भी रोका नहीं जाता।

HTTP/1.1 422 Unprocessable Entity
{
  "error": "validation_failed",
  "invalid_items": [3, 17],
  "message": "invalid address at index 3; amount exceeds coin precision at index 17"
}

यह वह व्यवहार है जो आप पेरोल के लिए चाहते हैं। एक गेटवे जो चुपचाप एक खराब पंक्ति को काटता है 1800.123456789 या छोड़ता है, वह किसी व्यक्ति को कम भुगतान करेगा या हटा देगा, और आप तब तक नहीं देखेंगे जब तक कोई शिकायत नहीं करता। झंडा लगाए गए अनुक्रमांक को ठीक करें और पूरे बैच को फिर से प्रस्तुत करें।

इडेम्पोटेंसी: पुनः प्रयास कभी भी डबल-पे नहीं करते

नेटवर्क समय समाप्त हो जाते हैं। एक भुगतान अनुरोध जो मध्य में विफल होता है, उसे अंधाधुंध पुनः प्रयास करना खतरनाक है, इसलिए एक Idempotency-Key हेडर भेजें — उस तार्किक बैच के लिए कोई भी स्थिर, अद्वितीय स्ट्रिंग (एक पेरोल अवधि, एक चालान समूह)। यदि वही कुंजी वाला अनुरोध फिर से आता है, तो Payora मूल बैच लौटाता है बजाय इसके कि एक दूसरा बनाए। उसी बैच के हर पुनः प्रयास के लिए कुंजी का पुन: उपयोग करें; वास्तव में नए बैच के लिए एक ताजा कुंजी का उपयोग करें।

• एक ही कुंजी, एक ही बैच — समय समाप्त होने के बाद पुनः प्रयास करना सुरक्षित है; आपको पहला परिणाम वापस मिलता है।
• नई कुंजी — एक नया बैच, आपके संतुलन पर एक नया नियंत्रण।
• वापस किए गए को स्टोर करें batch_idजितनी जल्दी हो सके, ताकि आप समायोजन कर सकें भले ही प्रतिक्रिया खो गई हो।

GET /v1/payout/{id} के साथ समायोजन करें

कॉन्फ़िगर की गई रिलीज़ फ़्लो के आगे बढ़ने के बाद, वर्तमान स्थिति के लिए पोल करें GET /v1/payout/{id} और एक प्रति-आइटम tx_hash जब लेनदेन का प्रमाण उपलब्ध हो। GET /v1/payout डैशबोर्ड और ऑडिट के लिए हाल के बैचों की सूची बनाता है। batch_id और प्रत्येक आइटम अनुक्रमांक को अपने रिकॉर्ड के खिलाफ स्टोर करें ताकि हर प्राप्तकर्ता उस प्रमाण से मेल खा सके जिसे आप उन्हें दिखा सकते हैं।

क्या आपको रिलीज़ से पहले एक वापस खींचने की आवश्यकता है?POST /v1/payout/{id}/cancelएक अभी भी लंबित बैच को रद्द करता है और रखे गए संतुलन को जारी करता है पूरी तरह से। एक बार जब आइटम ऑन-चेन जारी हो जाते हैं, तो वे अंतिम होते हैं, जैसे कोई भी क्रिप्टो लेनदेन — रद्द केवल तब काम करता है जब बैच लंबित हो।

पेमेन्ट.sent वेबहुक

हमेशा के लिए पोलिंग करने के बजाय, सदस्यता लें payout.sent। कॉन्फ़िगर की गई रिलीज़ प्रवाह पूरा होने के बाद और Payora के पास बैच आइटम के लिए लेनदेन का प्रमाण होने पर, Payora उसी HMAC साइनिंग का उपयोग करके एक साइन किया हुआ वेबहुक भेजता है invoice.paid। इसे उसी तरह सत्यापित करें — टाइमस्टैम्प, डॉट, कच्चे शरीर पर सिग्नेचर को फिर से गणना करें और स्थायी समय में तुलना करें:

$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $webhook_secret);
if (!hash_equals($expected, $signature_header)) { http_response_code(400); exit; }
// payload.event == "payout.sent", payload.batch_id, payload.items[].tx_hash

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

एक न्यूनतम एकीकरण चेकलिस्ट

1. एक खाता बनाएं और API कुंजी उत्पन्न करें पंजीकरण करें; आंतरिक बैलेंस को उस मुद्रा में फंड करें जिसमें आप भुगतान करेंगे।
2. कच्चा JSON बॉडी बनाएं, इसे साइन करें (टाइमस्टैम्प + "." + बॉडी) HMAC-SHA256 के साथ, तीन हेडर के साथ एक Idempotency-Key.
3. POST /v1/payout; पर 201 स्थायी करें batch_id, पर 422 झंडा लगे इंडेक्स को ठीक करें और फिर से भेजें।
4. खाते के लिए कॉन्फ़िगर किए गए अनुमोदन, साइनिंग या रिलीज़ चरणों को पूरा करें।
5. सत्यापित करें payout.sent वेबहुक, या पोल GET /v1/payout/{id}और प्रत्येक को रिकॉर्ड करेंtx_hash.

यह पूरा लूप है। API थकाऊ, त्रुटि-प्रवण भाग को हटा देता है - 500-लाइन बैच का निर्माण, मान्यकरण और ट्रैकिंग - जबकि आपके संचालन नियंत्रण यह तय करते हैं कि कब एक समीक्षा किया गया बैच वास्तव में जारी किया जाता है।

निर्माण शुरू करें

Mass Payout API अनुभाग को पढ़ें दस्तावेज़कीज़ प्राप्त करें पंजीकरण करेंऔर मास भुगतान पृष्ठ पर फीचर को अंत से अंत तक देखें। आप आज बैच निर्माण को स्वचालित कर सकते हैं और भुगतान जारी करने को आपके खाते के लिए कॉन्फ़िगर किए गए नियंत्रणों से जोड़े रख सकते हैं।