헥토파이낸셜 개발자센터

결제 승인 API

결제창(UI) 인증 완료 후 Server-to-Server로 실제 결제를 진행합니다.

테스트용 키 정보

주의 사항

authTrdNo 필수

결제창 응답의 trdNo(거래번호)를 authTrdNo 파라미터에 전달해야 합니다.

API 정보

POST/whitelabel/v1/pay_confirm.do
Content-Typeapplication/json
테스트https://tbapi.settlebank.co.kr/whitelabel/v1/pay_confirm.do
운영https://api.settlebank.co.kr/whitelabel/v1/pay_confirm.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)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HHmmss)
└mobileYnA(1)영문, 최대 1byte
모바일 여부
Y: 모바일웹/앱 N: PC
└osTypeA(1)영문, 최대 1byte
OS 구분
A: Android I: iOS W: Windows M: Mac E: 기타

data 객체

└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해시값
*trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + 해시키
└mchtCustIdAN(100)영문+숫자, 최대 100byte*
상점 고객아이디
└authTrdNoAN(40)영문+숫자, 최대 40byte*
결제창 응답의 거래번호 (trdNo)
└trdAmtAN(12)영문+숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액

응답 파라미터

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*pg_test
상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A18
전문 버전
*고정값
└methodA(2)영문, 최대 2byte*WL
결제수단
*고정값
└bizTypeAN(2)영문+숫자, 최대 2byte*B9
업무구분코드
*고정값
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20260107143000
상점주문번호
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드 (실패 시 상세코드)
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과 메시지
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCApg_test0000260107143100M1234567
헥토파이낸셜 거래번호 (취소 시 필수)
└trdDtN(8)숫자, 최대 8byte*20260107
거래일자
└trdTmN(6)숫자, 최대 6byte*143100
거래시간

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*
요청시 hash 값 그대로 return. 데이터 위변조 체크를 위해 요청 시 생성한 해시값과 비교 검증하세요.
NOTE

해시 검증

응답의 pktHash는 요청 시 전송한 해시값과 동일합니다. 요청 시 생성한 해시값(trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey)과 비교하여 데이터 무결성을 검증하세요.
└mchtCustIdAN(100)영문+숫자, 최대 100byte*honggildong
상점 고객아이디
└authTrdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCApg_test0000260107143000M1717578
헥토파이낸셜 거래번호
└payMethodAN(2)영문+숫자, 최대 2byte*CA
결제수단 코드
CA: 신용카드 RP: 간편현금
└fnNmHA(20)HA, 최대 20byte국민
카드사명 (신용카드 전용)
└fnCdAN(4)영문+숫자, 최대 4byteKBC
카드사코드 (신용카드 전용)
└svcDivCdN(1)숫자, 최대 1byte1
간편현금 연동구분
1: 펌뱅킹 2: 오픈뱅킹
└trdAmtAN(12)영문+숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5PaddingvqIWIiimsJ5efjSJpfnnTw==
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

요청 예시

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "B9",
        "encCd": "23",
        "mchtTrdNo": "ORDER20260107143000",
        "trdDt": "20260107",
        "trdTm": "143000",
        "mobileYn": "N",
        "osType": "W"
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "authTrdNo": "STFP_PGCApg_test0000260107143000M1717578",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw=="
    }
}

응답 예시

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "B9",
        "encCd": "23",
        "mchtTrdNo": "ORDER20260107143000",
        "trdNo": "STFP_PGCApg_test0000260107143100M1234567",
        "trdDt": "20260107",
        "trdTm": "143100",
        "outStatCd": "0021",
        "outRsltCd": "0000",
        "outRsltMsg": "정상적으로 처리되었습니다."
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "authTrdNo": "STFP_PGCApg_test0000260107143000M1717578",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw==",
        "payMethod": "CA",
        "fnNm": "국민",
        "fnCd": "KBC"
    }
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?