# 구매 API - 결제 상세 조회

## 1. API Overview

### Purpose

[context]
특정 결제 요청에 대한 상세 정보를 조회하는 API입니다.
`orderNo`를 기반으로 결제 상태, 결제 금액, 구매자 정보, 결제 이력 등 상세 내역을 반환합니다.  
조회 결과에는 결제 승인 여부, 정산 완료 여부, 취소 내역, 상품별 결제 금액 및 처리 이력 등이 포함됩니다.
이 API는 결제 처리 현황을 확인하거나 고객 응대 시 상세 정보를 제공하는 데 활용됩니다.
[/context]

> **참고**
> - `orderNo`는 **EBP에서 발급**되는 주문번호입니다.

### Details

[table:key-value]
| 항목            | 값                      |
| :-------------- | :---------------------- |
| **API Name**    | 결제 상세 조회          |
| **API Path**    | /api/v2/payment/detail  |
| **API ID**      | EBP_API_237             |
| **HTTP Method** | [badge:POST,blue,lg]    |
| **Region**      | [badge:Global,green-subtle,lg] |
[/table]

## 2. Request Specification

### 2.1 Request Header

@@include:common-headers-link.md@@

### 2.2 Request Data Schema

| depth | Field   | Details & Description            |
| :---- | :------ | :------------------------------- |
| -1    | orderNo | [type:string] [req:Yes] [desc:EBP 주문번호] |

### 2.3 Request Examples

#### JSON Example

```json
{
  "orderNo": "ORD-202511274242111"
}
```

## 3. Response Specification

### 3.1 Response Data Schema

