# Payment API

> 2328.io Payment API로 암호화폐 결제 세션을 생성하고 관리합니다.

Payment API를 사용하면 결제 세션을 생성하고, 고객을 호스팅된 결제 페이지로 리디렉션하며, 결제 상태를 추적할 수 있습니다.

## 결제 생성

<TwoCol>

결제 세션을 생성하고 고객이 결제할 수 있는 URL을 반환합니다.

### 요청 매개변수

| 필드 | 타입 | 필수 | 설명 | 값 |
|-------|------|----------|-------------|--------|
| `amount` | decimal | yes | 통화 단위의 결제 금액, 예: `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | yes | 법정화폐(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 | yes | 가맹점 측 주문 ID, 예: `ORDER-12345` (최대 128자) | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | no | 미리 선택된 암호화폐 | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | no\* | 네트워크 코드 (`to_currency`가 설정된 경우 또는 `currency`가 암호화폐인 경우 필수) | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | no | 결제 후 리디렉션할 URL, 예: `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | no | `url_return`의 대안 | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | no | webhook 알림용 URL, 예: `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | no | 추천인 코드 | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `fee_split` | decimal | no | 결제자에게 전가할 가맹점 수수료의 비율, 0–100 (%). 0 = 가맹점이 전액 부담, 100 = 결제자가 전액 부담. 프로젝트 수준 설정을 덮어씁니다. **예: `30`** (결제자가 수수료의 30%를 부담). | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `price_markup` | decimal | no | 청구 금액에 적용할 마크업 또는 할인, −99 ~ 100 (%). 프로젝트 수준 설정을 덮어씁니다. **예: `5`** (+5%) 또는 `-10` (10% 할인). | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `description` | string | no | 선택적 청구 설명(최대 200자). 결제 페이지에서 결제자에게 표시됩니다. **예: `Premium plan — Order #12345`**. | <InputValue name="description" placeholder="Premium plan — Order #12345" /> |
| `ttl_seconds` | int | no | 청구 유효 기간(초). `300`(5분) ~ `86400`(24시간). 이 시간이 지나면 청구가 만료되어 결제할 수 없습니다. 기본값: `3600`(1시간). **예: `3600`**. | <InputValue name="ttl_seconds" type="integer" placeholder="3600" /> |

### 응답

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

- 결제를 완료하려면 고객을 `result.url`로 리디렉션하세요.
- `tg_deeplink` — Telegram MiniApp을 통한 결제용 Telegram bot deeplink.
- `qr` — 입금 주소의 base64 인코딩된 QR 코드(data URI). 주소가 이미 할당된 경우(즉, `network`가 `to_currency`와 함께 지정되거나 `currency`가 암호화폐일 때) 제공됩니다. 그 외에는 `null`입니다.
- `txid`, `payment_amount` — 고객이 결제하기 전까지 `null`입니다. 온체인에서 트랜잭션이 감지되면 채워집니다. 시점은 `payment_status: paid` webhook을 수신하여 확인하세요.
- `exchange_rate` — 변환이 아직 적용되지 않은 경우(예: 법정화폐 → 암호화폐 환율이 잠기지 않은 경우) `null`입니다. 결제자 통화가 선택되면 채워집니다.

<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`로 현재 결제 상태를 조회합니다.

### 요청 매개변수

| 필드 | 타입 | 필수 | 설명 | 값 |
|-------|------|----------|-------------|--------|
| `uuid` | string | yes\* | 결제 UUID (생성 시 `result.uuid`) | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | yes\* | 가맹점 측 주문 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>

필터링과 페이지네이션을 지원하는 모든 결제 목록을 조회합니다.

### 요청 매개변수

| 필드 | 타입 | 필수 | 설명 | 값 |
|-------|------|----------|-------------|--------|
| `status` | string | no | 결제 상태로 필터링([References](/docs/references) 참고) | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | no | 시작 일자 (YYYY-MM-DD), 예: `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | no | 종료 일자 (YYYY-MM-DD), 예: `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | no | 페이지 번호, 기본값 `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | no | 페이지당 항목 수, 기본값 `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>