real 1transaction - nicepayments/nicepay-manual GitHub Wiki

1 Transaction 결제 방식은 나이스페이먼츠에서 '인증' 과 '승인' 단계를 모두 처리하는 서비스입니다.

이는 2 Transaction 방식에서 가맹점이 따로 처리해야 하는 두 단계를 하나로 합쳐, 결제 프로세스를 단순화합니다.

가맹점은 인증 요청 시 승인까지 처리된 후에 승인 응답을 받게 되므로, 복잡한 구현 없이 빠른 결제 처리가 가능합니다.

하지만, 이 방식을 선택할 때는 몇 가지 중요한 고려사항이 있습니다.

중요한 고려사항

• 가맹점의 네트워크 상태

  • 가맹점의 트래픽이 증가하여 네트워크 상태가 불안정한 경우, 나이스페이먼츠로부터의 응답을 받지 못할 가능성이 있습니다.
  • 이를 방지하기 위해 추가적인 검증 및 확인 절차가 필요할 수 있습니다.

• 웹훅의 필수성

  • 웹훅은 1 Transaction 방식에서 중요한 역할을 합니다.
  • 웹훅을 통해 나이스페이먼츠로부터의 응답을 안정적으로 받을 수 있으며, 데이터의 일관성도 확보합니다.

• 결제 검증의 필수성

  • 1 Transaction 방식에서도 결제 검증은 필수입니다.
  • 나이스페이먼츠가 모든 과정을 처리하더라도, 가맹점에서의 추가적인 검증 절차를 통해 결제의 안전성을 더욱 강화할 수 있습니다.

1 Transaction 방식은 이러한 측면들이 적절히 처리될 때 가장 효과를 발휘합니다.

올바르게 구현되면, 이 방식은 가맹점이 빠르고 효율적인 결제 처리를 진행할 수 있습니다.

가맹점 테스트 상점의 Client 승인 & basic 인증으로 발급 받은 clientId 및 secretKey로 아래 연동을 진행합니다.

• 1 Transaction 인증 요청 명세서

결제창 JS SDK 삽입

<script src="https://pay.nicepay.co.kr/v1/js/"></script> // (1)

• (1): https://pay.nicepay.co.kr/v1/js/
  • 가맹점이 결제창을 일관되고 효율적으로 사용할 수 있도록 정의한 JS SDK

결제창 JS 호출 코드

<script src="https://pay.nicepay.co.kr/v1/js/"></script>
<script>
    function serverAuth() {
        AUTHNICE.requestPay({                               // (1) 나이스페이먼츠 결제창 호출 함수
            clientId: 'R1_xxx',                             // (2) 가맹점 운영환경 1Transaction(Client 승인 & basic 인증)
            method: 'card',                                 // (3) 고객 결제 수단
            orderId: 'your-unique-orderid',                 // (4) 가맹점 고유 주문정보
            amount: 1004,                                   // (5) 가맹점 상품 금액
            goodsName: '나이스페이-상품',                   // (6) 가맹점 상품 명
            returnUrl: 'http://localhost:4567/serverAuth'   // (7) 가맹점 인증 결과 응답받을 URL
        });
    }
</script>

• (1): AUTHNICE.requestPay
  • 나이스페이먼츠 결제창 호출 함수
• (2): clientId: 'R1_xxx'
  • 가맹점 테스트 상점의 key 정보에서 발급 받은 clientId
• (3): method: 'card'
  • 고객이 선택한 결제 수단
  • 운영환경에서 제공하는 인증 결제창 결제수단
• (4): orderId: 'your-unique-orderid'
  • 가맹점 고유 주문정보
  • 나이스페이먼츠에서 가맹점이 요청한 결제 요청이 중복처리가 되지 않도록 검증
• (5): amount: 1004
  • 결제 금액
  • 가맹점에서 판매하는 상품 금액
• (6): returnUrl: 'http://localhost:4567/serverAuth'
  • 가맹점에서 인증에 대한 응답 결과를 반환 받을 URL
  • 2 Transaction 인증 응답 명세서

인증 요청에 대한 F&Q

• 1 Transaction 승인 응답

승인 응답에 대한 설명

승인 응답은 결제 과정 중에서 고객의 카드사에 의해 특정 금액의 결제가 허가되었음을 나타내는 메시지입니다.

가맹점은 실시간(인증 요청 시의 returnUrl)으로 결과를 확인 할 수도 있고, 동시에 결제수단에 대한 웹훅 URL을 등록하였을 경우, 웹훅을 통해 결제통보를 서버로 전달받을 수 있습니다.

웹훅을 통해 결제통보를 받는 경우 가맹점은 결제결과에 대한 추가적인 검증을 진행할 수 있습니다.

운영 승인 응답 데이터

{
  "resultCode": "0000",
  "resultMsg": "정상 처리되었습니다.",
  "tid": "{{tid}}",
  "cancelledTid": null,
  "orderId": "{{unique_orderId}",
  "ediDate": "2023-08-14T17:07:28.021+0900",
  "signature": "{{hex(sha256(tid + amount + ediDate+ SecretKey))}}",
  "status": "paid",
  "paidAt": "2023-08-14T17:07:27.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={{tid}}",
  "mallUserId": null,
  "issuedCashReceipt": false,
  "coupon": null,
  "card": {
    "cardCode": "{{카드사코드}}",
    "cardName": "{{카드사}}",
    "cardNum": "{{신용카드 번호}}", // PCI-DSS 앞 6자리, 뒤 4자리 외 마스킹 처리
    "cardQuota": 0,
    "isInterestFree": false,
    "cardType": "credit",
    "canPartCancel": true,
    "acquCardCode": "{{매입사 코드}}",
    "acquCardName": "{{매입사 명}}"
  },
  "vbank": null,
  "bank": null,
  "cellphone": null,
  "cancels": null,
  "cashReceipts": null,
  "messageSource": "nicepay"
}