Cash Receipt Registration API

API for registering a cash receipt with the NTS.

Important Notes

A Successful API Registration Is Not the Final NTS Issuance

This API accepts the cash receipt registration request and issues an approval number. The accepted records are batch-submitted to the NTS the next day (D+1), so even if the response resultCd is 0000, you must verify the final processing result via the Issuance Error List Inquiry or Issuance Status Inquiry API on the next day.

Taxable Amount Calculation

Total transaction amount = Supply value (amt) + VAT (vat) + Service charge (svcAmt). For taxable transactions, the supply value must be greater than the VAT.

NOTE

Retain Response Values

The trTime and authNo received in the response are used for voids, status inquiries, and error checks. Store them together with the order number (transNo) in your merchant system.

When issuing with the self-issuance number (0100001234), the customer can change ownership to their own name via Hometax.
Cash receipts are batch-submitted to the NTS at 00:00 on D+1 following the request.
Issuance results can be verified via the Issuance Error List Inquiry API after 13:00 on D+1.

API Information

GET/POST/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo

Content-Type

요청application/x-www-form-urlencoded;charset=UTF-8

응답text/plain;charset=UTF-8

테스트https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo

운영https://cash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo

Request Parameters

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

└midAN(10)Alphanumeric, up to 10 bytes*Merchant ID.

Merchant ID.

*Merchant ID issued by Hecto Financial

└assortA(1)Alphabetic, up to 1 bytes*Approval type.

Approval type.

0: Approval (Registration)

└transNoAN(50)Alphanumeric, up to 50 bytes*Order number (unique merchant identifier).

Order number (unique merchant identifier).

*Unique order number managed by the merchant. Duplicate order numbers are rejected regardless of date.

└ordNmAN(30)Alphanumeric, up to 30 bytesOrderer name.

Orderer name.

└trDtAN(14)Alphanumeric, up to 14 bytes*Transaction datetime (yyyyMMddHHmmss).

Transaction datetime (yyyyMMddHHmmss).

└taxYnA(1)Alphabetic, up to 1 bytesTax type.

Tax type.

N: Taxable Y: Tax-exempt G: Mixed taxation null: Auto-calculated based on merchant account settings

*N (taxable): enter the taxable amount in amt and the VAT in vat
Y (tax-exempt): enter the tax-free amount in amt and 0 in vat
G (mixed taxation): enter the taxable + tax-free amount in amt and the VAT on the taxable portion in vat (0 VAT is also valid)
Not entered (null): if taxYn is not sent, the tax type is determined based on the registered merchant account settings and auto-calculated from amt (the total transaction amount)

└amtN(10)Numeric, up to 10 bytes*Supply value.

Supply value.

*Taxable: taxable amount; Tax-exempt: tax-free amount; Mixed: taxable + tax-free amount

└vatN(10)Numeric, up to 10 bytes*VAT.

VAT.

*Taxable: VAT amount; Tax-exempt: 0; Mixed: VAT on the taxable portion

└svcAmtN(10)Numeric, up to 10 bytesService charge.

Service charge.

└bizRegNoN(10)Numeric, up to 10 bytesSub-business registration number.

Sub-business registration number.

*When issuing under a sub-business registration number, taxYn must be provided as the sub-business's tax type.

└purposeA(1)Alphabetic, up to 1 bytes*Purpose type.

Purpose type.

0: Income deduction 1: Expense proof

*Enter 0 (income deduction) when requesting with the self-issuance number.

└identityGbA(1)Alphabetic, up to 1 bytes*Cash receipt registration number type.

Cash receipt registration number type.

1: Card number (NTS-registered card) 2: Resident registration number 3: Business registration number 4: Mobile phone number

*Enter 4 (mobile phone number) when requesting with the self-issuance number.

└identityN(18)Numeric, up to 18 bytes*Cash receipt registration number.

Cash receipt registration number.

*Enter the registration number matching the identityGb type
Enter digits only
Self-issuance number: 0100001234 (10 digits, not the 11-digit number 010-0000-1234)

└deductionTypeA(1)Alphabetic, up to 1 bytesAdditional deduction type.

Additional deduction type.

Y: Public transportation C: Cultural expenses (books, performances, sports facilities) T: Traditional market B: Books/performances at traditional market

*Enter only for the applicable additional-deduction transaction
A single business that provides cultural expense income deduction is processed as cultural expenses even if the value is omitted
If the business registration number designated for traditional market / cultural expenses at a traditional market is not registered with the NTS as an additional-deduction target, the result is returned as TSN and registered as standard income deduction; once later registered as an additional-deduction target, it is automatically applied as an additional deduction
From 2025/07/01, sports facility fees (swimming pools, gyms, etc.) are also included in cultural expenses (C): training fees 50%, entry fees and equipment rental (towels, sportswear) 100% deduction

Response Parameters

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

└resultCdAN(4)Alphanumeric, up to 4 bytes*Response code.0000

Response code.

0000: Success

└resultMsgAHN(100)Alphanumeric + Korean, up to 100 bytes*Response message.Cash receipt registration was successful.

Response message.

*Cash receipt registration was successful. (on success) / Error message (on failure, e.g., Order number is missing. - 1113)

└trTimeN(14)Numeric, up to 14 bytes*Issuance datetime.20210316144106

Issuance datetime.

*On registration: value of trDt

└authNoAN(9)Alphanumeric, up to 9 bytes*Approval number.F62624672

Approval number.

*Cash receipt approval number to be registered with the NTS (merchant must retain this value).

Request Example

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=0
&transNo=AP20210316144106
&ordNm=
&trDt=20210316144106
&taxYn=N
&amt=9090
&vat=910
&svcAmt=0
&bizRegNo=1018163383
&purpose=0
&identityGb=4
&identity=0100001234
&deductionType=

Response Example

Success

{
  "trTime": "20180401001200",
  "resultCd": "0000",
  "authNo": "F62624672",
  "resultMsg": "Cash receipt registration was successful."
}

Failure

{
  "trTime": "",
  "resultCd": "1010",
  "authNo": "",
  "resultMsg": "Amount information is incorrect."
}

Request Result Codes

Code	Message	Description
0000	Cash receipt registration was successful.	Successfully registered
1000	Cash receipt registration service is unavailable.	Not a cash receipt merchant
1010	Amount information is incorrect. Please check the card number. Please check the resident registration number. Please check the business registration number. Please check the mobile phone number.	Amount-related: incorrect amount information; Card number validation error; Resident registration number validation error; Business registration number validation error; Mobile phone number validation error
1111	Exception Message	System error
1112	Order number is missing.	transNo is empty
1113	A void with the same transNo/same amount already exists.	Duplicate void request
1114	The original transaction that was processed normally does not exist.	No original transaction found on void
1115	A previously registered transaction already exists.	Duplicate registration request
1116	The void amount exceeds the original transaction amount.	Void amount exceeded
1117	Required information is missing.	Required data missing
1118	Original transaction information for reprocessing does not exist.	No original transaction on reprocessing request
1119	This record is subject to auto-reprocessing.	Transaction is an auto-reprocessing target
1120	A reprocessing request already exists.	Duplicate reprocessing request
1121	Please check the parameters.	Parameter error
2000	Registered merchant not found. Please check your ID.	Merchant ID error

Need technical support?

Code Samples

HectoFinancial GitHub