Skip to content

nicepayments/nicepay-manual

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

179 Commits
api
api
 
 
common
common
 
 
image
image
 
 
management
management
 
 
migration
migration
 
 
README.md
README.md
 
 

Repository files navigation

🚀 NicePay For Startups 개발자 가이드


공통

개발 전 필요한 공통적인 가이드 입니다.
개발 준비 | API·JS SDK | TEST·샘플코드 | 코드집 | 더 알아보기

👉 개발언어를 클릭하면 소스코드를 확인할수 있습니다.

문서

API 명세와 코드가 포함된 기술문서 입니다.
결제·발급 | 조회 | 거래·정산·대사 | 취소·환불·망취소 | 웹훅 | APP | 더 알아보기

운영

운영에 필요한 정보 입니다.
지원환경 | 오류관리 | 개발정보 | 더 알아보기



⚡ Quick guide

시작하기

빠른 개발을 위한 ⚡ Quick guide 입니다.
가이드에 따라 순서대로 진행하면 ⏱️ 10분 정도의 시간으로 TEST개발이 가능 합니다.


📝 사전 준비 사항

⚠️ 중요

IP 제약이 있는 네트워크 환경에서 Test를 진행하는 경우 API호출을 위해 방화벽 작업이 필요할 수 있습니다.
👉 방화벽 정책 확인하기


Over-view

설명

  • 결제자가 브라우저에서 JS SDK의 Method인 AUTHNICE.requestPay() 를 통해 💡 결제창을 호출합니다.
  • 이후 결제자는 💡 결제창에서 카드사 및 결제 원천사로 접근해 인증을 진행합니다.
  • 나이스페이는 결제자의 인증결과를 AUTHNICE.requestPay()의 object value로 전달된 returnUrl로 POST 합니다.
  • 가맹점은 POST 데이터의 위변조 여부를 체크하고, 응답된 tid를 승인 API로 전달하면 💳 결제(승인)요청이 완료됩니다.

샌드박스를 통한 TEST 개발 예시

  • Server 승인 / Basic 인증 기준으로 결제창 TEST 개발흐름 예시를 설명 합니다.

JS Include

  • clientId는 가맹점관리자 TEST상점에서 발급한 클라이언트키를 사용 합니다.
  • 테스트상점(샌드박스)에서 clientId를 발급하면 즉시 TEST가 가능합니다.
javascript
<script src="https://pay.nicepay.co.kr/v1/js/"></script> <!-- 나이스페이 결제창 JS SDK -->

<script>
function serverAuth() {
  AUTHNICE.requestPay({
    clientId: 'S2_af4543a0be4d49a98122e01ec2059a56',
    method: 'card',
    orderId: '유니크한-주문번호',
    amount: 1004,
    goodsName: '나이스페이-상품',
    returnUrl: 'http://localhost:3000/serverAuth', //API를 호출할 Endpoint 입력
    fnError: function (result) {
      alert('개발자확인용 : ' + result.errorMsg + '')
    }
  });
}
</script>
  
<button onclick="serverAuth()">serverAuth 결제하기</button>

⚠️ 중요

샌드박스를 통한 TEST가 완료되어 운영계 반영이 필요한 경우 아래 2가지 사항을 주의해주세요.

  1. JS SDK, API 도메인을 운영계 도메인으로 변경 합니다.
  2. clientId, secretKey를 운영계로 변경 합니다.

결제창 응답

  • 카드사 인증을 성공하면 authResultCode가 0000으로 응답 됩니다.
Accept: application/x-www-form-urlencoded
{
  authResultCode: '0000',
  authResultMsg: '인증 성공',
  tid: 'UT0000113m01012111051714341073',
  clientId: 'S2_af4543a0be4d49a98122e01ec2059a56',
  orderId: 'c74a5960-830b-4cd8-82a9-fa1ce739a18f',
  amount: '1004',
  mallReserved: '',
  authToken: 'NICEUNTTB06096FF8F653AA366E7EEED1101AAAE',
  signature: '99ea68bf15681741e793ece56ab87891b9bdc94cd54abdcb55b2884f4336155a'
}

authResultCode가 0000 으로 응답된 경우 결제창을 통한 인증과정이 성공된 것을 의미합니다.
인증과정이 성공한 경우 tid(거래key)값을 승인(결제) API로 전달하여 💳 결제(승인)을 요청 할 수 있습니다.


결제(승인) API 호출

