결제 및 출금/Payment API

Payment API

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

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

결제 생성

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

요청 매개변수

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

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

결제 정보

uuid 또는 order_id로 현재 결제 상태를 조회합니다.

요청 매개변수

필드	타입	필수	설명	값
`uuid`	string	yes*	결제 UUID (생성 시 `result.uuid`)
`order_id`	string	yes*	가맹점 측 주문 ID

uuid 또는 order_id 중 최소 하나는 반드시 지정해야 합니다.

RequestPOST/v1/payment/info

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

결제 목록

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

요청 매개변수

필드	타입	필수	설명
`status`	string	no	결제 상태로 필터링(References 참고)
`date_from`	date	no	시작 일자 (YYYY-MM-DD), 예: `2026-01-01`
`date_to`	date	no	종료 일자 (YYYY-MM-DD), 예: `2026-01-31`
`page`	int	no	페이지 번호, 기본값 `1`
`per_page`	int	no	페이지당 항목 수, 기본값 `15`, 최댓값 `5000`

RequestPOST/v1/payment/list

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.