신용카드 승인 API (인증/승인 분리)

인증과 승인을 분리하여 처리하는 신용카드 결제 API입니다. 인증 완료 후 별도로 승인 요청을 진행합니다.

테스트용 키 정보

주의 사항

인증/승인 분리 방식

인증 요청시 생성한 상점주문번호(mchtTrdNo)를 반드시 사용해야 하며, authTrdNo는 인증 성공시 응답받은 거래번호를 사용합니다.

인증 완료 후 승인만 별도로 진행하는 API입니다.
인증시 사용한 상점주문번호와 인증거래번호가 필요합니다.
빌키 발급은 별도 서비스 신청이 필요합니다.

API 정보

POST/spay/APIService.do

Content-Typeapplication/json

테스트https://tbgw.settlebank.co.kr/spay/APIService.do

운영https://gw.settlebank.co.kr/spay/APIService.do

요청 파라미터

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*헥토파이낸셜에서 부여하는 고유 상점아이디

헥토파이낸셜에서 부여하는 고유 상점아이디

└verAN(4)영문+숫자, 최대 4byte*전문의 버전

전문의 버전

*고정값

└methodA(2)영문, 최대 2byte*결제수단

결제수단

*고정값

└bizTypeAN(2)영문+숫자, 최대 2byte*업무 구분코드

업무 구분코드

*고정값 (승인용)

└encCdN(2)숫자, 최대 2byte*암호화 구분 코드

암호화 구분 코드

*고정값

└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점주문번호 (인증 요청시 생성한 번호 반드시 사용)

상점주문번호 (인증 요청시 생성한 번호 반드시 사용)

└trdDtN(8)숫자, 최대 8byte*요청일자 (YYYYMMDD)

요청일자 (YYYYMMDD)

└trdTmN(6)숫자, 최대 6byte*요청시간 (HHMMSS)

요청시간 (HHMMSS)

└mobileYnA(1)영문, 최대 1byte모바일 여부

모바일 여부

Y: 모바일웹/앱 N: PC 또는 그 외

└osTypeA(1)영문, 최대 1byteOS 구분

OS 구분

A: Android I: IOS W: Windows M: Mac E: 기타

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*SHA-256SHA256 방식으로 생성한 해쉬값(실시간 생성)

SHA256 방식으로 생성한 해쉬값

NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey

└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64거래금액

거래금액

└authTrdNoAN(40)영문+숫자, 최대 40byte*인증거래번호 (인증 성공시 응답받은 거래번호)

인증거래번호 (인증 성공시 응답받은 거래번호)

응답 파라미터

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*헥토파이낸셜에서 부여하는 고유 상점아이디nxca_jt_hd

헥토파이낸셜에서 부여하는 고유 상점아이디

└verAN(4)영문+숫자, 최대 4byte*전문의 버전0A19

전문의 버전

*고정값

└methodA(2)영문, 최대 2byte*결제수단CA

결제수단

*고정값

└bizTypeAN(2)영문+숫자, 최대 2byte*업무 구분코드B2

업무 구분코드

*승인용 고정값

└encCdN(2)숫자, 최대 2byte*암호화 구분 코드23

암호화 구분 코드

*고정값

└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점주문번호ORDER20211231100000

상점주문번호

└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜에서 발급한 고유한 거래번호SOFP_PGMPnxhp_sb_hd0211021111808M1234567

헥토파이낸셜에서 발급한 고유한 거래번호

└trdDtN(8)숫자, 최대 8byte*요청일자 (YYYYMMDD)20211231

요청일자 (YYYYMMDD)

└trdTmN(6)숫자, 최대 6byte*요청시간 (HHMMSS)100000

요청시간 (HHMMSS)

└outStatCdN(4)숫자, 최대 4byte*거래상태코드0061

거래상태코드

0061: 인증 성공 (인증 단계) 0021: 승인 성공 (승인 단계) 0031: 실패

*인증/승인 분리 방식에서는 인증 단계에서 0061, 승인 단계에서 0021이 반환됩니다.

└outRsltCdN(4)숫자, 최대 4byte*결과코드. 거래상태가 '0031'일 경우, 상세 코드 전달0000

결과코드. 거래상태가 '0031'일 경우, 상세 코드 전달

*거절 코드 표 참고

└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*결과 메세지 (URL Encoding, UTF-8)정상적으로 처리되었습니다.

결과 메세지 (URL Encoding, UTF-8)

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*요청시 hash 값 그대로 return

요청시 hash 값 그대로 return

└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding거래금액1000

거래금액

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte요청값을 응답으로 Bypassname=HongGilDong&age=25

요청값을 응답으로 Bypass

└apprNoN(15)숫자, 최대 15byte신용카드 승인번호30001234

신용카드 승인번호

└intMonN(2)숫자, 최대 2byte신용카드 할부개월수00

신용카드 할부개월수

└fnNmAH(20)영문+한글, 최대 20byte신용카드 카드사명우리카드

신용카드 카드사명

└fnCdAN(4)영문+숫자, 최대 4byte신용카드 카드사코드LTC

신용카드 카드사코드

└pointTrdNoAN(40)영문+숫자, 최대 40byte포인트거래번호 (포인트다모아 복합결제시)STFP_PGCAnxca_jt_il0211129135810M1494620

포인트거래번호 (포인트다모아 복합결제시)

└pointTrdAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding포인트거래금액 (포인트다모아 복합결제시)1000

포인트거래금액 (포인트다모아 복합결제시)

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└cardTrdAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding신용카드결제금액 - 할인/포인트 제외4000

