결제 및 출금/정적 지갑

정적 지갑

특정 주문 또는 사용자에 연결되는 영구 입금 주소 — 정기 결제와 장기 결제에 적합합니다.

Markdown으로 보기·llms.txt

정적 지갑은 암호화폐 결제를 수신하기 위한 영구 주소입니다. 특정 order_id에 연결되며 project_id + order_id + currency + network 조합으로 고유하게 식별됩니다.

정적 지갑의 활용 사례:

동일 사용자로부터의 반복 입금
사용자 프로필에 표시되는 장기 결제 주소
사용자별 안정적인 주소를 제공해야 하는 대량 입금 흐름

정적 지갑 생성

POST/v1/static-wallet

요청 매개변수

필드	타입	필수	설명
`currency`	string	yes	암호화폐 (USDT, BTC, ETH 등)
`network`	string	yes	네트워크 코드
`order_id`	string	yes	가맹점 측 주문/사용자 ID (최대 255자)
`label`	string	no	지갑 라벨 (최대 255자)
`url_callback`	string	yes	webhook 알림용 URL
`invite_code`	string	no	추천인 코드

요청 예시

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

응답 예시

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

지갑 정보

uuid 또는 address로 정적 지갑 정보를 조회합니다.

POST/v1/static-wallet/info

요청 매개변수

필드	타입	필수	설명
`uuid`	string	yes*	정적 지갑 UUID
`address`	string	yes*	블록체인 지갑 주소

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

응답 예시

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

total_received — 이 지갑이 수신한 모든 입금의 합계, currency 단위.
transactions_count — 지금까지 수신한 입금 횟수.
qr — 입금 주소의 base64 인코딩된 QR data URI (정적 지갑은 생성 시 주소가 할당되므로 항상 제공됩니다).

지갑 목록

POST/v1/static-wallet/list

요청 매개변수

필드	타입	필수	설명
`status`	string	no	상태로 필터링 (`active`, `inactive`)
`currency`	string	no	통화로 필터링
`network`	string	no	네트워크로 필터링
`order_id`	string	no	order_id로 필터링
`page`	int	no	페이지 번호 (기본값: 1)
`per_page`	int	no	페이지당 항목 수 (기본값: 20, 최댓값: 100)

응답 예시

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

지갑 활성화 / 비활성화

정적 지갑이 새로운 결제를 수락할지 여부를 전환합니다.

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

요청

두 endpoint 모두 단일 매개변수를 받습니다:

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

응답 예시

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

enable의 경우 status는 "active"이며 message는 "Static wallet enabled successfully"로 표시됩니다.

지갑 거래 내역

정적 지갑이 수신한 모든 입금 목록을 조회합니다.

POST/v1/static-wallet/transactions

요청 매개변수

필드	타입	필수	설명
`uuid`	string	yes	정적 지갑 UUID
`date_from`	date	no	시작 일자 (YYYY-MM-DD)
`date_to`	date	no	종료 일자 (YYYY-MM-DD)
`page`	int	no	페이지 번호 (기본값: 1)
`per_page`	int	no	페이지당 항목 수 (기본값: 15, 최댓값: 5000)

응답 예시

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

fee_amount — 이 입금에서 차감된 플랫폼 수수료, currency 단위.
net_amount — 수수료 차감 후 가맹점 잔액에 반영된 금액.

정적 지갑 webhook

정적 지갑에서 결제가 수신되면 시스템은 url_callback으로 webhook을 전송합니다.

정적 지갑의 webhook 형식은 일반 결제 webhook과 다릅니다. 특히 정적 지갑 webhook에는 잔액 반영에 사용해야 하는 merchant_amount 필드가 포함됩니다.

Webhook payload

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

정적 지갑 webhook에는 url이나 expires_at이 포함되지 않습니다(주소가 영구적이며 세션이 아니기 때문). 다만 exchange_rate와 created_at은 포함됩니다.

필드 레퍼런스

필드	타입	설명
`uuid`	string	이 입금에 해당하는 트랜잭션(청구) UUID
`order_id`	string	정적 지갑의 `order_id`
`amount`	decimal (8 dp)	수신한 암호화폐 금액
`currency`	string	수신 암호화폐 (지갑의 `currency`와 동일)
`amount_usd`	decimal (8 dp)	수신 시점의 USD 환산 금액
`exchange_rate`	decimal	적용된 암호화폐 / USD 환율
`payer_currency`	string	정적 지갑에서는 `currency`와 동일
`payer_amount`	decimal (8 dp)	정적 지갑에서는 `amount`와 동일
`network`	string	블록체인 네트워크
`address`	string	정적 지갑 주소
`payment_status`	string	정적 지갑에서는 항상 `paid`
`txid`	string	블록체인 트랜잭션 해시
`payment_amount`	decimal (8 dp)	`amount`와 동일
`merchant_amount`	decimal (18 dp)	수수료 차감 후 금액 — 잔액 반영에 사용하세요
`created_at`	string (ISO 8601)	입금 수신 시각
`sign`	string (hex)	payload의 HMAC-SHA256 서명

모범 사례

고유한 order_id — 사용자 또는 주문마다 고유한 order_id를 사용하세요
멱등성 — 중복 적립을 방지하기 위해 처리 전에 txid를 확인하세요
서명 검증 — 자금을 반영하기 전 반드시 sign 서명을 검증하세요
merchant_amount 사용 — 사용자 잔액에는 payment_amount가 아닌 merchant_amount를 기준으로 반영하세요