क्रिप्टो भुगतान स्वीकार करें

Paysell एक पेमेंट प्रोसेसर है, वॉलेट नहीं। आप कभी भी प्राइवेट की को हैंडल नहीं करते, ब्लॉकचेन पर नज़र नहीं रखते, या यह तय नहीं करते कि लेन-देन कब अंतिम है — यह हिस्सा हम संभालते हैं।

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

छह चरण, ज़्यादातर हमारी तरफ़ से:

1. 1

   आपका ग्राहक पे पर क्लिक करता है

   आपका सर्वर राशि और आपके अपने ऑर्डर रेफ़रेंस के साथ हमारे API को कॉल करता है।

2. 2

   हम एक पता देते हैं

   एक ताज़ा रिसीविंग एड्रेस पहले से तैयार पूल से लिया जाता है और इस इनवॉइस से जोड़ा जाता है। एक पता ठीक एक खुले इनवॉइस का होता है, इसी तरह भुगतान उससे मिलाया जाता है।

3. 3

   ग्राहक कॉइन भेजता है

   वह QR कोड स्कैन करता है या पता कॉपी करता है। उसे उस payment_url पर भेजें जो हम लौटाते हैं और पेज आपके लिए सब कुछ संभाल लेता है — राशि, पता, QR, काउंटडाउन, लाइव स्टेटस।

4. 4

   हम ट्रांसफ़र पहचानते हैं

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

5. 5

   हम फ़ाइनलिटी का इंतज़ार करते हैं

   मास्टरचेन में शामिल होना, साथ में ऊपर तीन ब्लॉक। लगभग पंद्रह सेकंड — एक भुगतान जो सेटल दिखे और बाद में गायब हो जाए, वह आपका नुकसान होगा, इसलिए हम यह जोखिम नहीं लेते।

6. 6

   जमा हो गया, और आपको बताया जाता है

   फ़ीस काट ली जाती है, बाकी आपके बैलेंस में आता है, और आपके order_id के साथ एक हस्ताक्षरित वेबहुक आपके सर्वर पर जाता है।

भुगतान से कॉलबैक तक: लगभग एक मिनट — लगभग पंद्रह सेकंड नेटवर्क पुष्टिकरण के, बाकी निगरानी किए गए पतों का हमारा स्वीप है।

फ़ीस 0.2% है, आपकी दुकान के रजिस्टर होने के समय तय हो जाती है। अगर बाद में मानक दर बदलती है, तो आपकी नहीं बदलती — यह हर इनवॉइस में एक संख्या के रूप में लिखी जाती है, किसी सेटिंग के संदर्भ के रूप में नहीं।

फ़ीस जो वास्तव में आता है उस पर ली जाती है, इनवॉइस में मांगी गई राशि पर नहीं। 5 USDT का बिल बनाएं और 20 मिलें, तो फ़ीस 20 पर गणना होती है। कम भुगतान हो, तो जो आया उस पर गणना होती है।

Invoice:   5.000000 USDT
Received: 20.000000 USDT   (the buyer sent more)
Fee 0.2%:  0.040000 USDT   (on 20, not on 5)
Credited: 19.960000 USDT

अतिरिक्त भुगतान पूरी तरह जमा किया जाता है — हम अंतर नहीं रखते। कम भुगतान इनवॉइस को खुला छोड़ देता है ताकि खरीदार उसी पते पर बाकी राशि जमा कर सके।

पाँच कदम। दो आपके अकाउंट एरिया में क्लिक हैं, एक आपके सर्वर से भेजी गई एक ही रिक्वेस्ट है, और आख़िरी दो अपने आप हो जाते हैं।

1. 1

   एक दुकान बनाएं

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

2. 2

   एक API की जारी करें

   आपकी दुकान → API कीज़ → नई की। की और वेबहुक सीक्रेट एक ही बार दिखाए जाते हैं, फिर कभी नहीं। इन्हें डेटाबेस पासवर्ड की तरह सुरक्षित रखें, और इन्हें कभी ब्राउज़र में न भेजें।

3. 3

   एक इनवॉइस बनाएं

   आपके सर्वर से एक रिक्वेस्ट, वापसी में एक लिंक। नीचे दिए गए चारों स्निपेट बिल्कुल एक ही चीज़ भेजते हैं।

4. 4

   खरीदार को payment_url पर भेजें

   यही पूरा चेकआउट है — राशि, पता, QR कोड, काउंटडाउन, लाइव स्टेटस — और बनाने के लिए कुछ नहीं है। खरीदार को असल में क्या दिखता है, इसके लिए देखें चेकआउट।

5. 5

   वेबहुक का इंतज़ार करें

   जैसे ही पैसा चेन पर पुष्ट होकर जमा हो जाता है, हम आपके सर्वर पर हस्ताक्षरित payment.credited इवेंट POST करते हैं। हस्ताक्षर सत्यापित करें, फिर ऑर्डर को भुगतान किया गया चिह्नित करें — लेकिन तभी जब data.status paid या overpaid हो। देखें वेबहुक।

