# Payment API

> Tạo và quản lý các phiên thanh toán tiền điện tử với Payment API của 2328.io.

Payment API cho phép bạn tạo phiên thanh toán, chuyển hướng khách hàng đến trang checkout được hosted và theo dõi trạng thái thanh toán.

## Tạo thanh toán

<TwoCol>

Tạo một phiên thanh toán và trả về URL để khách hàng thanh toán.

### Tham số yêu cầu

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `amount` | decimal | yes | Số tiền thanh toán theo đơn vị tiền tệ, ví dụ `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | yes | Tiền pháp định (USD, EUR, RUB, …) hoặc tiền điện tử (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 | yes | ID đơn hàng của bạn, ví dụ `ORDER-12345` (tối đa 128 ký tự) | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | no | Tiền điện tử được chọn trước | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | no\* | Mã mạng (bắt buộc nếu `to_currency` được đặt hoặc `currency` là tiền điện tử) | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | no | URL chuyển hướng sau khi thanh toán, ví dụ `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | no | Phương án thay thế cho `url_return` | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | no | URL nhận thông báo webhook, ví dụ `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | no | Mã người giới thiệu | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `fee_split` | decimal | no | Tỷ lệ phí merchant chuyển sang cho người trả, 0–100 (%). 0 = merchant trả toàn bộ, 100 = người trả gánh toàn bộ. Ghi đè cài đặt cấp project. **Ví dụ: `30`** (người trả gánh 30% phí). | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `price_markup` | decimal | no | Phụ phí hoặc chiết khấu trên số tiền hóa đơn, −99 đến 100 (%). Ghi đè cài đặt cấp project. **Ví dụ: `5`** (+5%) hoặc `-10` (giảm 10%). | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `description` | string | no | Mô tả hóa đơn tùy chọn (tối đa 200 ký tự). Hiển thị cho người trả trên trang thanh toán. **Ví dụ: `Premium plan — Order #12345`**. | <InputValue name="description" placeholder="Premium plan — Order #12345" /> |
| `ttl_seconds` | int | no | Thời gian sống của hóa đơn tính bằng giây, từ `300` (5 phút) đến `86400` (24 giờ). Sau khoảng thời gian này hóa đơn hết hạn và không thể thanh toán được nữa. Mặc định: `3600` (1 giờ). **Ví dụ: `3600`**. | <InputValue name="ttl_seconds" type="integer" placeholder="3600" /> |

### Phản hồi

```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..."
  }
}
```

- Chuyển hướng khách hàng đến `result.url` để hoàn tất thanh toán.
- `tg_deeplink` — deeplink Telegram bot để thanh toán qua Telegram MiniApp.
- `qr` — QR code mã hóa Base64 (data URI) của địa chỉ nạp tiền. Có giá trị khi địa chỉ đã được gán (khi `network` được đặt cùng với `to_currency`, hoặc khi `currency` là tiền điện tử); ngược lại là `null`.
- `txid`, `payment_amount` — `null` cho đến khi khách hàng trả tiền. Được điền vào sau khi giao dịch được phát hiện trên chuỗi. Lắng nghe webhook `payment_status: paid` để biết thời điểm.
- `exchange_rate` — `null` nếu việc quy đổi chưa áp dụng được (ví dụ tỷ giá fiat → crypto chưa được chốt). Được điền vào khi đã chọn được tiền của người trả.

<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>

## Thông tin thanh toán

<TwoCol>

Lấy trạng thái thanh toán hiện tại theo `uuid` hoặc `order_id`.

### Tham số yêu cầu

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `uuid` | string | yes\* | UUID của thanh toán (lấy từ `result.uuid` khi tạo) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | yes\* | ID đơn hàng của bạn | <InputValue name="order_id" placeholder="ORDER-12345" /> |

> **INFO:** Phải cung cấp ít nhất một trong `uuid` hoặc `order_id`.

<TwoColAside>

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

</TwoColAside>

</TwoCol>

## Danh sách thanh toán

<TwoCol>

Lấy danh sách tất cả thanh toán có hỗ trợ lọc và phân trang.

### Tham số yêu cầu

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `status` | string | no | Lọc theo trạng thái thanh toán (xem [References](/docs/references)) | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | no | Ngày bắt đầu (YYYY-MM-DD), ví dụ `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | no | Ngày kết thúc (YYYY-MM-DD), ví dụ `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | no | Số trang, mặc định `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | no | Số mục mỗi trang, mặc định `15`, tối đa `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>