> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bolta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cash Receipt Webhooks

> Describes the event types, payloads, and delivery timing for cash receipt issuance and cancellation results.

For delivery method, firewall settings, and logs, see [Webhook Events](/en/docs/api-introduction/webhook-events).

## Event Types

Cash receipt issuance and cancellation are asynchronous. The API sends the final result in one of the following events.

| Event Type                         | Description            |
| ---------------------------------- | ---------------------- |
| `CASH_RECEIPT_ISSUED`              | Issuance succeeded     |
| `CASH_RECEIPT_ISSUE_FAILED`        | Issuance failed        |
| `CASH_RECEIPT_CANCELED`            | Cancellation succeeded |
| `CASH_RECEIPT_CANCEL_FAILED`       | Cancellation failed    |
| `CASH_RECEIPT_EXTERNALLY_CANCELED` | Canceled outside Bolta |

## Payload

### Issuance Success

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cashReceiptApprovalNumber": "123456789012"
  }
}
```

| Field                            | Type   | Description                  |
| -------------------------------- | ------ | ---------------------------- |
| `eventType`                      | string | Event type                   |
| `data.issuanceKey`               | string | Issuance key                 |
| `data.cashReceiptApprovalNumber` | string | Cash receipt approval number |

### Issuance Failure

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUE_FAILED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "INVALID_RECIPIENT_IDENTIFIER",
      "message": "현금영수증 발급 수단 정보를 확인해주세요."
    }
  }
}
```

| Field                | Type   | Description                       |
| -------------------- | ------ | --------------------------------- |
| `eventType`          | string | Event type                        |
| `data.issuanceKey`   | string | Issuance key                      |
| `data.cause.code`    | string | Failure code                      |
| `data.cause.message` | string | Failure reason returned in Korean |

### Cancellation Success

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCELED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| Field                      | Type   | Description                                   |
| -------------------------- | ------ | --------------------------------------------- |
| `eventType`                | string | Event type                                    |
| `data.issuanceKey`         | string | Issuance key for the cancellation request     |
| `data.originalIssuanceKey` | string | Original issuance key of the canceled receipt |

### Cancellation Failure

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCEL_FAILED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "ORIGINAL_ISSUANCE_FAILED",
      "message": "원본 현금영수증 발행이 실패해 취소 요청을 처리할 수 없습니다."
    }
  }
}
```

| Field                      | Type   | Description                                         |
| -------------------------- | ------ | --------------------------------------------------- |
| `eventType`                | string | Event type                                          |
| `data.issuanceKey`         | string | Issuance key for the cancellation request           |
| `data.originalIssuanceKey` | string | Original issuance key of the receipt being canceled |
| `data.cause.code`          | string | Failure code                                        |
| `data.cause.message`       | string | Failure reason returned in Korean                   |

The following codes appear only in `CASH_RECEIPT_CANCEL_FAILED`.

* `ORIGINAL_ISSUANCE_FAILED`: Bolta accepted the cancellation request while the original issuance was in progress, but the original issuance later failed
* `CANCELLATION_TARGET_NOT_FOUND`: The cancellation target could not be found, was already canceled, or already had a cancellation request

### Canceled Outside Bolta

Bolta sends this event when an issued cash receipt is canceled outside Bolta (for example, on Hometax).

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_EXTERNALLY_CANCELED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| Field              | Type   | Description                                             |
| ------------------ | ------ | ------------------------------------------------------- |
| `eventType`        | string | Event type                                              |
| `data.issuanceKey` | string | Issuance key of the cash receipt canceled outside Bolta |

## Webhook Delivery Time

| Event                                                 | Delivery time                                |
| ----------------------------------------------------- | -------------------------------------------- |
| `CASH_RECEIPT_ISSUED`                                 | After the issuance result is final           |
| `CASH_RECEIPT_ISSUE_FAILED`                           | After the issuance failure is final          |
| `CASH_RECEIPT_CANCELED`, `CASH_RECEIPT_CANCEL_FAILED` | After the cancellation result is final       |
| `CASH_RECEIPT_EXTERNALLY_CANCELED`                    | After the external cancellation is confirmed |

A test key (`test_`) records the final status as soon as the request is processed, and Bolta sends the webhook no sooner than 10 seconds after accepting the request.

You can receive the same event more than once. Process webhooks idempotently with `eventType` and `issuanceKey`.

<Warning>
  `202 Accepted` only means Bolta accepted the request. Treat a cash receipt as unconfirmed until the status API returns `ISSUED` or you receive `CASH_RECEIPT_ISSUED`.
</Warning>

## When a Webhook Does Not Arrive

Check with [Retrieve Cash Receipt Status](/en/api-reference/cash-receipt/retrieve-cash-receipt-status). For a live request that remains in progress or awaits issuance-result confirmation, check again after 17:00 KST on the following day.