Issuing Cash Receipts

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.

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

202 means that the API accepted the request. It does not confirm issuance or cancellation.

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.

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.

Register the supplier with the Register Issuer API, then register its certificate. See Certificate Registration Integration.

Header	Required	Description
`Authorization`	Yes	Use the `Basic {apiKey}` format. See the Authentication guide
`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

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.

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.

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

{ "type": "SELF" }

{ "type": "PHONE", "value": "010-1234-5678" }

{ "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.

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.

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"

Set the cancellation request’s Bolta-Client-Reference-Id to a different value from the issuance request.

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.

-H "Bolta-Webhook-Test-Code: INVALID_RECIPIENT_IDENTIFIER"

For the list of failure codes, see Error codes.

Cash receipt webhooks - cash receipt result event payloads
Error codes - cash receipt failure codes
Authentication guide - Authorization, Bolta-Client-Reference-Id
API Reference - request/response schemas

API Introduction

API Guides

Use Cases

SDK / No-code

Processing flow

Pricing

Issuance

Recipient types

Supplier information

Amount

Status

Cancellation

Reproducing a failure webhook (testing)

​Processing flow

​Pricing

​Issuance

​Recipient types

​Supplier information

​Amount

​Status

​Cancellation

​Reproducing a failure webhook (testing)

​Related documents

Processing flow

Pricing

Issuance

Recipient types

Supplier information

Amount

Status

Cancellation

Reproducing a failure webhook (testing)

Related documents