헥토파이낸셜 개발자센터

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?