Processing flow
Cash receipt issuance and cancellation are asynchronous. The API first returns202 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.
- 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.
Pricing
Cash receipt issuance deducts no points.Issuance
To issue a cash receipt, callPOST /v1/cashReceipts.
Register the supplier with the Register Issuer API, then register its certificate. See Certificate Registration Integration.
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.issuanceKey). Store it for cancellation requests.
Recipient types
Setrecipient.value based on recipient.type.
For
PHONE, also set the issuance purpose in recipient.purpose.
For
SELF and BUSINESS_REGISTRATION_NUMBER, the type sets the purpose. If you include purpose with either type, the API returns 400 Bad Request.
Supplier information
Amount
Set each field inamount 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.
Status
Query the processing status with theBolta-Client-Reference-Id used in the issuance or cancellation request.
status to determine success or failure. If the request failed, check failure for details.
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. Set{issuanceKey} in the path to the issuanceKey from the issuance response.
You cannot cancel while the original request is PENDING. The API returns 409 with ORIGINAL_ISSUANCE_PENDING. Request again after its status changes. If the original already has a cancellation request in progress or completed, the API returns 409 with CANCELLATION_ALREADY_REQUESTED. A new client reference ID gets the same response, so check the existing cancellation with the status API.
If the original was fully or partially canceled outside Bolta (for example, on Hometax), the API still accepts the cancellation request and returns 202 Accepted. The request then ends as CANCEL_FAILED with the failure code CANCELLATION_TARGET_NOT_FOUND. Check it in the status response’s failure.code or the webhook’s data.cause.code. The same applies when the original is already EXTERNALLY_CANCELED.
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 theBolta-Webhook-Test-Code header to a failure code. The API sends the corresponding failure webhook.
Related documents
- 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
