01 개요
정기/반복결제 개요
네이버페이 정기/반복결제의 전체 과정을 간략하게 나타내면 다음과 같습니다.
사용자가 정기/반복결제 상품의 결제 수단으로 네이버페이를 선택하면 네이버페이 정기/반복결제 등록 페이지가 열립니다.
네이버페이 정기/반복결제 등록 페이지에서 등록을 완료한 후에는 가맹점 서버의 스케줄링에 의해 결제 승인 API가 호출되고 서버 대 서버로 결제가 승인됩니다.
02 인증
인증방법
네이버페이 간편결제는 인증에 oAuth 2.0을 사용합니다.
클라이언트 ID와 클라이언트 비밀번호를 발급받아 API 요청 시 요청 헤더에 다음과 같이 입력하며 TLS/SSL을 사용하여 암호화합니다.
X-Naver-Client-Id: {클라이언트 ID}X-Naver-Client-Secret: {클라이언트 시크릿} |
클라이언트 ID와 클라이언트 시크릿은 보안상 노출되면 안 되는 값입니다.
따라서 클라이언트 바이너리 등에 저장하면 안 됩니다. 외부에 노출된 경우 해당 값에 대한 인증을 무효화하고 새로 발급받아 사용해야 합니다.
네이버페이 간편결제 API 서버는 IP 주소 기반 ACL(access control list)을 사용하지 않습니다.
TLS/SSL 지원 버전
네이버페이 간편결제 API는 TLS 1.0~TLS 1.2를 지원합니다. SSL은 더 이상 지원하지 않으므로 TLS 1.0 이상을 지원하는 클라이언트 라이브러리를 사용해야 합니다.
03 방화벽
방화벽
가맹점은 가맹점에서 네이버페이 서버로 나가는 호출인 아웃바운드 트래픽에 대해 다음과 같이 가맹점 서버의 방화벽을 설정합니다.
방화벽 가이드 443 port 허용
04 API URL 형식
백엔드 API 서버 URL 형식
네이버페이 정기/반복결제 API의 URL 형식은 다음과 같습니다.
//{API 도메인} / {파트너 ID} / naverpay / payments / recurrent / {API성격} / {API 버전} / {API명} |
반드시 HTTPS로 호출해야 합니다.
API 도메인은 다음과 같습니다.
- 개발(dev-api-server): dev.apis.naver.com
- 운영(api-server): apis.naver.com
네이버페이 간편결제 API를 호출하는 예는 다음과 같습니다.
POST //dev.apis.naver.com/{파트너 ID}/naverpay/payments/recurrent/regist/v1/reserve HTTP/1.1HeaderX-Naver-Client-Id: {클라이언트 ID}X-Naver-Client-Secret: {클라이언트 시크릿}Content-Type: application/x-www-form-urlencoded -d productCode={정기/반복결제 상품 코드} \-d productName={정기/반복결제 상품명} \ -d totalPayAmount={첫 달 결제 예상 금액} \-d returnUrl={등록 완료 후 이동할 URL} \-d actionType={작업 유형} \-d targetRecurrentId={기존 정기/반복결제 등록 번호} |
정기/반복결제 등록 페이지
네이버페이 정기/반복결제 API에서 사용하는 정기/반복결제 등록 페이지의 주소는 다음과 같습니다.
//{서비스 도메인}/payments/recurrent/{등록 예약 번호} |
등록 예약 번호는 정기/반복결제 등록 예약 요청 결과 응답으로 전달받습니다.
서비스 도메인은 다음과 같습니다.
- 개발(dev-service-server)
- PC 웹 : test-pay.naver.com
- 모바일 웹 : test-m.pay.naver.com
- 운영(service-server)
- PC 웹 : pay.naver.com
- 모바일 웹 : m.pay.naver.com
05 기본 응답 형식
기본 응답 형식
네이버페이 정기/반복결제 API의 기본 응답 형식은 다음과 같습니다.
{ "code" : "Success", "message" : "", "body" : {} } |
code | String of Codes | O | 결과 코드 |
message | String | O | 상세 메시지 |
body | Object | O |
Success | String | 성공 |
RequireParameter | String | 필수 파라미터 누락 |
InvalidParameter | String | 입력값이 조건을 만족하지 않음 |
Fail | String | 기타 실패 |
결제 승인 요청 API 호출 트래픽은 10TPS를 넘지 않아야 합니다.
06 정기/반복결제 등록 흐름
정기/반복결제 등록 흐름
네이버페이 정기/반복결제를 등록하는 과정은 다음과 같습니다.
사용자가 정기/반복결제 상품의 결제 수단으로 네이버페이를 선택하면 네이버페이 정기/반복결제 등록 페이지가 열립니다.
사용자가 등록 페이지에서 결제 수단을 선택 완료하면 가맹점의 returnUrl로 이동하면서 임시 등록 번호가 전달됩니다.
가맹점은 등록 정보를 생성한 후, 네이버페이에 등록 완료를 요청해야 하며, 네이버페이에서는 응답 결과로 최종 등록 번호를 넘겨줍니다.
가맹점에서는 최종 정기/반복결제 등록 정보를 생성합니다.
이 단계에는 오직 등록만 이루어지며, 결제 승인은 별도 결제 API를 사용해야 합니다.
07 정기/반복결제 등록예약 API
정기/반복결제 등록예약 API
네이버페이 정기/반복결제를 등록예약 요청하고 응답으로 등록예약 번호를 받습니다.
POST //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/regist/v1/reserveContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/regist/v1/reserve \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \-d productCode={정기/반복결제 상품 코드} \-d productName={정기/반복결제 상품명} \-d totalPayAmount={첫 달 결제 예상 금액} \-d returnUrl={등록 완료 후 이동할 URL} \-d purchaserName: {구매자이름} \-d purchaserBirthday: {구매자 생년월일} \-d actionType={작업 유형} \-d targetRecurrentId={기존 정기/반복결제 등록 번호} |
productCode | String | 100바이트 | O | 가맹점의 상품 코드 정기/반복결제는 사용자별로 동일한 상품코드에 대해서 중복 등록할 수 없습니다. 결제수단 변경시에는 (actionType="CHANGE") 이전에 등록한 값과 동일한 productCode 값을 넘겨야 합니다. |
productName | String | 512바이트 | O | 가맹점의 상품명 등록 페이지에서 사용자에게 보여줍니다 |
totalPayAmount | Number | O | 첫 달 결제 예상 금액 등록 페이지에서 사용자에게 보여주는 값으로, 결제가 발생하지는 않습니다 - 해당 필드를 0원으로도 호출 가능합니다. 단, 결제수단 등록화면 내에 금액란이 따로 노출되지 않습니다. | |
returnUrl | String | 3000바이트 | O | 정기/반복결제 등록 완료 후 이동할 URL 네이버페이는 등록 완료 후, 가맹점이 등록한 returnUrl로 리디렉션을 수행합니다 가맹점은 구매자에게 등록 결과 정보를 노출할 수 있습니다 |
purchaserName | String | 64바이트 | 구매자 성명. 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다 | |
purchaserBirthday | String | 8바이트 | 구매자 생년월일(yyyymmdd). 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다 | |
actionType | String | 20바이트 | O | 신규 정기/반복결제를 등록하려는 것인지 기존 정기/반복결제의 결제 수단을 변경하려는 것인지 구분합니다 신규 등록: "NEW" 결제 수단 변경: "CHANGE" |
targetRecurrentId | String | 50바이트 | actionType값이 "CHANGE"이면 현재 사용하고 있는 정기/반복결제 등록 번호(recurrentId)값을 전달합니다 actionType값이 "CHANGE"이고 targetRecurrentId값이 등록되어 있는 정기/반복결제 등록 번호이면, 등록 완료 후 새로운 정기/반복결제 등록 번호가 발급되고 targetRecurrentId값에 해당하는 정기/반복결제는 해지됩니다 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
reserveId | String | 50바이트 | 등록 예약 번호 |
ResponseHTTP/1.1 200 OK{ "code" : "Success", "message" : "detail message(optional)", "body" : { "reserveId" : "" }} |
08 정기/반복결제 등록창 호출
등록창 호출
정기/반복결제 등록 페이지를 호출하며, 등록예약 응답으로 받은 등록예약번호(reserveId)를 사용합니다.
등록 페이지는 사용자가 네이버에 로그인되어 있지 않은 경우 네이버 로그인 페이지로 유도하는 기능을 제공합니다.
요청
GET //{서비스 도메인}/payments/recurrent/{등록 예약 번호}Content-Type: application/x-www-form-urlencoded |
성공응답
등록 예약 프로세스가 정상적으로 수행되었을 때 성공으로 응답합니다.
응답필드resultCode | String | 결제 결과(Success: 성공) |
reserveId | String | 등록 예약 번호 |
tempReceiptId | String | 임시 접수 번호 |
Redirect: {returnUrl}?resultCode=Success&reserveId={등록 예약 번호}&tempReceiptId={임시 접수 번호} |
실패 응답
응답필드resultCode | String | 결제 결과(하단의 표 참고) |
resultMessage | String | 실패 사유 메시지 |
reserveId | String | 등록 예약 번호 |
UserCancel | String | 구매자 취소 팝업으로 결제 창을 호출한 경우에 해당 resultCode를 받은 경우 서비스 시나리오에 따라 적절하게 창을 닫아야 합니다 |
그 외 성공(Success)이 아닌 resultCode에 대해서는 적절한 사용자 안내 처리 또는 resultMessage 그대로 전달 |
Redirect: {returnUrl}?resultCode={resultCode}&resultMessage={resultMessage}&reserveId={등록 예약 번호} |
네이버 로그인 페이지는 보안 정책에 따라 X-Frame-Options : SAMEORIGIN으로 제공합니다.
따라서 결제 페이지를 해당 iframe 혹은 frame 내에서 호출하면 네이버 로그인 페이지 유도 기능에 문제가 발생할 수 있으니 연동 진행 시 주의해야 합니다.
09 정기/반복결제 등록완료 API
정기/반복결제 등록완료 API
정기/반복결제 최종 등록완료를 요청합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/regist/v1/approvalContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/regist/v1/approval \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \-d reserveId={등록 예약 번호} \-d tempReceiptId={임시 접수 번호} |
reserveId | String | 50바이트 | O | 등록 예약 요청 결과로 받은 등록 예약 번호 |
tempReceiptId | String | 50바이트 | O | 등록 페이지 호출 결과 returnUrl에서 받은 임시 접수 번호 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
reserveId | String | 50바이트 | 등록 예약 요청 결과로 받은 등록 예약 번호 |
tempReceiptId | String | 50바이트 | 등록 페이지 호출 결과 returnUrl에서 받은 임시 접수 번호 |
recurrentId | String | 50바이트 | 정식 정기/반복결제 등록 번호 결제 예약/승인을 요청할 때 이 등록 번호를 사용합니다 |
actionType | String | 30바이트 | 등록 예약 시 가맹점이 전달한 actionType |
preRecurrentId | String | 50바이트 | actionType이 "CHANGE"인 경우 변경되기 전 정기/반복결제 등록 번호 |
userEmail | String | 정기/반복결제 등록한 유저의 이메일 (일부 계약된 가맹점에서만 사용) | |
userIdentifier | String | 28바이트 | 암호화된 사용자 구분값 (해당 필드로 사용자 정보 식별은 불가하며, 일부 계약된 가맹점에서만 사용 가능) |
ResponseHTTP/1.1 200 OK{ "code" : "Success", "message" : "detail message(optional)", "body" : { "reserveId" : "등록 예약 번호", "tempReceiptId" : "임시 접수 번호", "recurrentId" : "정기/반복결제 등록 번호", "actionType" : "CHANGE", "preRecurrentId" : "이전 정기/반복결제 등록 번호" } |
10 결제예약 API
결제예약 API
결제승인 예약을 요청합니다. 이 API를 호출하여 응답으로 받은 토큰을 결제승인요청 API 호출에 사용합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/pay/v1/reserveContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/pay/v1/reserve \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \-d recurrentId={정기/반복결제 등록 번호} \-d totalPayAmount=1000 \-d taxScopeAmount=800 \-d taxExScopeAmount=200 \-d productName={상품명} \-d merchantPayId={가맹점 결제번호 or 주문번호} \-d merchantUserId={가맹점의 사용자 키} \-d useCfmYmdt={이용완료일} \ |
recurrentId | String | 50바이트 | O | 정기/반복결제 등록 번호 |
totalPayAmount | Number | O | 총 결제 금액 | |
taxScopeAmount | Number | O | 과세 대상 금액. 과세 대상 금액 + 면세 대상 금액 = 총 결제 금액 | |
taxExScopeAmount | Number | O | 면세 대상 금액. 과세 대상 금액 + 면세 대상 금액 = 총 결제 금액 | |
productName | String | 512바이트 | O | 상품명 |
merchantPayId | String | 64바이트 | O | 가맹점 주문내역 확인 가능한 가맹점 결제번호 또는 주문번호를 전달해야 합니다 |
merchantUserId | String | 50바이트 | O | 가맹점의 사용자 키(개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다) |
merchantExtraParameter | String | 4000바이트 | 가맹점 자체적으로 추가 구분값으로 활용 가능한 별도의 예비 필드 (개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다) | |
useCfmYmdt | String | 50바이트 | 이용완료일(yyyymmdd) 가맹점 타입이 이용완료일 정산 또는 이용완료일 포인트 적립인 경우 필수 해당 값을 기준으로 이용완료일 정산의 경우 '정산기준일' 또는 이용완료일 포인트 적립인 경우 '포인트적립 기준일'이 지정됩니다. 이용완료일은 반드시 결제일과 같거나 결제일 이후여야 하며, 이용완료일이 결제일자 이전으로 적용될 경우 에러(InvalidUseCfmYmdt)가 발생됩니다. |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidRecurrentId | String | 유효하지 않은 정기/반복결제 등록 번호 |
recurrentId | String | 50바이트 | 정기/반복결제 등록 번호 |
token | String | 50바이트 | 결제 예약 토큰 |
11 결제승인 API
결제승인 API
결제승인을 요청합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/pay/v2/approvalContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/pay/v2/approval \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \-d recurrentId={정기/반복결제 등록 번호} \-d token={결제 예약 토큰} |
recurrentId | String | 50바이트 | O | 정기/반복결제 등록 번호 |
token | String | 50바이트 | O | 결제 승인 예약 시 발급받은 결제 예약 토큰 |
최종 결제 승인이 완료되기까지 시간이 걸리므로 timeout을 60초로 설정해야 합니다.
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidRecurrentId | String | 유효하지 않은 정기/반복결제 등록 번호 |
BankCheckTime | String | 은행 점검 시간(23시 45분~0시 10분) |
UnderAgeAmountLimit | String | 미성년자 월 결제 한도 초과 |
FailUnderAgeAmountLimitValidation | String | 미성년자 한도 확인 실패에 따른 결제 불가 |
PaymentBlocked | String | 사용자 결제 차단 설정에 따른 결제 불가 (일부 계약된 가맹점에서만 사용) |
NotEnoughAccountBalance | String | 충전 중 계좌 잔고 부족 시 |
NotRegisteredAccount | String | 충전 중 미등록 계좌인 경우 |
BankMaintenance | String | 충전 계좌 점검 시 |
AlreadyOnGoing | String | 해당 결제번호로 결제가 이미 진행 중일 때 |
recurrentId | String | 50바이트 | 정기/반복결제 등록 번호 |
token | String | 50바이트 | 결제 예약 토큰 |
paymentId | String | 50바이트 | 네이버페이 결제번호 |
detail | Object | 네이버페이 정기/반복결제승인 결과 상세정보 아래쪽 detail 항목 참조 |
paymentId | String | 50바이트 | 네이버페이 결제번호 |
payHistId | String | 50바이트 | 네이버페이 결제 이력 번호 |
merchantId | String | 50바이트 | 가맹점 아이디 (가맹점센터 로그인 아이디) |
merchantName | String | 50바이트 | 가맹점명 |
merchantPayKey | String | 64바이트 | 가맹점의 결제번호 |
merchantUserKey | String | 50바이트 | 가맹점의 사용자 키 |
admissionTypeCode | String | 2바이트 | 결제승인 유형 01:원결제 승인건, 03:전체취소 건, 04:부분취소 건 |
admissionYmdt | String | 14바이트 | 결제/취소 일시(YYYYMMDDHH24MMSS) |
tradeConfirmYmdt | String | 50바이트 | 거래완료 일시(정산기준날짜, YYYYMMDDHH24MMSS) 비에스크로 가맹점은 결제일/취소일시와 같은 값을 가지고, 에스크로 가맹점은 거래완료 API를 호출하여야 값이 반환됩니다 |
admissionState | String | 10바이트 | 결제/취소 시도에 대한 최종결과 SUCCESS:완료, FAIL:실패 |
totalPayAmount | Number | 총 결제/취소 금액 | |
primaryPayAmount | Number | 주 결제 수단 결제/취소 금액 | |
npointPayAmount | Number | 네이버페이 포인트 결제/취소 금액 | |
primaryPayMeans | String | 10바이트 | 주 결제 수단 CARD:신용카드, BANK:계좌이체 |
cardCorpCode | String | 10바이트 | 주 결제 수단 카드사 지원 카드사 정보를 참고 바랍니다 |
cardNo | String | 50바이트 | 일부 마스킹 된 신용카드 번호 |
cardAuthNo | String | 30바이트 | 카드승인번호 취소 시에는 승인 번호 개념이 없으므로 원결제 승인 건에 대해서만 이 값이 반환됩니다 |
cardInstCount | Number | 할부 개월 수 (일시불은 0) | |
bankCorpCode | String | 10바이트 | 주 결제 수단 은행 지원 은행 정보를 참고 바랍니다 |
bankAccountNo | String | 50바이트 | 일부 마스킹 된 계좌 번호 |
productName | String | 128자 | 상품명 |
settleExpected | Boolean | true/false. 정산 예정 금액과 결제 수수료 금액이 계산되었는지 여부를 나타냅니다 이 값이 false이면 아래 두 필드인 settleExpectAmount,payCommissionAmount 값은 무의미합니다 | |
settleExpectAmount | Number | 정산 예정 금액 결제 후 약 1시간 후에 데이터가 생성되며, 그 전까지는 0값이 반환됩니다 (settleExpeted=true이면 0 값도 의미를 갖습니다) | |
payCommissionAmount | Number | 결제 수수료 금액 결제 후 약 1시간 후에 데이터가 생성되며, 그 전까지는 0값이 반환됩니다 (settleExpeted=true이면 0 값도 의미를 갖습니다) | |
merchantExtraParameter | String | 4000바이트 | 가맹점 자체적으로 추가 구분값으로 활용 가능한 별도의 예비 필드 |
12 정기/반복결제 해제 API
정기/반복결제 해지 API
등록된 정기/반복결제 항목을 해지하여 더이상 결제가 발생하지 않도록 합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/expire/v1/requestContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/expire/v1/request?recurrentId={정기/반복결제 등록 번호} \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \-d recurrentId={정기/반복결제 등록 번호} \-d expireRequester={해지 요청자} \-d expireReason={해지 사유} \ |
recurrentId | String | 50바이트 | O | 해지할 정기/반복결제 등록 번호 |
expireRequester | String | 1바이트 | O | 해지 요청자(1: 구매자, 2: 가맹점 관리자) 구분하기 어려우면 가맹점 관리자로 입력합니다 |
expireReason | String | 256바이트 | O | 해지 사유 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
recurrentId | String | 50바이트 | 해지된 정기/반복결제 등록 번호 |
13 정기/반복결제 등록 상태 조회 API
정기/반복결제 등록 상태 조회 API
정기/반복결제 등록 상태를 조회합니다.
요청
GET //{API 도메인}/{파트너 ID}/naverpay/payments/recurrent/inquiry/v1/infoContent-Type: application/x-www-form-urlencoded |
curl -X GET //dev.apis.naver.com/naverpay-partner/naverpay/payments/recurrent/inquiry/v1/info?recurrentId={정기/반복결제 등록 번호} \-H X-Naver-Client-Id:{client id} \-H X-Naver-Client-Secret:{client secret} \ |
recurrentId | String | 50바이트 | O | 정기/반복결제 등록 번호 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
recurrentId | String | 50바이트 | 정기/반복결제 등록 번호 |
productCode | String | 100바이트 | 상품 코드 |
naverPointUse | String | 10바이트 | 네이버포인트 우선 결제 여부 Y: 네이버포인트를 결제 수단으로 사용함 N: 네이버포인트를 결제 수단으로 사용하지 않음 |
primaryPayMeans | String | 30바이트 | 주 결제 수단(CARD: 신용카드, BANK: 계좌 이체) |
primaryPayMeansCorpCd | String | 10바이트 | 주 결제 수단 카드사/은행 코드 자세한 내용은 지원 카드사 정보, 지원 은행 정보를 참고 바랍니다 |
primaryPayMeansNo | String | 50바이트 | 주 결제 수단 번호. 일부 마스킹된 카드/계좌 번호 |
recurrentState | String | 20바이트 | 정기/반복결제 등록 상태 VALID: 유효한 상태 EXPIRED: 해지된 상태 |
registYmdt | String | 14바이트 | 정기/반복결제를 등록한 날짜(yyyyMMddhhmmss) |
expireYmdt | String | 14바이트 | 정기/반복결제를 해지한 날짜(yyyyMMddhhmmss) |
14 결제취소
결제취소 API
결제취소를 요청합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/v1/cancelContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/v1/cancel \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \-d paymentId={결제 완료 시 전달된 paymentId} \-d cancelAmount={취소금액} \-d cancelReason=testCancel \-d cancelRequester=2 |
paymentId | String | 50바이트 | O | 네이버페이 결제번호 |
merchantPayKey | String | 가맹점의 결제 번호 | ||
cancelAmount | Number | O | 취소 요청 금액 | |
cancelReason | String | 256바이트 | O | 취소 사유 |
cancelRequester | String | 1바이트 | O | 취소 요청자(1: 구매자, 2: 가맹점 관리자) 구분이 애매한 경우 가맹점 관리자로 입력합니다 |
taxScopeAmount | Number | O | 과세 대상 금액. 과세 대상 금액 + 면세 대상 금액 = 총 결제 금액 | |
taxExScopeAmount | Number | O | 면세 대상 금액. 과세 대상 금액 + 면세 대상 금액 = 총 결제 금액 | |
doCompareRest | Number | 가맹점의 남은 금액과 네이버페이의 남은 금액이 일치하는지 체크하는 기능을 수행할지 여부 1: 수행 0: 미수행 | ||
expectedRestAmount | Number | 이번 취소가 수행되고 난 후에 남을 가맹점의 예상 금액 옵션 파라미터인 doCompareRest값이 1일 때에만 동작합니다 Ex) 결제금액 1000원 중 200원을 취소하고 싶을 때 => expectedRestAmount =800원, cancelAmount=200원으로 요청 |
주의
취소가 완료되기까지 시간이 걸리므로, Timeout 시간을 최소 60초로 설정해야 합니다
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidPaymentId | String | 유효하지 않은 네이버페이 결제번호 |
AlreadyCanceled | String | 이미 전체 취소된 결제 |
OverRemainAmount | String | 취소 요청 금액이 잔여 결제 금액을 초과 |
PreCancelNotComplete | String | 이전에 요청한 취소가 완료되지 않은 상태 이전에 요청했던 취소 정보로 재시도 요청해야 이전 취소가 완료되고 다음 취소를 수행할 수 있습니다 |
TaxScopeAmtGreaterThanRemainError | String | 취소 가능한 과면세 금액보다 큰 금액 요청 |
TaxScopeAmountError | String | 과/면세금액의 합이 취소 요청 금액과 다른 상태 과세 대상 금액 + 면세 대상 금액 = 취소 요청 금액 |
RestAmountDiff | String | 가맹점의 예상 잔여금액(expectedRestAmount)과 네이버페이의 잔여금액이 일치하지 않음 |
CancelNotComplete | String | 취소처리가 완료되지 않아, 반드시 취소 재시도가 필요 |
AlreadyOnGoing | String | 해당 결제번호로 요청이 이미 진행 중인 경우 |
paymentId | String | 50바이트 | 네이버페이 결제번호 |
payHistId | String | 50바이트 | 취소 결제 번호 |
primaryPayMeans | String | 10바이트 | 취소 처리된 주 결제 수단(CARD: 신용카드, BANK: 계좌 이체) |
primaryPayCancelAmount | Number | 주 결제 수단 취소 금액 | |
primaryPayRestAmount | Number | 추가로 취소 가능한 주 결제 수단 잔여 결제 금액 | |
npointCancelAmount | Number | 네이버페이 포인트 취소 금액 | |
npointRestAmount | Number | 추가로 취소 가능한 네이버페이 포인트 잔여 결제 금액 | |
cancelYmdt | String | 14바이트 | 취소 일시(YYYYMMDDHH24MMSS) |
totalRestAmount | Number | 추가로 취소 가능한 전체 잔여 결제 금액(primaryPayRestAmount + npointRestAmount) |
15 거래완료
거래완료 API
구매자가 결제를 완료하고 배송이 완료된 상태에서 가맹점과 구매자 간의 주문을 최종적으로 완료합니다.
여러 상품을 한 번에 주문한 경우 모든 상품의 주문이 완료되었을 때 호출해야 합니다.
실물 배송 상품을 일부라도 취급하는 가맹점은 모든 결제 건에 구매 안전 서비스를 적용해야 합니다.
에스크로 타입 가맹점인 경우에 사용합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/v1/purchase-confirmContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/v1/purchase-confirm \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \-d paymentId={네이버페이가 발급한 결제 번호} \-d requester=2 |
paymentId | String | 50바이트 | O | 네이버페이 결제번호 |
requester | String | 20바이트 | O | 요청자(1: 구매자, 2: 가맹점 관리자) 구분이 애매한 경우 가맹점 관리자로 입력합니다 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidPaymentId | String | 유효하지 않은 네이버페이 결제번호 |
NotSupportedMerchant | String | 해당 API 를 사용할 수 없는 가맹점인 경우 |
PreCancelNotComplete | String | 취소가 정상적으로 완료되지 않아 구매 확정 불가 다시 취소 시도해야 합니다 |
AlreadyOnGoing | String | 해당 결제번호로 요청이 이미 진행 중인 경우 |
AlreadyConfirm | String | 이미 구매확정된 결제번호 |
paymentId | String | 50바이트 | 구매 확정 대상 네이버페이 결제번호 |
confirmTime | String | 14바이트 | 구매 확정 일시(YYYYMMDDHH24MMSS) |
16 결제내역조회
결제내역조회 API
결제내역을 조회합니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/v2/list/historyContent-Type: application/json |
1. 결제건별 조회 예제curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/v2/list/history \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \-H Content-Type: application/json \--data @param.json [File : param.json]{ "paymentId":"20151119NP1000007910"} 2. 기간별 조회 예제curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/v2/list/history \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \-H Content-Type: application/json \--data @param.json [File : param.json]{ "startTime":"20170101000000", "endTime":"20170107235959"} |
paymentId | String | 50바이트 | 조회하고자 하는 네이버페이 결제번호 결제번호를 입력값으로 선택하면 startTime, endTime, pageNumber, rowsPerPage 파라미터 값은 무시됩니다 | |
startTime | String | 14바이트 | 검색 시작 일시(YYYYMMDDHH24MMSS) 검색 기간(startTime과 endTime 사이의 시간)은 31일 이내여야 합니다 | |
endTime | String | 14바이트 | 검색 종료 일시(YYYYMMDDHH24MMSS) 검색 기간(startTime과 endTime 사이의 시간)은 31일 이내여야 합니다 | |
approvalType | String | 20바이트 | ALL:전체, APPROVAL:승인, CANCEL:취소 | |
pageNumber | Number | 조회하고자 하는 페이지번호 값이 없으면 1로 간주합니다 | ||
rowsPerPage | Number | 페이지 당 row 건수 1~100까지 지정 가능하며, 값이 없으면 20으로 간주합니다 | ||
collectChainGroup | Number | 1: 해당 그룹에 속한 모든 가맹점의 결제내역을 조회 할 수 있습니다 일반 개별 가맹점에서는 사용 할 수 없고, 그룹형 마스터 가맹점만 사용 가능한 옵션입니다 |
paymentId만 파라미터로 사용하여 결제 내역을 조회할 수 있습니다
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
RequireCondition | String | 입력값이 조건을 만족하지 않습니다. paymentId 혹은 검색 시간 조건이 필요합니다 |
TimeConditionError | String | 검색 기간 오류(31일 이내) |
list | Object[] | 결제 내역 배열. 자세한 내용은 "표 3 결제 내역"을 참고 바랍니다 | |
totalCount | Number | 조회조건에 대한 전체건수 | |
responseCount | Number | 현재 페이지에 대한 응답건수 | |
totalPageCount | Number | 전체 페이지 개수 | |
currentPageNumber | Number | 응답 된 현재 페이지 번호 |
paymentId | String | 50바이트 | 네이버페이 결제번호 |
payHistId | String | 50바이트 | 네이버페이 결제 이력 번호 |
merchantId | String | 50바이트 | 가맹점 아이디 (가맹점센터 로그인 아이디) |
merchantName | String | 50바이트 | 가맹점명 |
merchantPayKey | String | 64바이트 | 가맹점의 결제번호 |
merchantUserKey | String | 50바이트 | 가맹점의 사용자 키 |
admissionTypeCode | String | 2바이트 | 결제승인 유형 01:원결제 승인건, 03:전체취소 건, 04:부분취소 건 |
admissionYmdt | String | 14바이트 | 결제/취소 일시(YYYYMMDDHH24MMSS) |
tradeConfirmYmdt | String | 50바이트 | 거래완료 일시(정산기준날짜, YYYYMMDDHH24MMSS) 비에스크로 가맹점은 결제일/취소일시와 같은 값을 가지고, 에스크로 가맹점은 거래완료 API를 호출하여야 값이 반환됩니다 |
admissionState | String | 10바이트 | 결제/취소 시도에 대한 최종결과 SUCCESS:완료, FAIL:실패 |
totalPayAmount | Number | 총 결제/취소 금액 | |
primaryPayAmount | Number | 주 결제 수단 결제/취소 금액 | |
npointPayAmount | Number | 네이버페이 포인트 결제/취소 금액 | |
primaryPayMeans | String | 10바이트 | 주 결제 수단 CARD:신용카드, BANK:계좌이체, 수단정보가 없고 npointPayAmount값이 있으면 충전결제 |
cardCorpCode | String | 10바이트 | 주 결제 수단 카드사 지원 카드사 정보를 참고 바랍니다 |
cardNo | String | 50바이트 | 일부 마스킹 된 신용카드 번호 |
cardAuthNo | String | 30바이트 | 카드승인번호 취소 시에는 승인 번호 개념이 없으므로 원결제 승인 건에 대해서만 이 값이 반환됩니다 |
cardInstCount | Number | 할부 개월 수 (일시불은 0) | |
bankCorpCode | String | 10바이트 | 주 결제 수단 은행 지원 은행 정보를 참고 바랍니다 |
bankAccountNo | String | 50바이트 | 일부 마스킹 된 계좌 번호 |
productName | String | 128자 | 상품명 |
merchantExtraParameter | String | 4000바이트 | 가맹점 자체적으로 추가 구분값으로 활용 가능한 별도의 예비 필드 |
settleInfo | Object | 정산 데이터 그룹. 자세한 내용은 "표 4 정산 데이터"을 참고 바랍니다 |
settleCreated | Boolean | 정산 데이터 생성 여부 (true/false) 결제 후 약 1시간 후에 생성되며, 이 값이 false이면 아래 4개 필드의 값은 무의미하다. | |
primarySettleAmount | Number | 주결제수단 정산 입금금액 | |
primaryCommissionAmount | Number | 주결제수단 정산 수수료 금액 | |
npointSettleAmount | Number | 네이버페이 포인트 정산 입금금액 | |
npointCommissionAmount | Number | 네이버페이 정산 수수료 금액 |
ResponseHTTP/1.1 200 OK{ "code" : "Success", "message": "detail message(optional)", "body": { "responseCount": 1, "totalCount": 1, "totalPageCount": 1, "currentPageNumber": 1, "list": [ { "cardAuthNo": "00000000", "bankAccountNo": "", "bankCorpCode": "", "paymentId": "20170000NP1000229665", "cardCorpCode": "C0", "cardInstCount": 0, "settleInfo": { "primaryCommissionAmount": 30, "npointCommissionAmount": 20, "primarySettleAmount": 470, "npointSettleAmount": 480, "totalSettleAmount": 850, "totalCommissionAmount": 50, "settleCreated": true }, "merchantName": "나의가맹점", "productName": "나의상품", "payHistId": "20170000NP1000229668", "merchantId": "MID12345", "admissionYmdt": "20170914163930", "tradeConfirmYmdt": "20170915163956", "totalPayAmount": 1000, "merchantPayKey": "orderKey-91516397", "merchantUserKey": "ID12345", "admissionTypeCode": "01", "primaryPayMeans": "CARD", "admissionState": "SUCCESS", "primaryPayAmount": 500, "npointPayAmount": 500, "cardNo": "123456**********" } ] } } |
17 현금영수증발행대상 금액조회
현금영수증 발행대상 금액조회 API
현금영수증 발행대상 금액을 조회합니다. 취소가 발생하면 남은 결제금액 중 현금영수증 발행대상 금액 정보를 제공합니다.
요청
GET //{API 도메인}/{파트너 ID}/naverpay/payments/v1/receipt/cash-amountContent-Type: application/x-www-form-urlencoded |
curl -X GET //dev.apis.naver.com/naverpay-partner/naverpay/payments/v1/receipt/cash-amount?paymentId={네이버페이가 발급한 결제 번호} \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \ |
GET //{API 도메인}/{파트너 ID}/naverpay/payments/v1/receipt/npoint-cash-amount는 더 이상 사용하지 않습니다.(deprecated).
파라미터paymentId | String | 50바이트 | O | 네이버페이 결제번호 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidPaymentId | String | 유효하지 않은 네이버페이 결제번호 |
npointCashAmount | Number | 네이버페이 포인트 결제 금액 중 현금 영수증 발행 대상 금액 |
giftCardCashAmount | Number | 기프트카드 결제 금액 중 현금 영수증 발행 대상 금액 |
primaryCashAmount | Number | 현금성 주 결제 수단 결제 금액 중 현금 영수증 발행 대상 금액 |
envDepositCashAmount | Number | 현금성 결제 금액 중 컵 보증금, 현금 영수증 발행 제외 대상 금액 |
primaryPayMeans | String | 결제에 사용된 현금성 주 결제 수단 정보(BANK: 계좌이체, 수단정보가 없고 npointCashAmount값이 있으면 충전결제) |
totalCashAmount | Number | 현금 영수증 발행 대상 총 금액 npointCashAmount + giftCardCashAmount + primaryCashAmount - envDepositCashAmount |
supplyCashAmount | Number | 현금성 총 공급가 네이버페이 포인트 현금성 공급가 + 기프트카드 현금성 공급가 + 현금성 주 결제 수단(계좌 간편 결제) 공급가 - 컵 보증금 금액 |
vatCashAmount | Number | 현금성 총 부가세 현금성 네이버페이 포인트 부가세 + 현금성 기프트카드 부가세 + 현금성 주 결제 수단(계좌 간편 결제) 부가세 |
18 네이버페이 포인트 적립 요청
네이버페이 포인트 적립 요청 API
네이버페이 포인트 적립을 요청합니다.
비에스크로 타입 가맹점 중 수동 적립 방식을 선택한 경우에 사용합니다.
가맹점 타입과 네이버페이 포인트 적립 시점에스크로 | 거래 완료 시 적립 | 거래 완료 API 호출 시 적립 됩니다. |
비에스크로 | 자동 적립 | 결제 완료 후(*거래 완료 아님) 15일 후(협의에 따라 30일 후)에 자동 적립 됩니다. |
수동 적립 | 상기 네이버페이 포인트 적립 요청 API 호출 시 적립 됩니다. |
이 절에서 설명하는 API는 수동 적립 방식을 선택한 경우 사용하는 API입니다.
에스크로 타입 가맹점은 거래 완료 API 호출 시 네이버페이 포인트가 적립됩니다.
요청
POST //{API 도메인}/{파트너 ID}/naverpay/payments/v1/naverpoint-saveContent-Type: application/x-www-form-urlencoded |
curl -X POST //dev.apis.naver.com/naverpay-partner/naverpay/payments/v1/naverpoint-save \-H X-Naver-Client-Id:{발급된 client id} \-H X-Naver-Client-Secret:{발급된 client secret} \-d paymentId={네이버페이가 발급한 결제 번호} \ |
paymentId | String | 50바이트 | O | 네이버페이 결제번호 |
응답
결과코드Success | String | 성공 |
InvalidMerchant | String | 유효하지 않은 가맹점 |
InvalidPaymentId | String | 유효하지 않은 네이버페이 결제번호 |
InvalidMerchantType | String | 이 API를 사용할 수 없는 가맹점 |
AlreadyOnGoing | String | 해당 결제번호로 요청이 이미 진행 중인 경우 |
paymentId | String | 50 바이트 | 네이버페이포인트 적립 완료 된 네이버페이 결제번호 |
맨위로