> ## 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.

# Issuing Cash Receipts

> The flow and input rules for the cash receipt issuance, status, and cancellation APIs.

## Processing flow

Cash receipt issuance and cancellation are asynchronous. The API first returns `202 Accepted` and an `issuanceKey`. Check the final result via webhook or the status API.

1. **Webhook** - the API sends a result event to your registered URL. Register a webhook to receive results without polling.
2. **Status API** - query the current status with `Bolta-Client-Reference-Id`.

<Info>
  `202` means that the API accepted the request. It does not confirm issuance or cancellation.
</Info>

Final status and webhook timing depend on the key and the processing result.

* **Test key** - You can retrieve the final status as soon as the request is processed. The automatic webhook is sent no sooner than 10 seconds after the API accepts the request.
* **Live key** - A request that remains in progress or needs its issuance result confirmed can be finalized after 17:00 KST on the following day. Bolta sends the webhook after the final status changes.

For exact timing, see [Webhook Delivery Time](/en/docs/api-introduction/webhook-cash-receipt#webhook-delivery-time).

## Pricing

Cash receipt issuance deducts no points. For high-volume issuance, contact your Bolta representative.

## Issuance

To issue a cash receipt, call `POST /v1/cashReceipts`.

<Info>
  Register the supplier with the [Register Issuer API](/en/api-reference/issuer/register-issuer), then register its certificate. See [Certificate Registration Integration](/en/docs/api-introduction/certificate-registration).
</Info>

| Header                      | Required | Description                                                                                               |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `Authorization`             | Yes      | Use the `Basic {apiKey}` format. See the [Authentication guide](/en/docs/api-introduction/authentication) |
| `Bolta-Client-Reference-Id` | Yes      | Enter a client reference ID between 1 and 255 characters to use as the idempotency key                    |
| `Bolta-Webhook-Test-Code`   | No       | Enter this header only to reproduce a failure webhook with a test key                                     |

<Info>
  If the same API key retries with the same client reference ID, request content, and request type, the API returns `202 Accepted` with the existing request's `issuanceKey`. If the request content or type differs, the API returns `409 Conflict` with `IDEMPOTENCY_CONFLICT`. This rule applies to both issuance and cancellation requests.
</Info>

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/cashReceipts \
  -H "Authorization: Basic {apiKey}" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id" \
  -H "Content-Type: application/json" \
  -d '{
    "itemName": "Service fee",
    "issuer": {
      "businessRegistrationNumber": "1234567890",
      "organizationName": "Supplier Company",
      "representativeName": "Jane Doe",
      "telephone": "02-1234-5678"
    },
    "recipient": { "type": "PHONE", "value": "010-1234-5678" },
    "amount": { "supplyAmount": 100, "vatAmount": 10, "taxFreeAmount": 0 }
  }'
```

The API returns an issuance key (`issuanceKey`). Store it for cancellation requests.

```json theme={"dark"}
{ "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I" }
```

### Recipient types

Set `recipient.value` based on `recipient.type`.

| Type (`type`)                  | Meaning                                             | `value`                                                 |
| ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- |
| `SELF`                         | Self-issuance (issue without recipient information) | Omitted (or `null`)                                     |
| `PHONE`                        | Mobile phone number                                 | A `010-1234-5678` format mobile phone number            |
| `BUSINESS_REGISTRATION_NUMBER` | Business registration number (proof of expenditure) | A 10-digit business registration number without hyphens |

```json theme={"dark"}
{ "type": "SELF" }
```

```json theme={"dark"}
{ "type": "PHONE", "value": "010-1234-5678" }
```

```json theme={"dark"}
{ "type": "BUSINESS_REGISTRATION_NUMBER", "value": "0987654321" }
```

### Supplier information

| Field                        | Rule                                                                                                                                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `businessRegistrationNumber` | A 10-digit business registration number without hyphens                                                                                                                                                                         |
| `organizationName`           | Organization name. Up to 20 characters                                                                                                                                                                                          |
| `representativeName`         | Representative name. Up to 10 characters                                                                                                                                                                                        |
| `telephone`                  | An `010-1234-5678` or `070-1234-5678` number, a landline number with an area code, a 3- or 4-digit exchange, and a 4-digit subscriber number, or a representative number with a 15xx, 16xx, or 18xx prefix followed by 4 digits |

### Amount

Set each field in `amount` to no more than `9,999,999,999`. The total (`supplyAmount + vatAmount + taxFreeAmount`) must also be no greater than `9,999,999,999` and greater than 0.

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| `supplyAmount`  | Supply amount                             |
| `vatAmount`     | VAT amount                                |
| `taxFreeAmount` | Tax-free amount (optional, defaults to 0) |

## Status

Query the processing status with the `Bolta-Client-Reference-Id` used in the issuance or cancellation request.

```bash theme={"dark"}
curl "https://xapi.bolta.io/v1/cashReceipts/status?clientReferenceId=your-unique-reference-id" \
  -H "Authorization: Basic {apiKey}"
```

Use `status` to determine success or failure. If the request failed, check `failure` for details.

| status                                             | Meaning                                 |
| -------------------------------------------------- | --------------------------------------- |
| `PENDING`                                          | Accepted, processing not started        |
| `REQUEST_SUCCESS`                                  | Request delivered. Not the final result |
| `ISSUED`                                           | Issuance succeeded                      |
| `CANCELED`                                         | Cancellation succeeded                  |
| `EXTERNALLY_CANCELED`                              | Canceled outside Bolta                  |
| `REQUEST_FAILURE`, `ISSUE_FAILED`, `CANCEL_FAILED` | Failed (check `failure`)                |

After successful issuance, the API also returns the cash receipt approval number in `cashReceiptApprovalNumber`.

Do not resubmit a live-key request that stays `PENDING` or `REQUEST_SUCCESS`.

## Cancellation

You can fully cancel a cash receipt whose issuance processing was accepted. You can cancel it before its Hometax issuance is final, but not while the original request is `PENDING`. Set `{issuanceKey}` in the path to the `issuanceKey` from the issuance response.

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/cashReceipts/MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I/cancellation \
  -H "Authorization: Basic {apiKey}" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id-cancel"
```

<Info>
  Set the cancellation request's `Bolta-Client-Reference-Id` to a different value from the issuance request.
</Info>

## Reproducing a failure webhook (testing)

When calling the issuance or cancellation API with a test key, set the `Bolta-Webhook-Test-Code` header to a failure code. The API sends the corresponding failure webhook.

```bash theme={"dark"}
-H "Bolta-Webhook-Test-Code: INVALID_RECIPIENT_IDENTIFIER"
```

For the list of failure codes, see [Error codes](/en/docs/api-introduction/error-codes#cash-receipt-webhook).

## Related documents

* [Cash receipt webhooks](/en/docs/api-introduction/webhook-cash-receipt) - cash receipt result event payloads
* [Error codes](/en/docs/api-introduction/error-codes) - cash receipt failure codes
* [Authentication guide](/en/docs/api-introduction/authentication) - `Authorization`, `Bolta-Client-Reference-Id`
* [API Reference](/en/api-reference/cash-receipt/issue-cash-receipt) - request/response schemas