---
title: 주문 취소
description: POST /v2/invoices/{id}/cancel 로 결제 대기나 만료 주문을 취소해요.
sidebar:
  order: 6
  badge: POST
---

```http
POST /v2/invoices/{id}/cancel
```

결제 대기(`PENDING`)나 만료(`EXPIRED`) 주문을 취소해요. 취소한 주문에는 입금이 매칭되지 않고, 같은 입금자명과 금액으로 새 주문을 만들 수 있어요. 취소한 주문도 목록과 단건 조회에 `CANCELED` 상태로 남아요.

취소하면 v2 웹훅에는 [`invoice.canceled`](/api-reference/webhooks/invoice-canceled), v1 웹훅에는 [`invoice.deleted`](/api-reference/v1/webhooks/invoice-deleted)가 가요. [카페24 연동](/cafe24)으로 만든 주문을 취소해도 카페24 주문은 취소하지 않아요.

결제 완료된 주문은 취소할 수 없어요. 대시보드 **입금 내역**에서 매칭을 해제하면 주문이 결제 대기로 돌아가고, 그다음 취소할 수 있어요.

v1 API의 [주문 삭제](/api-reference/v1/invoices/delete)와 같은 일을 해요.

## 경로 파라미터

| 파라미터 | 타입 | 설명 |
| --- | --- | --- |
| `id` | string | 취소할 주문 ID예요. `ivc_`로 시작해요. |

## 요청 본문

본문은 보내지 않아도 돼요.

| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `reason` | string | | 취소 사유예요. 200자까지예요. 대시보드와 `cancelReason`에 보여요. |

## 요청 예시

```bash cURL
curl -X POST https://api.paysync.kr/v2/invoices/ivc_a1b2c3d4e5f6g7h8i9j0k1l2/cancel \
  -H "Authorization: Bearer $PAYSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "고객 요청으로 주문 취소" }'
```

```js Node.js
const res = await fetch(`https://api.paysync.kr/v2/invoices/${invoiceId}/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ reason: "고객 요청으로 주문 취소" }),
});
const { code, data } = await res.json();
```

```python Python
import os
import requests

res = requests.post(
    f"https://api.paysync.kr/v2/invoices/{invoice_id}/cancel",
    headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
    json={"reason": "고객 요청으로 주문 취소"},
)
print(res.json())
```

## 응답

`status`가 `CANCELED`로 바뀐 [주문 객체](/api-reference/invoices/get#주문-객체)가 와요.

```json 200 OK
{
  "code": "10001",
  "data": {
    "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
    "number": 1043,
    "status": "CANCELED",
    "canceledAt": 1777350000,
    "cancelReason": "고객 요청으로 주문 취소",
    "canceledBy": { "type": "API_KEY", "accountId": null, "apiKeyId": "apk_k3l4m5n6o7p8q9r0s1t2u3v4", "name": "쇼핑몰 서버" },
    "...": "..."
  }
}
```

## 오류

| HTTP | `code` | 발생 조건 |
| --- | --- | --- |
| 401 | `290006` | API 키가 올바르지 않아요. |
| 403 | `80002` | [API 키의 계좌 범위](/api-reference#api-키-계좌-제한) 밖의 주문이에요. |
| 403 | `290007` | 읽기 전용 API 키예요. |
| 404 | `20014` | 주문이 없어요. |
| 409 | `220011` | 이미 결제 완료됐거나 취소된 주문이에요. |
| 422 | `30007` | JSON 본문을 읽을 수 없어요. |
| 422 | `220001` | 주문 ID 형식이 틀렸어요. |
| 422 | `220020` | `reason`이 200자를 넘어요. |