헥토파이낸셜 개발자센터
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

2nd-tier PG Sub-Merchant Registration API

The 2nd-tier PG Sub-Merchant Registration is the process of registering and managing the information of sub-merchants (sub-merchants) who use payment services through a PG company (electronic payment intermediary) with card companies. Under the Electronic Financial Transactions Act and the Specialized Credit Finance Business Act, PG companies are obligated to register the business information of merchants under their umbrella with card companies, thereby ensuring transparency in payment flows and a robust merchant management system.

When payments are made online through a PG company, it is the sub-merchant—not the PG company—that actually provides the goods or services. Card companies need to know who these sub-merchants are, what industry they operate in, and whether they are legitimate businesses. PG companies must therefore promptly transmit sub-merchant registration, change, and termination information.

This document explains the file integration method and important notes for integration.


Notes

NOTE

SFTP File Transfer Method

This specification uses SFTP file transmission, not HTTP API. The file format is a fixed-length (500 bytes) format. SFTP connection information will be provided separately after the merchant ID is issued.

Communication Specification

ItemDescription
Data transmission methodSFTP file transmission
Access accountTo be provided separately
MAIN SFTP Server61.252.169.33 (port: 5210)
DR SFTP Server14.34.14.26 (port: 5210)
TEST/REAL distinctionDistinguished by folder
Character encodingEUC_KR

File Structure

HEADER RECORD
DATA RECORD
...
DATA RECORD
TRAILER RECORD

Field Types

TypeDescriptionAlignmentPadding
NNumeric fieldRight'0'
ACharacter field (alphabet)LeftSPACE
SCharacter field (special characters)LeftSPACE
HCharacter field (Korean)LeftSPACE

File Transmission/Reception Schedule

FileSchedule
Sub-merchant registration request fileUpload by 08:00 on the current day (transmitted 365 days a year)
Sub-merchant registration result fileGenerated after 05:00 for the current day (generated 365 days a year)

Sub-Merchant Registration Request (Merchant → Hecto Financial)

File Spec

ItemDescription
File nameST_BIZREG_REQ_RequestDate (RequestDate: YYYYMMDD)
1 Record500 bytes
File path/bizreg_req
Test file path/bizreg_req/test
If no dataUpload with only HEADER and TRAILER records

HEADER RECORD

FieldPositionLengthTypeDescription
Record type12ASet "HD"
File creation date38NYYYYMMDD
FILLER11490ASPACE

DATA RECORD

FieldPositionLengthTypeRequiredDescription
Record type12A*Set "RD"
Registration type32AN*00: New / 01: Termination / 02: Change. Note: Lotte Card does not use 02: Change
2nd PG business number510AN*2nd-tier PG or open market business registration number. Omit hyphens (-)
Card company code154AN*Enter one code from the card issuer code table. For multiple card issuer registrations, repeat the same merchant info
Business registration number (sub-merchant)1810AN*Final sub-merchant registration number. Omit hyphens (-)
Industry name (sub-merchant)2820HSKorean 10 characters (20 bytes). Special characters allowed
Company name (sub-merchant)4840ANHS*Korean 20 characters (40 bytes). Special characters allowed
Postal code (sub-merchant)885AN5-digit new postal code
Address (sub-merchant)93100ANHSExcluding postal code
Representative name (sub-merchant)19340ANHS*
Phone number (sub-merchant)23311AN*Main phone number of the sub-merchant. Omit hyphens (-)
Email (sub-merchant)24440ANSMain email address of the sub-merchant
Website URL (sub-merchant)28480ANS*If no URL, use the 2nd-tier PG company URL
Registration date3648N*YYYYMMDD
FILLER372128ASPACE
NOTE

Required Fields

Required fields are marked with *.

TRAILER RECORD

FieldPositionLengthTypeDescription
Record type12ASet "TR"
Total record count310NTotal number of DATA records
New registration count1310NNumber of new registrations in DATA
Change count2310NNumber of changes in DATA
Termination count3310NNumber of terminations in DATA
FILLER43458ASPACE

Sub-Merchant Registration Result (Hecto Financial → Merchant)

File Spec

ItemDescription
File nameST_BIZREG_RSP_FileCreationDate (FileCreationDate: YYYYMMDD)
1 Record500 bytes
File path/bizreg_rsp
Test file path/bizreg_rsp/test
If no dataUpload with only HEADER and TRAILER records

HEADER RECORD

FieldPositionLengthTypeDescription
Record type12ASet "HD"
File creation date38ANYYYYMMDD
FILLER11490ASPACE

DATA RECORD

