승인 API 연동하기
1. 승인 API Flow
2. 설명 (Description)
- 인증 응답 데이터를 기반으로 PG사로 승인 요청을 진행하는 API입니다.
- 해당 API로 승인 요청 후 정상 응답을 받아야만 결제가 완료됩니다.
3. 요청 (Request)
3.1. HTTP Request
- Method:
POST - URL:
https://webapi.nicepay.co.kr/webapi/pay_process.jsp - Content-Type:
application/x-www-form-urlencoded - Encoding:
EUC-KR
3.2. 요청 파라미터
| 필드명 | 크기(byte) | 필수 | 설명 |
|---|---|---|---|
| TID | 30 | O | 승인 요청할 거래 아이디 (인증 응답으로 받은 TxTid 사용) |
| AuthToken | 40 | O | 인증 토큰 (인증 응답으로 받은 AuthToken 사용) |
| MID | 10 | O | 가맹점 아이디 |
| Amt | 12 | O | 망취소 요청 금액 (거래 금액과 동일한 값으로 설정) |
| EdiDate | 14 | O | 요청 전문 생성 일시(YYYYMMDDHHMISS) |
| SignData | 256 | O | 위변조 검증 데이터, 생성규칙: hex(sha256(AuthToken + MID + Amt + EdiDate + MerchantKey)) |
| CharSet | 10 | 인증 응답 인코딩 (euc-kr(default) / utf-8) | |
| EdiType | 10 | 응답전문 유형 (JSON(default) / KV) *KV:Key=value | |
| MallReserved | 500 | 가맹점 여분필드 (나이스페이 가공 없음) |
4. 응답 (Response)
4.1. 공통 응답 파라미터
PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| ResultCode | 4 | 결과코드 (결제수단 별 성공코드: 3001 CARD / 0000 CMS_BANK) |
| ResultMsg | 100 | 결과 메세지 |
| Amt | 12 | 결제 금액 |
| MID | 10 | 가맹점 아이디 |
| Moid | 64 | 가맹점 주문번호 |
| Signature | 500 | 위변조 검증 데이터, 생성 규칙: hex(sha256(TID + MID + Amt + MerchantKey)) |
| BuyerEmail | 60 | 구매자 이메일 주소 |
| BuyerTel | 20 | 구매자 연락처 |
| BuyerName | 30 | 구매자명 |
| GoodsName | 40 | 상품명 |
| TID | 30 | 거래 아이디 |
| AuthCode | 30 | 승인번호 (신용카드, 계좌이체, 휴대폰) |
| AuthDate | 12 | 승인일시 (YYMMDDHHMISS) |
| PayMethod | 10 | 결제수단 (신용카드: CARD, 계좌간편결제: CMS_BANK) |
| MallReserved | 500 | 가맹점 여분필드 (요청 시 Data 그대로 전달) |
승인 응답 관련 참고 사항
4.2. 신용카드 승인 응답 추가 파라미터
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| CardCode | 3 | 카드 발급사 코드 |
| CardName | 100 | 카드 발급사 이름 |
| CardNo | 20 | 카드 번호 (일부 마스킹 처리) |
| CardQuota | 2 | 할부개월 (00: 일시불, 02: 2개월, 03: 3개월, ...) |
| CardInterest | 1 | 가맹점 분담 무이자 적용 여부 (0: 미적용, 1: 적용) |
| AcquCardCode | 3 | 매입 카드사 코드 |
| AcquCardName | 100 | 매입 카드사 이름 |
| CardCl | 1 | 카드 구분 (0: 신용, 1: 체크) |
| CcPartCl | 1 | 부분취소 가능 여부 (0: 불가능, 1: 가능) |
| CardType | 2 | 카드 형태 (01: 개인, 02: 법인, 03: 해외) |
| ClickpayCl | 2 | 간편결제 구분 |
| CouponAmt | 12 | 쿠폰 금액 |
| CouponMinAmt | 12 | 쿠폰 최소 금액 |
| PointAppAmt | 12 | 카드사 포인트 승인금액 |
| MultiCl | 1 | 옵션: 페이코/카카오/토스 간편결제 복합결제 여부 (0: 복합결제 미사용, 1: 복합결제 사용) |
| MultiCardAcquAmt | 12 | 옵션: 페이코/카카오/토스 간편결제 간편결제 신용카드 금액 |
| MultiPointAmt | 12 | 옵션: 페이코/카카오/토스 간편결제 간편결제 포인트(페이코 포인트, 카카오머니, 토스머니) 금액 |
| MultiCouponAmt | 32 | 옵션: 페이코/카카오/토스 간편결제 간편결제 쿠폰(페이코 쿠폰, 카카오 포인트, 토스 포인트) 금액 |
| MultiRcptAmt | 12 | 옵션: 페이코 간편결제 페이코 머니 거래건 현금영수증 발급 대상 금액 |
| RcptType | 10 | 옵션: 네이버페이-포인트 결제 현금영수증 타입 (0:발행안함,1:소득공제,2:지출증빙) |
| RcptTID | 30 | 옵션: 네이버페이-포인트 결제 현금영수증 TID |
| RcptAuthCode | 30 | 옵션: 네이버페이-포인트 결제 현금영수증 승인번호 |
4.3. 계좌간편결제 승인 응답 파라미터
| 필드명 | 크기(byte) | 설명 |
|---|---|---|
| EasyBankCode | 3 | 결제 은행 코드 |
| EasyBankName | 20 | 결제 은행명 |
| EasyBankUserNo | 20 | 간편결제 회원 일련번호 |
| EasyBankAccountNo | 20 | 결제 계좌번호 (일부 마스킹 처리) |
| RcptResultCode | 4 | 현금영수증 결과코드 (7001: 성공, 이외 실패) |
| RcptResultMsg | 100 | 현금영수증 결과 메세지 |
| RcptType | 10 | 현금영수증 타입 (0:발행안함,1:소득공제,2:지출증빙) |
| RcptTID | 30 | 현금영수증 TID |
| RcptAuthCode | 30 | 현금영수증 승인번호 |
5. 예시
아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.
5.1. 요청 예시
POST /webapi/pay_process.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded
TID=payutest0m01012608141116191323&AuthToken=PAYTOKEN269E752BA68B1F3508DC34FA332A1C26&MID=payutest0m&Amt=1004&EdiDate=20260813090704&SignData=d105473e73c2bd9bbd00b303aba2ab247ac3c4b24a6c65482ea62c2204108954
5.2. 응답 예시
{
"CardCode":"02",
"CardName":"KB국민",
"CardNo":"55704292****2079",
"CardQuota":"00",
"CardInterest":"0",
"AcquCardCode":"02",
"AcquCardName":"KB국민",
"CardCl":"0",
"CcPartCl":"1",
"CouponAmt":"000000000000",
"CouponMinAmt":"000000000000",
"PointAppAmt":"000000000000",
"ClickpayCl":"",
"MultiCl":"",
"MultiCardAcquAmt":"",
"MultiPointAmt":"",
"MultiCouponAmt":"",
"MultiDiscountAmt":"",
"RcptType":"",
"RcptTID":"",
"RcptAuthCode":"",
"CardType":"01",
"ApproveCardQuota":"00",
"PointCl":"0",
"ResultCode":"3001",
"ResultMsg":"카드 결제 성공",
"MsgSource":"PG",
"Amt":"000000001004",
"MID":"payutest0m",
"Moid":"TEST_123",
"BuyerEmail":"test@abc.com",
"BuyerTel":"01012345678",
"BuyerName":"나이스",
"GoodsName":"나이스페이 테스트상품",
"TID":"payutest0m01012608141116191323",
"AuthCode":"30044935",
"AuthDate":"260814111621",
"PayMethod":"CARD",
"CartData":"",
"Signature":"e1dae4da41f3fd606156c942aad98e2d52b2542ee851e847889351d8263d475f",
"MallReserved":""
}