The same request, four ways

curl -X POST https://paysell.me/api/merchant/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT_TON",
    "amount": "5",
    "order_id": "order-1042",
    "idempotency_key": "order-1042"
  }'

खरीदार को रिस्पॉन्स में मिले payment_url पर रीडायरेक्ट करें। बस हो गया — बाकी वेबहुक के रूप में आएगा।

What to do next

• Write the webhook receiver — Webhooks and A complete receiver. Nothing else on this page matters as much: it is what turns a payment into a paid order.
• Handle underpaid and overpaid, not just paid — see Status reference.
• Read Typical mistakes, then walk the go-live checklist before you point real customers at it.

हर रिक्वेस्ट Authorization हेडर में आपकी की ले जाती है:

Authorization: Bearer sk_live_IH4SNdnYsv-yabTuPCVln4vOvvGoEyxA

यहाँ जारी की गई हर की sk_live_ से शुरू होती है। sk_test_ प्रीफ़िक्स केवल टेस्ट नेटवर्क पर चलने वाली डिप्लॉयमेंट में मौजूद है, और ऐसी कोई डिप्लॉयमेंट पेश नहीं की जाती — देखें टेस्टिंग। हम एक तरफ़ा हैश स्टोर करते हैं, की खुद नहीं, इसलिए कोई भी, हम सहित, इसे आपको दोबारा नहीं दिखा सकता। खो दी? नई जारी करें और पुरानी रद्द करें।

दुकान की से निकाली जाती है, इसलिए कोई भी रिक्वेस्ट दुकान आईडी नहीं लेती। एक की केवल अपनी ही दुकान पर काम कर सकती है।

पते में संस्करण होता है: /api/merchant/v1/…। एक संस्करण के भीतर हम केवल फ़ील्ड जोड़ते हैं — कुछ भी नाम नहीं बदलता और चुपचाप अर्थ नहीं बदलता। जो बदलाव आपका कोड तोड़ देगा, उसे नया उपसर्ग /v2 मिलता है, और /v1 घोषित अवधि तक चलता रहता है।

This is the whole merchant API. Balances, payouts and history are not in it — they live in your account area, where a person is looking at them.

Every path is relative to https://paysell.me/api/merchant/v1. There is no list endpoint and no refund endpoint — see Refunds.

रिक्वेस्ट बॉडी

रिस्पॉन्स · 201

{
  "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
  "payment_url": "https://paysell.me/pay/12c22c1a-a496-4c1e-abe3-72661ef8706e",
  "address": "UQAvDJp7QDwqRcuNQBiK2GhBt71Xh1_UMYPCzMkQAoBPmZKl",
  "asset": "USDT_TON",
  "amount": "5",
  "amount_minor": "5000000",
  "status": "pending",
  "paid": "0",
  "paid_minor": "0",
  "order_id": "order-1042",
  "description": "Pro subscription",
  "expires_at": "2026-09-06T17:20:55Z",
  "created_at": "2026-09-06T15:20:55Z"
}

इसे अपने ऑर्डर में कैसे इस्तेमाल करें

ऊपर जैसा ही रूप, जिसमें status, paid और paid_minor वर्तमान स्थिति दिखाते हैं: paid बताता है कि सामान्य इकाइयों में कितना आ चुका है, और paid_minor वही रकम सबसे छोटी इकाई में पूर्णांक के रूप में। वेबहुक छूट जाने पर बैकअप के रूप में, या धन्यवाद पेज पर उपयोगी।

इसे हर कुछ सेकंड में एक बार से ज़्यादा पोल न करें, और वेबहुक को मुख्य चैनल मानें। किसी और दुकान के इनवॉइस 404 का जवाब देते हैं — 403 नहीं, ताकि किसी आईडी के अस्तित्व की जांच न की जा सके।

ऐसे इनवॉइस को बंद कर देता है जो अब भी खुला है — pending या underpaid — और उसका पता रिलीज़ कर देता है। इसका उपयोग तब करें जब ग्राहक चेकआउट छोड़ दे: पते एक सीमित संसाधन हैं, और उन्हें लौटाना पूल को स्वस्थ रखता है।

जो इनवॉइस अब खुला नहीं है, वह 409 का जवाब देता है। किसी underpaid इनवॉइस को रद्द करने से किसी को कॉइन वापस नहीं मिलते: जो पैसा पहले ही जमा हो चुका है वह आपके बैलेंस पर बना रहता है, और बंद केवल यह होता है कि अब टॉप-अप स्वीकार नहीं किया जाएगा।

