# Purchase API - Cancel Payment

## 1. API Overview

### Purpose

[context]
This API handles payment cancellation requests.<br>It processes cancellations based on the order number and includes refund account details when necessary.<br>The request may contain item-level cancellation details and corresponding amounts.<br>After processing the cancellation, the API returns the result to the merchant to ensure a secure refund process.
[/context]

> **Note**: 
> - Cancellation can be processed at the order level, product level, or for a specific amount.
> - **Cancellations before capture** can only be processed as full cancellations. If a partial cancellation is required, it must be requested after the capture has been completed.

### Details

[table:key-value]
| Item            | Value                  |
| :-------------- | :--------------------- |
| **API Name**    | Cancel Payment         |
| **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:The reference value for processing (Order Number)]                                             |
| 0     | totalCancelAmount | [type:number] [req:Yes] [desc:Total cancellation amount (must match the sum of item amounts)]                                |
| 0     | refundAccount     | [type:object] [req:Optional] [desc:Refund account information]                                                               |
| 1     | accountNumber     | [type:number] [req:Optional] [desc:Account number]                                                                           |
| 1     | bankCode          | [type:string] [req:Optional] [desc:Bank code]                                                                                |
| 1     | accountHolderName | [type:string] [req:Optional] [desc:Account holder name]                                                                      |
| 0     | items             | [type:array] [req:Yes] [desc:List of items to cancel]                                                                        |
| 1     | seq               | [type:number] [req:Yes] [desc:Sequence number]                                                                               |
| 1     | itemType          | [type:string] [req:Yes] [desc:Item type] [eg:PHYSICAL, DIGITAL, SUBSCRIPTION, DELIVERY, SERVICE] |
| 1     | itemId            | [type:string] [req:Yes] [desc:Item ID]                                                                                       |
| 1     | quantity          | [type:number] [req:Yes] [desc:Quantity to cancel]                                                                            |
| 1     | amount            | [type:number] [req:Yes] [desc:Cancel amount]                                                                                 |
| 1     | taxAmount         | [type:number] [req:Optional] [desc:Tax amount to cancel]                                                                     |

@@include:item-type.md@@

### 2.3 Request Examples

[tabs]
[tab:Full Order Cancel]
```json:scrollable
// Full order cancellation
{
  "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:Item Cancel]
```json:scrollable
// Item-level cancellation
{
  "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:Partial Amount Cancel]
```json:scrollable
// Partial cancellation by amount
{
  "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:Response data]                                 |
| 0     | orderNo                | [type:string] [req:Yes] [desc:Order number (unique identifier)]              |
| 0     | totalProductAmount     | [type:number] [req:Yes] [desc:Total amount of canceled products]             |
| 0     | totalProductTaxAmount  | [type:number] [req:Yes] [desc:Total tax amount for canceled products]        |
| 0     | totalDeliveryAmount    | [type:number] [req:Yes] [desc:Total amount of canceled delivery]             |
| 0     | totalDeliveryTaxAmount | [type:number] [req:Yes] [desc:Total tax amount for canceled delivery]        |
| 0     | processedCount         | [type:number] [req:Yes] [desc:Number of processed items]                     |
| 0     | returnRequestId        | [type:string] [req:Yes] [desc:Identifier for the return request]             |
| 0     | items                  | [type:array] [req:Yes] [desc:List of canceled items]                         |
| 1     | seq                    | [type:number] [req:Yes] [desc:Sequence number]                               |
| 1     | itemId              | [type:string] [req:Yes] [desc:Product ID]                                    |
| 1     | quantity               | [type:number] [req:Yes] [desc:Quantity canceled]                             |
| 1     | amount                 | [type:number] [req:Optional] [desc:Cancel amount]                            |
| 1     | taxAmount              | [type:number] [req:Optional] [desc:Tax amount canceled]                      |

### 3.2 Response Samples

[tabs]
[tab:Full Order Cancel]
```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,
        "itemId": "P001",
        "quantity": 2,
        "amount": 50000.0,
        "taxAmount": 5000.0
      },
      {
        "seq": 2,
        "itemId": "P002",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      },
      {
        "seq": 3,
        "itemId": "P003",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[tab:Item Cancel]
```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,
        "itemId": "P002",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      },
      {
        "seq": 3,
        "itemId": "P003",
        "quantity": 1,
        "amount": 3000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[tab:Partial Amount Cancel]
```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,
        "itemId": "P003",
        "quantity": 1,
        "amount": 2000.0,
        "taxAmount": 0.0
      }
    ]
  }
}
```
[/tabs]