dpot-backend/Web.Api/postman/Payment.postman_collection.json

{
  "info": {
    "_postman_id": "dpot-payment-danal-v1",
    "name": "DPOT Payment API (Danal PG)",
    "description": "다날 PG 결제 연동 API\n\n## 결제 흐름\n1. **주문 생성** → `POST /api/payment/order`\n2. **다날 SDK 결제창 호출** (프론트엔드)\n3. **결제 승인** → `POST /api/payment/confirm`\n4. (선택) **결제 취소** → `POST /api/payment/cancel`\n\n## 사용법\n1. `baseUrl` 변수 설정 (기본값: `https://localhost:4000`)\n2. 로그인 후 `accessToken` 변수에 JWT Bearer 토큰 입력",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://localhost:4000",
      "type": "string",
      "description": "API 서버 URL (개발: https://localhost:4000 / 운영: https://api.dpot.web.or.kr)"
    },
    {
      "key": "accessToken",
      "value": "",
      "type": "string",
      "description": "JWT Bearer 토큰 (로그인 후 발급)"
    },
    {
      "key": "orderID",
      "value": "",
      "type": "string",
      "description": "주문 생성 후 저장된 OrderID"
    },
    {
      "key": "transactionID",
      "value": "",
      "type": "string",
      "description": "다날 결제 완료 후 반환된 TransactionID"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{accessToken}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "1. 주문 생성",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/payment/order",
          "host": ["{{baseUrl}}"],
          "path": ["api", "payment", "order"]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"amount\": 10000,\n  \"paymentMethod\": \"Card\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "description": "금액과 결제수단으로 주문을 생성합니다.\n\n**결제수단 (`paymentMethod`):**\n- `Card` — 신용카드\n- `KakaoPay` — 카카오페이\n- `NaverPay` — 네이버페이\n- `Transfer` — 계좌이체\n- `Mobile` — 휴대폰\n- `VirtualAccount` — 가상계좌\n- `Payco` — 페이코\n\n**응답 저장 (Tests 탭 스크립트로 자동 저장):**\n```\npm.collectionVariables.set('orderID', pm.response.json().data.orderID);\n```"
      },
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const res = pm.response.json();",
              "if (res.success && res.data && res.data.orderID) {",
              "    pm.collectionVariables.set('orderID', res.data.orderID);",
              "    console.log('orderID saved:', res.data.orderID);",
              "}"
            ]
          }
        }
      ]
    },
    {
      "name": "2. 결제 승인",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/payment/confirm",
          "host": ["{{baseUrl}}"],
          "path": ["api", "payment", "confirm"]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"orderID\": \"{{orderID}}\",\n  \"transactionID\": \"{{transactionID}}\",\n  \"method\": \"CARD\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "description": "다날 결제창 완료 후 서버 승인 API를 호출합니다.\n\n**`method` 값 (다날 결제수단 코드):**\n- `CARD` — 신용카드\n- `KAKAOPAY` — 카카오페이\n- `NAVERPAY` — 네이버페이\n- `TRANSFER` — 계좌이체\n- `MOBILE` — 휴대폰\n- `VIRTUAL_ACCOUNT` — 가상계좌\n\n**응답:**\n```json\n{\n  \"success\": true,\n  \"pointAmount\": 10000,\n  \"message\": \"충전이 완료되었습니다.\",\n  \"paidAt\": \"2026-03-26T03:30:00Z\"\n}\n```"
      },
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const res = pm.response.json();",
              "if (res.data) {",
              "    console.log('pointAmount:', res.data.pointAmount);",
              "    console.log('paidAt:', res.data.paidAt);",
              "}"
            ]
          }
        }
      ]
    },
    {
      "name": "3. 결제 취소",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/payment/cancel",
          "host": ["{{baseUrl}}"],
          "path": ["api", "payment", "cancel"]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"orderID\": \"{{orderID}}\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "description": "결제 완료(Paid) 상태의 주문을 전액 취소합니다.\n\n- `Paid` 상태 주문만 취소 가능\n- 다날 취소 API 호출 후 지갑 포인트 차감\n- 성공 시 HTTP 200, 실패 시 400/500 반환"
      }
    },
    {
      "name": "4. 클라이언트 설정 조회",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/payment/config",
          "host": ["{{baseUrl}}"],
          "path": ["api", "payment", "config"]
        },
        "description": "프론트엔드 다날 SDK 호출에 필요한 `clientKey`와 `merchantID`를 반환합니다.\n\n**응답:**\n```json\n{\n  \"clientKey\": \"test_ck_...\",\n  \"merchantID\": \"T0000000000\"\n}\n```"
      }
    },
    {
      "name": "5. 가상계좌 입금 통보 (Webhook)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/api/payment/noti/vaccount",
          "host": ["{{baseUrl}}"],
          "path": ["api", "payment", "noti", "vaccount"]
        },
        "body": {
          "mode": "raw",
          "raw": "{\n  \"code\": \"SUCCESS\",\n  \"message\": \"입금완료\",\n  \"transactionID\": \"TX-TEST-001\",\n  \"orderID\": \"{{orderID}}\",\n  \"amount\": \"10000\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "auth": {
          "type": "noauth"
        },
        "description": "다날 서버에서 가상계좌 입금 완료 시 호출하는 서버-투-서버 Webhook입니다.\n\n- **인증 불필요** (AllowAnonymous)\n- 다날 서버 IP: `150.242.132.116`\n- 입금 확인 후 포인트 자동 적립\n- `amount` 필드는 **문자열** 형식\n\n**성공 응답:**\n```json\n{ \"code\": \"SUCCESS\" }\n```\n\n**실패 응답:**\n```json\n{ \"code\": \"FAIL\" }\n```"
      }
    }
  ]
}