헥토파이낸셜 개발자센터
ProductsProducts
Payment Gateway
Cards, bank & digital wallets
My Bank Pay
Open banking debit
Easy Cash Payment
Stored-account payments
White-Label Payments
White-label checkout
Cash Receipt
Firm Banking
VAN Virtual Account
Prepaid Wallet
Integrate with LLMs
MCP server & AI chatbot
API & SDKAPI & SDK
Payment Gateway
Cards, bank & digital wallets
My Bank Pay
Open banking debit
Easy Cash Payment
Stored-account payments
White-Label Payments
White-label checkout
Cash Receipt
Firm Banking
VAN Virtual Account
Prepaid Wallet
블로그Blog
Service Status
Payment Gateway
My Bank Pay
Easy Cash Payment
White-Label Payments
Cash Receipt
Firm Banking
VAN Virtual Account
Prepaid Wallet
Integrate with LLMs
MCP 서버 및 AI 챗봇
Payment Gateway
My Bank Pay
Easy Cash Payment
White-Label Payments
Cash Receipt
Firm Banking
VAN Virtual Account
Prepaid Wallet
Blog
Technical blog & news
Service Status
Incidents and scheduled maintenance
Payment Gateway
Before You BeginServers & NetworkIntegration OverviewWebhooksCancellations & RefundsGo Live
Checkout IntegrationJavaScript SDKForm-Based Checkout Integration
Credit Card CheckoutCredit Card Direct APICredit Card WebhookCredit Card Deferred CaptureRegister Card (Billkey Checkout)Charge with Payment TokenDelete Payment TokenCancel Charge
Bank Transfer CheckoutBank Transfer WebhookBank Transfer Deferred CaptureCancel Bank Transfer
Virtual Account CheckoutVirtual Account Deposit WebhookIssue Virtual AccountFixed/Unlimited Virtual AccountModify Virtual AccountCancel Virtual AccountDeposit LookupRefund Virtual AccountSimulate Deposit
010 Virtual Account Overview010 Virtual Account CheckoutPhone Ownership Verification — RequestPhone Ownership Verification — ConfirmDuplicate Amount CheckIssue 010 Virtual AccountCancel 010 Virtual AccountRefund 010 Virtual Account010 Virtual Account Deposit WebhookSimulate 010 Deposit
Mobile Payment CheckoutMobile Payment WebhookMobile Payment — Two-Step CaptureMobile Recurring PaymentCancel Mobile PaymentRefund Mobile Payment
Gift Card CheckoutGift Card WebhookCancel Gift Card Payment
T-money CheckoutT-money WebhookCancel T-money Payment
Point Damoa CheckoutPoint Damoa WebhookPoint Damoa Deferred CaptureCancel Point Damoa Payment
Digital Wallets OverviewPAYCO CheckoutPAYCO SandboxSamsung Pay CheckoutKakaoPay CheckoutNaverPay CheckoutTossPay CheckoutDigital Wallet WebhookCancel Digital Wallet PaymentWallet Recurring PaymentSubscription StatusCancel Subscription
Real-time Transaction LookupReceipt (Sales Slip) Inquiry (No Auth)Receipt (Sales Slip) Inquiry (Auth)Transaction ReconciliationSettlement ReconciliationSub-Merchant RegistrationPreferential Settlement (SME)SME Refund Adjustment
Error CodesCard Issuer CodesBank CodesPayment Method CodesVirtual Account Bank Codes
My Bank Pay
Before You BeginServers & NetworkIntegration Overview
Checkout SDK
My Bank Pay — AuthenticateMy Bank Pay — CaptureMy Bank Pay — CancelMy Bank Pay — Network Cancel
Transaction Result LookupTransaction HistoryCash Receipt Lookup
Create Recurring TokenCharge via Recurring TokenCancel Subscription
Error CodesBank CodesBank Maintenance Schedule
Easy Cash Payment
Before You BeginServers & NetworkFirm Banking Integration Flow
Mobile Identity Verification — RequestMobile Identity Verification — ConfirmAccount Holder Name Lookup IAccount Holder Name Lookup IIAccount Holder Name (with Amount)Account Ownership VerificationAccount Ownership — RequestAccount Ownership — ConfirmIVR Verification — RequestIVR Verification — ConfirmOwnership Verification HistoryPayment PIN Verification
Register AccountDeregister AccountSelf-Service Account RegistrationKFTC Deregistered Account Lookup
Capture PaymentCancel / Refund PaymentSend RemittanceRemittance Account Balance
Create Recurring TokenCharge via Recurring TokenCancel SubscriptionSubscription DetailsSubscription History
Transaction Result LookupTransaction HistoryAccount ListSupported BanksBank Maintenance CheckOwnership Verification Bank MaintenanceConnectivity Test
Before You BeginServers & NetworkOpen Banking Integration Flow
Register AccountRegister Open Banking AccountDeregister Open Banking Service
Capture PaymentCancel PaymentSend Remittance
Submit Refund ClaimRefund Claim Status
Transaction Result LookupTransaction HistoryAccount ListWithdrawal Limit
Decline Code ReferenceBank Code ReferenceBank Maintenance Schedule
White-Label Payments
Before You BeginServers & NetworkIntegration Overview
Payment CheckoutCapture PaymentCancellations & Refunds
Inquiry
Error CodesBank CodesBank Maintenance Schedule
Cash Receipt
Before You BeginServers & NetworkIntegration Overview
Issue Cash ReceiptCancel Cash Receipt
Issuance Error LookupIssuance Status Lookup
Reprocessing RegistrationReprocessing Result Lookup
Reference
Firm Banking
Before You BeginIntegration Overview
Connection Management
Interbank TransferCollection TransferCollection Account SetupReserve Transfer (SC Bank)Trust Deposit (Woori Bank)
Transfer Failure WebhookTransaction Statement WebhookBill Statement WebhookBill Statement — Missing SequenceReserve Transfer Result Webhook (SC)Transfer Failure — Missing SequenceTransaction Detail — Missing Sequence
Account Holder Name LookupTransfer Result LookupBalance LookupReserve Transfer Result (SC)Auto Transfer Result (SC)
Transfer ReconciliationCollection ReconciliationWebhook Delivery Status
Connection Management
FX RemittanceCancel FX RemittanceFX Remittance Result WebhookFX Remittance Result — Missing SequenceFX Remittance (MX)FX Remittance Result Webhook (MX)FX Remittance — Missing Sequence (MX)
FX Same-Bank Holder LookupFX Account Holder LookupExchange Rate LookupExchange Rate Lookup (KEB)FX Remittance Result LookupFX Balance Lookup
FX Remittance ReconciliationFX Auto Transfer ReconciliationFX Same-Bank Remittance Reconciliation
FX Transaction Statement WebhookFX Transaction Statement — Missing Sequence
VAN Virtual Account
Getting Started with VAVSCommunication and Message FormatCommon Header
Recipient InquiryDeposit and Cancellation
RemittanceDeposit Balance Inquiry
Reconciliation
Account Holder InquiryActual Depositor NotificationActual Depositor FileMissing Actual Depositor InquiryWithdrawal Account Registration
Bank CodesResponse CodesChannel CodesBank Operating Hours
Prepaid Wallet
Before You BeginServers & NetworkIntegration Overview
Member Registration UIMy Account UI
Spend BalanceVoid SpendSend Money GiftRevoke Points
Balance LookupBalance OptionsBalance DetailsBalance by Top-upWithdrawable BalanceTransaction ListTransaction DetailsTransaction Details by StoreMember DetailsExpiring PointsTop-up Methods
Top-upCancel Top-upWithdraw FundsPending Withdrawal
Error CodesTransaction Type Codes

