헥토파이낸셜 개발자센터

010 Virtual Account Refund API

An API for refunding a completed 010 virtual account deposit transaction.

Test Key Information

API Information

POST/spay/APIRefund.do
Content-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APIRefund.do
운영https://gw.settlebank.co.kr/spay/APIRefund.do

Important Notes

Refund Service Registration Required

The refund feature is only available for merchants with refund service registered. Contact your sales representative to register for the refund service.
NOTE

Sandbox Environment Limitation

In the sandbox environment, refund requests using actual account holder names and account numbers will result in an error. Please perform refund testing in the production environment.

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
└verAN(4)Alphanumeric, up to 4 bytes*
Message version
└methodA(2)Alphabetic, up to 2 bytes*
Payment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*
Business type code
*C0: Refund
└encCdN(2)Numeric, up to 2 bytes*
Encryption type code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Merchant order number for refund (newly generated)
└trdDtN(8)Numeric, up to 8 bytes*
Refund request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Refund request time (HHmmss)
└mobileYnA(1)Alphabetic, up to 1 bytes
Mobile indicator
Y: Mobile web/app N: PC or other
└osTypeA(1)Alphabetic, up to 1 bytes
OS type
A: Android I: IOS W: Windows M: Mac E: Other

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA-256(실시간 생성)
Hash value generated using SHA256
*Refund request date + refund request time + merchant ID + merchant order number + refund amount (plaintext) + hash key
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*
Transaction number issued by Hecto Financial at the time of issuance
└crcCdA(3)Alphabetic, up to 3 bytes*
Currency code
└cnclOrdN(3)Numeric, up to 3 bytes*
Cancel sequence (starts from 001; second partial cancel is 002)
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status. Follows merchant default settings if blank.
Y: Tax-exempt N: Taxable G: Mixed tax
└cnclAmtN(9)Numeric, up to 9 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Refund amount
└taxAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount of the refund (required for mixed tax)
└vatAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount of the refund (required for mixed tax)
└taxFreeAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount of the refund (required for mixed tax)
└refundBankCdAN(3)Alphanumeric, up to 3 bytes*
Bank code for refund
└refundAcntNoN(16)Numeric, up to 16 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Account number for refund
└refundDpstrNmAHN(50)Alphanumeric + Korean, up to 50 bytes*
Account holder name for refund account
└cnclRsnAHN(255)Alphanumeric + Korean, up to 255 bytes
Refund reason message

Response Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxva_sb_il
Merchant ID
└verAN(4)Alphanumeric, up to 4 bytes*0A18
Message version
└methodA(2)Alphabetic, up to 2 bytes*VA
Payment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*C0
Business type code
└encCdN(2)Numeric, up to 2 bytes*23
Encryption type code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*REFUND20211231100000
Merchant order number
└trdNoAN(40)Alphanumeric, up to 40 bytes*STBK_0123456789
Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*20211231
Refund request date
└trdTmN(6)Numeric, up to 6 bytes*120000
Refund request time
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Result code (0000 indicates success)
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*75ac014c33165f3ee0c331123a0049f37a6e1578f8cec1d3d0374ffb75f18496
Response hash value
└orgTrdNoAN(40)Alphanumeric, up to 40 bytesSTBK_0123456789
Original transaction number
└cnclAmtN(9)Numeric, up to 9 bytesAES-256AES-256/ECB/PKCS5Padding1000
Refund amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding0
Remaining cancellable balance after refund
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

Request Example

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdDt": "20211231",
    "trdTm": "120000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "hash value",
    "orgTrdNo": "STBK_0123456789",
    "crcCd": "KRW",
    "cnclOrd": "001",
    "taxTypeCd": "N",
    "cnclAmt": "AES-encrypted refund amount",
    "refundBankCd": "011",
    "refundAcntNo": "AES-encrypted account number",
    "refundDpstrNm": "Hong Gil-dong"
  }
}

Response Example

Success

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdNo": "STBK_0123456791",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "Processed successfully."
  },
  "data": {
    "pktHash": "response hash value",
    "orgTrdNo": "STBK_0123456789",
    "cnclAmt": "AES-encrypted refund amount",
    "blcAmt": "AES-encrypted balance"
  }
}

Failure

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0031",
    "outRsltCd": "0005",
    "outRsltMsg": "Refund service is not registered for this merchant."
  },
  "data": {}
}
💬

Need technical support?

무엇이든 물어보세요