की बनाते समय वेबहुक URL सेट करें। जब भुगतान जमा होता है तब हम वहाँ POST भेजते हैं — और तब भी जब अतिरिक्त जांच के लिए रोकी गई कोई जमा राशि अस्वीकार कर दी जाती है। हर डिलीवरी हस्ताक्षरित होती है, और जब तक आप 2xx का जवाब न दें तब तक हम लगभग डेढ़ दिन तक दोबारा कोशिश करते रहते हैं। माल status: paid या overpaid पर छोड़ें — केवल कॉल आ जाने पर नहीं।

इवेंट

क्या आता है

{
  "event_id": "99f74f58-efbb-4af1-b0a3-76b0073f9e6b",
  "type": "payment.credited",
  "data": {
    "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
    "order_id": "order-1042",
    "asset": "USDT_TON",
    "amount": "5000000",
    "credited": "4905000",
    "fee": "95000",
    "status": "paid",
    "paid_minor": "5000000",
    "tx_hash": "97a1f0…"
  }
}

{
  "event_id": "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
  "type": "payment.rejected",
  "data": {
    "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
    "order_id": "order-1042",
    "asset": "USDT_TON",
    "amount": "5000000",
    "tx_hash": "97a1f0…",
    "reason": "could not be matched to any order"
  }
}

फ़ील्ड मैपिंग

हर डिलीवरी के हेडर

X-Paysell-Event:      payment.credited
X-Paysell-Event-Id:   99f74f58-efbb-4af1-b0a3-76b0073f9e6b
X-Paysell-Timestamp:  1789000000
X-Paysell-Signature:  sha256=6f1c0e6a…

हस्ताक्षर सत्यापित करना

हर रिक्वेस्ट पर उस वेबहुक सीक्रेट से हस्ताक्षर होता है जो की बनाते समय एक ही बार दिखाया गया था। हस्ताक्षर है HMAC-SHA256(secret, "{timestamp}.{raw_body}") — X-Paysell-Timestamp से लिया गया टाइमस्टैम्प, एक शाब्दिक बिंदु, और फिर बॉडी के बाइट्स। कुछ भी करने से पहले इसे जांचें: इसके बिना, जो कोई भी आपका URL जान लेगा वह आपको एक भुगतान किया हुआ ऑर्डर थमा सकता है।

Python:

import hmac, hashlib, time