Tools

Encryption Test
Payment Gateway
Before You BeginServers & NetworkIntegration OverviewWebhooksCancellations & RefundsGo Live
Checkout IntegrationJavaScript SDKForm-Based Checkout Integration
Credit Card CheckoutCredit Card Direct APICredit Card WebhookCredit Card Deferred CaptureRegister Card (Billkey Checkout)Charge with Payment TokenDelete Payment TokenCancel Charge
Bank Transfer CheckoutBank Transfer WebhookBank Transfer Deferred CaptureCancel Bank Transfer
Virtual Account CheckoutVirtual Account Deposit WebhookIssue Virtual AccountFixed/Unlimited Virtual AccountModify Virtual AccountCancel Virtual AccountDeposit LookupRefund Virtual AccountSimulate Deposit
010 Virtual Account Overview010 Virtual Account CheckoutPhone Ownership Verification — RequestPhone Ownership Verification — ConfirmDuplicate Amount CheckIssue 010 Virtual AccountCancel 010 Virtual AccountRefund 010 Virtual Account010 Virtual Account Deposit WebhookSimulate 010 Deposit
Mobile Payment CheckoutMobile Payment WebhookMobile Payment — Two-Step CaptureMobile Recurring PaymentCancel Mobile PaymentRefund Mobile Payment
Gift Card CheckoutGift Card WebhookCancel Gift Card Payment
T-money CheckoutT-money WebhookCancel T-money Payment
Point Damoa CheckoutPoint Damoa WebhookPoint Damoa Deferred CaptureCancel Point Damoa Payment
Digital Wallets OverviewPAYCO CheckoutPAYCO SandboxSamsung Pay CheckoutKakaoPay CheckoutNaverPay CheckoutTossPay CheckoutDigital Wallet WebhookCancel Digital Wallet PaymentWallet Recurring PaymentSubscription StatusCancel Subscription
Real-time Transaction LookupReceipt (Sales Slip) Inquiry (No Auth)Receipt (Sales Slip) Inquiry (Auth)Transaction ReconciliationSettlement ReconciliationSub-Merchant RegistrationPreferential Settlement (SME)SME Refund Adjustment
Error CodesCard Issuer CodesBank CodesPayment Method CodesVirtual Account Bank Codes
My Bank Pay
Before You BeginServers & NetworkIntegration Overview
Checkout SDK
My Bank Pay — AuthenticateMy Bank Pay — CaptureMy Bank Pay — CancelMy Bank Pay — Network Cancel
Transaction Result LookupTransaction HistoryCash Receipt Lookup
Create Recurring TokenCharge via Recurring TokenCancel Subscription
Error CodesBank CodesBank Maintenance Schedule
Easy Cash Payment
Before You BeginServers & NetworkFirm Banking Integration Flow
Mobile Identity Verification — RequestMobile Identity Verification — ConfirmAccount Holder Name Lookup IAccount Holder Name Lookup IIAccount Holder Name (with Amount)Account Ownership VerificationAccount Ownership — RequestAccount Ownership — ConfirmIVR Verification — RequestIVR Verification — ConfirmOwnership Verification HistoryPayment PIN Verification
Register AccountDeregister AccountSelf-Service Account RegistrationKFTC Deregistered Account Lookup
Capture PaymentCancel / Refund PaymentSend RemittanceRemittance Account Balance
Create Recurring TokenCharge via Recurring TokenCancel SubscriptionSubscription DetailsSubscription History
Transaction Result LookupTransaction HistoryAccount ListSupported BanksBank Maintenance CheckOwnership Verification Bank MaintenanceConnectivity Test
Before You BeginServers & NetworkOpen Banking Integration Flow
Register AccountRegister Open Banking AccountDeregister Open Banking Service
Capture PaymentCancel PaymentSend Remittance
Submit Refund ClaimRefund Claim Status
Transaction Result LookupTransaction HistoryAccount ListWithdrawal Limit
Decline Code ReferenceBank Code ReferenceBank Maintenance Schedule
White-Label Payments
Before You BeginServers & NetworkIntegration Overview
Payment CheckoutCapture PaymentCancellations & Refunds
Inquiry
Error CodesBank CodesBank Maintenance Schedule
Cash Receipt
Before You BeginServers & NetworkIntegration Overview
Issue Cash ReceiptCancel Cash Receipt
Issuance Error LookupIssuance Status Lookup
Reprocessing RegistrationReprocessing Result Lookup
Reference
Firm Banking
Before You BeginIntegration Overview
Connection Management
Interbank TransferCollection TransferCollection Account SetupReserve Transfer (SC Bank)Trust Deposit (Woori Bank)
Transfer Failure WebhookTransaction Statement WebhookBill Statement WebhookBill Statement — Missing SequenceReserve Transfer Result Webhook (SC)Transfer Failure — Missing SequenceTransaction Detail — Missing Sequence
Account Holder Name LookupTransfer Result LookupBalance LookupReserve Transfer Result (SC)Auto Transfer Result (SC)
Transfer ReconciliationCollection ReconciliationWebhook Delivery Status
Connection Management
FX RemittanceCancel FX RemittanceFX Remittance Result WebhookFX Remittance Result — Missing SequenceFX Remittance (MX)FX Remittance Result Webhook (MX)FX Remittance — Missing Sequence (MX)
FX Same-Bank Holder LookupFX Account Holder LookupExchange Rate LookupExchange Rate Lookup (KEB)FX Remittance Result LookupFX Balance Lookup
FX Remittance ReconciliationFX Auto Transfer ReconciliationFX Same-Bank Remittance Reconciliation
FX Transaction Statement WebhookFX Transaction Statement — Missing Sequence
VAN Virtual Account
Getting Started with VAVSCommunication and Message FormatCommon Header
Recipient InquiryDeposit and Cancellation
RemittanceDeposit Balance Inquiry
Reconciliation
Account Holder InquiryActual Depositor NotificationActual Depositor FileMissing Actual Depositor InquiryWithdrawal Account Registration
Bank CodesResponse CodesChannel CodesBank Operating Hours
Prepaid Wallet
Before You BeginServers & NetworkIntegration Overview
Member Registration UIMy Account UI
Spend BalanceVoid SpendSend Money GiftRevoke Points
Balance LookupBalance OptionsBalance DetailsBalance by Top-upWithdrawable BalanceTransaction ListTransaction DetailsTransaction Details by StoreMember DetailsExpiring PointsTop-up Methods
Top-upCancel Top-upWithdraw FundsPending Withdrawal
Error CodesTransaction Type Codes

