# 구매 API - 결제 취소

## 1. API Overview

### Purpose

[context]
결제 취소를 요청하는 API입니다.<br>주문번호를 기반으로 결제 취소를 처리하며, 필요한 경우 환불 계좌 정보를 함께 전달합니다.<br>취소 요청에는 상품별 취소 내역과 금액 정보가 포함될 수 있습니다.<br>이 API는 결제 취소 후 결과를 상점에 전달하여 환불 프로세스를 안전하게 진행할 수 있도록 합니다.
[/context]

> **참고**: 
> - 주문 단위, 상품 단위, 혹은 특정 금액 단위로 취소가 가능합니다.
> - **매입 전 취소**는 전액 취소만 가능합니다. 부분 취소를 원할 경우에는 매입을 완료한 후 부분 취소를 요청해야 합니다.

### Details

[table:key-value]
| 항목            | 값                     |
| :-------------- | :--------------------- |
| **API Name**    | 결제 취소              |
| **API Path**    | /api/v2/payment/cancel |
| **API ID**      | EBP_API_232            |
| **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                              |
| :---- | :---------------- |:---------------------------------------------------|
| 0     | orderNo           | [type:string] [req:Yes] [desc:처리의 기준이 되는 값 (주문번호)] |
| 0     | totalCancelAmount | [type:number] [req:Yes] [desc:총 취소 금액 (items의 amount 합계와 일치해야 함)] |
| 0     | refundAccount     | [type:object] [req:Optional] [desc:-]              |
| 1     | accountNumber     | [type:number] [req:Optional] [desc:계좌번호]           |
| 1     | bankCode          | [type:string] [req:Optional] [desc:은행코드]           |
| 1     | accountHolderName | [type:string] [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, DELIVERY, SERVICE] |
| 1     | itemId         | [type:string] [req:Yes] [desc:상품 ID]               |
| 1     | quantity          | [type:number] [req:Yes] [desc:상품 갯수]               |
| 1     | amount            | [type:number] [req:Yes] [desc:취소금액]                |
| 1     | taxAmount         | [type:number] [req:Optional] [desc:세금금액]           |

@@include:item-type.md@@

### 2.3 Request Examples

[tabs]
[tab:주문 단위 취소]
```json:scrollable
// 전체 주문 취소
{
  "orderNo": "ORD20251224001",
  "totalCancelAmount": 106000.0,
  "refundAccount": {
    "accountNumber": "1234567890",
    "bankCode": "001",
    "accountHolderName": "John Doe"
  },
  "items": [
    {
      "seq": 1,
      "itemType": "PHYSICAL",
      "itemId": "P001",
      "quantity": 2,
      "amount": 50000.0,
      "taxAmount": 5000.0
    },
    {
      "seq": 2,
      "itemType": "PHYSICAL",
      "itemId": "P002",
      "quantity": 1,
      "amount": 3000.0,
      "taxAmount": 0.0
    },
    {
      "seq": 3,
      "itemType": "PHYSICAL",
      "itemId": "P003",
      "quantity": 1,
      "amount": 3000.0,
      "taxAmount": 0.0
    }
  ]
}
```
[tab:상품 단위 취소]
```json:scrollable
// 아이템(상품) 단위 취소
{
  "orderNo": "ORD20251224001",
  "totalCancelAmount": 6000.0,
  "refundAccount": {
    "accountNumber": "1234567890",
    "bankCode": "001",
    "accountHolderName": "John Doe"
  },
  "items": [
    {
      "seq": 2,
      "itemType": "PHYSICAL",
      "itemId": "P002",
      "quantity": 1,
      "amount": 3000.0,
      "taxAmount": 0.0
    },
    {
      "seq": 3,
      "itemType": "PHYSICAL",
      "itemId": "P003",
      "quantity": 1,
      "amount": 3000.0,
      "taxAmount": 0.0
    }
  ]
}
```
[tab:금액 단위 취소]
```json:scrollable
// 금액 단위 부분 취소
{
  "orderNo": "ORD20251224001",
  "totalCancelAmount": 2000.0,
  "refundAccount": {
    "accountNumber": "1234567890",
    "bankCode": "001",
    "accountHolderName": "John Doe"
  },
  "items": [
    {
      "seq": 3,
      "itemType": "PHYSICAL",
      "itemId": "P003",
      "quantity": 1,
      "amount": 2000.0,
      "taxAmount": 0.0
    }
  ]
}
```
[/tabs]