def is_ours(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:      # ±5 minutes
        return False
    signed = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    # compare_digest, not ==: a plain comparison leaks the answer through timing
    return hmac.compare_digest("sha256=" + expected, signature)

Node.js:

const crypto = require("node:crypto")

function isOurs(body, signature, timestamp, secret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false  // ±5 min
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(timestamp + ".").update(body)   // body is the raw Buffer, not a parsed object
    .digest("hex")
  const a = Buffer.from(expected), b = Buffer.from(signature)
  // timingSafeEqual throws when the lengths differ, so check that first
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

कच्चे बॉडी बाइट्स पर हस्ताक्षर करें, बिल्कुल वैसे ही जैसे वे मिले हैं। JSON को पार्स करके दोबारा सीरियलाइज़ करेंगे तो बाइट्स बदल जाएंगे — की का क्रम, स्पेसिंग — और हस्ताक्षर मेल नहीं खाएगा। तुलना नियत समय में करें (hmac.compare_digest, crypto.timingSafeEqual): सादा == गलत पहले बाइट पर जल्दी लौट आता है, और यही अंतर एक-एक बाइट करके हस्ताक्षर का अनुमान लगाने के लिए काफ़ी है।

टाइमस्टैम्प विंडो

जिसका भी टाइमस्टैम्प आपकी अपनी घड़ी से पाँच मिनट से ज़्यादा दूर हो — किसी भी दिशा में — उसे अस्वीकार करें। टाइमस्टैम्प हस्ताक्षरित स्ट्रिंग के अंदर ठीक इसीलिए है कि हस्ताक्षर तोड़े बिना उसे बदला न जा सके; विंडो ही उसे असल सुरक्षा में बदलती है। इसके बिना, एक बार पकड़ी गई रिक्वेस्ट हमेशा के लिए वैध रहती है और कभी भी दोहराई जा सकती है — अकेला हस्ताक्षर कभी एक्सपायर नहीं होता। अपने सर्वर की घड़ी NTP पर रखें, वरना यह जांच अच्छी-भली डिलीवरी को भी अस्वीकार करने लगेगी।

दोहराव

एक ही इवेंट एक से ज़्यादा बार आ सकता है। यह बग नहीं है: हम तब तक दोबारा कोशिश करते हैं जब तक आप 2xx का जवाब न दें, और जो डिलीवरी सफल रही लेकिन जिसका जवाब हम तक कभी नहीं पहुँचा, वह फिर से भेजी जाती है। X-Paysell-Event-Id रिकॉर्ड करें (यह बॉडी में event_id के रूप में भी आता है) और दूसरी बार आने पर कुछ न होने दें।

दोबारा कोशिशें

पहली कोशिश भुगतान जमा होते ही निकल जाती है। अगर वह विफल होती है — टाइमआउट, कनेक्शन अस्वीकार, TLS एरर, कोई रीडायरेक्ट, या कोई भी ग़ैर-2xx स्टेटस — तो हम एक तय शेड्यूल पर दोबारा कोशिश करते हैं:

1 मिनट → 5 मिनट → 15 मिनट → 1 घंटा → 6 घंटे → 24 घंटे

कुल सात कोशिशें, लगभग 31 घंटों में फैली हुई। शुरुआती कोशिशें पास-पास हैं क्योंकि आम वजह यह होती है कि रिसीवर रीस्टार्ट हो रहा था और अब तक लौट भी आया है; बाद वाली छितरी हुई हैं क्योंकि जो सर्वर एक दिन से बंद पड़ा है उस पर हथौड़े बरसाने से किसी का भला नहीं होता।

आख़िरी कोशिश के बाद डिलीवरी को dropped चिह्नित कर दिया जाता है और हम अपने आप रुक जाते हैं। यह खोई नहीं है: आपके अकाउंट एरिया में भुगतान की पंक्ति उसकी स्थिति, कोशिशों की संख्या और एरर का वर्ग दिखाती है, साथ में एक फिर से भेजें बटन जो सातों कोशिशों का नया दौर शुरू कर देता है। आपका दूसरा सहारा है GET /api/merchant/v1/invoices/{invoice_id} — इनवॉइस को अपना स्टेटस हमेशा पता होता है।

वेबहुक URL कैसा होना चाहिए

URL की जांच तब होती है जब आप उसे सेव करते हैं, और फिर हर एक डिलीवरी से पहले दोबारा। जो URL जांच में विफल होता है, उसे सेव करते समय 422 और code: "webhook_url_rejected" के साथ जवाब मिलता है, और अगर वह बाद में विफल होने लगे तो डिलीवरी failed चिह्नित हो जाती है — बिना किसी दोबारा कोशिश के। नियम ये हैं:

• केवल `https://`, और पोर्ट 443। वेबहुक में भुगतान का ब्योरा होता है; सादे http में उसे रास्ते का कोई भी पढ़ सकता है।
• डोमेन नाम, IP पता नहीं। आपको वैसे भी सर्टिफ़िकेट चाहिए, और नंगे IP के लिए सर्टिफ़िकेट जारी नहीं होते।
• कोई `localhost` नहीं, और न ही .local, .internal, .corp, .lan या .test नाम — हमारे सर्वर आपके नेटवर्क तक पहुँच नहीं सकते, और जो नाम हमारे अपने नेटवर्क के अंदर रिज़ॉल्व होता है, ठीक उसी को हमें कभी कॉल नहीं करना चाहिए।
• URL में कोई क्रेडेंशियल नहीं (https://user:pass@…)। ज़रूरत हो तो अपना टोकन पाथ में या क्वेरी पैरामीटर में डालें।
• नाम जिन भी पतों पर रिज़ॉल्व होता है, वे सब सार्वजनिक होने चाहिए — A और AAAA दोनों। प्राइवेट, लूपबैक, लिंक-लोकल और CGNAT रेंज अस्वीकार की जाती हैं, और यह जांच हर डिलीवरी से पहले दोहराई जाती है, इसलिए बाद में रिकॉर्ड को 127.0.0.1 पर मोड़ देना भी काम नहीं करेगा।
• रीडायरेक्ट एक विफलता है, कोई पड़ाव नहीं। हम उनका पीछा नहीं करते: आपने जो पता दिया था वह जांचा गया था, और Location हेडर वाला नहीं।

जल्दी जवाब दें

कोई भी 2xx चलेगा, दस सेकंड के भीतर — कनेक्शन समेत यही हमारा पूरा टाइमआउट है। पहले जवाब दें, धीमा काम उसके बाद करें; जो एंडपॉइंट जवाब देने से पहले अपने ही डेटाबेस का इंतज़ार करता है, वह देर-सबेर टाइमआउट के रूप में दर्ज होगा और उसे दोबारा भेजा जाएगा, और आप एक ही इवेंट दो बार प्रोसेस करेंगे। बाकी सब कुछ — 4xx, 5xx, रीडायरेक्ट, अटक जाना — विफल कोशिश गिना जाता है और ऊपर वाले शेड्यूल में लौट जाता है।

डिलीवरी, ईमानदारी से

जिसकी गारंटी है वह है डिलीवरी तंत्र: लगभग 31 घंटों में सात कोशिशें, आपके अकाउंट एरिया से मैनुअल रीसेंड, और एक इनवॉइस एंडपॉइंट जिसे असली स्टेटस हमेशा पता होता है। अपना फ़्लो ऐसा बनाएं कि कभी न पहुँचने वाले वेबहुक से आपका कुछ न बिगड़े — अपने थैंक-यू पेज पर इनवॉइस पढ़ें, या घंटे में एक बार खुले इनवॉइस का मिलान कर लें। वेबहुक तेज़ रास्ता है, इकलौता रास्ता नहीं।

The snippets above verify one signature. This is the whole endpoint: raw body, signature check, deduplication by event_id, a fast 2xx, and the one condition that is allowed to mark an order paid.

Node.js with Express. express.raw is the part people get wrong: express.json() hands you a parsed object, and bytes you re-serialise from it are not the bytes we signed.

const express = require("express")
const crypto = require("node:crypto")

const app = express()
const SECRET = process.env.PAYSELL_WEBHOOK_SECRET

function isOurs(body, signature, timestamp) {
  const sentAt = Number(timestamp)
  if (!Number.isFinite(sentAt)) return false
  if (Math.abs(Date.now() / 1000 - sentAt) > 300) return false   // ±5 minutes

  const expected = "sha256=" + crypto
    .createHmac("sha256", SECRET)
    .update(timestamp + ".").update(body)      // raw Buffer, not a parsed object
    .digest("hex")

  const a = Buffer.from(expected), b = Buffer.from(signature ?? "")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

app.post(
  "/paysell/webhook",
  express.raw({ type: "application/json" }),   // NOT express.json()
  async (req, res) => {
    const signature = req.get("X-Paysell-Signature")
    const timestamp = req.get("X-Paysell-Timestamp")
    if (!isOurs(req.body, signature, timestamp)) return res.sendStatus(401)

    const event = JSON.parse(req.body.toString("utf8"))

    // Answer first: 10 seconds is the whole timeout, connection included.
    res.sendStatus(200)

    // Deduplicate. In real code this is a unique column, not a Set.
    if (await alreadyHandled(event.event_id)) return
    await remember(event.event_id)

    if (event.type !== "payment.credited") return
    const { order_id, status, credited, asset, tx_hash } = event.data

    // The only condition that may release the goods.
    if (status !== "paid" && status !== "overpaid") return
    await markOrderPaid(order_id, { credited, asset, tx_hash })
  }
)

Python with Flask. request.get_data() is the raw body; request.form and request.json are not.

import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["PAYSELL_WEBHOOK_SECRET"]


def is_ours(body: bytes, signature: str, timestamp: str) -> bool:
    try:
        sent_at = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - sent_at) > 300:              # ±5 minutes
        return False

    signed = timestamp.encode() + b"." + body
    expected = hmac.new(SECRET.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, signature)


@app.post("/paysell/webhook")
def paysell_webhook():
    body = request.get_data()                          # raw bytes, unparsed
    if not is_ours(body, request.headers.get("X-Paysell-Signature", ""),
                   request.headers.get("X-Paysell-Timestamp", "")):
        return "", 401

    event = json.loads(body)

    # Deduplicate. In real code this is a unique column, not a set.
    if already_handled(event["event_id"]):
        return "", 200                                 # a repeat is still a success
    remember(event["event_id"])

    if event["type"] == "payment.credited":
        data = event["data"]
        # The only condition that may release the goods.
        if data["status"] in ("paid", "overpaid"):
            mark_order_paid(data["order_id"], data)

    return "", 200                                     # 2xx within 10 seconds

What the code is doing, and why

• Verify before anything acts on the body. An unsigned request that reaches your business logic is a paid order for whoever found your URL.
• Answer 2xx first, work afterwards. Ten seconds is the whole timeout, connection included. A handler that waits for its own database gets recorded as a timeout and retried, and you process the same event twice.
• Deduplicate on `event_id` in storage that survives a restart. The in-memory set in the examples keeps them short; a real one is a unique column in your database.
• Mark the order paid only on `status: paid` or `overpaid`. underpaid means part of the money arrived and the invoice is still open, and a deposit in the wrong coin never makes an invoice paid either.
• Answer 2xx to a duplicate too. A repeat that gets a 4xx looks like a failure to us and comes back again on the schedule.

payment.rejected arrives at the same endpoint. It means a deposit held for an additional check was declined and the money will not be credited: release nothing, and if the invoice was already paid by an earlier transfer, this event is about the extra deposit, not about that payment.

इनवॉइस

भुगतान

आपके अकाउंट एरिया में दिखता है; भुगतान के दौरान ग्राहक को सपोर्ट करते समय उपयोगी।

जब कोई भुगतान `review` में जाता है

कुछ जमा तुरंत क्रेडिट होने के बजाय अतिरिक्त जांच के लिए रोक लिए जाते हैं: असामान्य रूप से बड़ी रकम, ऐसे पते पर आने वाले कॉइन जिस पर कोई खुला इनवॉइस नहीं है, या हम जिन दो ब्लॉकचेन स्रोतों को पोल करते हैं उनका इस बारे में आपस में मेल न खाना कि हुआ क्या। कुछ खोता नहीं है — पैसा फ़ैसले का इंतज़ार करता है, और फ़ैसला होते ही वेबहुक चल जाता है, जो मिनटों बाद भी हो सकता है और घंटों बाद भी। इसलिए review दिख रहे भुगतान पर कॉलबैक का न आना विफलता नहीं, सामान्य बात मानें। अगर यह किसी ऑर्डर के लिए मायने रखता है, तो tx_hash बताकर सपोर्ट से पूछें।

राशियाँ कॉइन की सामान्य इकाइयों में, स्ट्रिंग के रूप में भेजें — "1.5" का अर्थ डेढ़ है। न JSON संख्या, न सबसे छोटी इकाई।

संख्या नहीं बल्कि स्ट्रिंग, क्योंकि JSON संख्याएँ IEEE-754 डबल होती हैं और नैनोटन में बड़ी राशि उनमें ठीक-ठीक नहीं समाती। कॉइन के पास जितने दशमलव स्थान हैं उससे अधिक देने पर 422 मिलता है — आपके पैसे को चुपचाप गोल नहीं किया जाता। वेबहुक में उल्टा है: वहाँ amount, fee और credited सबसे छोटी इकाई में पूर्णांक हैं, क्योंकि उस ओर को कोड पढ़ता है, इंसान नहीं।

// Send amounts in the coin's normal units, as a string:
const amount = "1.5"   // one and a half TON or USDT

// In responses, amount is that same human string; amount_minor is the
// integer in smallest units — use it for exact maths, as a string or BigInt:
BigInt(invoice.amount_minor)  // e.g. 1500000n

न्यूनतम कोई नौकरशाही नहीं है। हमारी फ़ीस प्रतिशत में है, लेकिन भुगतान लेने में एक निश्चित राशि खर्च होती है: रिसीविंग एड्रेस से USDT निकालने का मतलब है पहले उसे गैस से फंड करना — हमारी अपनी जेब से। कुछ डॉलर से कम पर फ़ीस हैंडलिंग का खर्च भी नहीं निकालती, और ऐसा भुगतान स्वीकार करने का मतलब होगा आपको ऐसा पैसा जमा करना जिसे हिलाना ही अलाभकारी है।

अधिकतम सीमा बड़े व्यापारियों के बारे में नहीं है — यह इकाइयों की गलती के लिए बिछाया गया जाल है। जहाँ आपका मतलब "5" था वहाँ "5000000" भेजें, तो वरना आपको पचास लाख डॉलर का इनवॉइस मिल जाता: खरीदार बेतुका आंकड़ा देखकर चला जाता है। असली ऑर्डर इस छत तक कभी नहीं पहुँचता; गलती हमेशा पहुँचती है। दोनों छतें सेटिंग्स हैं (invoice_max_ton, invoice_max_usdt) और आपकी दुकान के लिए बढ़ाई जा सकती हैं — बस कह दीजिए।

प्रति घंटा सीमा और एक साथ खुले इनवॉइस की सीमा, दोनों पता पूल की रक्षा करती हैं। हर खुला इनवॉइस एक रिसीविंग एड्रेस रोके रखता है, और किसी एक साइट पर बेकाबू लूप वरना सबके लिए पूल खाली कर देगा। नई दुकान एक साथ 20 इनवॉइस खुले रख सकती है; हर उस इनवॉइस के लिए जिसका भुगतान उसने वास्तव में वसूला है, यह भत्ता एक बढ़ जाता है, अधिकतम 200 तक। underpaid खुला ही गिना जाता है — वह अब भी अपना पता रोके हुए है, बाकी रकम का इंतज़ार कर रहा है। छोड़ दिए गए इनवॉइस को रद्द करने से उसका पता तुरंत लौट आता है। एक ही idempotency_key के साथ दोबारा कोशिशें प्रति घंटा सीमा में नहीं गिनी जातीं।

रिक्वेस्ट की सीमा प्रति API की 120 प्रति मिनट है — दो कॉल प्रति सेकंड, किसी भी असली ऑर्डर प्रवाह से कहीं ज़्यादा। 429 के साथ Retry-After हेडर सेकंडों में आता है: तंग लूप में दोबारा कोशिश करने के बजाय उतनी देर रुकें, क्योंकि लूप विंडो को और आगे ही खिसकाता है।

एरर JSON के रूप में वापस आते हैं, दो रूपों में। जो कुछ हम या प्रोसेसिंग कोर तय करते हैं, वह detail के नीचे {code, message} जोड़ी रखता है। जिस रिक्वेस्ट बॉडी का सत्यापन विफल होता है, उसके लिए वहाँ इसके बजाय फ़ील्ड एररों की सूची आती है। detail.code पढ़ने से पहले जांचें कि आपको कौन सा रूप मिला — और `code` पर शाखा बनाएं, कभी `message` पर नहीं: शब्द कभी भी बदल सकते हैं, कोड नहीं बदलेगा।

{
  "detail": {
    "code": "invalid_input",
    "message": "invoice amount below the minimum: 0.010000 USDT_TON, minimum 3.000000 USDT_TON"
  }
}

{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "amount"],
      "msg": "Input should be a valid string",
      "input": 5
    }
  ]
}

