# Payment API

> 2328.io Payment API के साथ क्रिप्टोकरेंसी भुगतान session बनाएँ और प्रबंधित करें।

Payment API आपको भुगतान session बनाने, customer को hosted checkout पर redirect करने, और भुगतान status track करने की सुविधा देता है।

## भुगतान बनाएँ

एक भुगतान session बनाता है और customer को pay करने के लिए एक URL लौटाता है।

### Request parameters

| Field | Type | आवश्यक | Description | Values |
|-------|------|----------|-------------|--------|
| `amount` | decimal | हाँ | currency में भुगतान राशि, जैसे `100.00` |  |
| `currency` | string | हाँ | Fiat currency (USD, EUR, RUB, …) या क्रिप्टोकरेंसी (USDT, TRX, BTC, …) | `USD`, `EUR`, `RUB`, `KZT`, `UAH`, `UZS`, `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `order_id` | string | हाँ | आपका order ID, जैसे `ORDER-12345` (अधिकतम 128 chars) |  |
| `to_currency` | string | नहीं | पहले से चुनी हुई क्रिप्टोकरेंसी | `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `network` | string | नहीं\* | Network code (आवश्यक यदि `to_currency` set है या `currency` एक क्रिप्टोकरेंसी है) | `TRX-TRC20`, `ETH-ERC20`, `BASE`, `BSC-BEP20`, `AVAX-C`, `POL-MATIC`, `TON`, `SOL`, `BTC`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `url_return` | string | नहीं | भुगतान के बाद redirect URL, जैसे `https://your-site.com/return` |  |
| `url_success` | string | नहीं | `url_return` का विकल्प |  |
| `url_callback` | string | हाँ | webhook notifications के लिए URL, जैसे `https://your-site.com/webhook` |  |
| `invite_code` | string | नहीं | Referrer code |  |
| `fee_split` | decimal | नहीं | Merchant fee का वह हिस्सा जो payer पर डाला गया है, 0–100 (%)। 0 = merchant पूरी तरह भरता है, 100 = payer पूरी तरह भरता है। Project-level setting को override करता है। **उदाहरण: `30`** (payer fee का 30% कवर करता है)। |  |
| `price_markup` | decimal | नहीं | Invoice राशि पर markup या discount, −99 से 100 (%)। Project-level setting को override करता है। **उदाहरण: `5`** (+5%) या `-10` (10% discount)। |  |
| `description` | string | नहीं | वैकल्पिक invoice description (अधिकतम 200 chars)। भुगतान page पर payer को दिखाया जाता है। **उदाहरण: `Premium plan — Order #12345`**। |  |
| `ttl_seconds` | int | नहीं | Invoice की वैधता seconds में, `300` (5 मिनट) से `86400` (24 घंटे) तक। इस अवधि के बाद invoice expire हो जाता है और इसका भुगतान नहीं किया जा सकता। Default: `3600` (1 घंटा)। **उदाहरण: `3600`**। |  |

### Response

```json
{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- भुगतान पूरा करने के लिए customer को `result.url` पर redirect करें।
- `tg_deeplink` — Telegram MiniApp के माध्यम से भुगतान के लिए Telegram bot deeplink।
- `qr` — deposit address का Base64-encoded QR code (data URI)। तब उपस्थित रहता है जब address पहले से assigned हो (जब `network`, `to_currency` के साथ set हो, या जब `currency` एक क्रिप्टोकरेंसी हो); अन्यथा `null`।
- `txid`, `payment_amount` — customer के pay करने तक `null` रहते हैं। On-chain transaction detect होने पर भर जाते हैं। यह कब हुआ जानने के लिए `payment_status: paid` webhook को सुनें।
- `exchange_rate` — `null` यदि conversion अभी लागू नहीं है (जैसे fiat → crypto rate अभी lock नहीं हुआ है)। Payer currency चुने जाने पर भर जाता है।

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/payment`
  - `amount` (decimal, required)
  - `currency` (enum, required): USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `order_id` (string, required)
  - `to_currency` (enum): USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `network` (enum): TRX-TRC20,ETH-ERC20,BASE,BSC-BEP20,AVAX-C,POL-MATIC,TON,SOL,BTC,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `url_return` (string)
  - `url_success` (string)
  - `url_callback` (string, required)
  - `invite_code` (string)
  - `fee_split` (decimal)
  - `price_markup` (decimal)
  - `description` (string)
  - `ttl_seconds` (integer)

