본문으로 건너뛰기

승인 취소 API 연동하기

1. 승인 취소 API Flow​

2. 설명 (Description)​

  • 인증결제 서비스를 통해 승인된 거래건을 취소하고자 할 때 요청하는 API입니다.
  • 결제 취소 요청 및 응답 시 모든 값은 server-side에서 처리해야 하며 민감 정보가 외부에 노출되지 않도록 주의해야 합니다.

3. 요청 (Request)​

3.1. HTTP Request​

  • Method: POST
  • URL: https://pg-api.nicepay.co.kr/webapi/cancel_process.jsp
  • Content-Type: application/x-www-form-urlencoded
  • Encoding: EUC-KR

3.2. 요청 파라미터​

필드명크기(byte)필수설명
TID30O취소 요청할 거래 아이디
MID10O가맹점 아이디
Moid64O취소 요청 시 주문번호 (고유한 값으로 설정, 나이스페이 가공 없음)
CancelAmt12O취소 금액
CancelMsg100O취소 사유 (euc-kr)
PartialCancelCode1O전체/부분취소 여부 (0: 전체취소, 1: 부분취소)
EdiDate14O요청 전문 생성 일시(YYYYMMDDHHMISS)
SignData256O위변조 검증 데이터, 생성규칙: hex(sha256(MID + CancelAmt + EdiDate + MerchantKey))
CharSet10인증 응답 인코딩 (euc-kr(default) / utf-8)
EdiType10응답전문 유형 (JSON(default) / KV) *KV:Key=value
MallReserved500가맹점 여분필드 (나이스페이 가공 없음)
RefundAcctNo16가상계좌 환불 시 필수 환불받을 계좌번호 입력
RefundBankCd3가상계좌 환불 시 필수 환불받을 계좌의 은행 코드 입력
RefundAcctNm10가상계좌 환불 시 필수 환불받을 계좌의 예금주명 입력 (euc-kr)

4. 응답 (Response)​

4.1. 응답 파라미터​

PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.

필드명크기(byte)설명
ResultCode4결과코드 (2001, 2211: 성공, 이외 실패)
ResultMsg100결과 메세지
ErrorCD4에러코드 (취소 실패 시 오류 코드 응답)
ErrorMsg100에러 메세지 (취소 실패 시 오류 상세 메세지 응답)
CancelAmt12취소 금액
MID10가맹점 아이디
Moid64가맹점 취소 주문번호
Signature500위변조 검증 데이터, 생성 규칙: hex(sha256(TID + MID + CancelAmt + MerchantKey))
PayMethod10결제수단 (신용카드: CARD, 계좌이체: BANK, 가상계좌: VBANK, 휴대폰: CELLPHONE)
TID30거래 아이디
CancelDate8취소일자 (YYYYMMDD)
CancelTime6취소 시간 (HHmmss)
CancelNum8취소번호
RemainAmt12부분취소 후 잔액
MallReserved500가맹점 여분필드 (요청 시 Data 그대로 전달)

5. 예시​

아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.

5.1. 요청 예시​

POST /webapi/cancel_process.jsp HTTP/1.1
Host: pg-api.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded

TID=nictest00m01012608131607041648&MID=nictest00m&Moid=moid1234567890&CancelAmt=1004&CancelMsg=고객요청&PartialCancelCode=0&EdiDate=20260813091332&SignData=398e7c2b79ab0a9cdb82954513a9e910d13fc9fb7fc739281d1498a120bbb18d

5.2. 응답 예시​

{
  "CouponAmt": "000000000000",
  "ClickpayCl": "",
  "MultiCardAcquAmt": "",
  "MultiPointAmt": "",
  "MultiCouponAmt": "",
  "MultiDiscountAmt": "",
  "ResultCode": "2001",
  "ResultMsg": "취소 성공",
  "ErrorCD": "0000",
  "ErrorMsg": "정상취소",
  "MsgSource": "PG",
  "CancelAmt": "000000001004",
  "MID": "nictest00m",
  "Moid": "moid1234567890",
  "Signature": "16b738caa1bc9e213395a78f5b09b5f9b96bf22ab2b4e5867de1f8029c6d3dfd",
  "PayMethod": "CARD",
  "TID": "nictest00m01012608131607041648",
  "CancelDate": "20260813",
  "CancelTime": "161332",
  "CancelNum": "00000000",
  "RemainAmt": "000000000000",
  "MallReserved": ""
}