कोड

हमारे तय किए हुए फ़ैसलों का रूप यह है: {"detail": {"code": …, "message": …}}। मर्चेंट API ये कोड लौटाता है।

502 का मतलब यह नहीं कि इनवॉइस नहीं बना — रिक्वेस्ट सफल हो सकती थी और जवाब वापसी के रास्ते में खो गया। उसी idempotency_key से दोबारा कोशिश करें और आपको या तो मौजूदा इनवॉइस मिलेगा या एक नया, कभी दो नहीं।

payment_url points at https://paysell.me/pay/{invoice_id}. One page, no account, no login, mobile first, and nothing for you to build.

On the page

• Your shop's name, the amount and the coin, large, with the invoice's description underneath.
• A countdown to expires_at — plus the 24-hour grace period when the invoice is underpaid.
• The invoice's short id with a copy button, so a buyer can quote it to your support.
• Wallet buttons: Tonkeeper and MyTonWallet open with the address and the amount already filled in. Other reveals a QR code and the address with a copy button.
• A warning that only this invoice's coin, on the TON network, may be sent — anything else is lost.

How the page reacts

If you build your own

You gain your own branding and take on all of the above: the exact address string, the right coin, the countdown with its grace period, the underpayment case, and polling. GET /api/merchant/v1/public/invoices/{invoice_id} is the same unauthenticated read the hosted page uses — rate limited per IP, so poll it no more often than every few seconds. Print the address exactly as returned.