curl -X POST 'https://sandbox-api.nicepay.co.kr/v1/payments/UT0000113m01012111051714341073'
-H 'Content-Type: application/json' 
-H 'Authorization: Basic UzJfYWY0NTQzYTBiZTRkNDlhOTgxMjJlMDFlYzIwNTlhNTY6OWViODU2MDcxMDM2NDZkYTlmOWMwMmIxMjhmMmU1ZWU=' 
-D '{
  "amount" : 1004
}'

⚠️ 중요

샌드박스를 통한 TEST가 완료되면 운영계 도메인으로 변경 해주세요.
운영계 ex) api.nicepay.co.kr/v1/payments/UT0000113m01012111051714341073


Authorization basic credentials 알고리즘

Base64(`client-key`:`secret-key`)

API 호출을 위해 Authorization basic credentials 생성은 클라이언트키 + : + 시크릿키 문자열을 Base64 인코딩하여 생성 합니다.

clientKey = 'S2_af4543a0be4d49a98122e01ec2059a56'
secretKey = '9eb85607103646da9f9c02b128f2e5ee'
>> `S2_af4543a0be4d49a98122e01ec2059a56:9eb85607103646da9f9c02b128f2e5ee`

Base64('S2_af4543a0be4d49a98122e01ec2059a56:9eb85607103646da9f9c02b128f2e5ee')
>> `UzJfYWY0NTQzYTBiZTRkNDlhOTgxMjJlMDFlYzIwNTlhNTY6OWViODU2MDcxMDM2NDZkYTlmOWMwMmIxMjhmMmU1ZWU=`

예시처럼 최종 생성된 credentials을 API 호출 시 활용 합니다.

결제(승인) 응답 예시

Content-type: application/json
{
  resultCode: '0000',
  resultMsg: '정상 처리되었습니다.',
  tid: 'UT0000113m01012111051714341073',
  cancelledTid: null,
  orderId: 'c74a5960-830b-4cd8-82a9-fa1ce739a18f',
  ediDate: '2021-11-05T17:14:35.150+0900',
  signature: '63b251b31c909eebef1a9f4fcc19e77bdcb8f64fc1066a29670f8627186865cd',
  status: 'paid',
  paidAt: '2021-11-05T17:14:35.000+0900',
  failedAt: '0',
  cancelledAt: '0',
  payMethod: 'card',
  amount: 1004,
  balanceAmt: 1004,
  goodsName: '나이스페이-상품',
  mallReserved: null,
  useEscrow: false,
  currency: 'KRW',
  channel: 'pc',
  approveNo: '000000',
  buyerName: null,
  buyerTel: null,
  buyerEmail: null,
  receiptUrl: 'https://npg.nicepay.co.kr/issue/IssueLoader.do?type=0&innerWin=Y&TID=UT0000113m01012111051714341073',
  mallUserId: null,
  issuedCashReceipt: false,
  coupon: null,
  card: {
    // 샌드박스 응답결과는 모두 임의값입니다. resultCode가 0000 이면 응답 TEST 성공입니다.
    cardCode: '04',
    cardName: '삼성', // (샌드박스) 응답 결과는 삼성카드로 고정
    cardNum: '123412******1234',
    cardQuota: 0,
    isInterestFree: false,
    cardType: 'credit',
    canPartCancel: true,
    acquCardCode: '04',
    acquCardName: '삼성'
  },
  vbank: null,
  cancels: null,
  cashReceipts: null
}

⚠️ 중요

샌드박스를 통해 TEST를 진행하는 경우 승인(결제)가 발생되지 않아 편리하게 TEST를 할수 있습니다. 또한 실제 승인(결제)가 발생되지 않기 때문에 임의 값이 응답됩니다.


샘플코드

아이콘을 클릭하면 언어별 샘플코드를 확인 할 수 있습니다.


더 알아보기

결제 개발을 위해 더 상세한 정보가 필요하다면📌 공통 탭의 정보를 활용하고,
API 개발을 위한 각 인터페이스의 개발 명세가 필요하다면 📚 문서 탭의 자료를 확인 해주세요.
개발이 완료되어 운영에 필요한 정보와 Tip은 ☸️ 운영 탭의 정보를 통해 확인이 가능 합니다.

📌 공통

개발 전 필요한 공통적인 가이드 입니다.

📚 문서

API 명세와 코드가 포함된 기술문서 입니다.

☸️ 운영

운영에 필요한 정보 입니다.

About

나이스페이먼츠 결제연동 매뉴얼

Resources

Readme
Activity

Stars

39 stars

Watchers

3 watching

Forks

15 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •