신용카드 결제 (직호출 방식) API
카드사 인증창을 직접 호출하여 결제를 진행하는 방식입니다. 일반 결제창과 달리 중간 UI 없이 바로 카드사 인증 화면으로 이동합니다.
테스트용 키 정보
API 정보
POST/card/cardDirect.do
Content-Type
application/x-www-form-urlencoded테스트
https://tbnpg.settlebank.co.kr/card/cardDirect.do운영
https://npg.settlebank.co.kr/card/cardDirect.do일반 결제창과의 차이점
NOTE
직호출 방식의 특징
직호출 방식은 결제수단 선택 화면 없이 바로 카드사 인증창으로 이동합니다. 할부개월수(instmtMon)를 지정하면 해당 값으로 바로 결제가 진행됩니다.
| 구분 | 일반 결제창 (/card/main.do) | 직호출 (/card/cardDirect.do) |
|---|---|---|
| UI 흐름 | 결제수단 선택 → 카드사 인증 | 바로 카드사 인증 |
| 할부개월수 | 선택 리스트 노출 | 요청값으로 바로 결제 |
| 용도 | 일반적인 결제 연동 | 간소화된 결제 플로우 |
주의 사항
상점아이디 속성에 따른 화면 분기
상점아이디가 일반 인증 결제로 설정되어 있는 경우 카드사 인증창이 나타나고, 비인증 또는 구인증으로 설정되어 있는 경우 카드정보 입력창이 나타납니다.
- 신용카드 빌키(billKey)를 내려받고자 하는 경우, 빌키 서비스를 영업 담당자를 통해 별도 신청해야 합니다.
- 빌키를 발급받은 경우, 해당 빌키로 2회차 결제 API 요청하면 됩니다. (신용카드 빌키 결제 API 참고)
- 매출전표의 발행금액은 가맹점에서 전송하는 파라미터를 기준으로 표기됩니다.
- 예) 과세 가맹점에서 거래금액 1,000원을 전송하는 경우
- 거래금액만 전송: 과세 909, 부가세 91로 표기
- 과세금액 900, 부가세금액 100 전송: 과세 900, 부가세 100으로 표기
- 예) 과세 가맹점에서 거래금액 1,000원을 전송하는 경우
요청 파라미터
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
필수 파라미터
└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_jt_il: 인증 nxca_jt_bi: 비인증 nxca_ks_gu: 구인증└methodAN(20)영문+숫자, 최대 20byte*PG 서비스에 해당하는 결제 구분 코드
PG 서비스에 해당하는 결제 구분 코드
*고정값
└cardGbAN(4)영문+숫자, 최대 4byte*특정카드사 코드. 직호출 방식에서 특정 카드사 인증창을 호출하기 위한 필수값
특정카드사 코드. 직호출 방식에서 특정 카드사 인증창을 호출하기 위한 필수값
*카드사 코드는 카드사 코드 참조 페이지를 확인하세요.
└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거래금액 (USD 사용시 100을 곱하여 전달)거래금액 (USD 사용시 100을 곱하여 전달)
*KRW: 1000 / USD: ex) $1.00 → 100
└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고객명고객명
└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상점에서 보내주는 고유 고객아이디 혹은 유니크키상점에서 보내주는 고유 고객아이디 혹은 유니크키
└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비과세금액 (복합과세일 경우 필수)비과세금액 (복합과세일 경우 필수)
└svcAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding + Base64신용카드 봉사료신용카드 봉사료
└instmtMonN(2)숫자, 최대 2byte할부개월수. 직호출 방식에서는 요청된 할부 개월 수로 바로 결제 진행
할부개월수. 직호출 방식에서는 요청된 할부 개월 수로 바로 결제 진행
00: 일시불 2~12: 할부개월수*00: 일시불, 2~12: 할부개월수
└cardTypeN(1)숫자, 최대 1byte카드결제타입
카드결제타입
3: 앱카드 전용가능 카드사[신한/삼성/현대/KB/농협/롯데]└chainUserIdAN(100)영문+숫자, 최대 100byte현대카드 PayShot ID. 카드사와 직접 제휴계약 진행 후 사용 가능
현대카드 PayShot ID. 카드사와 직접 제휴계약 진행 후 사용 가능
└appSchemeAN(100)영문+숫자, 최대 100byte앱스키마 (AppScheme://~) 형식. 자체앱을 구축하는 경우 사용
앱스키마 (AppScheme://~) 형식. 자체앱을 구축하는 경우 사용
└custIpAN(15)영문+숫자, 최대 15byte고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소. IPv4 형식으로 입력 (IPv6 불가)
고객 IP주소. 상점 서버의 IP가 아닌, 고객 기기의 IP주소. IPv4 형식으로 입력 (IPv6 불가)
응답 파라미터
결제 완료 또는 실패 시 nextUrl로, 고객이 결제창 내 X 버튼을 클릭하면 cancUrl로 리다이렉트되며 아래 파라미터가 전달됩니다. 브라우저 종료 및 뒤로가기는 감지되지 않습니다.
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_jt_il헥토파이낸셜에서 부여하는 고유 상점아이디
nxca_jt_il: 인증 nxca_jt_bi: 비인증 nxca_ks_gu: 구인증└outStatCdAN(4)영문+숫자, 최대 4byte*거래상태코드 (성공/실패)
0021거래상태코드 (성공/실패)
0021: 성공 0031: 실패└outRsltCdAN(4)영문+숫자, 최대 4byte*거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
0000거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*결과메세지 (URL Encoding, UTF-8)
정상적으로 처리되었습니다.결과메세지 (URL Encoding, UTF-8)
└methodAN(20)영문+숫자, 최대 20byte*PG 서비스에 해당하는 결제 구분 코드
cardPG 서비스에 해당하는 결제 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문번호 (한글 제외)
ORDER20211231100000상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtCustIdAN(50)영문+숫자, 최대 50byte
AES-256AES-256/ECB/PKCS5Padding상점에서 보내주는 고유 고객아이디 혹은 유니크키HongGilDong상점에서 보내주는 고유 고객아이디 혹은 유니크키
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜 거래번호
STFP_PGCAnxca_jt_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결제 승인 일시
└authNoN(15)숫자, 최대 15byte신용카드 승인 번호
30001234신용카드 승인 번호
└intMonN(2)숫자, 최대 2byte신용카드 할부 개월 수
00신용카드 할부 개월 수
└fnNmAH(20)영문+한글, 최대 20byte신용카드 카드사명
우리카드신용카드 카드사명
└fnCdAN(4)영문+숫자, 최대 4byte신용카드 카드사 코드
LTC신용카드 카드사 코드
└pointTrdNoAN(40)영문+숫자, 최대 40byte고객이 포인트 결제를 했을 경우 포인트 결제 건 거래번호
STFP_PGCAnxca_jt_il0211129135810M1494620고객이 포인트 결제를 했을 경우 포인트 결제 건 거래번호
└pointTrdAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding고객이 포인트 결제를 했을 경우 포인트 결제 금액1000고객이 포인트 결제를 했을 경우 포인트 결제 금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└cardTrdAmtN(12)숫자, 최대 12byte
AES-256AES-256/ECB/PKCS5Padding고객이 할인 받은 금액 또는 포인트금액을 제외한 신용카드 결제금액4000고객이 할인 받은 금액 또는 포인트금액을 제외한 신용카드 결제금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└billKeyAN(50)영문+숫자, 최대 50byte*빌키 서비스 이용시 발급되는 자동결제키. 2회차 결제 시 사용
SBILL_0123456789빌키 서비스 이용시 발급되는 자동결제키. 2회차 결제 시 사용
*영업 담당자를 통해 별도 신청 필요
노티 전문 (결과통보)
결제 완료 후 헥토파이낸셜에서 가맹점으로 노티(결과통보)가 전송됩니다.
NOTE
노티 전문 확인
신용카드 결제 결과통보 파라미터와 처리 방법은 노티 전문 문서를 참고하세요.