@@include:standard-response.md@@
| -1    | data                  | [type:object] [req:Yes] [desc:응답 데이터]                                                         |
| 0     | orderNo               | [type:string] [req:Yes] [desc:거래를 식별하는 고유 주문 번호]                                      |
| 0     | storeRequestNo        | [type:string] [req:Yes] [desc:상점 시스템 연동을 위한 스토어측 요청 번호]                          |
| 0     | pgTransactionId       | [type:string] [req:Optional] [desc:최초 결제에 대한 PG 거래 ID]                                    |
| 0     | pgCancelTransactionId | [type:string] [req:Optional] [desc:취소/환불에 대한 PG 거래 ID]                                    |
| 0     | buyerName             | [type:string] [req:Optional] [desc:구매자/고객 이름]                                               |
| 0     | paymentStatus         | [type:string] [req:Yes] [desc:현재 결제 상태] [eg:REQUESTED, APPROVED, CANCELED, PARTIAL_CANCELED] |
| 0     | countryCode           | [type:string] [req:Optional] [desc:국가 코드] [eg:KR, US]                                          |
| 0     | countryName           | [type:string] [req:Optional] [desc:국가명 (영문 또는 현지화)]                                      |
| 0     | paymentRequestedAt    | [type:string] [req:Yes] [desc:결제 요청 시각[tooltip:UTC, ISO-8601]]                              |
| 0     | approvedAt            | [type:string] [req:Optional] [desc:결제 승인 시각[tooltip:UTC, ISO-8601]]                         |
| 0     | settlementCompletedAt | [type:string] [req:Optional] [desc:정산 완료 시각[tooltip:UTC, ISO-8601]]                         |
| 0     | canceledAt            | [type:string] [req:Optional] [desc:결제 취소 시각[tooltip:UTC, ISO-8601]]                         |
| 0     | cancellationDetail    | [type:string] [req:Optional] [desc:취소 상세 내용 또는 메모[tooltip:사유, 부분 취소 정보]]        |
| 0     | paymentMethodName     | [type:string] [req:Yes] [desc:읽기 쉬운 결제 수단명] [eg:신용카드, 토큰화된 카드]                  |
| 0     | storeName             | [type:string] [req:Yes] [desc:스토어 또는 판매자 이름]                                             |
| 0     | purchaseChannel       | [type:string] [req:Optional] [desc:구매 채널명] [eg:Online, POS]                                   |
| 0     | currencyCode          | [type:string] [req:Yes] [desc:통화 코드] [eg:USD, KRW]                                             |
| 0     | productAmount         | [type:number] [req:Yes] [desc:할인 전 상품 총액]                                                   |
| 0     | discountAmount        | [type:number] [req:Optional] [desc:주문에 적용된 할인 금액]                                        |
| 0     | deliveryFee           | [type:number] [req:Optional] [desc:배송료]                                                         |
| 0     | totalPaymentAmount    | [type:number] [req:Yes] [desc:할인 및 수수료 적용 후 총 결제 금액]                                 |
| 0     | productTaxAmount      | [type:number] [req:Optional] [desc:상품에 적용된 세금 금액]                                        |
| 0     | deliveryFeeTaxAmount  | [type:number] [req:Optional] [desc:배송료에 적용된 세금 금액]                                      |
| 0     | cancelAmount          | [type:number] [req:Optional] [desc:취소 금액]                                                      |
| 0     | items                 | [type:array] [req:Yes] [desc:품목 목록]                                                            |
| 1     | seq                   | [type:number] [req:Yes] [desc:순번]                                                                |
| 1     | itemType           | [type:string] [req:Yes] [desc:상품 유형] [eg:PHYSICAL, DIGITAL, SUBSCRIPTION, DELIVERY, SERVICE] |
| 1     | itemId             | [type:string] [req:Yes] [desc:상품 고유 식별자]                                                    |
| 1     | itemName           | [type:string] [req:Yes] [desc:상품명]                                                              |
| 1     | sellerNo              | [type:string] [req:Yes] [desc:판매자 식별자]                                                       |
| 1     | unitPrice          | [type:number] [req:Yes] [desc:원래 상품 금액]                                                      |
| 1     | subtotalAmount         | [type:number] [req:Yes] [desc:총 상품 금액 (단가 × 수량]                                                       |
| 1     | discountAmount        | [type:number] [req:Optional] [desc:할인 금액]                                                      |
| 1     | paymentAmount         | [type:number] [req:Yes] [desc:최종 결제 금액]                                                      |
| 1     | quantity              | [type:number] [req:Yes] [desc:판매 수량]                                                           |
| 1     | confirmedAt           | [type:string] [req:Optional] [desc:구매 확정일[tooltip:UTC, ISO-8601]]                              |
| 0     | cancelItems           | [type:array] [req:Yes] [desc:취소 품목 목록]                                                       |
| 1     | cancelNo              | [type:string] [req:Yes] [desc:취소 고유 식별자]                                                    |
| 1     | pgTransactionId       | [type:string] [req:Optional] [desc:취소에 대한 PG 거래 ID]                                         |
| 1     | canceledAt            | [type:string] [req:Yes] [desc:취소 일시[tooltip:UTC, ISO-8601]]                                    |
| 1     | seq                   | [type:string] [req:Yes] [desc:취소된 상품의 고유 식별자]                                           |
| 1     | seq                   | [type:number] [req:Yes] [desc:순번]                                                                |
| 1     | itemId             | [type:string] [req:Yes] [desc:상품 고유 식별자]                                                    |
| 1     | itemName           | [type:string] [req:Yes] [desc:상품명]                                                              |
| 1     | quantity              | [type:number] [req:Yes] [desc:취소 수량]                                                           |
| 1     | paymentAmount          | [type:number] [req:Yes] [desc:총 결제 금액]                                                      |
| 1     | cancelAmount          | [type:number] [req:Yes] [desc:총 취소 금액]                                                        |
| 0     | histories             | [type:array] [req:Optional] [desc:결제 처리 과정에 대한 감사 추적 로그 (audit trail)]              |
| 1     | seq                   | [type:number] [req:Yes] [desc:로그 순번]                                                           |
| 1     | processedAt           | [type:string] [req:Yes] [desc:처리 발생 시각[tooltip:UTC, ISO-8601]]                                     |
| 1     | eventName             | [type:string] [req:Yes] [desc:발생한 이벤트 이름] [eg:Payment Requested]                           |
| 1     | result                | [type:string] [req:Yes] [desc:처리 결과] [eg:SUCCESS, FAILURE]                                     |
| 1     | reason                | [type:string] [req:Optional] [desc:처리 결과에 대한 상세 사유]                                     |
| 1     | processedBy           | [type:string] [req:Optional] [desc:해당 처리를 수행한 시스템 또는 사용자 ID]                       |

### 3.2 Response Samples

#### Success Response

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "1767146488599",
  "timestamp": "2025-12-31T02:01:28.600976Z",
  "data": {
    "orderNo": "ORD-202511274242111",
    "storeRequestNo": "P25112711771579",
    "pgTransactionId": "K202511277931269531",
    "pgCancelTransactionId": null,
    "buyerName": "성준호",
    "paymentStatus": "APPROVED",
    "countryCode": "KR",
    "countryName": "Republic of Korea",
    "paymentRequestedAt": "2025-11-27T12:19:34.0Z",
    "approvedAt": "2025-11-27T12:19:50.0Z",
    "settlementCompletedAt": "2025-11-27T12:19:50.0Z",
    "canceledAt": null,
    "cancellationDetail": null,
    "paymentMethodName": "신용카드(CNSPay)",
    "storeName": "엘지이닷컴",
    "purchaseChannel": "폰클라이언트",
    "currencyCode": "KRW",
    "productAmount": 1310000.0,
    "discountAmount": 0.0,
    "deliveryFee": 0.0,
    "totalPaymentAmount": 1310000.0,
    "productTaxAmount": 0.0,
    "deliveryFeeTaxAmount": 0.0,
    "cancelAmount": 0.0,
    "items": [
      {
        "seq": 1,
        "itemType": "PHYSICAL",
        "itemId": "75UT9300BW.AKRG",
        "itemName": "LG 울트라 HD TV (벽걸이형)",
        "sellerId": "CPKR810001",
        "productAmount": 1310000.0,
        "discountAmount": 0.0,
        "paymentAmount": 1310000.0,
        "taxAmount": 0.0,
        "quantity": 1,
        "confirmedAt": "2025-11-27T12:19:50.0Z",
        "confirmedAtLocal": "2025-11-27T21:19:50.0Z"
      }
    ],
    "cancelItems": [],
    "histories": [
      {
        "seq": 1,
        "processedAt": "2025-11-27T12:19:34.0Z",
        "processedAtLocal": "2025-11-27T21:19:34.0",
        "eventName": "Payment Requested",
        "result": "SUCCESS",
        "reason": "Client payment request initiated",
        "processedBy": "CORE"
      },
      {
        "seq": 2,
        "processedAt": "2025-11-27T12:19:50.0Z",
        "processedAtLocal": "2025-11-27T21:19:50.0",
        "eventName": "PG Approval Success",
        "result": "SUCCESS",
        "reason": "Payment gateway approved the transaction",
        "processedBy": "PG-GATEWAY"
      }
    ]
  }
}
```