SME Differential Settlement API
SME Differential Settlement is the process of settling the difference between the preferential fee rate applied to small and medium-sized merchants and the fee actually applied by the PG company. Under government policy, small and medium-sized merchants with annual revenue below a certain threshold receive preferential fee rates from card companies, and PG companies are required to return the corresponding differential amount to those merchants.
In general, PG companies settle with merchants using their own fee rates. Subsequently, when the merchant creates a differential settlement request file containing sub-merchant business numbers for each sales amount and submits it to the PG company, the PG company requests settlement from the card issuer based on that data.
In this process, a difference arises between the preferential fee rate confirmed by the card issuer and the fee rate previously applied by the PG company. The Differential Settlement is the process of paying the confirmed differential amount to the merchant as the final settlement.
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 (400 bytes) format. SFTP connection information will be provided separately after the merchant ID is issued.
Communication Specification
| Item | Description |
|---|---|
| Data transmission method | SFTP file transmission |
| Access account | SFTP account created and provided separately upon firewall allowance request after merchant ID issuance |
| MAIN SFTP Server | 61.252.169.33 (port: 5210) |
| DR SFTP Server | 14.34.14.26 (port: 5210) |
| TEST/REAL distinction | Distinguished by access account or folder |
| Character encoding | UTF-8 |
File Structure
START RECORD
HEADER RECORD (per merchant ID) SEGMENT 1
DATA RECORD
...
DATA RECORD
TOTAL RECORD
HEADER RECORD (per merchant ID) SEGMENT 2
DATA RECORD
...
DATA RECORD
TOTAL RECORD
...
HEADER RECORD (per merchant ID) SEGMENT n
DATA RECORD
TOTAL RECORD
END RECORD
Field Types
| Type | Description | Alignment | Padding |
|---|---|---|---|
| N | Numeric field | Right | '0' |
| A | Character field | Left | SPACE |
Differential & Refund Settlement Policy
Differential Settlement Transmission/Reception Schedule
| File | Schedule |
|---|---|
| Differential settlement request file | Upload by 13:00 on D+1 based on transaction date (D) (transmitted 365 days a year) |
| Differential settlement result file | Uploaded by 04:00 on business day +7 from the differential settlement request date |
NOTE
Transmission/Reception Schedule Example
Transaction date (D): January 7, 2023 (Sat) → Differential settlement request file (Merchant → Hecto Financial): January 8, 2023 (Sun) → Differential settlement result file (Hecto Financial → Merchant): January 17, 2023 (Tue)
Differential Settlement Transmission Targets
- As per the refund settlement policy effective from the second half of 2022 (September), transmission of differential settlement data for the general (4) sales tier is mandatory.
- When cart sales occur, the final sub-merchant business number cannot be duplicated per PG transaction number.
- When transmitting differential settlement data for cart sales, all final sub-merchant sales must be included, and the transaction amount per PG transaction number must match the sum of final sub-merchant sales amounts.
Cancellation Sales Omission/Delayed Submission
If cancellation sales are omitted or submitted late, they may be processed automatically based on the original approval differential settlement records. If the original approval differential settlement is not a cart sale, both full and partial cancellations are subject to automatic processing. If the original approval differential settlement is a cart sale, only full cancellations are subject to automatic processing. In such cases, the result will be included in the result file, and the merchant's reservation field will be set to an arbitrary key value by Hecto Financial.
Refund Settlement
- First implemented in September 2022
- For new merchants, initially classified as general (4) merchants; fee refund settlement is processed for sales that did not receive SME preferential fee rates during the half-year period
- List of eligible merchants for refund is received from the Credit Finance Association
- Example: For a business opened in February, if SME preferential fee is applied in July, the difference in fees (general - SME) from February to July is refunded
Refund Settlement Method:
- Merchants (2nd-tier PG) do not transmit a separate refund settlement request file to Hecto Financial
- Refund settlement is requested from card companies based on previously transmitted differential settlement sales data (Hecto Financial internal processing)
- Refund settlement is not possible for returned differential settlement records, so management of returned differential settlement records is essential
Differential Settlement Request (Merchant (2nd-tier PG) → Hecto Financial)
File Spec
| Item | Description |
|---|---|
| File name | ST_PRFT_REQ_RequestDate (RequestDate: YYYYMMDD) |
| 1 Record | 400 bytes |
| File path | /edi_req |
| Test file path | /edi_req/test |
START RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "01" |
| Request date | 3 | 8 | N | YYYYMMDD |
| Business number | 11 | 10 | AN | 2nd-tier PG business number |
| PG company identifier | 21 | 10 | AN | "SETTLEBANK" |
| FILLER | 31 | 370 | AN | Space |
HEADER RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "10" |
| Merchant ID | 3 | 10 | AN | Merchant ID issued by Hecto Financial |
| FILLER | 13 | 388 | AN | Space |
DATA RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "11" |
| Approval/cancellation flag | 3 | 1 | AN | 0: Approval / 1: Cancellation |
| Transaction date | 4 | 8 | N | Transaction date (YYYYMMDD). Approval or cancellation date |
| Intermediate sub-merchant number | 12 | 10 | AN | 2nd-tier PG business number (10 digits) |
| Final sub-merchant number | 22 | 10 | AN | Final sub-merchant business registration number (10 digits) |
| Original approval PG transaction number | 32 | 40 | AN | Original approval PG transaction number |
| Partial cancellation sequence | 72 | 2 | N | Approval: 0, 1st partial or full cancellation: 1, Nth cancellation: N (required) |
| Merchant order number | 73 | 100 | AN | Unique order number generated by the merchant |
| Sub-merchant sales amount | 173 | 15 | N | Final sub-merchant sales amount. Omit [-] sign for cancellations |
| Transaction acquiring amount | 188 | 15 | N | Transaction amount per PG transaction number. Omit [-] sign for cancellations |
| Approval date | 203 | 8 | AN | Approval date of original transaction (YYYYMMDD) |
| Merchant reservation field | 211 | 40 | AN | Receipt identification key. Value is set in result message as-is |
| Cancellation PG transaction number | 251 | 40 | AN | Used when approval/cancellation flag is 1 (cancellation). Enter the cancellation PG transaction number; in this case, the entered partial cancellation sequence is not used |
| FILLER | 291 | 109 | AN | Space |
Cancellation PG Transaction Number Guide
The cancellation PG transaction number field is a required input for new integrations after August 2024. If it is difficult to accurately verify the partial cancellation sequence, please enter the cancellation PG transaction number.
TOTAL RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "12" |
| Total record count | 3 | 7 | N | Number of DATA lines (approval + cancellation count) |
| Total sales amount | 10 | 18 | AN | Sub-merchant sales amount in DATA (approval - cancellation amount). [-] sign can be shown |
| FILLER | 28 | 373 | AN | Space |
END RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "02" |
| Total line count | 3 | 7 | N | Matches total DATA record count for all merchant IDs |
| FILLER | 10 | 391 | AN | Space |
Differential Settlement Result (Hecto Financial → Merchant (2nd-tier PG))
File Spec
| Item | Description |
|---|---|
| File name | ST_PRFT_RSP_FileCreationDate (FileCreationDate: YYYYMMDD) |
| 1 Record | 400 bytes |
| Production file path | /edi_rsp |
| Test file path | /edi_rsp/test |
START RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "01" |
| Request date from | 3 | 8 | N | Differential settlement request start date (YYYYMMDD) |
| Request date to | 11 | 8 | N | Differential settlement request end date (YYYYMMDD) |
| File creation date | 19 | 8 | N | YYYYMMDD |
| Business number | 27 | 10 | AN | 2nd-tier PG business number |
| PG company identifier | 37 | 10 | AN | "SETTLEBANK" |
| FILLER | 47 | 354 | AN | Space |
HEADER RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "10" |
| Merchant ID | 3 | 10 | AN | Merchant ID issued by Hecto Financial |
| FILLER | 13 | 388 | AN | Space |
DATA RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "11" |
| Approval/cancellation flag | 3 | 1 | AN | 0: Approval / 1: Cancellation |
| Transaction date | 4 | 8 | N | Transaction date (YYYYMMDD). Approval or cancellation date |
| Request date | 12 | 8 | N | Differential settlement request date (YYYYMMDD) |
| Intermediate sub-merchant number | 20 | 10 | AN | 2nd-tier PG business number (10 digits) |
| Final sub-merchant number | 30 | 10 | AN | Sub-merchant business registration number (10 digits) |
| PG transaction number | 40 | 40 | AN | PG transaction number (approval or cancellation transaction number) |
| Partial cancellation sequence | 80 | 2 | N | Approval: 0, 1st partial or full cancellation: 1, Nth cancellation: N |
| Merchant order number | 82 | 100 | AN | Unique order number generated by the merchant |
| Sub-merchant sales amount | 182 | 15 | N | Omit [-] sign for cancellations |
| Original transaction acquiring amount | 197 | 15 | N | Omit [-] sign for cancellations |
| Approval date | 212 | 8 | AN | Approval date of original transaction (YYYYMMDD) |
| Merchant reservation field | 220 | 40 | AN | Receipt identification key. Value is set in result message as-is |
| Sub-merchant tier | 260 | 1 | AN | 0: Micro / 1: Small1 / 2: Small2 / 3: Small3 / 4: General. Card company response sub-merchant tier; if null value received, responds as 4 (General) |
| Differential supply value | 261 | 15 | N | Omit [-] sign for cancellations |
| Differential VAT | 276 | 15 | N | Omit [-] sign for cancellations |
| Differential settlement amount | 291 | 15 | N | Omit [-] sign for cancellations |
| Differential settlement date | 306 | 8 | N | YYYYMMDD |
| Differential settlement result code | 314 | 4 | AN | Hecto Financial validation result code before card issuer transmission (refer to differential settlement code table) |
| Card company result code | 318 | 2 | AN | Card issuer response code (refer to card issuer code table). May be null depending on the differential settlement result code |
| FILLER | 320 | 81 | AN |
TOTAL RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "12" |
| Total record count | 3 | 7 | N | Number of sub-merchant records in DATA (approval + cancellation count) |
| Total sales amount | 10 | 18 | AN | Sub-merchant sales amount in DATA (approval - cancellation amount). [-] sign can be shown |
| Differential supply value total | 28 | 15 | AN | [-] sign can be shown |
| Differential VAT total | 43 | 15 | AN | [-] sign can be shown |
| Differential settlement amount total | 58 | 15 | AN | [-] sign can be shown |
| FILLER | 73 | 328 | AN | Space |
END RECORD
| Field | Position | Length | Type | Description |
|---|---|---|---|---|
| Record type | 1 | 2 | AN | "02" |
| Total line count | 3 | 7 | N | Total DATA record count |
| FILLER | 10 | 391 | AN | Space |
Code Tables
Differential Settlement Result Codes (Hecto Financial Validation Result Codes)
| Error Code | Error Message |
|---|---|
| 0000 | Normal |
| 1101 | Merchant ID does not exist |
| 1102 | Merchant not eligible for differential settlement |
| 1103 | Not an SME business number |
| 1201 | Transaction does not exist |
| 1202 | Original transaction acquiring amount mismatch |
| 1203 | Original transaction acquiring amount and sub-merchant sales amount mismatch |
| 1301 | Cancellation before acquiring |
| 1302 | Same-day cancellation transaction |
| 1401 | Differential settlement acquiring result not received |
| 1501 | Completed differential settlement record exists |
| 1502 | Differential settlement in progress |
| 1601 | Final sub-merchant number format error |
| 1602 | Cancellation final sub-merchant number approval record does not exist |
| 1603 | No differential settlement information for original cancellation transaction |
| 2101 | Duplicate final sub-merchant number sales in cart transaction |
| 9999 | Other error (contact PG company) (e.g. duplicate transmission, final sub-merchant number error, etc.) |
Card Issuer Result Codes
| Error Code | Error Message |
|---|---|
| 00 | Normal |
| 01 | Card issuer classification value error (does not exist or mismatch) |
| 02 | Sales amount error (mismatch between original sales amount and sum of sub-merchant sales amounts) |
| 03 | Duplicate submission (transmitting already processed records) |
| 04 | Original acquiring returned (original sales does not exist or sales amount error, etc.) |
| 05 | Acquiring cancellation type error (normal/cancellation mismatch between original and sub-merchant sales) |
| 06 | Acquiring transmission date error |
| 07 | Approval date error |
| 08 | Approval number error (no sales corresponding to original approval number) |
| 09 | Merchant number error 1 (merchant number is SPACE or unregistered merchant) |
| 10 | Merchant number error 2 (not a differential settlement merchant number) |
| 11 | Card number error |
| 12 | Intermediate sub-merchant error (non-qualifying electronic financial business, etc.) |
| 13 | Differential settlement delayed submission |
| 14 | Card issuer classification value normal record returned. In a cart transaction consisting of A, B, C, if C's classification value is in error, C is returned with code 01. However, since A and B have correct classification values but are returned due to C, they are distinguished with code 14 |
| 15 | Returned when differential settlement is submitted after full sales cancellation. Additional return condition reason: to prevent delayed submission of differential settlement cancellation |
| 99 | Other |
Need technical support?
Code Samples
HectoFinancial GitHub