Tools

Encryption Test

NTS Error Codes

Complete list of NTS error codes that may occur during cash receipt registration.


Error Code List

Error CodeAuto-ReprocessingError DescriptionDetails and Resolution
TS1OIdentity verification (resident registration number / business registration number / mobile phone number) errorInput value is incorrect when:
• The 'identity verification' field meets any of the following conditions:
- 9 digits or fewer
- 14 digits or more
- 11 digits and does not start with 0 → Not a mobile phone number
TS2OIdentity verification (card) errorInput value is incorrect when:
• A cash receipt dedicated card (starting with 15442020) is not 18 digits
• The 'identity verification' field is 12 digits but does not start with 126 → Not a cash receipt M card number
TS3XTransaction with excluded business entity errorInput value is incorrect when:
• The merchant's business registration number is included in the BLO (issuance-prohibited business list)

Resolution
• Before submitting cash payment records to the NTS, verify that the merchant's business registration number is not registered in the BLO.
TS4XTransaction amount errorInput value is incorrect when:
• Total transaction amount ≠ supply value + VAT + service charge
• Supply value < VAT
• Total transaction amount is 1 or less
TS5XApproval number + transaction date duplicate errorDuplicate approval number and transaction date
TS6OTransaction date errorNote
• For POS approval codes:
- Records with a transaction date of 2017.04.03 (Mon) are valid only if submitted by 2017.04.05 (Wed)
- Records with a transaction date of 2017.04.06 (Thu) are valid only if submitted by 2017.04.10 (Mon)
※ 4.8 (Sat) and 4.9 (Sun) are excluded from deadline calculation as weekends
TS7XTransaction with unregistered business entity errorResolution
• Verify business registration status at NTS Hometax (www.hometax.go.kr) > Inquiry/Issuance > Business Entity Status using the business registration number. Then resubmit within the valid deadline range for the approval code.
TS8XFile layout errorInput value is incorrect when:
• The approval number is not exactly 9 digits, or the last 7 digits are not numeric
• The cash receipt business registration number is not 10 numeric digits
• The merchant business registration number is not 10 numeric digits
TSBOIdentity verification type mismatchRegistration number type mismatch
TSCOVoid transaction input error – original approval number input errorInput value is incorrect when:
• The void transaction is missing either the original approval number or original transaction date
TSDXApproval transaction input error – original approval number + transaction date inputOriginal approval number and transaction date input error for approval transaction
TSEXVoid transaction input error – merchant business registration number mismatchInput value is incorrect when:
• The merchant business registration numbers of the approval and void transactions do not match

