헥토파이낸셜 개발자센터

Void / Refund API

Void a completed payment transaction. For simple cash payments, funds are refunded to the debited account.

Sandbox Key Information

Important Notes

orgTrdNo Required

Pass the trdNo (transaction reference number) from the payment response as the orgTrdNo parameter.
NOTE

Partial Void

For partial voids on credit cards, cnclOrd must be incremented sequentially starting from 001.

API Information

POST/whitelabel/v1/pay_cancel.do
Content-Typeapplication/json
테스트https://tbapi.settlebank.co.kr/whitelabel/v1/pay_cancel.do
운영https://api.settlebank.co.kr/whitelabel/v1/pay_cancel.do

Request Parameters

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

params Object

└mchtIdAN(12)Alphanumeric, up to 12 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.
└encCdN(2)Numeric, up to 2 bytes*
Encryption type code.
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number for the void request.
└trdDtN(8)Numeric, up to 8 bytes*
Void request date (yyyyMMdd).
└trdTmN(6)Numeric, up to 6 bytes*
Void request time (HHmmss).
└mobileYnA(1)Alphabetic, up to 1 bytes
Mobile flag.
Y: Mobile web/app N: PC
└osTypeA(1)Alphabetic, up to 1 bytes
OS type.
A: Android I: iOS W: Windows M: Mac E: Other

data Object

└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
Hash value generated using SHA-256.
*trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(plaintext) + hash key
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*
Merchant customer ID.
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*
Transaction reference number from the payment response (trdNo).
└trdAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Void amount (required for partial void).
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status.
N: Taxable Y: Tax-exempt G: Mixed taxation
└taxAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed taxation).
└vatAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed taxation).
└taxFreeAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed taxation).
└svcAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Service charge.
└crcCdA(3)Alphabetic, up to 3 bytes
Currency code (required for credit card).
└cnclOrdN(3)Numeric, up to 3 bytes
Void sequence number (required for credit card; starts at 001).

Response Parameters

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*pg_test
Merchant ID.
└verAN(4)Alphanumeric, up to 4 bytes*0A18
Message version.
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*WL
Payment method.
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*C4
Business type code.
*Fixed value
└encCdN(2)Numeric, up to 2 bytes*23
Encryption type code.
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*CANCEL20260107150000
Merchant order number.
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code.
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Rejection code (detailed code on failure).
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message.
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCApg_test0000260107150000M7654321
Void transaction reference number.
└trdDtN(8)Numeric, up to 8 bytes*20260107
Void response date.
└trdTmN(6)Numeric, up to 6 bytes*150000
Void response time.

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*
The hash value echoed back from the request. Compare against the hash generated at request time to verify data integrity.
NOTE

Hash Verification

The pktHash in the response is identical to the hash sent in the request. Verify data integrity by comparing it against the hash you generated (trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(plaintext) + hashKey).
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*honggildong
Merchant customer ID.
└payMethodA(2)Alphabetic, up to 2 bytes*CA
Payment method code.
RT: Simple payment void CA: Credit card void
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCApg_test0000260107143100M1234567
Original transaction reference number.
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status.
Y: Tax-exempt N: Taxable G: Mixed taxation
└trdAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5PaddingvqIWIiimsJ5efjSJpfnnTw==
Transaction amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└taxAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
Taxable portion of the void amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└vatAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
VAT portion of the void amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└taxFreeAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
Tax-free portion of the void amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└svcAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
Service charge portion of the void amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└crcCdA(3)Alphabetic, up to 3 bytesKRW
Currency code (credit card only).
└cnclOrdN(3)Numeric, up to 3 bytes001
Void sequence number (starts at 001; credit card only).
└cardCnclAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
Credit card transaction amount (credit card only).
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding
Remaining voidable balance.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└pktNoAN(20)Alphanumeric, up to 20 bytes
Message number (simple cash payment only).

Request Example

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "C4",
        "encCd": "23",
        "mchtTrdNo": "CANCEL20260107150000",
        "trdDt": "20260107",
        "trdTm": "150000",
        "mobileYn": "N",
        "osType": "W"
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "orgTrdNo": "STFP_PGCApg_test0000260107143100M1234567",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw==",
        "crcCd": "KRW",
        "cnclOrd": "001"
    }
}

Response Example

{
    "params": {
        "mchtId": "pg_test",
        "ver": "0A18",
        "method": "WL",
        "bizType": "C4",
        "encCd": "23",
        "mchtTrdNo": "CANCEL20260107150000",
        "trdNo": "STFP_PGCApg_test0000260107150000M7654321",
        "trdDt": "20260107",
        "trdTm": "150000",
        "outStatCd": "0021",
        "outRsltCd": "0000",
        "outRsltMsg": "Processed successfully."
    },
    "data": {
        "pktHash": "197884af9f63bcd2d9792cd5cd39f7b1e7525e88888e2cee28f64fa23bf53312",
        "mchtCustId": "honggildong",
        "payMethod": "CA",
        "orgTrdNo": "STFP_PGCApg_test0000260107143100M1234567",
        "trdAmt": "vqIWIiimsJ5efjSJpfnnTw=="
    }
}
💬

Need technical support?