지갑 서비스 API
지갑 서비스 API는 6개 섹션으로 구성된 RESTful API입니다. 모든 요청은 JSON 형식을 사용하며, 성공/실패 응답 모두 표준 응답 포맷을 따릅니다.
2.1 공통 응답 형식
필드
타입
설명
success
boolean
요청 성공 여부
data
object | null
응답 데이터 (성공 시)
error
object | null
에러 정보 (실패 시). code / message / details 포함.
requestId
string
서버 생성 요청 추적 ID
timestamp
string
응답 시각 (ISO 8601)
2.2 API 섹션 구성
섹션
Base Path
주요 기능
A. 기관 인증
/api/wallet-auth
API Key 갱신(POST /refresh), 폐기(DELETE /api-key), 세션 조회(GET /session)
B. 지갑 관리
/api/wallets
지갑 생성·조회·업데이트·비활성화 (NORMAL / INCENTIVE / GOVERNMENT)
C. 송금·이체
/api/wallets/transfer
ERC-3009 기반 가스비 없는 송금 실행 및 내역 조회
D. 충전·환불
/api/wallets/charge
지갑 충전, 부분/전액 충전 취소, NORMAL 지갑 전액 환불
E. 결제
/api/wallets/payment
복합결제(워터폴: GOVERNMENT→INCENTIVE→NORMAL), 결제 취소, 내역 조회
F. 트랜잭션
/api/wallets/{id}/transactions
모든 유형 트랜잭션 통합 조회 (10가지 유형 지원)
2.3 주요 API 상세
A. 기관 인증 및 권한
필드명
타입
필수
설명
apiKey
string
O
현재(또는 만료된) API Key
secretKey
string
O
최초 발급 시 받은 Secret Key (갱신 시 변경 없음)
► POST /api/wallet-auth/refresh — 응답: newApiKey, expiresAt
B. 지갑 생성
필드명
타입
필수
설명
userId
string
O
파트너사 내 사용자 고유 식별자
walletType
string
O
NORMAL / INCENTIVE / GOVERNMENT
metadata
object
-
파트너사 임의 메타데이터 (최대 5쌍)
► POST /api/wallets — 응답: walletId, walletAddress, walletType, balance, createdAt
C. 송금 실행
필드명
타입
필수
설명
fromWalletId
string
O
출금 지갑 식별자
toWalletAddress
string
O
수신 블록체인 주소 (0x 시작, 42자리)
amount
integer
O
송금 금액 (KRW, 양의 정수)
memo
string
-
송금 메모 (최대 200자)
► POST /api/wallets/transfer — ERC-3009 transferWithAuthorization 사용, 가스비 사용자 부담 없음
D. 충전
필드명
타입
필수
설명
walletId
string
O
충전 대상 지갑 식별자
amount
integer
O
충전 금액 (KRW, 최소 1,000원)
memo
string
-
충전 메모 (최대 200자)
► POST /api/wallets/charge | 취소: POST /api/wallets/charge/cancel (부분 취소 지원, 충전 후 30일 이내)
E. 결제 (복합결제 워터폴)
필드명
타입
필수
설명
payerWalletId
string
O
결제자 지갑 식별자
receiverWalletId
string
O
수신자 지갑 식별자
amount
integer
O
결제 금액 (KRW, 최소 100원)
incentiveAmount
integer
-
null: INCENTIVE 전액 사용 / 0: 미사용 / 금액: 해당 금액만 사용
memo
string
-
결제 메모 (최대 200자)
► POST /api/wallets/payment — 차감 순서: GOVERNMENT(0원) → INCENTIVE → NORMAL
► 인센티브는 NORMAL 지갑 사용분에 대해서만 적립됩니다.
F. 트랜잭션 통합 조회
유형(type)
설명
TRANSFER
송금 (보내기/받기)
CHARGE / CHARGE_CANCEL
충전 / 충전 취소
PAYMENT / PAYMENT_CANCEL
결제 / 결제 취소
REFUND
환불
INCENTIVE / INCENTIVE_USE / INCENTIVE_CANCEL / INCENTIVE_USE_CANCEL
인센티브 지급·사용·환수·복원
► GET /api/wallets/{walletId}/transactions — type 파라미터로 콤마 구분 다중 필터링 지원
2.4 공통 에러 코드
에러 코드
HTTP
설명
WAUTH_001 / 002
401
잘못된 / 만료된 API Key
WAUTH_003 / 004
403
구독 만료 / 플랜 한도 초과
WAL_002 / 004
404 / 400
존재하지 않는 지갑 / 비활성화된 지갑
TRF_001 / 002 / 003
400
잔액 부족 / 유효하지 않은 주소 / 일일 한도 초과
CHG_003 / 004
400
이미 취소된 충전 / 취소 가능 기간 초과
PAY_001 / 002 / 003
400
결제 잔액 부족 / 최소 금액 미달 / 이미 취소
TX_001
404
존재하지 않는 트랜잭션
RATE_001
429
Rate Limit 초과
SYS_001
500
내부 서버 오류
Last updated