POST - इनवॉइस बनाएं

एक क्रिप्टो भुगतान इनवॉइस बनाएं। मर्चेंट राशि (USD), ऑर्डर जानकारी और callback URL भेजता है; सिस्टम trans_id और url_payment लौटाता है ताकि ग्राहक को चेकआउट पेज पर रीडायरेक्ट किया जा सके।

Endpoint

POST https://api.payerscan.com/payment/crypto

Headers

Header	आवश्यक	विवरण
Content-Type	हाँ	application/json
x-api-key	हाँ	स्टोर की API Key

Request Body (JSON)

फ़ील्ड	प्रकार	आवश्यक	सीमाएं	विवरण
merchant_id	string	हाँ	खाली नहीं	स्टोर का मर्चेंट कोड (API Key से मेल खाना चाहिए)।
amount	number | string	हाँ	> 0 और ≤ 1,000,000	भुगतान राशि (USD)। उदाहरण: 100, "100"।
callback_url	string	अनुशंसित	अधिकतम 500 अक्षर, वैध URL	completed या expired स्थिति पर webhook प्राप्त करने का URL।
completed_url	string	नहीं	अधिकतम 500 अक्षर, वैध URL	सफल भुगतान के बाद रीडायरेक्ट URL।
expired_url	string	नहीं	अधिकतम 500 अक्षर, वैध URL	इनवॉइस समाप्त होने पर रीडायरेक्ट URL।
name	string	नहीं	अधिकतम 255 अक्षर	इनवॉइस का नाम/शीर्षक।
description	string	नहीं	अधिकतम 1000 अक्षर	इनवॉइस का विवरण।
request_id	string	नहीं	अधिकतम 255 अक्षर	मर्चेंट का ऑर्डर ID क्रॉस-रेफरेंस के लिए (response और webhook में लौटाया जाता है)। Idempotency के लिए भी उपयोग किया जाता है — नीचे नोट्स देखें।

उदाहरण Request

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

Response

सफल (HTTP 200)

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}

फ़ील्ड	विवरण
request_id	आपके द्वारा request में भेजा गया मान।
trans_id	अद्वितीय इनवॉइस कोड, लुकअप और webhook क्रॉस-रेफरेंस के लिए उपयोग किया जाता है।
status	नया बनाने पर हमेशा "waiting"।
amount	USD राशि (string)।
url_payment	चेकआउट पेज URL — ग्राहक को यहां रीडायरेक्ट करें।
expires_in_minutes	इनवॉइस की समाप्ति समय (मिनट)।

त्रुटियां (4xx / 5xx)

सभी त्रुटियां इस प्रारूप का पालन करती हैं:

{
  "status": "error",
  "message": "त्रुटि विवरण",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}

HTTP	error_code	विवरण
400	VALIDATION_ERROR	अमान्य body (आवश्यक फ़ील्ड गायब, गलत प्रकार, सीमाएं पार)। details.errors में विवरण है।
400	INVALID_MERCHANT_ID	merchant_id स्टोर की API Key से मेल नहीं खाता।
400	NO_PAYMENT_METHOD	स्टोर में कोई भुगतान विधि कॉन्फ़िगर नहीं है। इनवॉइस बनाने से पहले कम से कम एक वॉलेट पता या एक्सचेंज प्लेटफॉर्म कॉन्फ़िगर करें।
401	MISSING_API_KEY	कोई x-api-key header प्रदान नहीं किया गया।
401	INVALID_API_KEY	API key अमान्य है या मौजूद नहीं है।
403	ACCOUNT_INACTIVE	इस API key से जुड़ा खाता अक्षम है।
403	STORE_INACTIVE	इस API key से जुड़ा स्टोर अक्षम है।
402	INSUFFICIENT_BALANCE	स्टोर का शेष शुल्क के लिए अपर्याप्त है। details में current_balance, required_fee, shortage, fee_rate_percent, discount_percent, invoice_amount है।
429	RATE_LIMIT_EXCEEDED	अनुरोध सीमा पार (burst या sustained)। limit_type, retry_after_seconds है।
500	INTERNAL_ERROR	सर्वर त्रुटि।

त्रुटि कोड विवरण: API त्रुटि कोड।

Rate Limit

• Burst: 5 अनुरोध/सेकंड (प्रति API Key या IP)।
• Sustained: 60 अनुरोध/मिनट (प्रति API Key या IP)।

सीमा पार → HTTP 429, body में error_code: "RATE_LIMIT_EXCEEDED", retry_after_seconds।

नोट्स

• भुगतान विधि: स्टोर को इनवॉइस बनाने से पहले कम से कम एक वॉलेट पता या एक्सचेंज प्लेटफॉर्म (Binance Pay, OKX, Bybit, MEXC, Gate.io, Bitget, आदि) कॉन्फ़िगर करना होगा। यदि कॉन्फ़िगर नहीं किया गया, API NO_PAYMENT_METHOD त्रुटि लौटाता है।
• Idempotency: यदि आप एक ही स्टोर के लिए पहले से मौजूद request_id भेजते हैं, तो API नया बनाने के बजाय मौजूदा इनवॉइस लौटाता है। Response में idempotent: true शामिल होगा। यह retry करते समय डुप्लिकेट इनवॉइस बनने से रोकता है।
• शुल्क: शुल्क amount (USD) पर गणना किया जाता है और स्टोर के शेष से काटा जाता है। इनवॉइस बनाने से पहले पर्याप्त शेष सुनिश्चित करें। मुफ्त परीक्षण अवधि के दौरान, शुल्क माफ किया जाता है।
• Callback: completed/expired webhooks प्राप्त करने के लिए हमेशा callback_url भेजें; अन्यथा, आप केवल GET https://api.payerscan.com/invoice/:trans_id के माध्यम से जांच कर सकते हैं।
• request_id: webhook-ऑर्डर मैचिंग और idempotency सपोर्ट के लिए भेजने की अनुशंसा की जाती है।