None of these are exotic. Every one of them has cost somebody a day.

• Sending the amount as a number

  {"amount": 5} is a 422. It has to be the string "5": JSON numbers are IEEE-754 doubles, and a large sum in nanotons stops being exactly representable in one.

• Sending the smallest unit

  "5000000" for 5 USDT is a mistake in units, and the upper invoice limit exists to catch it. Smallest units are what comes back in webhooks, not what goes out in requests.

• Treating the webhook's arrival as payment

  Read data.status. underpaid is not paid, and a deposit in a coin the invoice did not ask for never makes it paid either. Release the goods on paid or overpaid, on nothing else.

• Not checking the timestamp

  A signature on its own never expires. Without the ±5 minute window on X-Paysell-Timestamp, a delivery captured once can be replayed at any time and will still verify.

• Verifying the signature over re-serialised JSON

  Parse the body and serialise it again and the bytes change — key order, spacing — and the HMAC no longer matches. Sign the raw bytes exactly as received.

• No deduplication

  The same event_id will arrive twice sooner or later: we retry until you answer 2xx, and a response lost on the way back looks like a failure from here. The second arrival must do nothing.

• Using the Idempotency-Key header

  This API reads idempotency_key from the request body; the header is not read at all. A retry without the field opens a second invoice for the same order.