Resolution
• When submitting a void transaction, verify the merchant business registration number from the original approval transaction.
TSFXVoid transaction input error – transaction type mismatchInput value is incorrect when:
• Verify and resubmit with the correct transaction type (income deduction / expense proof) for both the approval and void transactions.
TSGXVoid transaction input error – void request total exceeds voidable amountInput value is incorrect when:
• The total of all void requests exceeds the original approval amount — all voids on that date are in error
• Duplicate void request
TSHOVoid transaction input error – identity verification mismatchInput value is incorrect when:
• The recipient of the approval and void transactions differ

Input value is valid when the 'identity verification' field meets any of the following:
- 9 digits or fewer
- 14 digits or more
- 11 digits and does not start with 0 → Not a mobile phone number
TSJXDuplicate void transactionDuplicate void request
TSKXTraditional market sub-business serial number input error – layout errorInput value is incorrect when:
• The traditional market sub-business serial number is 4 numeric digits, but the serial number does not belong to a sub-business within the traditional market
TSLXTraditional market sub-business serial number input error – general business entityTraditional market code entered for a general business entity
TSMXTraditional market sub-business serial number input error – business entity outside traditional marketInput value is incorrect when:
• The business entity exists outside the traditional market
TSNXBooks/performance expenses transaction input error – unregistered books/performance expense business entity⚠ TSN is not an issuance failure — the transaction type was converted to general income deduction and the receipt was issued normally by the NTS.

