real 2transaction - nicepayments/nicepay-manual GitHub Wiki

가맹점 입장에서는 고객의 결제를 처리하기 위해 두 단계의 트랜잭션을 거쳐야 합니다.

첫째, 고객의 결제 수단이 유효한지 확인하는 '인증' 단계, 그리고 둘째, 실제 금액을 이체하는 '승인' 단계로 구성됩니다.

이 두 단계를 성공적으로 거치면 고객의 결제가 완료되며, 가맹점은 판매된 상품에 대한 금액을 받게 됩니다.

이를 2 Transaction 결제 방식이라 정의합니다.

sequenceDiagram
    actor Customer as 고객
    participant Merchant as 가맹점 서버
    participant PayWindow as NICEPAY 결제창
    participant NICEPAY as NICEPAY 서버
    participant CardCo as 카드사/은행

    Customer->>Merchant: 1. 상품 구매 요청
    Merchant->>PayWindow: 2. NICEPAY 결제 페이지 호출<br/>(AUTHNICE.requestPay 호출)
    PayWindow->>Customer: 3. 결제 페이지 제공

    Note over Customer,PayWindow: 결제창 호출 파라미터<br/>clientId: R2_xxx (운영) or S2_xxx (샌드박스)<br/>orderId, amount, goodsName, returnUrl

    PayWindow->>Customer: 4. 결제창 오픈
    Customer->>PayWindow: 5. 결제 정보 입력<br/>(카드번호, 유효기간 등)

    rect rgb(255, 250, 240)
        Note over PayWindow,CardCo: 🔐 Step 1: 인증 (Authentication)
        PayWindow->>NICEPAY: 6. 인증 요청
        NICEPAY->>CardCo: 7. 결제수단 유효성 확인
        CardCo-->>NICEPAY: 8. 인증 결과
    end

    alt 인증 성공 (authResultCode: 0000)
        NICEPAY->>Merchant: 9. returnUrl로 인증 결과 전달<br/>(tid, authToken, signature)

        Note over Merchant: signature 검증<br/>hex(sha256(authToken+clientId+amount+secretKey))

        Merchant->>Merchant: 10. 주문 검증 및 재고 확인

        rect rgb(240, 255, 240)
            Note over Merchant,CardCo: 💳 Step 2: 승인 (Authorization)
            Merchant->>NICEPAY: 11. 승인 API 호출<br/>POST /v1/payments/{tid}<br/>Header: Authorization Basic base64(clientId:secretKey)<br/>Body: {"amount": 1004}

            NICEPAY->>CardCo: 12. 승인 요청 (실제 결제 청구)
            CardCo-->>NICEPAY: 13. 승인 결과

            NICEPAY-->>Merchant: 14. 승인 응답<br/>(tid, orderId, status: paid, approveNo)
        end

        Merchant->>Merchant: 15. signature 검증 및 DB 저장<br/>hex(sha256(tid+amount+ediDate+secretKey))
        Merchant->>Customer: 16. 결제 완료 페이지

    else 인증 실패
        NICEPAY->>Merchant: 9. returnUrl로 실패 결과
        Merchant->>Customer: 결제 실패 안내
    end

    Note over Merchant,NICEPAY: ✅ 구간별 제어 가능<br/>✅ 에러 처리 유연<br/>✅ 추가 검증 가능

목적: 결제수단의 유효성만 확인 (실제 결제 X)

인증 응답 데이터:

authResultCode: 0000
authResultMsg: 인증 성공
tid: ORD20231215XXXXXXXXXX (30자)
authToken: NICEUNTxxxxxxxxxxxxxx (40자)
signature: hex(sha256(authToken + clientId + amount + secretKey))

주요 포인트:

• ⚠️ 인증 단계에서는 실제 결제 발생 안 함
• 샌드박스: tid로 승인 시 샘플 데이터 반환
• 운영: tid로 승인 시 실제 카드 청구

목적: 실제 결제 금액 청구

승인 요청:

curl -X POST 'https://api.nicepay.co.kr/v1/payments/{tid}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic {base64(clientId:secretKey)}' \
  -d '{"amount": 1004}'

승인 응답:

{
  "resultCode": "0000",
  "tid": "ORD20231215XXXXXXXXXX",
  "status": "paid",
  "approveNo": "12345678",
  "paidAt": "2023-12-15T14:30:00+09:00"
}

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

• 2 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: 'R2_xxx',                             // (2) 가맹점 운영 환경 2Transaction(Server 승인 & 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: 'R2_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

• 2 Transaction 인증 응답 명세서

인증 요청이 정상적인 처리가 되었다면 인증 요청시 returnUrl 필드에 기입한 URL로 인증에 대한 응답 결과를 받을 수 있습니다.

MIME 유형: application/x-www-form-urlencoded
authResultCode: 0000                                                    // (1)
authResultMsg: 인증 성공
tid: {{인증 성공에 대한 TID 30자}}                                      // (2)
clientId: {{R2_xxx server 승인 & basic 인증}}
orderId: {{가맹점 고유 주문번호}}
amount: 1004
authToken: {{NICEUNTxxx 40자}}
signature: {{hex(sha256(authToken + clientId + amount + secretKey}}     // (3)

• (1): authResultCode: 0000
  • 인증 결과 코드
  • 성공 시 "0000"을 반환합니다.
• (2): tid: {{인증 성공에 대한 TID 30자}}
  • 인증 성공 시 승인 요청을 위한 트랜잭션 ID
  • 거래 요청 및 취소, 거래조회 등으로 사용가능한 ID 입니다.
• (3): signature: {{hex(sha256(authToken + clientId + amount + secretKey}}
  • 응답의 무결성을 검증하기 위한 서명 값
  • 인증 응답에 대해 가맹점은 데이터 유효성 검증 가능

인증 응답 시점에서 결제가 발생하지 않습니다.
샌드박스 환경에서는 발급된 TID로 승인 요청 시, 승인응답 샘플 데이터를 반환합니다.
운영 서비스 환경에서는 발급된 TID로 승인 요청 시, 카드사에 인증된 결제를 고객에게 결제금액을 청구하도록 요청하여 결제가 완료됩니다.

• 2 Transaction 승인 요청 명세서

승인 요청 curl

curl -request POST 
--url 'https://api.nicepay.co.kr/v1/payments/{tid}' \                  # (1)
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {base64(clientId:secretKey)}' \         # (2)
--data '{
  "amount": 1004                                                       # (3)
}'

• (1): --url 'https://api.nicepay.co.kr/v1/payments/{tid}'
  • 승인요청 API 호출
  • 인증 응답 결과로 받은 TID를 사용하여 결제 요청
• (2): --header 'Authorization: Basic {base64(clientId:secretKey)}'
  • 승인 요청 시 특정 가맹점의 인가 처리
  • Server 승인 & basic 인증으로 발급 받은 키 정보로 base64 인코딩
• (3): "amount": 1004
  • 결제 금액
  • 승인 요청을 위한 필수 값

Terminal에서 base64 인코딩하기

echo -n 'clientId:secretKey' | base64

Windows PowerShell을 이용한 인코딩

powershell "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('clientId:secretKey'))"

• 2 Transaction 승인 응답

승인 응답에 대한 설명

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

가맹점은 실시간으로 응답 받아볼 수도 있고, 동시에 결제수단에 대한 웹훅 URL을 등록하였을 경우, 웹훅을 통해 결제통보를 서버로 전달받을 수 있습니다.

웹훅을 통해 결제통보를 받는 경우, 별도의 응답이 해당 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"
}