# 개요

> 2328.io와 암호화폐 결제 처리 및 출금을 통합하기 위한 기술 사양.

2328.io API 문서에 오신 것을 환영합니다. 본 레퍼런스는 암호화폐 결제 처리 및 출금을 애플리케이션에 통합하는 방법을 설명합니다.

## 시작하기

통합을 시작하려면:

1. [2328.io](https://2328.io)에서 가맹점 계정과 프로젝트를 생성합니다
2. 프로젝트 설정에서 **project UUID**와 **API key**를 발급받습니다
3. 출금 기능을 사용할 계획이라면 별도의 **Payout API key**를 생성합니다
4. [Authentication](/docs/authentication) 섹션을 읽고 요청 서명 방법을 익힙니다
5. 첫 번째 [Create Payment](/docs/payments) 호출을 수행합니다

## Base URL

모든 프로덕션 API 요청은 다음 base URL을 사용합니다:

```
https://api.2328.io/api
```

> **WARNING:** 모든 요청은 반드시 **HTTPS**로 이루어져야 합니다. HTTPS를 사용하지 않는 요청은 차단됩니다.

## 가능한 작업

2328.io API로 다음과 같은 작업을 수행할 수 있습니다:

- **암호화폐 결제 수락** — 결제 세션을 생성하고 고객을 호스팅된 결제 페이지 또는 Telegram MiniApp으로 리디렉션
- **자금 출금** — 가맹점 잔액에서 임의의 블록체인 주소로 프로그래밍 방식의 출금 실행
- **잔액 조회** — 통화별 머천트 계정 잔액, USD 환산액, AML로 잠긴 금액을 확인합니다
- **정적 지갑 사용** — 사용자 또는 주문에 연결된 영구 입금 주소 생성
- **환율 조회** — 법정화폐 및 암호화폐 페어의 실시간 환율 조회
- **Webhook 수신** — 결제 상태가 변경될 때 즉시 알림 수신
## 요청 제한

API는 **프로젝트당 초당 최대 10회 요청**을 허용합니다. 제한을 초과한 요청은 HTTP `429 Too Many Requests` 응답을 받습니다 — 잠시 대기 후 재시도하세요.

## 올바른 통합 패턴 선택

| 요구사항 | 추천 패턴 | 이유 |
|-------------|---------------------|-----|
| 고객이 결제 방법을 선택하도록 허용 | 호스팅된 결제 | 결제를 생성하고 `result.url`로 리디렉션; 2328.io가 현재 사용 가능한 방향을 제공합니다. |
| 고객을 자체 결제 내에 유지 | 직접 주소 **H2H** 송장 | 결제 생성 시 `to_currency` 및 `network` 보내기; 반환된 `address`, `payer_amount`, `qr` 렌더링. |
| 정확히 `25 USDT` 또는 `0.001 BTC` 청구 | 암호화폐 표시 송장 | 암호화폐를 `currency`에 넣고 정확한 소수점 금액을 `amount`에 입력하세요. |
| 각 사용자에게 재사용 가능한 입금 주소 제공 | 고정 지갑 | 주소는 영구적이며 여러 독립적인 입금을 받을 수 있습니다. |
| 들어오는 자산을 하나의 잔액 통화로 표준화 | 자동 변환 | 대시보드에서 프로젝트 규칙을 구성하고 변환이 완료되면 `convert` 결과를 사용하세요. |
| 기존 상인 잔액 교환 | 수동 변환 | `/v1/convert/price`로 미리보기 후 `/v1/convert`로 실행 |
| 자금을 블록체인 주소로 전송 | 지급 | 별도의 지급 API 키를 사용하고, 먼저 계산한 후 지급 상태를 조정합니다. |

> **INFO:** 호스티드 체크아웃과 H2H는 같은 결제 API의 두 가지 표현입니다. H2H가 결제를 약화시키거나 서명하지 않은 결제를 생성하지는 않습니다: 백엔드는 여전히 인보이스를 생성하며, 2328.io는 여전히 주소와 상태를 소유하고 있고, 서명된 웹훅은 결제 확정에 대해 권위가 있습니다.

## 통합 불변식

이 규칙들은 모든 운영 환경 통합에 적용됩니다:

- **Backend only** — API 키를 브라우저, 모바일 애플리케이션, 로그, 분석, 그리고 지원 스크린샷에 노출하지 마세요.
- **Decimal strings** — 문자열로 돈을 보내고 저장하세요. 암호화폐나 환율을 이진 부동소수점 연산으로 절대 반올림하지 마세요.
- **Immutable idempotency keys** — 첫 요청 전에 `order_id`를 생성하고 전체 요청을 그것과 함께 보존하세요. 같은 `order_id`로 재시도하면 변경된 필드를 적용하는 대신 원래 객체를 반환할 수 있습니다.
- **Webhook-first settlement** — 리다이렉트, 클라이언트 폴링, 사용자 제공 거래 해시, HTTP 타임아웃은 결제 증명이 아닙니다.
- **Verify, deduplicate, then mutate** — HMAC를 검증하고, 멱등성(idempotency) 기록을 원자적으로 청구하고, 주문/잔액을 한 번 업데이트하고, HTTP 200을 신속하게 반환하세요.
- **Reconciliation** — 손실된 웹훅이 영구적 불일치를 남기지 않도록 결제, 정적 지갑(static-wallet), 송금 상태를 주기적으로 조회하세요.
- **Dynamic availability** — `/v1/directions`로 통화/네트워크 쌍을 검증합니다. 지원되는 자산이라도 한 쪽의 입금 또는 출금 방향이 일시적으로 비활성화될 수 있습니다.
- **Explicit status policy** — 제품을 라이브로 전환하기 전에 부분 결제, 과지불, 만료, AML 잠금, 변환 대체, 모호한 상위 타임아웃 처리 방식을 결정합니다.

## 권장 데이터를 저장

결제의 경우 최소한 `uuid`, `order_id`, 원본 요청 본문, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, 최신 `payment_status`, `txid`, `payment_amount`, `merchant_amount`, 선택적 `convert` 블록 및 검증된 원시 웹훅 페이로드를 저장합니다.

정적 지갑의 경우, 지갑 `uuid`, 주소, 통화, 네트워크, 고객/계정 참조, 상태, 콜백 URL을 입금 기록과 별도로 보관하십시오. 각 입금은 고유한 거래 `uuid`, `txid`, 상태, 수취 금액, 상점 금액, 환전 결과가 필요합니다.