가상계좌 결제 (결제창 방식)
결제창 방식은 고객이 결제 화면에서 직접 가상계좌를 발급받아 입금하는 방식입니다.
테스트용 키 정보
API 정보
POST/vbank/main.do
Content-Type
application/x-www-form-urlencoded테스트
https://tbnpg.settlebank.co.kr/vbank/main.do운영
https://npg.settlebank.co.kr/vbank/main.do주의 사항
가상계좌 입금 안내
가상계좌는 발급 후 만료일까지 유효하며, 입금금액이 설정된 금액과 정확히 일치해야 자동 승인됩니다.
- 가상계좌번호는 고유하며, 중복 발급되지 않습니다.
- 만료일 이후에는 입금이 불가능합니다.
- 입금 완료 시 노티(notiUrl)를 통해 결과를 받을 수 있습니다.
요청 파라미터
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
필수 파라미터
└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il: 가상계좌└methodAN(20)영문+숫자, 최대 20byte*PG 서비스에 해당하는 결제 구분 코드
PG 서비스에 해당하는 결제 구분 코드
*고정값
└trdDtN(8)숫자, 최대 8byte*요청일자 (yyyyMMdd)
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*요청시간 (HH24MISS)
요청시간 (HH24MISS)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문번호 (한글 제외)
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtNameAHN(100)영문+한글+숫자, 최대 100byte*상점한글명
상점한글명
└mchtENameAN(100)영문+숫자, 최대 100byte*상점영문명
상점영문명
└pmtPrdtNmAHN(128)영문+한글+숫자, 최대 128byte*결제상품명
결제상품명
└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 값으로 채번 성공(0051)/실패(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고객명고객명
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte기타 주문 정보를 입력하는 상점 예약 필드
기타 주문 정보를 입력하는 상점 예약 필드
└emailAN(60)영문+숫자, 최대 60byte
AES-256AES-256/ECB/PKCS5Padding + Base64이메일 주소이메일 주소
└prdtTermN(14)숫자, 최대 14byte상품제공기간 (yyyyMMddHHmmss). 값이 없으면 일반결제로 표기
상품제공기간 (yyyyMMddHHmmss). 값이 없으면 일반결제로 표기
└mchtCustIdAN(50)영문+숫자, 최대 50byte
AES-256AES-256/ECB/PKCS5Padding + Base64상점에서 보내주는 고유 고객아이디 혹은 유니크키상점에서 보내주는 고유 고객아이디 혹은 유니크키
└custAcntSumryAHN(50)영문+한글+숫자, 최대 50byte통장인자내용. 고객의 통장에 찍힐 인자명. 공백일 경우 상점한글명을 사용
통장인자내용. 고객의 통장에 찍힐 인자명. 공백일 경우 상점한글명을 사용
└expireDtN(14)숫자, 최대 14byte입금만료일시 (yyyyMMddHHmmss)
입금만료일시 (yyyyMMddHHmmss)
*미설정시 거래일 기준 10일 뒤로 자동 설정. 최대 현재일 기준 +365일(1년)까지 설정 가능
└cphoneNoN(11)숫자, 최대 11byte
AES-256AES-256/ECB/PKCS5Padding + Base64휴대폰번호 (하이픈 제거)휴대폰번호 (하이픈 제거)
└taxTypeCdA(1)영문, 최대 1byte면세여부. 공백일 경우 상점 설정에 따름
면세여부. 공백일 경우 상점 설정에 따름
N: 과세 Y: 면세 G: 복합과세└taxAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding + Base64과세금액 (복합과세일 경우 필수)과세금액 (복합과세일 경우 필수)
└vatAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding + Base64부가세금액 (복합과세일 경우 필수)부가세금액 (복합과세일 경우 필수)
└taxFreeAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding + Base64비과세금액 (복합과세일 경우 필수)비과세금액 (복합과세일 경우 필수)
└custIpAN(15)영문+숫자, 최대 15byte고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소. IPv4 형식으로 입력 (IPv6 불가)
고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소. IPv4 형식으로 입력 (IPv6 불가)
응답 파라미터
가상계좌 발급 완료 시 nextUrl로, 고객이 결제창 내 X 버튼을 클릭하면 cancUrl로 리다이렉트되며 아래 파라미터가 전달됩니다. 실제 입금 결과는 고객 입금 후 notiUrl(노티 전문)로 전달됩니다.
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il헥토파이낸셜에서 부여하는 고유 상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*거래상태코드 (성공/실패)
0051거래상태코드 (성공/실패)
0051: 채번 성공(입금대기중) 0031: 실패└outRsltCdAN(4)영문+숫자, 최대 4byte*거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
0000거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*결과메세지 (URL Encoding, UTF-8)
정상적으로 처리되었습니다.결과메세지 (URL Encoding, UTF-8)
└methodAN(20)영문+숫자, 최대 20byte*PG 서비스에 해당하는 결제 구분 코드
vbankPG 서비스에 해당하는 결제 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문번호
ORDER20211231100000상점에서 생성하는 고유 주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜 거래번호
STFP_PGVBnxvb_jt_il0211129135810M1494620헥토파이낸셜 거래번호
└trdAmtN(12)숫자, 최대 12byte*
AES-256AES-256/ECB/PKCS5Padding거래금액1000거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└vtlAcntNoN(30)숫자, 최대 30byte
AES-256AES-256/ECB/PKCS5Padding발급된 가상계좌번호1234567890123456발급된 가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└fnNmAH(50)영문+한글, 최대 50byte가상계좌 은행명
국민은행가상계좌 은행명
└fnCdN(4)숫자, 최대 4byte가상계좌 은행코드
004가상계좌 은행코드
└expireDtN(14)숫자, 최대 14byte가상계좌 입금기한 (yyyyMMddHHmmss)
20271231235959가상계좌 입금기한 (yyyyMMddHHmmss)
└mchtCustIdAN(50)영문+숫자, 최대 50byte
AES-256AES-256/ECB/PKCS5Padding상점고객아이디HongGilDong상점고객아이디
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└authDtN(14)숫자, 최대 14byte승인일시 (가상계좌 주문/채번 일시)
20211231100000승인일시 (가상계좌 주문/채번 일시)
└reqIssueDtN(14)숫자, 최대 14byte채번요청일시 (010가상계좌인 경우)
20211231100000채번요청일시 (010가상계좌인 경우)
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte요청으로 받은 필드값을 응답으로 Bypass
name=HongGilDong&age=25요청으로 받은 필드값을 응답으로 Bypass
노티 전문 (결과통보)
가상계좌는 채번노티와 입금노티 2번의 노티가 전송됩니다.
2단계 노티 처리 필수
가상계좌는 계좌 발급 시(채번노티)와 실제 입금 완료 시(입금노티) 각각 노티가 전송됩니다. 반드시 두 노티를 모두 처리해야 합니다. 노티 전문 문서 보기
