# Payment API

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

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

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

<TwoCol>

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

### Request parameters

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

<TwoColAside>

<Credentials />

<TryIt endpoint="POST /v1/payment">
  <Param name="amount" type="decimal" required />
  <Param name="currency" type="enum" required values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="order_id" type="string" required />
  <Param name="to_currency" type="enum" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="network" type="enum" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" />
  <Param name="url_return" type="string" />
  <Param name="url_success" type="string" />
  <Param name="url_callback" type="string" />
  <Param name="invite_code" type="string" />
  <Param name="fee_split" type="decimal" />
  <Param name="price_markup" type="decimal" />
  <Param name="description" type="string" />
  <Param name="ttl_seconds" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>

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

<TwoCol>

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

### Request parameters

| Field | Type | आवश्यक | Description | Values |
|-------|------|----------|-------------|--------|
| `uuid` | string | हाँ\* | Payment UUID (creation पर `result.uuid` से) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | हाँ\* | आपका order ID | <InputValue name="order_id" placeholder="ORDER-12345" /> |

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

<TwoColAside>

<TryIt endpoint="POST /v1/payment/info">
  <Param name="uuid" type="string" />
  <Param name="order_id" type="string" />
</TryIt>

</TwoColAside>

</TwoCol>

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

<TwoCol>

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

### Request parameters

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

<TwoColAside>

<TryIt endpoint="POST /v1/payment/list">
  <Param name="status" type="enum" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" />
  <Param name="date_from" type="string" />
  <Param name="date_to" type="string" />
  <Param name="page" type="integer" />
  <Param name="per_page" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>