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. We recommend webhooks for real-time processing.
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.

Issuance

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

Register the supplier’s certificate before issuing a cash receipt. Issuance fails without a registered certificate. See Certificate Registration Integration.

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

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.

{ "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": "1234567890" }

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

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.

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.

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"

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.

Webhook events - cash receipt result event payloads
Error codes - cash receipt failure codes
Authentication guide - Authorization, Supplier-Key, 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