구매 API - 결제 취소 #

1. API Overview #

Purpose #

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

참고:

주문 단위, 상품 단위, 혹은 특정 금액 단위로 취소가 가능합니다.

매입 전 취소는 전액 취소만 가능합니다. 부분 취소를 원할 경우에는 매입을 완료한 후 부분 취소를 요청해야 합니다.

Details #

항목	값
API Name	결제 취소
API Path	/api/v2/payment/cancel
API ID	EBP_API_232
HTTP Method	POST
Region	Global

2. Request Specification #

2.1 Request Header #

상세한 헤더 정보는 Common Headers 문서를 참고하세요.

2.2 Request Data Schema #

depth	Field	Details & Description
0	orderNo	`string` 🔴 Required 처리의 기준이 되는 값 (주문번호)
0	totalCancelAmount	`number` 🔴 Required 총 취소 금액 (items의 amount 합계와 일치해야 함)
0	refundAccount	`object` ⚪ Optional -
1	accountNumber	`number` ⚪ Optional 계좌번호
1	bankCode	`string` ⚪ Optional 은행코드
1	accountHolderName	`string` ⚪ Optional 예금주명
0	items	`array` 🔴 Required -
1	seq	`number` 🔴 Required 일련번호
1	itemType	`string` 🔴 Required 상품 유형. 정산 관리를 위해 세분화된 유형을 입력합니다. e.g., PHYSICAL, DIGITAL, DELIVERY, SERVICE
1	itemId	`string` 🔴 Required 상품 ID
1	quantity	`number` 🔴 Required 상품 갯수
1	amount	`number` 🔴 Required 취소금액
1	taxAmount	`number` ⚪ Optional 세금금액

상품 유형 가이드

PHYSICAL: 실물 본품 (TV, 냉장고 등)

DIGITAL: 디지털 상품 (소프트웨어, e-기프트카드 등)

SUBSCRIPTION: 구독비 (가전 렌탈, 정기 케어서비스 등)

DELIVERY: 배송비

SERVICE: 서비스비 (설치비, 철거비 등)

2.3 Request Examples #

주문 단위 취소

상품 단위 취소

금액 단위 취소

// 전체 주문 취소
{
  "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
    }
  ]
}

// 아이템(상품) 단위 취소
{
  "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
    }
  ]
}

// 금액 단위 부분 취소
{
  "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 결과 코드 (성공 "0", 에러 시 "EBP-A-0001" 등)
-1	message	`string` 🔴 Required 결과 메시지 (성공 또는 에러 상세)
-1	requestId	`string` 🔴 Required 추적을 위한 고유 요청 ID
-1	timestamp	`string` 🔴 Required ISO 8601 형식의 응답 타임스탬프 e.g., 2025-12-19T14:24:00+09:00
-1	data	`object` 🔴 Required 응답 데이터
0	orderNo	`string` 🔴 Required 주문번호 (처리의 기준이 되는 값)
0	totalProductAmount	`number` 🔴 Required 취소 상품 금액 합계
0	totalProductTaxAmount	`number` 🔴 Required 취소 상품 세금 금액 합계
0	totalDeliveryAmount	`number` 🔴 Required 취소 배송 금액 합계
0	totalDeliveryTaxAmount	`number` 🔴 Required 취소 배송 세금 금액 합계
0	processedCount	`number` 🔴 Required 처리 건수
0	returnRequestId	`string` 🔴 Required 반품 신청 번호
0	items	`array` 🔴 Required 취소 상품 목록
1	seq	`number` 🔴 Required 일련번호
1	itemType	`string` 🔴 Required 상품 유형 e.g., PHYSICAL, DIGITAL, DELIVERY, SERVICE
1	itemId	`string` 🔴 Required 상품 ID
1	quantity	`number` 🔴 Required 취소 수량
1	amount	`number` ⚪ Optional 취소 금액
1	taxAmount	`number` ⚪ Optional 취소 세금 금액

3.2 Response Samples #

전체 주문 취소

상품 단위 취소

금액 단위 취소

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

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

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