Refund Virtual Account API
An API that processes refunds to the customer's account for completed virtual account transactions.
Test Key Information
API Information
POST/spay/APIRefund.do
Content-Type
application/json테스트
https://tbgw.settlebank.co.kr/spay/APIRefund.do운영
https://gw.settlebank.co.kr/spay/APIRefund.doImportant Notes
Virtual Account Refund Notice
Upon receiving the refund API response (and C0 webhook), the merchant should process the refund as complete. The actual deposit to the customer's account will be processed on the next business day, and no separate webhook will be sent upon deposit completion. The refund feature is only available to merchants registered for the refund service.
- Upon receiving the refund API response and C0 webhook, the merchant should process the refund as complete. The actual deposit to the customer's account will be processed on the next business day. No separate webhook will be sent upon deposit completion.
- Refunds may fail during bank maintenance hours (23:30–00:35). Please avoid requesting refunds during this time period.
- In the sandbox environment, please use fictitious account numbers and account holder names to protect personal information.
- Partial refunds are supported; increment the cancellation order number (cnclOrd) sequentially for each request.
Request Parameters
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
params Object
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Unique merchant ID assigned by Hecto Financial
Unique merchant ID assigned by Hecto Financial
nx_mid_il: Virtual account test└verAN(4)Alphanumeric, up to 4 bytes*Message version
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*Payment method
Payment method
*Fixed value (VA: Virtual Account)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
Business type code
*Fixed value (C0: Refund)
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant for the refund
Unique order number generated by the merchant for the refund
└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)
Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)
Request time (HHMMSS)
└mobileYnA(1)Alphabetic, up to 1 bytesMobile indicator
Mobile indicator
Y: Mobile web/app N: PC or other└osTypeA(1)Alphabetic, up to 1 bytesOS type
OS type
A: Android I: iOS W: Windows M: Mac E: Otherdata Object
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256Hash value generated using SHA256(실시간 생성)Hash value generated using SHA256
NOTE
Hash Generation Combination
trdDt + trdTm + mchtId + mchtTrdNo + cnclAmt (plaintext) + hashKey
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*Transaction number issued by Hecto Financial at the time of the issuance request
Transaction number issued by Hecto Financial at the time of the issuance request
*For the fixed-unlimited method (acntType=3), use the transaction number (trdNo) received in the deposit-completion webhook (bizType: B1), not the transaction number from issuance.
└crcCdA(3)Alphabetic, up to 3 bytes*Currency type value
Currency type value
*Fixed value
└cnclOrdN(3)Numeric, up to 3 bytes*Cancellation order number (starts from 001; for the 2nd partial cancellation, use 002)
Cancellation order number (starts from 001; for the 2nd partial cancellation, use 002)
└taxTypeCdA(1)Alphabetic, up to 1 bytesTax exemption status (required for mixed taxation)
Tax exemption status (required for mixed taxation)
N: Taxable Y: Tax-exempt G: Mixed taxation└cnclAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Refund amountRefund amount
└taxAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Taxable amount of the refund amount (required for mixed taxation)Taxable amount of the refund amount (required for mixed taxation)
└vatAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64VAT amount of the refund amount (required for mixed taxation)VAT amount of the refund amount (required for mixed taxation)
└taxFreeAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Tax-free amount of the refund amount (required for mixed taxation)Tax-free amount of the refund amount (required for mixed taxation)
└refundBankCdAN(3)Alphanumeric, up to 3 bytes*Refund bank code
Refund bank code
*Refer to the Virtual Account Bank Code List
└refundAcntNoN(16)Numeric, up to 16 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Refund account numberRefund account number
└refundDpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytes*Refund account holder name
Refund account holder name
└cnclRsnAHN(255)Alphanumeric + Korean, up to 255 bytesRefund reason
Refund reason
Response Parameters
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
params Object
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Merchant ID
nx_mid_ilMerchant ID
└verAN(4)Alphanumeric, up to 4 bytes*Message version
0A19Message version
└methodA(2)Alphabetic, up to 2 bytes*Payment method
VAPayment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
C0Business type code
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
23Encryption type code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number
ORDER20211231100000Merchant order number
└trdNoAN(40)Alphanumeric, up to 40 bytes*Hecto Financial transaction number
STFP_PGVAnx_mid_il00210806075210M1853381Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)
20211231Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)
100000Request time (HHMMSS)
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code (success/failure)
0021Transaction status code (success/failure)
0021: Success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Result code
0000Result code
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message
Processed successfully.Result message
data Object
└pktHashAN(64)Alphanumeric, up to 64 bytes*Returns the hash value from the request as-is
f395b6725a9a18...Returns the hash value from the request as-is
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*Transaction number issued by Hecto Financial at the time of the issuance request
STFP_PGVAnx_mid_il00210806075210M1853381Transaction number issued by Hecto Financial at the time of the issuance request
└cnclAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingRefund amount1000Refund amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingRemaining refundable balance based on the transaction number after a successful refund0Remaining refundable balance based on the transaction number after a successful refund
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
Webhook (Hecto Financial → Merchant)
When a refund is complete, Hecto Financial sends a webhook to your server.
Webhook Parameters
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status
0021Transaction status
0021: Success└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number assigned by Hecto Financial
STFP_PGVAnx_mid_il0211129135810M1494620Unique transaction number assigned by Hecto Financial
└methodA(2)Alphabetic, up to 2 bytes*Payment method
VAPayment method
VA: Virtual Account└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type
C0Business type
C0: Refund└mchtIdAN(10)Alphanumeric, up to 10 bytes*Merchant ID
nx_mid_ilMerchant ID
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number
ORDER20211231100000Merchant order number
└trdDtmN(14)Numeric, up to 14 bytes*Transaction date and time (YYYYMMDDhhmmss)
20211231100000Transaction date and time (YYYYMMDDhhmmss)
└trdAmtN(12)Numeric, up to 12 bytesTransaction amount
1000Transaction amount
└orgTrdNoAN(40)Alphanumeric, up to 40 bytesOriginal transaction number
STFP_PGVAnx_mid_il0211129135810M1494620Original transaction number
└orgTrdDtN(8)Numeric, up to 8 bytesOriginal transaction date
20211231Original transaction date
└cnclTypeN(2)Numeric, up to 2 bytesCancellation transaction type
00Cancellation transaction type
00: Full cancellation 10: Partial cancellation└pktHashAN(64)Alphanumeric, up to 64 bytes*Hash value (transaction status code + transaction date + transaction time + merchant ID + merchant order number + transaction amount + hash key)
a2d6d597d55d7c9b...Hash value (transaction status code + transaction date + transaction time + merchant ID + merchant order number + transaction amount + hash key)
Webhook Response
The merchant sends a response to Hecto Financial.
| Response | Description |
|---|---|
| "OK" | On success (uppercase) |
| "FAIL" | On failure (uppercase; webhook is resent when responding with FAIL) |
| Others | Recognized as abnormal failure; webhook is resent up to the configured number of times |
Need technical support?
Code Samples
HectoFinancial GitHubAPI Test