신용카드결제금액 - 할인/포인트 제외

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└billKeyAN(50)영문+숫자, 최대 50byte빌키 (자동결제키)SBILL_0123456789

빌키 (자동결제키)

*영업 담당자를 통해 별도 신청 필요

└dcTrdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding할인거래금액1000

할인거래금액

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└dcYnA(1)영문, 최대 1byte*할인여부Y

할인여부

Y: 할인금액 존재 N: 할인금액 없음

└ninstmtTypeCdA(1)영문, 최대 1byte무이자할부여부Y

무이자할부여부

Y: 무이자 N: 일반할부/일시불

└cardNoAN(20)영문+숫자, 최대 20byteAES-256AES-256/ECB/PKCS5Padding카드번호 (마스킹, 상점설정정보에 따른 옵션값)123456******7890

카드번호 (마스킹, 상점설정정보에 따른 옵션값)

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└ornPntUseYnA(1)영문, 최대 1byte카드사포인트사용유무Y

카드사포인트사용유무

Y: 사용 N: 미사용

└ornPntAmtA(12)영문, 최대 12byteAES-256AES-256/ECB/PKCS5Padding카드사포인트사용금액1000

카드사포인트사용금액

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

요청 예시

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "100000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6",
    "trdAmt": "AES암호화된금액",
    "authTrdNo": "SOFP_PGMPnxhp_sb_hd0211021111808M1234567"
  }
}

응답 예시

성공 응답

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "SOFP_PGMPnxhp_sb_hd0211021111808M1234567",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "정상적으로 처리되었습니다."
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6",
    "trdAmt": "AES암호화된금액",
    "apprNo": "30001234",
    "intMon": "00",
    "fnNm": "우리카드",
    "fnCd": "LTC",
    "billKey": "SBILL_0123456789",
    "dcTrdAmt": "AES암호화된할인금액",
    "dcYn": "Y",
    "ninstmtTypeCd": "N"
  }
}

실패 응답

{
  "params": {
    "mchtId": "nxca_jt_hd",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B2",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0031",
    "outRsltCd": "1001",
    "outRsltMsg": "결제 요청 정보 누락"
  },
  "data": {
    "pktHash": "980f95d9b059dd15394eeb39e9d7bc8b3500f9afa4a38bea10877cd46a42caf6"
  }
}

응답 코드

거래 상태 코드 (outStatCd)

코드	설명	비고
0061	인증 성공	인증/승인 분리 방식의 인증 단계
0021	승인 성공	인증/승인 분리 방식의 승인 단계
0031	실패	상세 코드는 outRsltCd 참고
0051	채번 성공	가상계좌 발급

PG 공통 응답 코드 (outRsltCd)

코드	설명
0000	정상처리
0009	사용자취소
1001	결제 필수 정보 누락 (상점아이디)
1002	결제 필수 정보 누락 (버전)
1003	결제 필수 정보 누락 (결제수단)
1004	결제 필수 정보 누락 (업무구분코드)
1005	결제 필수 정보 누락 (상점주문번호)
1006	결제 필수 정보 누락 (요청일자)
1007	결제 필수 정보 누락 (요청시간)
1008	결제 필수 정보 누락 (해시값)
1009	결제 필수 정보 누락 (거래금액)
1010	결제 필수 정보 누락 (암호화구분코드)
1011	결제 필수 정보 누락 (거래번호)
1012	결제 필수 정보 누락 (취소금액)
1013	결제 필수 정보 누락 (환불금액)
1101	결제 요청 정보 길이 오류 (상점아이디)
1102	결제 요청 정보 길이 오류 (버전)
1103	결제 요청 정보 길이 오류 (결제수단)
1104	결제 요청 정보 길이 오류 (업무구분코드)
1105	결제 요청 정보 길이 오류 (상점주문번호)
1106	결제 요청 정보 길이 오류 (요청일자)
1107	결제 요청 정보 길이 오류 (요청시간)
1108	결제 요청 정보 길이 오류 (해시값)
1109	결제 요청 정보 길이 오류 (거래금액)
1110	결제 요청 정보 길이 오류 (암호화구분코드)
1111	결제 요청 정보 길이 오류 (거래번호)
1112	결제 요청 정보 길이 오류 (취소금액)
1113	결제 요청 정보 길이 오류 (환불금액)
1901	해쉬값 불일치 오류
1902	암호화 항목 미처리 오류
2001	보안숫자 불일치
2002	보안숫자 입력시간 초과
2003	보안숫자 입력횟수 초과
5001	잘못된 경로로 접근 (상점정보 없음)
5002	잘못된 경로로 접근 (상점 미사용)
5003	잘못된 경로로 접근 (결제수단 미계약)
5004	잘못된 경로로 접근 (결제수단 미사용)
5005	잘못된 경로로 접근 (업무구분 미지원)
5006	잘못된 경로로 접근 (IP 차단)
9001	게이트웨이 내부 오류
9002	게이트웨이 통신 오류
9003	게이트웨이 데이터베이스 오류
9004	게이트웨이 타임아웃
9901	원천사 시스템 점검
9902	원천사 시스템 장애
9903	원천사 통신 오류
9904	원천사 타임아웃
9905	원천사 응답 오류

신용카드 전용 응답 코드 (outRsltCd)

코드	설명
CA01	원천사 점검 중
CA02	원천사 장애
CA20	카드 유효기간이 유효하지 않음
CA65	인증거래 미약정 가맹점
CA82	카드사 전화 요망
CA83	해당 거래는 취소가 불가함

더 궁금한 내용이 있나요?

FAQ

기술지원이 필요한가요?

코드 샘플

HectoFinancial GitHub