• Assuming detail is always an object

  It is {code, message} for anything we or the core decide, and a list of field errors when the body itself fails validation. Check which one you got before reading detail.code.

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

किसी खरीदार को रिफ़ंड देने के लिए, अपने अकाउंट एरिया से सपोर्ट टिकट खोलें और उसमें invoice_id या tx_hash, राशि, और जिस पते पर भेजना है वह दें। ऑपरेटर भुगतान की जांच करता है, आपके बैलेंस से पैसा निकालता है, और उसी टिकट में जवाब देता है। इसमें एक कार्य-दिवस लगने की उम्मीद रखें, एक मिनट की नहीं।

दो नतीजे ऐसे हैं जिन्हें ध्यान में रखकर डिज़ाइन करना चाहिए। अधिक भुगतान पूरा का पूरा आपको जमा होता है — हम उसमें से कुछ नहीं रखते — इसलिए जिस खरीदार ने ज़्यादा भेज दिया उसे अंतर लौटाना आपका फ़ैसला है, और वह इसी रास्ते से होता है। और कम भुगतान वाला इनवॉइस, जब तक खुला है, रिफ़ंड का मामला नहीं है: पैसा आपके बैलेंस पर है, पते पर अब भी नज़र रखी जा रही है, और खरीदार बस बाकी रकम भेज सकता है। फ़ैसला करने की नौबत तभी आती है जब छूट अवधि के बाद इनवॉइस पैसे समेत expired हो जाए।

यहाँ की कीज़ लाइव हैं: जारी की गई हर की sk_live_ की है, जो प्रोडक्शन कोर और TON मेननेट के विरुद्ध चलती है। अलग से कोई टेस्ट एनवायरनमेंट नहीं है, और इसका एक फ़ायदा है: आप ठीक उसी रास्ते से गुज़रते हैं जिससे आपके असली ऑर्डर गुज़रेंगे।