FieldPositionLengthTypeDescription
Record type12ASet "RD"
Registration type32AN00: New / 01: Termination / 02: Change
2nd PG business number510AN2nd-tier PG or open market business registration number. Omit hyphens (-)
Card company code154ANRefer to card issuer code table
Business registration number (sub-merchant)1810ANFinal sub-merchant registration number. Omit hyphens (-)
Industry name (sub-merchant)2820ANHSKorean 10 characters (20 bytes). Special characters allowed
Company name (sub-merchant)4840ANHSKorean 20 characters (40 bytes). Special characters allowed
Postal code (sub-merchant)885AN5-digit new postal code
Address (sub-merchant)93100ANHSExcluding postal code
Representative name (sub-merchant)19340ANHS
Phone number (sub-merchant)23311ANMain phone number of the sub-merchant. Omit hyphens (-)
Email (sub-merchant)24440ANSMain email address of the sub-merchant
Website URL (sub-merchant)28480ANS
Registration date3648ANYYYYMMDD
Card company result code3724AN
PG company result code3764AN
FILLER380120ASPACE

TRAILER RECORD

FieldPositionLengthTypeDescription
Record type12ASet "TR"
Total record count310NTotal number of DATA records
New registration count1310NNumber of new registrations in DATA
Change count2310NNumber of changes in DATA
Termination count3310NNumber of terminations in DATA
FILLER43458ASPACE

Code Tables

PG Company Result Codes

Error CodeError Message
0000Normal
9999Other error (contact PG company)

Card Issuer Codes

CodeCard IssuerNotes
1001BC Card
1002Kookmin Card
1003Hana (Exchange) Card
1004Samsung CardSamsung Card sub-merchant registration follows a separate process and may be excluded from the request. If transmitted, it will not be included in the result file
1005Shinhan Card
1007Woori CardNot registering will not cause differential settlement rejection, but may result in omission from SME preferential tier selection
1008Hyundai Card
1009Lotte Card
1015NH Card

Card Company Result Codes

Kookmin Card

Return CodeReturn Reason
00Normal processing
01Registration type error
02Company name error
03Business registration number (PG) error
04Merchant number error
05Business number (sub-merchant) error
06Required value missing (company name)
07Required value missing (URL)
08Required value missing (phone number)
11Business registration number (PG) 1st-tier sub-merchant not registered
12Already registered (1st-tier sub-merchant)
99Other

NH Card

Return CodeReturn Reason
00Normal processing
01Record type error
02Registration type error
03VAN institution code error
04Business registration number (PG) error
05Merchant number error
06Business number (sub-merchant) error
07Company name error (required and integrity)
08URL error (required and integrity)
09Phone number error (required and integrity)
10Registration date error
11Sub-merchant not registered when registration type is 01 or 02
12Sub-merchant already registered when registration type is 00
13Total count error
99Other

Shinhan Card

Return CodeReturn Reason
00Normal processing
01Registration type error
02Business registration number (PG) error
03Business number (sub-merchant) error
04Company name error
05Phone number error
06Representative name (sub-merchant) error
07Sub-merchant not registered when registration type is 01 or 02
99Other

Woori Card / Hyundai Card

Return CodeReturn Reason
00Normal processing
01Registration type error
02VAN institution code error
03Business registration number (PG) error
04Business number (sub-merchant) error
05Company name (sub-merchant) missing
06Website URL (sub-merchant) missing
07Phone number (sub-merchant) missing
08Registration date error
09Sub-merchant not registered when registration type is 01 or 02
10Sub-merchant already registered when registration type is 00
99Other

Hana Card

Return CodeReturn Reason
00Normal processing
01Registration type error
02Company name error
03Business registration number (PG) error
04Merchant number error
05Business number (sub-merchant) error
06Required value missing (company name)
07Required value missing (URL)
08Required value missing (phone number)
11Business registration number (PG) 1st-tier sub-merchant not registered
12Already registered (1st-tier sub-merchant)
99Other

Lotte Card

Return CodeReturn Reason
00Normal processing
01Registration type error
02Company name error
03Business registration number (PG) error
04Merchant number error
05Business number (sub-merchant) error
06Required value missing (company name)
07Required value missing (URL)
08Required value missing (phone number)
11Sub-merchant not registered when registration code is 01
99Other

BC Card

Return CodeReturn Reason
01Registration type error
02Business registration number (PG) error
03PG company code error
04PG merchant not found in BC
05Business number (sub-merchant) error
06Sub-merchant phone number error
07No valid existing registration information
99Other
💬

Need technical support?

Code Samples

HectoFinancial GitHub
API Test