API डॉक्यूमेंटेशन

परिचय

Payman API एक JSON REST API है। सभी रिक्वेस्ट HTTPS पर https://payman33.com/v1 को जाती हैं।

ऑथेंटिकेशन

अकाउंट बनाते समय मिला एक्सेस टोकन bearer टोकन के रूप में भेजें। यह सिर्फ़ एक बार दिखाया जाता है और दोबारा जारी नहीं किया जा सकता, इसलिए इसे गोपनीय रखें और कभी भी क्लाइंट-साइड कोड में न डालें।

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

मैसेज भेजें

POST /messages

फ़ील्ड	टाइप	विवरण
`to`	string[]	E.164 फ़ॉर्मेट में प्राप्तकर्ता। हर रिक्वेस्ट में 10,000 तक।
`text`	string	मैसेज का टेक्स्ट: एक SMS, 160 अक्षरों तक (GSM-7), या 70 अगर इसमें कोई दूसरे अक्षर या इमोजी हों। इससे लंबा टेक्स्ट अस्वीकार कर दिया जाता है।
`schedule_at`	string	वैकल्पिक। बाद में भेजने के लिए ISO-8601 समय, 30 दिन आगे तक।
`callback_url`	string	वैकल्पिक। HTTPS URL जिस पर डिलीवरी रिपोर्ट भेजी जाती हैं।

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

सुरक्षित रूप से दोबारा कोशिश करने के लिए Idempotency-Key हेडर जोड़ें: 24 घंटे के भीतर वही key दोबारा भेजने पर मैसेज फिर से नहीं भेजा जाता, बल्कि मूल रिस्पॉन्स लौटाया जाता है।

मैसेज स्टेटस

GET /messages/{id}

स्टेटस: पहले queued, फिर sent, फिर delivered या failed। शेड्यूल किया गया मैसेज भेजे जाने तक scheduled रहता है; POST /messages/{id}/cancel से इसे रद्द करें (और चार्ज वापस पाएँ)।

वेबहुक

डिलीवरी रिपोर्ट आने पर हम उसे आपके callback_url पर POST करते हैं। हर रिक्वेस्ट में X-Payman-Signature हेडर होता है, जो आपके वेबहुक सीक्रेट (डैशबोर्ड, API टैब) से बॉडी का HMAC-SHA256 है, ताकि आप उसे वेरिफ़ाई कर सकें। फ़ेल हुई डिलीवरी 3 बार तक दोबारा भेजी जाती है।

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

बैलेंस

GET /balance

आपका मौजूदा बैलेंस USDT में लौटाता है। कीमतें USD में दी गई हैं; 1 USDT = 1 USD।

एरर

HTTP	कोड	अर्थ
400	`invalid_request`	फ़ील्ड मौजूद नहीं है या गलत फ़ॉर्मेट में है।
401	`unauthorized`	API कुंजी मौजूद नहीं है या अमान्य है।
402	`insufficient_balance`	भेजना जारी रखने के लिए टॉप-अप करें।
403	`verification_required`	बिना वेरिफ़िकेशन वाला अकाउंट आज की प्राप्तकर्ता लिमिट तक पहुँच गया है।
404	`not_found`	आपके अकाउंट में ऐसा कोई मैसेज नहीं है।
429	`rate_limited`	बहुत ज़्यादा रिक्वेस्ट। `Retry-After` हेडर में बताए समय के बाद दोबारा कोशिश करें।

रेट लिमिट

डिफ़ॉल्ट लिमिट हर अकाउंट के लिए 50 रिक्वेस्ट प्रति सेकंड है। बड़े कैंपेन के लिए बल्क सेंड (to में कई नंबर) इस्तेमाल करें। बिना वेरिफ़िकेशन वाले अकाउंट प्रति दिन 500 प्राप्तकर्ताओं तक भेज सकते हैं।