Input value is incorrect when:
• The merchant has not applied as a books/performance/sports facility business entity with the NTS
1. Merchant has not applied as a books/performance/sports facility business entity
   Cultural Expense Income Deduction > Income Deduction Business Entity > Apply
2. Merchant has applied but registration is not yet complete
3. Registration is complete but not yet reflected by the NTS (may take up to one month)

Resolution
• If TSN errors continue, verify whether the merchant has applied for and been registered as a books/performance/sports facility business entity.
TSOXPublic transportation transaction input error – books/performance/sports facility business entityInput value is incorrect when:
• The merchant for a transaction with the public transportation or books/performance/sports facility flag set to 'Y' is on the NTS books/performance/sports facility business entity list

Resolution
• If the merchant is a books/performance/sports facility business entity, change the flag to 'C' and resubmit.
E1OTransaction eligible date has passedThe valid submission deadline for the transaction has passed
E2XNo original transaction (on void request)No original transaction found on void
E3OIndividual field input value errorLayout error
E4XIndividual field input value errorLayout error
BLOXClosed/suspended business entityIssuance-prohibited business entity

Auto-Reprocessing Information

NOTE

Auto-Reprocessable Error Codes

Error codes marked 'O' for auto-reprocessing can be automatically reprocessed by Hecto Financial. If enrolled as an auto-reprocessing merchant, these error codes are reprocessed automatically.

Auto-reprocessable error codes (8 codes): TS1, TS2, TS6, TSB, TSC, TSH, E1, E3

Non-auto-reprocessable error codes (18 codes): TS3, TS4, TS5, TS7, TS8, TSD, TSE, TSF, TSG, TSJ, TSK, TSL, TSM, TSN, TSO, E2, E4, BLO


Important Notes

  • Merchants not enrolled in auto-reprocessing must manually submit reprocessing requests via the reprocessing API when errors occur.
  • The TSN error code indicates that the transaction type was changed to standard and successfully issued to the NTS.
    If it cannot be confirmed as a cultural expense deduction in the future, refer to the details and resolution in the error code list above.
  • When an error code occurs, refer to the details and resolution to identify the cause, correct it, and resubmit.
💬

Need technical support?

Code Samples

HectoFinancial GitHub