웹훅 관련 가이드 보완 (#510)

Co-authored-by: y0on2q <[email protected]> Co-authored-by: Ashley <[email protected]> Co-authored-by: finalchild <[email protected]> Co-authored-by: Sohyun Ashley Kim <[email protected]>
portone-io · Jun 19, 2024 · 17e9f37 · 17e9f37
1 parent 2ca9de3
commit 17e9f37
Show file tree

Hide file tree

Showing 6 changed files with 334 additions and 76 deletions.
diff --git a/src/content/docs/ko/v2-payment/_assets/v2/webhook-secret-1.png b/src/content/docs/ko/v2-payment/_assets/v2/webhook-secret-1.png
diff --git a/src/content/docs/ko/v2-payment/_assets/v2/webhook-secret-2.png b/src/content/docs/ko/v2-payment/_assets/v2/webhook-secret-2.png
diff --git a/src/content/docs/ko/v2-payment/confirm-process.mdx b/src/content/docs/ko/v2-payment/confirm-process.mdx
@@ -84,14 +84,65 @@ import ConfirmProcessImage1 from "./_assets/v2/confirm_process_v2_1.png";
 }
 ```
 
-해당 URL이 설정되면 포트원에서 결제 승인 요청 직전 해당 URL로 **HTTP 통신**이 진행되며
-아래와 같은 데이터가 POST로 요청됩니다. (Timeout : **10s**)
+## Payload Schema
 
-> `tx_id`: 포트원 결제번호
->
-> `payment_id`: 고객사 주문번호
->
-> `total_amount`: 결제 요청 금액
+콘솔에서 설정하신 웹훅 버전에 따라 상이한 형식의 payload가 송신됩니다.
 
-해당 요청에 대한 고객사 응답으로 HTTP Status **200** 응답인 경우에만 결제 승인을 요청합니다.
-<mark style="color:red;">**200 응답이 아닌 경우 결제가 진행되지 않으며 `결제 실패` 상태로 남습니다.**</mark>
+### `2024-01-01` 사용 시
+
+- `payment_id`: 고객사에서 채번한 결제건의 고유 주문 번호입니다.
+- `tx_id`: 포트원에서 채번한 결제건의 고유 거래 번호입니다.
+- `total_amount`: 결제건의 결제 요청 금액입니다.
+
+**컨펌 웹훅 payload 예시:**
+
+```json
+{
+  "payment_id": "example-payment-id",
+  "tx_id": "55451513-9763-4a7a-bb43-78a4c65be843",
+  "total_amount": 1000
+}
+```
+
+### `2024-04-25` 사용 시
+
+- `type`: 웹훅을 트리거한 이벤트의 타입입니다. 컨펌 웹훅의 경우 `type`의 값은 `Transaction.Confirm`으로 고정됩니다.
+
+- `timestamp`: 해당 웹훅을 트리거한 이벤트의 발생 시각(RFC 3339 형식)입니다.
+
+- `data`: 웹훅을 트리거한 이벤트의 실제 세부 내용입니다. 컨펌 웹훅의 경우 해당 필드의 상세 스키마는 아래와 같습니다.
+  - `paymentId`: 고객사에서 채번한 결제건의 고유 주문 번호입니다.
+  - `transactionId`: 포트원에서 채번한 결제건의 고유 거래 번호입니다.
+  - `totalAmount`: 결제건의 결제 요청 금액입니다.
+
+**컨펌 웹훅 payload 예시:**
+
+```json
+{
+  "type": "Transaction.Confirm",
+  "timestamp": "2024-04-25T10:00:00.000Z",
+  "data": {
+    "paymentId": "example-payment-id",
+    "transactionId": "55451513-9763-4a7a-bb43-78a4c65be843",
+    "totalAmount": 1000
+  }
+}
+```
+
+## SDK 실패 응답에 특정 에러 메세지 포함시키기
+
+고객사는 재고 부족 등의 이유로 포트원이 보낸 컨펌 프로세스 요청에 실패 응답을 보낼 수 있고, 이러한 실패 사유를 서비스를 이용하는 고객들에게 보여주고 싶을 수 있습니다.
+이러한 경우 Response Body에 `errorMessage` 라는 필드를 포함하여 에러 응답을 보내주시면 해당 메세지를 포함해 SDK 응답으로 리턴해드리고 있습니다.
+
+**Error Response Body 예시:**
+
+```json
+{
+  "errorMessage": "재고가 모두 소진되었습니다. 관리자에게 문의하세요."
+}
+```
+
+## 컨펌 웹훅 요청 검증하기
+
+컨펌 프로세스 웹훅 또한 다른 일반적인 웹훅과 동일한 방식으로 검사하시는 것을 권장합니다.
+[웹훅 연동하기 - 웹훅 요청 검증하기](./webhook#웹훅-요청-검증하기)를 참고하셔서 컨펌 웹훅을 신뢰할 수 있는지를 검사하세요.
diff --git a/src/content/docs/ko/v2-payment/pg/tosspay-v2.mdx b/src/content/docs/ko/v2-payment/pg/tosspay-v2.mdx
@@ -119,6 +119,7 @@ function requestPayment() {
             전달하지 않을경우, 기본값은 GENERAL 입니다.
 
             일반 (default) : `GENERAL` / 문화비 : `CULTURE` / 교통비 : `PUBLIC_TP`
+
         </ParamTree>
     </ParamTree>
 </ParamTree>
@@ -331,7 +332,6 @@ const response = await axios({
 
         **구매자 이메일**
     </ParamTree>
-
 </ParamTree>
 
 ## API 빌링키 예약/반복 결제 요청하기