개요
2328.io와 암호화폐 결제 처리 및 출금을 통합하기 위한 기술 사양.
2328.io API 문서에 오신 것을 환영합니다. 본 레퍼런스는 암호화폐 결제 처리 및 출금을 애플리케이션에 통합하는 방법을 설명합니다.
시작하기
통합을 시작하려면:
- 2328.io에서 가맹점 계정과 프로젝트를 생성합니다
- 프로젝트 설정에서 project UUID와 API key를 발급받습니다
- 출금 기능을 사용할 계획이라면 별도의 Payout API key를 생성합니다
- Authentication 섹션을 읽고 요청 서명 방법을 익힙니다
- 첫 번째 Create Payment 호출을 수행합니다
Base URL
모든 프로덕션 API 요청은 다음 base URL을 사용합니다:
https://api.2328.io/api모든 요청은 반드시 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 키를 사용하고, 먼저 계산한 후 지급 상태를 조정합니다. |
호스티드 체크아웃과 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, 상태, 수취 금액, 상점 금액, 환전 결과가 필요합니다.