Giters

SeokRae / nicepay-manual

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

🚀 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

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