헥토파이낸셜 개발자센터

선불금 사용 API

회원의 머니 및 포인트를 사용(결제)하는 API입니다.

API 정보

POST/v1/wallet/use
Content-Typeapplication/json
테스트https://tb-mps-api.hectofinancial.co.kr/v1/wallet/use
운영https://mps-api.hectofinancial.co.kr/v1/wallet/use

연동 프로세스

고객
가맹점
헥토파이낸셜
11. 결제 요청
22. 잔액 조회 API
33. 잔액 응답
44. 사용 API (PIN 인증)
55. 사용 완료 응답
66. 결제 완료

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└custNoAN(20)영문+숫자, 최대 20byte*
선불 회원번호
*헥토파이낸셜에서 부여하는 고유 선불 회원 번호
└mTrdNoAN(50)영문+숫자, 최대 50byte*
상점 거래번호
*상점에서 생성하는 거래번호 (한글 제외)
└trdAmtN(7)숫자, 최대 7byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액 (사용 요청 금액)
*AES-256/ECB/PKCS5Padding 암호화 후 Base64 인코딩
└mnyBlcN(7)숫자, 최대 7byte*AES-256AES-256/ECB/PKCS5Padding + Base64
머니 잔액
*선불 회원의 머니 잔액. AES-256/ECB/PKCS5Padding 암호화 필요
└pntBlcN(7)숫자, 최대 7byte*AES-256AES-256/ECB/PKCS5Padding + Base64
포인트 잔액
*선불 회원의 포인트 잔액. AES-256/ECB/PKCS5Padding 암호화 필요
└blcUseOrdAN(1)영문+숫자, 최대 1byte
잔액 사용 순서
M: 머니 우선 사용 P: 포인트 우선 사용 (기본값)
└reqDtAN(8)영문+숫자, 최대 8byte
요청 일자
*yyyyMMdd 형식
└reqTmAN(6)영문+숫자, 최대 6byte
요청 시각
*HHmmss 형식
└csrcIssReqYnAN(1)영문+숫자, 최대 1byte
현금영수증 발행 요청 여부
Y: 발행 요청 N: 발행 안함
*사용된 머니에 대한 현금영수증 발행 요청
└stlMIdAN(20)영문+숫자, 최대 20byte*AES-256AES-256/ECB/PKCS5Padding + Base64
정산 상점 아이디
*정산 대상 상점 아이디. AES-256/ECB/PKCS5Padding 암호화 필요
└storCdAN(20)영문+숫자, 최대 20byte
사용처 코드
└storNmAN(128)영문+숫자, 최대 128byte
사용처명
*사용 알림 메일 발송 시 해당 값이 메일 내용에 활용됩니다
└pinNoAN(6)영문+숫자, 최대 6byte*AES-256AES-256/ECB/PKCS5Padding + Base64
결제 비밀번호 (핀번호)
*AES-256/ECB/PKCS5Padding 암호화 필요
└mResrvField1AN(255)영문+숫자, 최대 255byte
상점 여유필드 1
*평문으로 송수신되므로 개인정보와 같은 민감정보 포함되지 않도록 주의
└mResrvField2AN(255)영문+숫자, 최대 255byte
상점 여유필드 2
*평문으로 송수신되므로 개인정보와 같은 민감정보 포함되지 않도록 주의
└mResrvField3AN(255)영문+숫자, 최대 255byte
상점 여유필드 3
*평문으로 송수신되므로 개인정보와 같은 민감정보 포함되지 않도록 주의
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA-256 해시값
*선불회원번호 + 상점아이디 + 상점거래번호 + 거래금액(평문) + 해시키

응답 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└rsltCdAN(4)영문+숫자, 최대 4byte*0000
응답코드
0000: 성공 그 외: 실패
└rsltMsgAN(255)영문+숫자, 최대 255byte*성공
응답 메시지

rsltObj (응답 객체)

└custNoAN(20)영문+숫자, 최대 20byte*2400001605
선불 회원번호
└mtrdNoAN(50)영문+숫자, 최대 50byte*ORDER20240716
상점 거래번호
*한글 제외
└trdNoAN(50)영문+숫자, 최대 50byte*24071616270200002193
거래 승인번호
*헥토파이낸셜에서 부여하는 고유 거래번호. 취소 시 필요
└trdDtAN(8)영문+숫자, 최대 8byte*20240716
거래 일자
*yyyyMMdd
└trdTmAN(6)영문+숫자, 최대 6byte*164101
거래 시각
*HHmmss
└trdAmtN(7)숫자, 최대 7byte*10000
거래금액
*사용된 금액 (머니 + 포인트)
└mnyAmtN(7)숫자, 최대 7byte*9000
사용된 머니 금액
└pntAmtN(7)숫자, 최대 7byte*1000
사용된 포인트 금액
└mnyBlcN(7)숫자, 최대 7byte*11000
사용 후 머니 잔액
└pntBlcN(7)숫자, 최대 7byte*0
사용 후 포인트 잔액
└pktHashAN(200)영문+숫자, 최대 200byte*
SHA-256 해시값
*선불회원번호 + 상점아이디 + 상점거래번호 + 거래승인번호 + 거래금액 + 머니금액 + 포인트금액 + 해쉬키

요청 예시

{
  "custNo": "2400001605",
  "mTrdNo": "NSTEST20240715000006",
  "trdAmt": "OtHHsG793ox9XewbvX21Lw==",
  "mnyBlc": "2fISihtRzzKJZZay2s8LFQ==",
  "pntBlc": "ceBxI7xbssp9mlz9hRzTJw==",
  "blcUseOrd": "M",
  "reqDt": "20240826",
  "reqTm": "160010",
  "csrcIssReqYn": "Y",
  "stlMId": "R0L4ColX2RqUDQyo5lWTPQ==",
  "storCd": "HF0001",
  "storNm": "헥토파이낸셜",
  "pinNo": "6NykSPILA01QdAh6sTGaBA==",
  "pktHash": "eb19306c05c1fd19c0fb185358243512d0ffad44ab299e629d89428ad6134f46"
}

응답 예시

성공

{
  "rsltCd": "0000",
  "rsltMsg": "성공",
  "rsltObj": {
    "custNo": "2400001605",
    "mtrdNo": "ORDER20240716",
    "trdNo": "24071616270200002193",
    "trdDt": "20240716",
    "trdTm": "164101",
    "trdAmt": "10000",
    "mnyAmt": "9000",
    "pntAmt": "1000",
    "mnyBlc": "11000",
    "pntBlc": "0",
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05de5ba815f463f00429061c"
  }
}

실패 (잔액 부족)

{
  "rsltCd": "T-009",
  "rsltMsg": "원거래금액/요청금액을 확인하세요"
}

실패 (비밀번호 오류)

{
  "rsltCd": "T-010",
  "rsltMsg": "결제 비밀번호가 일치하지 않습니다 (2회)"
}

주의사항

결제 비밀번호 오류 횟수 제한

결제 비밀번호를 5회 이상 틀리면 계정이 잠금 처리됩니다. 내정보 페이지에서 비밀번호를 재설정해야 합니다.
  • 잔액 조회 API를 먼저 호출하여 mnyBlc, pntBlc 값을 확인 후 사용해 주세요.
  • blcUseOrd로 머니/포인트 사용 우선순위를 지정할 수 있습니다.
  • 거래번호(mTrdNo)는 중복될 수 없습니다.
  • 모든 금액 파라미터는 평문값 기준이며, 암호화 시 디코딩된 값을 사용합니다.
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?