## 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     | totalProductAmount     | [type:number] [req:Yes] [desc:취소 상품 금액 합계]              |
| 0     | totalProductTaxAmount  | [type:number] [req:Yes] [desc:취소 상품 세금 금액 합계]         |
| 0     | totalDeliveryAmount    | [type:number] [req:Yes] [desc:취소 배송 금액 합계]              |
| 0     | totalDeliveryTaxAmount | [type:number] [req:Yes] [desc:취소 배송 세금 금액 합계]         |
| 0     | processedCount         | [type:number] [req:Yes] [desc:처리 건수]                        |
| 0     | returnRequestId        | [type:string] [req:Yes] [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, DELIVERY, SERVICE] |
| 1     | itemId              | [type:string] [req:Yes] [desc:상품 ID]                          |
| 1     | quantity               | [type:number] [req:Yes] [desc:취소 수량]                         |
| 1     | amount                 | [type:number] [req:Optional] [desc:취소 금액]                   |
| 1     | taxAmount              | [type:number] [req:Optional] [desc:취소 세금 금액]                |

### 3.2 Response Samples

[tabs]
[tab:전체 주문 취소]
```json:scrollable
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "1767129253908",
  "timestamp": "2025-12-30T21:14:13.909292900Z",
  "data": {
    "orderNo": "ORD20251224001",
    "totalProductAmount": 106000.0,
    "totalProductTaxAmount": 10000.0,
    "totalDeliveryAmount": 0.0,
    "totalDeliveryTaxAmount": 0.0,
    "processedCount": 3,
    "returnRequestId": "RETREQ20251224001",
    "items": [
      {
        "seq": 1,
        "itemType": "PHYSICAL",
        "itemId": "P001",
        "quantity": 2,
        "amount": 50000.0,
        "taxAmount": 5000.0
      },
      {
        "seq": 2,
        "itemType": "PHYSICAL",
        "itemId": "P002",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      },
      {
        "seq": 3,
        "itemType": "PHYSICAL",
        "itemId": "P003",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[tab:상품 단위 취소]
```json:scrollable
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "1767129253909",
  "timestamp": "2025-12-30T21:15:13.909292900Z",
  "data": {
    "orderNo": "ORD20251224001",
    "totalProductAmount": 6000.0,
    "totalProductTaxAmount": 0.0,
    "totalDeliveryAmount": 0.0,
    "totalDeliveryTaxAmount": 0.0,
    "processedCount": 2,
    "returnRequestId": "RETREQ20251224002",
    "items": [
      {
        "seq": 2,
        "itemType": "PHYSICAL",
        "itemId": "P002",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      },
      {
        "seq": 3,
        "itemType": "PHYSICAL",
        "itemId": "P003",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[tab:금액 단위 취소]
```json:scrollable
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "1767129253910",
  "timestamp": "2025-12-30T21:16:13.909292900Z",
  "data": {
    "orderNo": "ORD20251224001",
    "totalProductAmount": 2000.0,
    "totalProductTaxAmount": 0.0,
    "totalDeliveryAmount": 0.0,
    "totalDeliveryTaxAmount": 0.0,
    "processedCount": 1,
    "returnRequestId": "RETREQ20251224003",
    "items": [
      {
        "seq": 3,
        "itemType": "PHYSICAL",
        "itemId": "P003",
        "quantity": 1,
        "amount": 2000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[/tabs]