## होस्टेड चेकआउट, H2H, और सही क्रिप्टो राशि

एक ही एंडपॉइंट तीन अलग-अलग इनवॉइस रूपों का समर्थन करता है। जानबूझकर एक चुनें; उनकी राशि की अर्थव्यवस्था को मिलाएं नहीं।

### होस्टेड चेकआउट के साथ भुगतानकर्ता का चयन

`amount`, `currency`, `order_id`, और `url_callback` भेजें, लेकिन `to_currency` और `network` छोड़ दें। प्रतिक्रिया में `result.url` शामिल है; `address`, `qr`, और कभी-कभी भुगतानकर्ता फ़ील्ड `null` रहते हैं जब तक कि भुगतानकर्ता होस्टेड पेज पर दिशा का चयन नहीं करता।

```json
{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}
```

### डायरेक्ट-एड्रेस H2H इनवॉइस

दोनों `to_currency` और `network` भेजें। 2328.io API कॉल के दौरान ब्लॉकचेन चालान बनाता है, इसलिए सफल प्रतिक्रिया को ग्राहक को रीडायरेक्ट किए बिना आपके चेकआउट में प्रस्तुत किया जा सकता है।

```json
{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}
```

इन मानों को ठीक वैसे ही प्रस्तुत करें जैसा कि लौटाया गया है:

- `payer_amount` और `payer_currency` — भुगतान निर्देश;
- `network` और `address` — इस चालान के लिए एकमात्र गंतव्य;
- `qr` — उसी पते के लिए एक डेटा URI;
- `expires_at` — चालान की समय सीमा;
- `url` — एक उपयोगी होस्टेड फॉलबैक जब कस्टम चेकआउट पूरा नहीं हो पाता।

> **DANGER:** कभी भी कोई पता न बनाएं या उसका स्थान न लें, किसी अन्य चालान से कोई पता पुन: उपयोग न करें, या सार्वजनिक स्पॉट मूल्य से `payer_amount` की गणना न करें। API प्रतिक्रिया अधिकारकारी है।

### सटीक क्रिप्टो राशि के लिए चालान

जब चालान स्वयं क्रिप्टो में हो, तब क्रिप्टोकरेंसी को `currency` में डालें:

```json
{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}
```

अनुरोधित क्रिप्टो मूल्य `payer_currency` / `payer_amount` में संरक्षित है। सेवा आंतरिक रूप से खाता और दर क्षेत्रों के लिए USD मूल्य भी रख सकती है; उस सटीक क्रिप्टो निर्देश को उस मूल्य से बदलें नहीं। लौटाए गए दशमलव स्ट्रिंग्स को बनाए रखें, जिसमें अंतिम सटीकता शामिल है।

केवल एक समर्थित नेटवर्क वाली क्रिप्टोकरेंसी के लिए, नेटवर्क स्वचालित रूप से चुना जा सकता है। निर्णायक एकीकरण के लिए स्पष्ट रूप से `network` प्रदान करना फिर भी अनुशंसित है। स्थिरकॉइन जैसी बहु-नेटवर्क संपत्तियों के लिए, इसे हमेशा भेजें।

## इडेम्पोटेंसी और पुनः प्रयास

`order_id` प्रमाणित व्यापारी परियोजना तक सीमित है और निर्माण इडेम्पोटेंसी कुंजी के रूप में कार्य करता है। यदि कोई भुगतान पहले से मौजूद है, तो API उस सत्र को `state: 0` के साथ लौटाता है।

> **WARNING:** एक ही `order_id` के साथ पुनः प्रयास **not** का मतलब “इस चालान को अपडेट करें” है। बदली गई राशि, मुद्रा, कॉलबैक, मार्कअप, TTL, या दिशा फ़ील्ड को अनदेखा किया जा सकता है क्योंकि मौजूदा सत्र लौटाया जाता है। पहले अनुरोध को स्थायी बनाएं और अपने स्वयं के एप्लिकेशन में विरोधाभासी पुनः प्रयासों को अस्वीकार करें।

सिफारिश की गई निर्माण एल्गोरिदम:

1. अपने स्थानीय भुगतान प्रयास और अद्वितीय `order_id` को एक डेटाबेस लेन-देन में डालें।
2. हस्ताक्षरित API अनुरोध भेजें।
3. वापसी हुई `uuid` और पूरा उत्तर स्थायी रूप से सहेजें।
4. यदि HTTP परिणाम खो गया है, तो समान अनुरोध दोबारा प्रयास करें या `/v1/payment/info` को `order_id` द्वारा प्राप्त करें।
5. केवल इसलिए कि अपस्ट्रीम अनुरोध समय समाप्त हो गया, कभी भी दूसरा स्थानीय आदेश न बनाएं।