इसलिए इसे वैसे ही टेस्ट करें जैसे असली पैसे को छूने वाली किसी भी चीज़ को करेंगे: छोटी रकम पर। न्यूनतम राशि (0.1 TON या 3 USDT) का इनवॉइस बनाएं, उसे अपने ही वॉलेट से चुकाएं, और पूरा रास्ता देखें — पेमेंट पेज, वेबहुक, हस्ताक्षर की जांच, और आपके ऑर्डर का paid में बदलना। फ़ीस लागू होती है, और कॉइन सचमुच हिलते हैं।

जिन हिस्सों को आप बिना कुछ खर्च किए आज़मा सकते हैं: इनवॉइस बनाना और पढ़ना, उसे रद्द करना, गलत रूप वाली राशि पर 422, गलत की पर 401, और आपका अपना हस्ताक्षर-सत्यापन — अपने सीक्रेट से एक नमूना बॉडी साइन करें और उसे अपने ही हैंडलर को खिलाएं। असली भुगतान वाकई सिर्फ़ आख़िरी चरण के लिए चाहिए: एक वास्तविक payment.credited वेबहुक।

इंटीग्रेशन की योजना ऐसी बनाएं कि वह सैंडबॉक्स या नकली भुगतान पर निर्भर न हो: लाइव रास्ता जल्दी — और ज़्यादा सच्चाई से — जांचा जाता है।

Everything on this page also exists in a form a model can read directly. Point your assistant at one of these instead of pasting screenshots of documentation into a chat.

The three files

A prompt to start from

Copy this, replace the stack, and hand it to your assistant. It names the four things that go wrong most often, so the answer does not have to be corrected afterwards.

Read https://paysell.me/llms-full.txt and implement Paysell payments in my <stack>:
create invoices (POST /api/merchant/v1/invoices, Bearer sk_live_ key, amount as a
decimal string in normal units), redirect the buyer to payment_url, verify webhook
signatures (HMAC-SHA256 over "{timestamp}.{raw_body}", header X-Paysell-Signature,
reject anything whose X-Paysell-Timestamp is more than 300 seconds off), deduplicate
by event_id, answer 2xx within 10 seconds, and mark orders paid only on a
payment.credited event whose data.status is "paid" or "overpaid".

Feeding it to a specific tool

• Agents with web access — Claude Code, Cursor, Windsurf and the like: give them the /llms-full.txt link. One fetch, no setup.
• A chat window — ChatGPT, Claude, Gemini: paste the contents of /llms-full.txt into the conversation or attach it as a file. It is written to fit in one message.
• OpenAPI tooling — client generators, Postman, an agent's tool schema: point it at https://paysell.me/openapi.json. Its servers entry already carries the production base URL, so generated calls go to the right place.

• की केवल सर्वर-साइड है, कभी ब्राउज़र JavaScript में नहीं।
• वेबहुक हस्ताक्षर "{timestamp}.{raw_body}" के विरुद्ध, नियत समय में सत्यापित होता है।
• पाँच मिनट से पुरानी डिलीवरी अस्वीकार की जाती हैं, और सर्वर की घड़ी NTP पर है।
• दोहराया गया X-Paysell-Event-Id दूसरी बार कुछ नहीं करता।
• वेबहुक दस सेकंड के भीतर 2xx का जवाब देता है; धीमा काम उसके बाद होता है।
• वेबहुक URL पोर्ट 443 पर एक https:// डोमेन है, और उसके आगे कोई रीडायरेक्ट नहीं है।
• छूटा हुआ वेबहुक झेला जा सकता है: थैंक-यू पेज पर या मिलान-सफ़ाई के दौरान इनवॉइस एंडपॉइंट पढ़ा जाता है।
• idempotency_key प्रति ऑर्डर एक बार जनरेट होती है और दोबारा कोशिशों में फिर से इस्तेमाल होती है।
• राशियाँ सामान्य इकाइयों में स्ट्रिंग के रूप में जाती हैं; वेबहुक के अंक सबसे छोटी इकाई के रूप में पढ़े जाते हैं।
• पता बिल्कुल वैसे ही दिखाया जाता है जैसे लौटाया गया, बिना बदलाव के।
• overpaid और underpaid को संभाला जाता है, न सिर्फ़ paid को; expired में भी paid_minor हो सकता है।
• माल status: paid या overpaid पर छोड़ा जाता है, केवल कॉलबैक आ जाने पर कभी नहीं।
• 429 को Retry-After जितनी देर कहे उतना रुककर संभाला जाता है, तुरंत दोबारा कोशिश करके नहीं।
• बैलेंस हमसे पढ़े जाते हैं, सत्य के रूप में अलग से ट्रैक नहीं किए जाते।