결제 (Payments) API

Payments

Method	Endpoint	Description
GET	/payment-methods	사용자의 결제 수단 목록 조회
GET	/payments	사용자의 결제 내역 조회
POST	/payment-methods	새로운 결제 수단 등록
POST	/payments	결제 요청

---

[GET] 결제 수단 목록 조회 (/payment-methods)

Headers

Key	Value	Description
Authorization	Bearer jwt-access-token	JWT 인증을 위한 액세스 토큰

---

Request

No request body required.

Response

Success (200 OK):

{
   "success": true,
   "data": [
       {
           "methodId": "12345",
           "type": "credit_card",
           "lastFourDigits": "4242",
           "expiryDate": "2025-12"
       },
       {
           "methodId": "12346",
           "type": "toss",
           "email": "[email protected]"
       }
   ]
}

Exception

• 401 Unauthorized: 토큰이 없거나 유효하지 않은 경우

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 401,
    "message": "인증 토큰이 없거나 유효하지 않습니다",
    "path": "/payment-methods"
}

[POST] 결제 수단 등록 (/payment-methods)

Headers

Key	Value	Description
Authorization	Bearer jwt-access-token	JWT 인증을 위한 액세스 토큰
Content-Type	application/json	요청 본문이 JSON 형식임을 지정

---

Request

{
   "type": "credit_card",
   "number": "4242424242424242",
   "expiryDate": "2025-12",
   "cvv": "123"
}

Response

Success (201 Created):

{
   "success": true,
   "data": {
       "methodId": "12345",
       "type": "credit_card",
       "lastFourDigits": "4242",
       "expiryDate": "2025-12",
       "createdAt": "2024-11-19T12:00:00Z"
   }
}

Exception

• 400 Bad Request: 필수 필드 누락 또는 잘못된 데이터 형식

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 400,
    "message": "필수 필드가 누락되었거나 데이터 형식이 잘못되었습니다",
    "path": "/payment-methods"
}

• 401 Unauthorized: 인증 토큰이 없거나 유효하지 않은 경우

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 401,
    "message": "인증 토큰이 없거나 유효하지 않습니다",
    "path": "/payment-methods"
}

[GET] 결제 내역 조회 (/payments)

Headers

Key	Value	Description
Authorization	Bearer jwt-access-token	JWT 인증을 위한 액세스 토큰

---

Request

No request body required.

Response

Success (200 OK):

{
   "success": true,
   "data": [
       {
           "paymentId": "78901",
           "amount": 15000,
           "currency": "KRW",
           "status": "COMPLETED",
           "method": "credit_card",
           "createdAt": "2024-11-18T14:00:00Z"
       },
       {
           "paymentId": "78902",
           "amount": 20000,
           "currency": "KRW",
           "status": "PENDING",
           "method": "toss",
           "createdAt": "2024-11-19T12:00:00Z"
       }
   ]
}

Exception

• 401 Unauthorized: 인증 토큰이 없거나 유효하지 않은 경우

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 401,
    "message": "인증 토큰이 없거나 유효하지 않습니다",
    "path": "/payments"
}

[POST] 결제 요청 (/payments)

Headers

Key	Value	Description
Authorization	Bearer jwt-access-token	JWT 인증을 위한 액세스 토큰
Content-Type	application/json	요청 본문이 JSON 형식임을 지정

---

Request

{
   "amount": 15000,
   "currency": "KRW",
   "methodId": "12345",
   "description": "홍대 모각밥 참여 결제"
}

Response

Success (201 Created):

{
   "success": true,
   "data": {
       "paymentId": "78901",
       "amount": 15000,
       "currency": "KRW",
       "status": "COMPLETED",
       "method": "credit_card",
       "createdAt": "2024-11-19T12:00:00Z"
   }
}

Exception

• 400 Bad Request: 필수 필드 누락

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 400,
    "message": "필수 필드가 누락되었습니다",
    "path": "/payments"
}

• 401 Unauthorized: 인증 토큰이 없거나 유효하지 않은 경우

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 401,
    "message": "인증 토큰이 없거나 유효하지 않습니다",
    "path": "/payments"
}

• 402 Payment Required: 결제 실패

{
    "success": false,
    "timestamp": "2023-02-22T06:25:08.663Z",
    "status": 402,
    "message": "결제에 실패했습니다",
    "path": "/payments"
}