헥토파이낸셜 개발자센터

결제 취소 API

결제 완료된 거래를 취소합니다. 간편현금결제는 출금된 계좌로 환불됩니다.

테스트용 키 정보

주의 사항

orgTrdNo 필수

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

부분취소

신용카드 부분취소 시 cnclOrd를 001부터 순차적으로 증가시켜야 합니다.

API 정보

POST/whitelabel/v1/pay_cancel.do
Content-Typeapplication/json
테스트https://tbapi.settlebank.co.kr/whitelabel/v1/pay_cancel.do
운영https://api.settlebank.co.kr/whitelabel/v1/pay_cancel.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*
상점 고객아이디
└orgTrdNoAN(40)영문+숫자, 최대 40byte*
결제 응답의 거래번호 (trdNo)
└trdAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
취소금액 (부분취소 시 필수)
└taxTypeCdA(1)영문, 최대 1byte
면세여부
N: 과세 Y: 면세 G: 복합과세
└taxAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
과세금액 (복합과세 시 필수)
└vatAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
부가세금액 (복합과세 시 필수)
└taxFreeAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
비과세금액 (복합과세 시 필수)
└svcAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
봉사료
└crcCdA(3)영문, 최대 3byte
통화구분 (신용카드 필수)
└cnclOrdN(3)숫자, 최대 3byte
취소회차 (신용카드 필수, 001부터 시작)

응답 파라미터

params 객체

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

data 객체

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

해시 검증

응답의 pktHash는 요청 시 전송한 해시값과 동일합니다. 요청 시 생성한 해시값(trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey)과 비교하여 데이터 무결성을 검증하세요.
└mchtCustIdAN(100)영문+숫자, 최대 100byte*honggildong
상점 고객아이디
└payMethodA(2)영문, 최대 2byte*CA
결제수단 코드
RT: 간편결제취소 CA: 신용카드취소
└orgTrdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCApg_test0000260107143100M1234567
원거래번호
└taxTypeCdA(1)영문, 최대 1byte
면세여부
Y: 면세 N: 과세 G: 복합과세
└trdAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5PaddingvqIWIiimsJ5efjSJpfnnTw==
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└taxAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
취소금액 중 과세금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└vatAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
취소금액 중 부가세금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└taxFreeAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
취소금액 중 면세금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└svcAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
취소금액 중 봉사료
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└crcCdA(3)영문, 최대 3byteKRW
통화 구분 값 (신용카드 전용)
└cnclOrdN(3)숫자, 최대 3byte001
취소회차 (001부터 시작, 신용카드 전용)
└cardCnclAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
신용카드 거래금액 (신용카드 전용)
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding
취소가능잔액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└pktNoAN(20)영문+숫자, 최대 20byte
전문번호 (간편현금결제 전용)

요청 예시

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "C4",
        "encCd": "23",
        "mchtTrdNo": "CANCEL20260107150000",
        "trdDt": "20260107",
        "trdTm": "150000",
        "mobileYn": "N",
        "osType": "W"
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "orgTrdNo": "STFP_PGCApg_test0000260107143100M1234567",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw==",
        "crcCd": "KRW",
        "cnclOrd": "001"
    }
}

응답 예시

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "C4",
        "encCd": "23",
        "mchtTrdNo": "CANCEL20260107150000",
        "trdNo": "STFP_PGCApg_test0000260107150000M7654321",
        "trdDt": "20260107",
        "trdTm": "150000",
        "outStatCd": "0021",
        "outRsltCd": "0000",
        "outRsltMsg": "정상적으로 처리되었습니다."
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "payMethod": "CA",
        "orgTrdNo": "STFP_PGCApg_test0000260107143100M1234567",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw=="
    }
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?