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. Always check the final result via webhook or the status API.

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 - Some results are finalized quickly. 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 result webhook after the final status changes, so it does not guarantee receipt exactly at 17:00 KST. For exact timing, see Webhook Delivery Time.

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

Do not set value for SELF. Provide a valid value for PHONE and BUSINESS_REGISTRATION_NUMBER.

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

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. With a test key, the status can become final after the request is processed before the automatic webhook arrives at least 10 seconds later.

status	Meaning
`PENDING`	The API accepted the request and has not started processing it. Do not send the same request again.
`REQUEST_SUCCESS`	Request delivery completed. It does not confirm 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 just because it remains PENDING or REQUEST_SUCCESS. A request that remains in progress or needs its issuance result confirmed can be finalized after 17:00 KST on the following day. Check the final result via the status API or webhook.

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. Partial cancellation is not supported. 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. Check the final result via webhook or the status API.

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

-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

Issuance

Recipient types

Supplier information

Amount

Status

Cancellation

Reproducing a failure webhook (testing)

​Processing flow

​Issuance

​Recipient types

​Supplier information

​Amount

​Status

​Cancellation

​Reproducing a failure webhook (testing)

​Related documents

Processing flow

Issuance

Recipient types

Supplier information

Amount

Status

Cancellation

Reproducing a failure webhook (testing)

Related documents