# इनवॉइस का जीवनचक्र

इनवॉइस बनने से लेकर बंद होने या समय समाप्त होने तक का सफ़र तय करता है। यह सेक्शन बताता है कि वह किन स्थितियों में हो सकता है, उनके बीच कैसे जाता है और हर चरण पर व्यापारी क्या कर सकता है।

## इनवॉइस की स्थितियाँ

| स्थिति | API मान | विवरण | भुगतान खोज में शामिल |
| -------- | ---------- | ------------------------------------------------------------------------------ | ------------------------------------ |
| भुगतान बाकी | `unpaid` | इनवॉइस जारी है, भुगतान की समय-सीमा बीती नहीं है, कोई भुगतान नहीं मिला | हाँ |
| भुगतान हुआ | `paid` | भुगतान मिल गया है और इनवॉइस से जुड़ गया है | नहीं |
| समय समाप्त | `expired` | भुगतान की समय-सीमा बीत गई, कोई भुगतान नहीं मिला | हाँ, समाप्ति के बाद एक और घंटे तक |
| रद्द | `canceled` | व्यापारी ने इनवॉइस मैन्युअल रूप से या API से रद्द किया | नहीं |

## स्थितियों के बीच बदलाव

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

भुगतान हुआ स्थिति वाला इनवॉइस भी स्थिति नहीं बदलता — उसका न दोबारा भुगतान हो सकता है, न उसे रद्द किया जा सकता है।

## भुगतान की समय-सीमा

समय-सीमा इनवॉइस बनाते समय तय होती है और 30 मिनट से 12 घंटे तक की होती है। मान्य मान: 30 मिनट, 1 घंटा, 3 घंटे, 6 घंटे, 12 घंटे।

समय-सीमा तक ग्राहक को भुगतान फ़ॉर्म दिखता है और वह इनवॉइस का भुगतान कर सकता है। समाप्ति के बाद इनवॉइस समय समाप्त स्थिति में चला जाता है और भुगतान फ़ॉर्म भुगतान की पेशकश बंद कर देता है।

दोनों छोरों की अपनी कीमत है। छोटी समय-सीमा धीमे नेटवर्क पर जोखिम भरी है — ग्राहक शायद समय पर न कर पाए। लंबी समय-सीमा इनवॉइस बनाते समय की दर और भुगतान के समय की दर के बीच का फ़ासला बढ़ा देती है।

## भुगतान खोज की विंडो

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

इसीलिए इंटीग्रेटर के लिए नियम: भुगतान की सूचना को इसलिए न ठुकराएँ कि समय-सीमा बीत चुकी है — यह जाँच असली भुगतानों का एक हिस्सा काट देती है।

## इनवॉइस रद्द करना

अगर इनवॉइस में ग़लती है, तो आप उसे रद्द कर सकते हैं। रद्द करने के लिए दो शर्तें ज़रूरी हैं:

* इनवॉइस का भुगतान नहीं हुआ है — यानी वह भुगतान बाकी स्थिति में है
* किसी ने इनवॉइस का भुगतान पृष्ठ नहीं खोला; व्यू काउंटर शून्य पर है

दूसरी शर्त ऐसे इनवॉइस को रद्द करने से बचाती है, जिसे ग्राहक देख चुका है और शायद जिसका भुगतान शुरू कर चुका है।

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

## बनाते समय क्या लॉक होता है और भुगतान पर क्या दोबारा गिना जाता है

इनवॉइस बनाते समय सेवा फ़िएट राशि को मौजूदा विनिमय दर पर क्रिप्टो में बदलती है और मिली राशियों को इनवॉइस के लिए लॉक कर देती है। यही राशियाँ ग्राहक देखता है, और इन्हीं को सेवा ऑन-चेन खोजती है। दर का असर अब इन पर नहीं पड़ता: चाहे कितना भी समय बीते, ग्राहक ठीक लॉक की हुई राशि चुकाता है।

भुगतान के समय हिसाब की राशियाँ दोबारा गिनी जाती हैं:

| फ़ील्ड | क्या होता है |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `amountFiat` | फ़िएट मुद्रा में इनवॉइस की मूल राशि। कभी नहीं बदलती |
| `amountFiatUSD` | असल में मिली राशि से बदल दी जाती है, जो भुगतान के समय की विनिमय दर पर USD में बदली जाती है |
| `commissionFiatUSD` | नए `amountFiatUSD` मान से प्रोजेक्ट की शुल्क दर पर दोबारा गिनी जाती है |

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

## इनवॉइस के जीवन के दौरान सूचनाएँ

सूचनाएँ हर प्रोजेक्ट के लिए अलग सेट होती हैं। इनवॉइस की ऐसी दो सूचनाएँ हैं:

* **आने वाला भुगतान (Incoming payment)।** ईमेल और Telegram पर तब भेजी जाती है, जब आपके वॉलेट पर कोई भी आने वाला ट्रांज़ैक्शन पकड़ा जाता है, चाहे वह इनवॉइस से जुड़ा हो या नहीं।
* **इनवॉइस का भुगतान हुआ (Invoice paid)।** इनवॉइस के भुगतान हुआ स्थिति में जाते ही ईमेल, Telegram और Webhook URL पर भेजी जाती है — अपने-आप और मैन्युअल, दोनों तरह के जुड़ने पर।

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

## ग्राहक को स्टोर की साइट पर लौटाना

प्रोजेक्ट सेटिंग्स में आप दो URL सेट कर सकते हैं, जिन पर ग्राहक भुगतान पृष्ठ से लौटता है:

* **Successful URL** — इनवॉइस के भुगतान के बाद अपने-आप रीडायरेक्ट
* **Unsuccessful URL** — समय समाप्त या रद्द इनवॉइस खोलने पर अपने-आप रीडायरेक्ट

हर URL अलग से चालू होता है। अगर URL सेट नहीं है, तो ग्राहक भुगतान पृष्ठ पर ही रहता है और इनवॉइस की स्थिति देखता है।

URL में `uid` पैरामीटर — ग्राहक के लिए इनवॉइस ID — जोड़ दिया जाता है: `https://example.com/order/success?uid=AFhygKX21ecd`। स्टोर इसी से ऑर्डर खोजता है और ग्राहक को अपना पृष्ठ दिखाता है।

इन URL पर पहुँचना भुगतान की पुष्टि नहीं है — ग्राहक लिंक को ख़ुद भी खोल सकता है। ऑर्डर [webhook](./webhook-url/index.md) के आधार पर पूरे करें, या API से [इनवॉइस की स्थिति जाँचने](./api/index.md) के बाद।