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-Type
application/jsonSandbox
https://tbapi.settlebank.co.kr/whitelabel/v1/pay_cancel.doProduction
https://api.settlebank.co.kr/whitelabel/v1/pay_cancel.doRequest Parameters
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
params Object
└mchtIdAN(12)Alphanumeric, up to 12 bytes*Unique Merchant ID assigned by Hecto Financial.
Unique Merchant ID assigned by Hecto Financial.
└verAN(4)Alphanumeric, up to 4 bytes*Message version.
Message version.
└methodA(2)Alphabetic, up to 2 bytes*Payment method.
Payment method.
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code.
Business type code.
└encCdN(2)Numeric, up to 2 bytes*Encryption type code.
Encryption type code.
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number for the void request.
Unique order number for the void request.
└trdDtN(8)Numeric, up to 8 bytes*Void request date (yyyyMMdd).
Void request date (yyyyMMdd).
└trdTmN(6)Numeric, up to 6 bytes*Void request time (HHmmss).
Void request time (HHmmss).
└mobileYnA(1)Alphabetic, up to 1 bytesMobile flag.
Mobile flag.
Y: Mobile web/app N: PC└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 SHA-256.(auto-generated)Hash value generated using SHA-256.
*trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(plaintext) + hash key
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*Merchant customer ID.
Merchant customer ID.
└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*Transaction reference number from the payment response (trdNo).
Transaction reference number from the payment response (trdNo).
└trdAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Void amount (required for partial void).Void amount (required for partial void).
└taxTypeCdA(1)Alphabetic, up to 1 bytesTax exemption status.
Tax exemption status.
N: Taxable Y: Tax-exempt G: Mixed taxation└taxAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Taxable amount (required for mixed taxation).Taxable amount (required for mixed taxation).
└vatAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64VAT amount (required for mixed taxation).VAT amount (required for mixed taxation).
└taxFreeAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Tax-free amount (required for mixed taxation).Tax-free amount (required for mixed taxation).
└svcAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Service charge.Service charge.
└crcCdA(3)Alphabetic, up to 3 bytesCurrency code (required for credit card).
Currency code (required for credit card).
└cnclOrdN(3)Numeric, up to 3 bytesVoid sequence number (required for credit card; starts at 001).
Void sequence number (required for credit card; starts at 001).
Response Parameters
params Object
└mchtIdAN(12)Alphanumeric, up to 12 bytes*Merchant ID.
pg_testMerchant ID.
└verAN(4)Alphanumeric, up to 4 bytes*Message version.
0A18Message version.
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*Payment method.
WLPayment method.
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code.
C4Business type code.
*Fixed value
└encCdN(2)Numeric, up to 2 bytes*Encryption type code.
23Encryption type code.
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number.
CANCEL20260107150000Merchant order number.
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code.
0021Transaction status code.
0021: Success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Rejection code (detailed code on failure).
0000Rejection code (detailed code on failure).
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message.
Processed successfully.Result message.
└trdNoAN(40)Alphanumeric, up to 40 bytes*Void transaction reference number.
STFP_PGCApg_test0000260107150000M7654321Void transaction reference number.
└trdDtN(8)Numeric, up to 8 bytes*Void response date.
20260107Void response date.
└trdTmN(6)Numeric, up to 6 bytes*Void response time.
150000Void response time.
data Object
└pktHashAN(64)Alphanumeric, up to 64 bytes*Hash value generated using SHA256
Hash value generated using SHA256
NOTE
Hash Generation Combination
outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + mchtCustId + hash key
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*Merchant customer ID.
honggildongMerchant customer ID.
└payMethodA(2)Alphabetic, up to 2 bytes*Payment method code.
CAPayment method code.
RT: Simple payment void CA: Credit card void└orgTrdNoAN(40)Alphanumeric, up to 40 bytes*Original transaction reference number.
STFP_PGCApg_test0000260107143100M1234567Original transaction reference number.
└taxTypeCdA(1)Alphabetic, up to 1 bytesTax exemption status.
Tax exemption status.
Y: Tax-exempt N: Taxable G: Mixed taxation└trdAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingTransaction amount.vqIWIiimsJ5efjSJpfnnTw==Transaction amount.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└taxAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingTaxable portion of the void amount.Taxable portion of the void amount.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└vatAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingVAT portion of the void amount.VAT portion of the void amount.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└taxFreeAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingTax-free portion of the void amount.Tax-free portion of the void amount.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└svcAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingService charge portion of the void amount.Service charge portion of the void amount.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└crcCdA(3)Alphabetic, up to 3 bytesCurrency code (credit card only).
KRWCurrency code (credit card only).
└cnclOrdN(3)Numeric, up to 3 bytesVoid sequence number (starts at 001; credit card only).
001Void sequence number (starts at 001; credit card only).
└cardCnclAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingCredit card transaction amount (credit card only).Credit card transaction amount (credit card only).
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└blcAmtAN(12)Alphanumeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5PaddingRemaining voidable balance.Remaining voidable balance.
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└pktNoAN(20)Alphanumeric, up to 20 bytesMessage number (simple cash payment only).
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=="
}
}
