@portone/mcp-server 0.13.0

package/assets/docs/opi/ko/integration/cancel/v2/readme.md

@@ -0,0 +1,378 @@
+---
+title: 결제취소(환불) 연동하기
+description: 포트원 V2 결제취소 API를 이용한 결제취소 방법을 안내합니다.
+targetVersions:
+  - v2
+versionVariants:
+  v1: /opi/ko/integration/cancel/v1/basic
+---
+
+## 결제 취소 정책
+
+<div class="hint" data-style="warning">
+
+**중요: 결제와 취소는 반드시 포트원 대시보드나 API를 통해서만 진행하세요**
+
+PG사를 통해 직접 취소할 경우 포트원과 결제 상태가 동기화되지 않아
+데이터 불일치 문제가 발생할 수 있습니다.
+
+</div>
+
+### 가상계좌 환불
+
+<div class="hint" data-style="warning">
+
+**가상계좌 환불을 위해서는 PG사 가상계좌 특약서비스에 가입되어 있어야 합니다.**
+
+신용카드와는 달리 가상계좌의 경우 결제/환불에 대한 수수료는 환불대상에서 제외됩니다. 예를 들어 10,000원 결제건에 대해서 고객사는:
+
+- 결제 시: 9,700원(10,000원 - 가상계좌 발행 수수료 300원)을 PG사로부터 정산받습니다.
+- 환불 시: 10,300원(환불되어야할 10,000원 + 환불 계좌로의 송금 수수료 300원)을 PG사로 지불합니다.
+
+PG사는 이런 과정에서 발생할 수 있는 혼란을 미연에 방지하고자 **가상계좌 특약서비스에 가입한 고객사에 한해서만 가상계좌 환불을 제공**하고 있습니다.
+
+</div>
+
+- **필수 정보**: 환불 계좌 정보 (`refundAccount.bank`, `refundAccount.number`, `refundAccount.holderName`)
+  - 가상계좌는 단방향 결제수단이므로 환불 계좌 지정이 필수입니다
+  - 스마트로 가상계좌는 `refundAccount.holderPhoneNumber`도 필수입니다
+
+- **처리 시간**: 영업일 기준 1\~2일
+
+- **취소 기한**: 제한 없음
+
+- **수수료**: 건당 300원 (결제 수수료와 별도)
+
+### 휴대폰 소액결제
+
+- **취소 기한**: 결제월과 취소월이 동일한 경우에만 가능
+
+### 카드
+
+- **취소 기한**: 통상 1년 (카드사별 상이)
+
+### 카카오페이
+
+- **취소 기한**: 카드 1년 이내 / 머니 5년 이내
+
+### 네이버페이
+
+- **취소 기한**: 결제일로부터 1095일 이내
+
+### 페이팔
+
+- **취소 기한**: 180일 이내 (판매자 동의 필요)
+
+<div class="hint" data-style="info">
+
+결제 수단별 자세한 취소 정책은 [포트원 헬프센터](https://help.portone.io/content/cancel-deadline-by-paymethod)를 참고하세요.
+
+</div>
+
+## 결제 취소 API 호출
+
+자세한 설명은 [결제 취소 API](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fcancel) 문서를 참고하세요.
+
+### 전액 취소
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="cURL">
+
+```bash
+curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \
+  -H 'Authorization: PortOne {API_SECRET}' \
+  -H 'Content-Type: application/json' \
+  -d '{"reason":"고객 요청"}'
+```
+
+</div>
+
+<div class="tabs-content" data-title="JavaScript (Server SDK)">
+
+```ts
+import { PaymentClient } from "@portone/server-sdk";
+
+const paymentClient = PaymentClient({
+  secret: "your-api-secret",
+});
+
+// ... 생략 ...
+
+try {
+  const response = await paymentClient.cancelPayment({
+    paymentId: "payment-id",
+    reason: "고객 요청",
+  });
+  console.log(response);
+} catch (error) {
+  console.error(error);
+}
+```
+
+</div>
+
+</div>
+
+#### 주요 파라미터
+
+- paymentId: string
+
+  **결제 건 아이디**
+
+- reason: string
+
+  **취소 사유**
+
+### 부분 취소
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="cURL">
+
+```bash
+curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \
+  -H 'Authorization: PortOne {API_SECRET}' \
+  -H 'Content-Type: application/json' \
+  -d '{"reason":"고객 요청","currentCancellableAmount":10000,"amount":3000}'
+```
+
+</div>
+
+<div class="tabs-content" data-title="JavaScript (Server SDK)">
+
+```ts
+import { PaymentClient } from "@portone/server-sdk";
+
+const paymentClient = new PaymentClient({
+  secret: "your-api-secret",
+});
+
+// ... 생략 ...
+
+try {
+  const response = await paymentClient.cancelPayment({
+    paymentId: "payment-id",
+    reason: "고객 요청",
+    currentCancellableAmount: 10000, // 검증용 잔액 값
+    amount: 3000, // 취소할 금액
+  });
+  console.log(response);
+} catch (error) {
+  console.error(error);
+}
+```
+
+</div>
+
+</div>
+
+#### 주요 파라미터
+
+- paymentId: string
+
+  **결제 건 아이디**
+
+- reason: string
+
+  **취소 사유**
+
+- amount?: integer (64 bit)
+
+  **취소할 금액**
+
+  취소할 금액을 지정합니다. 지정하지 않으면 전액 취소가 진행됩니다.
+
+- currentCancellableAmount?: integer (64 bit)
+
+  **결제 건의 취소 가능 잔액**
+
+  본 취소 요청 이전의 취소 가능 잔액으로써, 값을 입력하면 잔액이 일치하는 경우에만 취소가 진행됩니다. 값을 입력하지 않으면 별도의 검증 처리를 수행하지 않습니다.
+
+### 가상계좌 환불
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="cURL">
+
+```bash
+curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \
+  -H 'Authorization: PortOne {API_SECRET}' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "reason": "고객 요청",
+    "refundAccount": {
+      "bank": "BANK_OF_KOREA",
+      "number": "1234567890",
+      "holderName": "홍길동",
+      "holderPhoneNumber": "01012345678"
+    }
+  }'
+```
+
+</div>
+
+<div class="tabs-content" data-title="JavaScript (Server SDK)">
+
+```ts
+import { PaymentClient } from "@portone/server-sdk";
+
+const paymentClient = PaymentClient({
+  secret: "your-api-secret",
+});
+
+// ... 생략 ...
+
+try {
+  const response = await paymentClient.cancelPayment({
+    paymentId: "payment-id",
+    reason: "고객 요청",
+    refundAccount: {
+      bank: "BANK_OF_KOREA",
+      number: "1234567890",
+      holderName: "홍길동",
+      holderPhoneNumber: "01012345678", // 스마트로 가상계좌 취소 시 필수
+    },
+  });
+  console.log(response);
+} catch (error) {
+  console.error(error);
+}
+```
+
+</div>
+
+</div>
+
+#### 주요 파라미터
+
+- paymentId: string
+
+  **결제 건 아이디**
+
+- reason: string
+
+  **취소 사유**
+
+- refundAccount?: object
+
+  **환불 계좌 정보**
+
+  - bank: string
+
+    **계좌 은행**
+
+    [Bank](https://developers.portone.io/api/rest-v2/type-def#Bank) 타입 참고
+
+  - number: string
+
+    **계좌 번호**
+
+  - holderName: string
+
+    **예금주**
+
+  - holderPhoneNumber?: string
+
+    **예금주 연락처**
+
+    스마트로 가상계좌 결제인 경우에 필요합니다.
+
+### 프로모션 적용 주문건 취소
+
+프로모션이 적용된 결제 건의 취소는 [프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund) 문서를 참고하세요.
+
+## 결제 취소 API 결과 처리
+
+자세한 설명은 [결제 취소 API](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fcancel) 문서를 참고하세요.
+
+```ts
+try {
+  const response = await paymentClient.cancelPayment({
+    paymentId: "payment-id",
+    reason: "고객 요청",
+    // ... 생략 ...
+  });
+
+  if (isUnrecognizedPaymentCancellation(response.cancellation)) {
+    console.error(`취소 실패: ${response.cancellation.status}`);
+  } else if (response.cancellation.status === "SUCCEEDED") {
+    console.log("취소 완료");
+  } else if (response.cancellation.status === "FAILED") {
+    console.error("취소 실패");
+  } else if (response.cancellation.status === "REQUESTED") {
+    console.log("취소 요청 완료");
+  }
+} catch (error) {
+  console.error("취소 실패:", error);
+}
+```
+
+## 웹훅을 통한 결제 취소 결과 수신
+
+관리자콘솔을 통한 취소를 포함하여 비동기로 처리되는 취소 요청이나 취소 상태 변경을 실시간으로 알림받으려면 웹훅을 설정해야 합니다.
+
+웹훅 연동 방법은 [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2) 문서를 참고하세요.
+
+### 결제 취소 관련 웹훅 이벤트
+
+- `Transaction.CancelPending`: (결제 취소가 비동기로 수행되는 경우) **결제 취소를 요청**했을 때
+- `Transaction.PartialCancelled`: **결제가 부분 취소**되었을 때
+- `Transaction.Cancelled`: **결제가 완전 취소**되었을 때
+
+### 웹훅 처리 예제
+
+```ts
+import * as PortOne from "@portone/server-sdk";
+import bodyParser from "body-parser";
+import express from "express";
+
+const app = express();
+
+// 웹훅 검증 시 텍스트로 된 body가 필요합니다.
+app.use(
+  "/webhook",
+  bodyParser.text({
+    type: "application/json",
+  }),
+);
+
+app.post("/webhook", async (req, res) => {
+  try {
+    // 웹훅 검증
+    const webhook = await PortOne.Webhook.verify(
+      process.env.PORTONE_WEBHOOK_SECRET,
+      req.body,
+      req.headers,
+    );
+
+    // 취소 이벤트 처리
+    if (
+      webhook.type === "Transaction.Cancelled" ||
+      webhook.type === "Transaction.PartialCancelled"
+    ) {
+      const { paymentId, cancellationId } = webhook.data;
+
+      console.log(
+        `${paymentId} 결제가 취소되었습니다. 취소 ID: ${cancellationId}`,
+      );
+    }
+
+    res.status(200).send("OK");
+  } catch (error) {
+    if (error instanceof PortOne.Webhook.WebhookVerificationError) {
+      console.error("웹훅 검증 실패:", error.message);
+    } else {
+      console.error("웹훅 처리 중 오류 발생:", error);
+    }
+    res.status(400).send("Bad Request");
+  }
+});
+```
+
+## 관련 문서
+
+- [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2): 결제 취소 알림을 받기 위한 웹훅 설정
+- [결제 연동 시작하기](https://developers.portone.io/opi/ko/integration/start/v2/readme): 기본적인 결제 연동 방법
+- [프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund): 프로모션이 적용된 결제의 취소 방법
+- [관리자 콘솔 가이드](https://help.portone.io/content/cancel-guide-using-admin-console): 관리자콘솔을 통해 결제 취소하는 방법

package/assets/docs/opi/ko/integration/checklist/readme-v1.md

@@ -0,0 +1,83 @@
+---
+title: 오픈 전 체크리스트
+description: 결제 오픈전 자가진단을 해볼수 있는 오픈 전 체크사항 리스트 입니다.
+targetVersions:
+  - v1
+---
+
+💡 서비스를 운영 시스템에 적용하기 전에 놓치기 쉬운 항목을 체크하여 운영장애를 사전에 방지합니다.
+
+## ✍️ 서비스 공통
+
+- **포트원 콘솔의 시스템설정이 운영정보로 설정**
+  - [ ] PG사상점아이디 / PG상점 Secret 을 설정 하였습니다.
+  - [ ] 테스트모드를 OFF로 설정 하였습니다.
+  - [ ] 웹훅(Notification)발송 공통 URL을 운영정보로 설정 하였습니다.
+  - [ ] IP보안설정이 운영서버 정보로 설정하였습니다.
+  - [ ] 카드 사용/고객사 이자부담 할부설정을 확인 하였습니다.
+  - [ ] m\_redirect\_URL을 운영정보로 설정 하였습니다.(리디렉션 방식(모바일/페이팔) 이용 시)
+  - [ ] confirm\_URL을 운영정보로 설정 하였습니다.(서비스 이용 시 - 포트원에 사전 요청 필요)
+
+- **결제창 정상 호출 및 결과처리**
+  - [ ] 결제창 호출이 셋팅한 PG사로 호출 되었습니다.
+  - [ ] 결제 이후 Callback 으로 결과 정상수신 / m\_redirect\_url로 302 리디렉션으로 결과 정상 수신하였습니다.
+  - [ ] 결제 완료(paid/canceled) 시 웹훅으로 처리결과를 정상수신 하였습니다.
+  - [ ] 웹훅으로 수신된 내용으로 시스템에 정상적으로 결과 반영 하였습니다.
+  - [ ] 웹훅에 대해 HTTP 200으로 응답하였습니다.
+  - [ ] 결제/취소 중 통신오류로 결과를 확정 지을 수 없을 경우에 대한 처리로직이 있습니다.
+  - [ ] 결제/취소 실패사유 별 재처리 로직이 있습니다.(예: 취소 실패 시 재취소를 할 수 있음)
+  - [ ] 결제/취소에 대한 전표내역을 확인할 수 있는 기능을 제공하거나 안내 할 수 있습니다.
+  - [ ] 주요 항목으로 데이터를 확인 할 수 있습니다.(승인번호 / imp\_uid / merchant\_uid)
+  - [ ] 중복으로 결과를 수신하여도 이를 처리하는 로직이 있습니다.
+
+⚠️ 결제수단 별 확인사항을 체크합니다.
+
+## 💳신용카드
+
+- [ ] 모든 카드사 심사가 완료 되었으며 승인,전체/부분취소 테스트를 완료 하였습니다.
+- [ ] 할부 및 무이자 설정이 결제창 내에 정상적으로 표시되는 것을 확인 하였습니다.
+- [ ] 체크/신용/해외 카드에 대해 정상적으로 결제/취소 되었습니다.(해외카드는 별도의 계약 필요)
+- [ ] 면세/과세 금액 설정 시 PG사 어드민 / 매출전표 표시내용과 일치합니다.
+- [ ] 정기결제 시 빌키 발급 이후 결제에 성공하였습니다.
+- [ ] 결제실패 시 해당 빌키를 삭제하고 새로운 결제 정보로 빌키를 새로 취득하고 결제 할 수 있습니다.
+
+## 💵가상계좌
+
+- [ ] 발급된 가상계좌의 은행코드로 은행명을 인식할 수 있습니다.
+- [ ] 발급된 가상계좌를 납부자에게 전달하고 삭제 할 수 있습니다.
+- [ ] 입급 결과를 수신하고 시스템에 반영 할 수 있습니다.
+- [ ] 입금 취소 시 이를 시스템에 반영 할 수 있습니다.
+- [ ] 환불 요청 시 환불을 요청하고 이를 처리 할 수 있습니다.
+
+## 💸 계좌이체
+
+- [ ] 출금이체 한 은행코드로 은행명을 인식할 수 있습니다.
+- [ ] 환불 요청 시 환불을 요청하고 이를 처리 할 수 있습니다.
+
+## 📱휴대전화
+
+- [ ] 모든 통신사 심사가 완료 되었으며 승인,전체/부분취소 테스트를 완료 하였습니다.
+  - KG이니시스, KCP(별도요청) 외 부분취소 불가
+
+- [ ] 정상 승인거래에 대해 당월에 한해 취소 처리 할 수 있습니다.
+
+## 🙋 본인인증
+
+- [ ] 외국인 여부에 대한 확인이 필요 할 경우 계약 완료 여부를 확인하였습니다.
+
+## 🧾현금영수증
+
+- [ ] 발급된 영수증을 조회 및 취소 할 수 있습니다.
+- [ ] 포트원을 통한 거래와 이 외 거래를 구분하여 처리 할 수 있습니다.
+
+⚠️ 제공하는 결제환경에서 모든 케이스를 테스트 합니다.
+
+|OS / 브라우져|IE / Edge|Chrome|Safari|FireFox|Whale|포털 웹뷰|SNS 웹뷰|
+|-------------|---------|------|------|-------|-----|---------|--------|
+|Window       |         |      |      |       |     |         |        |
+|Mac OS       |         |      |      |       |     |         |        |
+|Android      |         |      |      |       |     |         |        |
+|iOS          |         |      |      |       |     |         |        |
+
+- [ ] iOS에서 결제사 외부앱을 연동하기 위해 info.plist 을 작성하였습니다.
+- [ ] 결제 이 후 고객사 앱으로 돌아오기 위해 app\_scheme을 전달합니다.

package/assets/docs/opi/ko/integration/pg/v1/blue.md

@@ -0,0 +1,99 @@
+---
+title: 블루월넛
+description: 블루월넛 결제 연동방법을 안내합니다.
+targetVersions:
+  - v1
+---
+
+## 1. 블루월넛 PG 설정하기
+
+(관련 이미지 첨부)
+
+## 2.결제 요청하기
+
+[JavaScript SDK](https://developers.portone.io/sdk/ko/v1-sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여
+블루월넛 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)`
+호출 후 **callback** 으로 수신되어
+모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다.
+
+<div class="tabs-container">
+
+<div class="tabs-content" data-title="인증결제창 요청">
+
+```ts title="Javascript SDK"
+IMP.request_pay(
+  {
+    channelKey: "{콘솔 내 연동 정보의 채널키}",
+    pay_method: "card",
+    merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호
+    name: "주문명:결제테스트",
+    amount: 14000,
+    buyer_email: "test@portone.io",
+    buyer_name: "구매자이름",
+    buyer_tel: "010-1234-5678",
+    buyer_addr: "서울특별시 강남구 삼성동",
+    buyer_postcode: "123-456",
+  },
+  function (rsp) {
+    // callback 로직
+    /* ...중략... */
+  },
+);
+```
+
+**주요 파라미터 설명**
+
+- channelKey: string
+
+  **채널키**
+
+  결제를 진행할 채널을 지정합니다.
+
+  포트원 콘솔 내 \[결제 연동] - \[연동 정보] - \[채널 관리] 에서 확인 가능합니다.
+
+  (최신 JavaScript SDK 버전부터 사용 가능합니다.)
+
+- pg(deprecated)?: string
+
+  **PG사 구분코드**
+
+  `bluewalnut` 로 지정하면 됩니다.
+
+  <div class="hint" data-style="warning">
+
+  `pg` 파라미터는 지원 중단 예정입니다.
+
+  JS SDK를 가장 최신 버전으로 업그레이드 후 `channelKey` 파라미터로 채널 설정(PG사 구분)을 대체해주세요.
+
+  </div>
+
+- pay\_method: string
+
+  **결제수단 구분코드**
+
+  - card (신용카드)
+  - trans (실시간 계좌이체)
+  - vbank(가상계좌)
+  - phone (휴대폰소액결제)
+
+- merchant\_uid: string
+
+  **고객사 채번 주문 고유번호**
+
+  고객사에서 매번 고유하게 채번되어야 합니다.
+
+- amount: number
+
+  **결제금액**
+
+  지정하지 않은 경우 0원입니다.
+
+</div>
+
+<div class="tabs-content" data-title="비 인증결제">
+
+**포트원은 블루월넛 비 인증 결제를 지원하지 않습니다.**
+
+</div>
+
+</div>