> ## 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. We recommend webhooks for real-time processing.
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. Always check the final result via webhook or the status API.
</Info>

## Issuance

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

<Info>
  Register the supplier's certificate before issuing a cash receipt. Issuance fails without a registered certificate. See [Certificate Registration Integration](/en/api-introduction/certificate-registration).
</Info>

| Header                      | Required | Description                                                                                          |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `Authorization`             | Yes      | Use the `Basic {apiKey}` format. See the [Authentication guide](/en/api-introduction/authentication) |
| `Supplier-Key`              | Yes      | Enter the identification key for the supplier linked to `issuer.businessRegistrationNumber`          |
| `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                                |

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/cashReceipts \
  -H "Authorization: Basic {apiKey}" \
  -H "Supplier-Key: SupplierKey_bf8paz" \
  -H "Bolta-Client-Reference-Id: your-unique-reference-id" \
  -H "Content-Type: application/json" \
  -d '{
    "itemName": "Service fee",
    "issuer": {
      "businessRegistrationNumber": "5648102684",
      "organizationName": "Bolta Corporation",
      "representativeName": "M. Lee",
      "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": "1234567890" }
```

<Warning>
  Do not set `value` for `SELF`. Provide a valid `value` for `PHONE` and `BUSINESS_REGISTRATION_NUMBER`.
</Warning>

### Supplier information

Set `issuer.businessRegistrationNumber` to **the business registration number linked to `Supplier-Key`**.

| 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`                  | 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. If you omit `taxFreeAmount`, the API treats it as `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`, `REQUEST_SUCCESS`                       | In progress              |
| `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`.

## Cancellation

You can fully cancel an issued cash receipt. Partial cancellation is not supported. 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 "Supplier-Key: SupplierKey_bf8paz" \
  -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. Check the final result via webhook or the status API.
</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. Do not use this header in production (live).

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

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

## Related documents

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