Purchase API - Cancel Payment #

1. API Overview #

Purpose #

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

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 #

Item	Value
API Name	Cancel Payment
API Path	/api/v2/payment/cancel
API ID	EBP_API_232
HTTP Method	POST
Region	Global

2. Request Specification #

2.1 Request Header #

For detailed header information, please refer to the Common Headers documentation.

2.2 Request Data Schema #

depth	Field	Details & Description
0	orderNo	`string` 🔴 Required The reference value for processing (Order Number)
0	totalCancelAmount	`number` 🔴 Required Total cancellation amount (must match the sum of item amounts)
0	refundAccount	`object` ⚪ Optional Refund account information
1	accountNumber	`number` ⚪ Optional Account number
1	bankCode	`string` ⚪ Optional Bank code
1	accountHolderName	`string` ⚪ Optional Account holder name
0	items	`array` 🔴 Required List of items to cancel
1	seq	`number` 🔴 Required Sequence number
1	itemType	`string` 🔴 Required Item type e.g., PHYSICAL, DIGITAL, SUBSCRIPTION, DELIVERY, SERVICE
1	itemId	`string` 🔴 Required Item ID
1	quantity	`number` 🔴 Required Quantity to cancel
1	amount	`number` 🔴 Required Cancel amount
1	taxAmount	`number` ⚪ Optional Tax amount to cancel

Item Type Guide

PHYSICAL: Physical goods (TV, Refrigerator, etc.)

DIGITAL: Digital goods (Software, e-Gift card, etc.)

SUBSCRIPTION: Subscription fee (Appliance rental, regular care service, etc.)

DELIVERY: Shipping fee

SERVICE: Service fee (Installation, removal, etc.)

2.3 Request Examples #

Full Order Cancel

Item Cancel

Partial Amount Cancel

// 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
    }
  ]
}

// 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
    }
  ]
}

// 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
    }
  ]
}

3. Response Specification #

3.1 Response Data Schema #

depth	Field	Details & Description
-1	resultCode	`string` 🔴 Required Result code e.g., "0" for success, "EBP-A-0001" for error
-1	message	`string` 🔴 Required Result message
-1	requestId	`string` 🔴 Required Unique request identifier for tracking
-1	timestamp	`string` 🔴 Required Response timestamp in ISO 8601 format e.g., 2025-12-19T14:24:00+09:00
-1	data	`object` 🔴 Required Response data
0	orderNo	`string` 🔴 Required Order number (unique identifier)
0	totalProductAmount	`number` 🔴 Required Total amount of canceled products
0	totalProductTaxAmount	`number` 🔴 Required Total tax amount for canceled products
0	totalDeliveryAmount	`number` 🔴 Required Total amount of canceled delivery
0	totalDeliveryTaxAmount	`number` 🔴 Required Total tax amount for canceled delivery
0	processedCount	`number` 🔴 Required Number of processed items
0	returnRequestId	`string` 🔴 Required Identifier for the return request
0	items	`array` 🔴 Required List of canceled items
1	seq	`number` 🔴 Required Sequence number
1	itemId	`string` 🔴 Required Product ID
1	quantity	`number` 🔴 Required Quantity canceled
1	amount	`number` ⚪ Optional Cancel amount
1	taxAmount	`number` ⚪ Optional Tax amount canceled

3.2 Response Samples #

Full Order Cancel

Item Cancel

Partial Amount Cancel

{
  "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
      }
    ]
  }
}

{
  "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
      }
    ]
  }
}

{
  "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
      }
    ]
  }
}