상품권 결제 (결제창 방식)
상품권 결제창 방식은 고객이 보유한 상품권(틴캐시, 컬쳐캐쉬, 스마트문상, 도서상품권)을 사용하여 결제하는 방식입니다.
NOTE
티머니 결제
티머니 결제는 별도 결제수단으로 분리되어 있습니다.
테스트용 키 정보
API 정보
POST/gift/{상품권종류}/main.do
Content-Type
application/x-www-form-urlencoded테스트
https://tbnpg.settlebank.co.kr/gift/{상품권종류}/main.do운영
https://npg.settlebank.co.kr/gift/{상품권종류}/main.doNOTE
상품권 종류별 API 경로
상품권 종류(method)에 따라 호출 URL이 다릅니다.
| method | 테스트 URL | 운영 URL |
|---|---|---|
| teencash | https://tbnpg.settlebank.co.kr/gift/teenCash/main.do | https://npg.settlebank.co.kr/gift/teenCash/main.do |
| culturecash | https://tbnpg.settlebank.co.kr/gift/cultureCash/main.do | https://npg.settlebank.co.kr/gift/cultureCash/main.do |
| smartcash | https://tbnpg.settlebank.co.kr/gift/smartCash/main.do | https://npg.settlebank.co.kr/gift/smartCash/main.do |
| booknlife | https://tbnpg.settlebank.co.kr/gift/booknlife/main.do | https://npg.settlebank.co.kr/gift/booknlife/main.do |
주의 사항
상품권 결제 주의사항
상품권 종류에 따라 사용 가능한 금액과 조건이 다릅니다. 부분 사용 가능 여부를 확인하세요.
- 상품권 종류: 문화상품권, 도서상품권, 스마트문화상품권 등
- 상품권 잔액이 결제금액보다 적을 경우 잔액만큼만 사용됩니다.
- 일부 상품권은 부분 취소가 불가능할 수 있습니다.
- 상품권 정산은 상품권사 정책에 따라 진행됩니다.
요청 파라미터
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
필수 파라미터
└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il: 상품권└methodAN(20)영문+숫자, 최대 20byte*결제 구분 코드
결제 구분 코드
teencash: 틴캐시 culturecash: 컬쳐캐쉬 smartcash: 스마트문상 booknlife: 도서상품권*상품권 종류에 따라 선택
└trdDtN(8)숫자, 최대 8byte*요청일자 (yyyyMMdd)
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*요청시간 (HH24MISS)
요청시간 (HH24MISS)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문번호 (한글 제외)
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtNameAHN(100)영문+한글+숫자, 최대 100byte*상점한글명
상점한글명
└mchtENameAN(100)영문+숫자, 최대 100byte*상점영문명
상점영문명
└pmtPrdtNmAHN(50)영문+한글+숫자, 최대 50byte*결제상품명
결제상품명
└trdAmtN(12)숫자, 최대 12byte*
AES-256AES-256/ECB/PKCS5Padding + Base64거래금액거래금액
└notiUrlAN(250)영문+숫자, 최대 250byte*결제 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
결제 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
└nextUrlAN(250)영문+숫자, 최대 250byte*결제 결과 화면으로 전환되는 URL
결제 결과 화면으로 전환되는 URL
*결제창 내 버튼 클릭 시 리다이렉트 됩니다. outStatCd 값으로 결제 성공(0021)/실패(0031) 여부를 확인하세요.
└cancUrlAN(250)영문+숫자, 최대 250byte*고객이 결제창의 X 버튼 클릭 시 리다이렉트 되는 URL
고객이 결제창의 X 버튼 클릭 시 리다이렉트 되는 URL
*브라우저 종료, 뒤로가기 등은 감지되지 않습니다.
└pktHashAN(200)영문+숫자, 최대 200byte*
SHA-256SHA256 방식으로 생성한 해쉬값(실시간 생성)SHA256 방식으로 생성한 해쉬값
NOTE
해쉬 생성 조합
mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt(평문) + hashKey
선택 파라미터
└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byte
AES-256AES-256/ECB/PKCS5Padding + Base64고객명고객명
└mchtCustIdAN(50)영문+숫자, 최대 50byte
AES-256AES-256/ECB/PKCS5Padding + Base64상점 고객아이디상점 고객아이디
*컬쳐랜드상품권(컬쳐캐쉬, culturecash)의 경우 필수
└custIpAN(15)영문+숫자, 최대 15byte고객 IP 주소 (상점 서버 IP가 아닌 고객 기기의 IP 주소). IPv4 형식으로 입력 (IPv6 불가)
고객 IP 주소 (상점 서버 IP가 아닌 고객 기기의 IP 주소). IPv4 형식으로 입력 (IPv6 불가)
*컬쳐랜드상품권(컬쳐캐쉬, culturecash)의 경우 필수
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte상점 예약 필드 (결과 전달시 그대로 return)
상점 예약 필드 (결과 전달시 그대로 return)
└prdtTermN(14)숫자, 최대 14byte상품제공기간 (yyyyMMddHHmmss, 값이 없으면 일반결제로 표기)
상품제공기간 (yyyyMMddHHmmss, 값이 없으면 일반결제로 표기)
응답 파라미터
결제 완료 또는 실패 시 nextUrl로, 고객이 결제창 내 X 버튼을 클릭하면 cancUrl로 리다이렉트되며 아래 파라미터가 전달됩니다. 브라우저 종료 및 뒤로가기는 감지되지 않습니다.
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
공통 응답
└mchtIdAN(10)영문+숫자, 최대 10byte*상점아이디
nx_mid_il상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*거래상태코드
0021거래상태코드
0021: 성공 0031: 실패└outRsltCdAN(4)영문+숫자, 최대 4byte*결과코드
0000결과코드
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*결과메시지
정상적으로 처리되었습니다.결과메시지
└methodAN(20)영문+숫자, 최대 20byte*결제수단
teencash결제수단
teencash: 틴캐시 culturecash: 컬쳐캐쉬 smartcash: 스마트문상 booknlife: 도서상품권└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점 주문번호
ORDER20211231100000상점 주문번호
└mchtCustIdAN(50)영문+숫자, 최대 50byte
AES-256AES-256/ECB/PKCS5Padding상점 고객아이디 (컬쳐캐쉬의 경우 필수)HongGilDong상점 고객아이디 (컬쳐캐쉬의 경우 필수)
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜 거래번호
STFP_PGCAnx_mid_il0211129135810M1494620헥토파이낸셜 거래번호
└trdAmtN(12)숫자, 최대 12byte*
AES-256AES-256/ECB/PKCS5Padding거래금액1000거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte상점예약필드 (요청으로 받은 필드값을 응답으로 Bypass)
name=HongGilDong&age=25상점예약필드 (요청으로 받은 필드값을 응답으로 Bypass)
└authDtN(14)숫자, 최대 14byte승인일시
20211231100000승인일시
노티 전문 (결과통보)
결제 완료 후 헥토파이낸셜에서 가맹점으로 노티(결과통보)가 전송됩니다.
NOTE
노티 전문 확인
상품권 결제 결과통보 파라미터와 처리 방법은 노티 전문 문서를 참고하세요.