## भुगतान किनारे मामले

| स्थिति | सही संचालन |
|-----------|------------------|
| `address` / `qr` है `null` | भुगतानकर्ता दिशा आरंभ नहीं की गई है। `url` पर पुनर्निर्देशित करें, या नए `order_id` के साथ सही तरीके से निर्दिष्ट नया H2H इनवॉइस बनाएं। |
| HTTP `400` सत्यापन त्रुटि | फील्ड-लेवल `errors` पढ़ें; बिना बदले इनपुट को फिर से प्रयास न करें। |
| HTTP `429` | जिटर वाले घातीय बैकऑफ के साथ पुनः प्रयास करें और वही `order_id` रखें। |
| HTTP `503` / `direction_disabled` | `/v1/directions` ताज़ा करें; दिशा को अस्थायी रूप से छिपाएं या बाद में पुनः प्रयास करें। |
| क्लाइंट अनुरोध समय समाप्त | परिणाम को अज्ञात माना जाए। कुछ भी बनाने से पहले `order_id` द्वारा क्वेरी करें। |
| `underpaid_check` | आंशिक घटना को सहेजें और टॉप-अप या बाद की स्थिति का इंतजार करें। जब अधिक txids आएं तो दो बार क्रेडिट न करें। |
| `underpaid` | अंतिम अधूरे भुगतान की स्थिति। वास्तविक क्रेडिट राशि पर अपने कॉन्फ़िगर किए गए फुलफिलमेंट/मैनुअल-रिव्यु पॉलिसी लागू करें। |
| `overpaid` | अधिक धन के साथ सफल भुगतान। प्रतिलिपि रहित ढंग से पूरा करें और मिलान/रिफंड पॉलिसी के लिए वास्तविक राशि को सुरक्षित रखें। |
| `aml_lock` | स्वतः फंड्स जारी या पूरा न करें; इसे अनुपालन/सपोर्ट वर्कफ़्लो में रूट करें। |
| `cancel` | चालान की अवधि समाप्त या रद्द कर दी गई। यह न समझें कि देर से ऑन-चेन ट्रांसफर असंभव है; किसी भी बाद की घटना को सपोर्ट के साथ मिलाकर मिलान करें। |

ब्राउज़र रिटर्न URL केवल नेविगेशन के लिए है। एक ग्राहक इसे बिना भुगतान किए खोल सकता है, भुगतान करने के बाद इसे बंद कर सकता है, या बाद में फिर से चला सकता है। केवल सत्यापित API/वेबहुक स्थिति ही व्यापारी आदेश को निपटा सकती है।

## भुगतान की जानकारी

`uuid` या `order_id` से वर्तमान भुगतान status प्राप्त करें।

### Request parameters

| Field | Type | आवश्यक | Description | Values |
|-------|------|----------|-------------|--------|
| `uuid` | string | हाँ\* | Payment UUID (creation पर `result.uuid` से) |  |
| `order_id` | string | हाँ\* | आपका order ID |  |

> **INFO:** `uuid` या `order_id` में से कम से कम एक आवश्यक है।

#### Interactive request: `POST /v1/payment/info`
  - `uuid` (string)
  - `order_id` (string)

## भुगतान सूची

filtering और pagination के साथ सभी भुगतानों की सूची प्राप्त करें।

### Request parameters

| Field | Type | आवश्यक | Description | Values |
|-------|------|----------|-------------|--------|
| `status` | string | नहीं | भुगतान status के अनुसार filter (देखें [References](/docs/references)) | `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid`, `cancel` |
| `date_from` | date | नहीं | प्रारंभिक तिथि (YYYY-MM-DD), जैसे `2026-01-01` |  |
| `date_to` | date | नहीं | अंतिम तिथि (YYYY-MM-DD), जैसे `2026-01-31` |  |
| `page` | int | नहीं | Page संख्या, default `1` |  |
| `per_page` | int | नहीं | प्रति page items, default `15`, अधिकतम `5000` |  |

#### Interactive request: `POST /v1/payment/list`
  - `status` (enum): pending,check,paid,underpaid_check,underpaid,overpaid,cancel
  - `date_from` (string)
  - `date_to` (string)
  - `page` (integer)
  - `per_page` (integer)