Payment Refund

This API handles full or partial refunds for completed transactions. This is typically used for payment methods (like Virtual Account or Mobile Payment) where immediate cancellation is not possible and funds must be transferred back to the customer's account.

Note

• For cancelling Escrow approval transactions, please refer to Escrow Status Change.
• Two types of refund services are available: Settlement Refund (D+1) and Real-time Refund. Please consult with your sales representative to enable the specific service you need.

Real-time Refund

The refund is processed immediately to the customer's refund account upon request.

Settlement Refund (D+1)

The refund is processed to the customer's account on D+1 (Next Business Day). Since the processing is asynchronous, you must register a Webhook URL to receive the final result via notification.

Request

Request URL

POST https://{API Domain}/api/trades/revise
Content-type: application/json; charset=utf-8

Note

Supports API Idempotency (See API Idempotency)

Caution

Since final cancellation/refund takes time, you must set the timeout to 30 seconds.

Parameters

Field Name	Type	Length	Required	Description
mallId	String	8Byte	✅	Merchant ID assigned by KICC
shopTransactionId	String	60Byte	✅	Merchant Transaction ID (API Idempotency Key)
pgCno	String	20Byte	✅	Original PG Transaction ID
reviseTypeCode	String	2Byte	✅	Change Type Code (See Codes) Settlement Full: “60”, Settlement Partial: “62”
reviseSubTypeCode	String	4Byte		Change Sub-Type Code (See Sub-Codes)
amount	Number			Refund Amount. Required for Partial Refund.
remainAmount	Number			Remaining Amount. Used for validation during Partial Refund.
clientIp	String	20Byte		Requestor IP
clientId	String	32Byte		Requestor ID (Merchant Admin Login ID)
cancelReqDate	String	8Byte	✅	Refund Request Date (yyyyMMdd). Must use the current date.
msgAuthValue	String	200Byte	✅	Message Integrity Verification Value (See Message Authentication) Contact sales for the Secret Key.
reviseMessage	String	100Byte		Reason for Refund
refundQueryFlag	String	1Byte		Refund Result Query Flag ('Y': Query). Required for Real-time Refund timeout recovery. Retry if response is "VTIM" or "VT00".
refundInfo	Object		✅	Refund Account Info See refundInfo below
taxInfo	Object			Complex Tax Info (Required if using Complex Tax) See taxInfo below
basketUsed	String	1Byte		Split Settlement Basket Used (Y/N)
basketInfo	Object			Basket Info (Required if using Split Settlement) See basketInfo below

refundInfo (Refund Account Info)

Field Name	Type	Length	Required	Description
refundBankCode	String	3Byte	✅	Refund Bank Code (See Bank Codes)
refundAccountNo	String	14Byte	✅	Refund Account Number
refundDepositName	String	50Byte	✅	Account Holder Name
depositPgCno	String	20Byte		Deposit Transaction ID (Required for multi-deposit account refunds)

taxInfo (Complex Tax Info)

Field Name	Type	Length	Required	Description
taxationAmount	Number		✅	Refund Taxable Amount
taxFreeAmount	Number		✅	Refund Tax-free Amount
vatAmount	Number		✅	Refund VAT Amount

basketInfo (Basket Info for Split Settlement)

Field Name	Type	Length	Required	Description
productPgCno	String	20Byte	✅	Individual Product PG Transaction ID
sellerId	String	50Byte	✅	Seller ID

Request Example

{
    "mallId": "{Merchant ID}", 
    "shopTransactionId": "{API Idempotency Key}", 
    "pgCno": "{Original PG Transaction ID}",
    "reviseTypeCode": "40",
    "cancelReqDate": "{Current Date}",
    "msgAuthValue": "{Message Auth Value}",
    "reviseMessage": "Customer Changed Mind",
    "refundInfo": {
        "refundBankCode": "003",
        "refundAccountNo": "{Refund Account No}",
        "refundDepositName": "John Doe",
        "depositPgCno": "{Deposit Transaction ID}"
    }
}

Response

Parameters

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code (Success: “0000”)
resMsg	String	1000Byte	✅	Response Message
shopTransactionId	String	60Byte	✅	Returns the value sent in the request
mallId	String	8Byte		Merchant ID assigned by KICC
oriPgCno	String	20Byte		Original PG Transaction ID
cancelPgCno	String	20Byte		Refund PG Transaction ID
cancelAmount	Number		✅	Canceled Amount
remainAmount	Number			Remaining Balance (Returned if requested)
transactionDate	String	14Byte		Transaction Date/Time (yyyyMMddHHmmss)
statusCode	String	4Byte		Transaction Status Code (See Status Codes)
statusMessage	String	50Byte		Transaction Status Message
escrowUsed	String	1Byte		Escrow Usage (Y/N)
reviseInfo	Object			Refund Response Info See reviseInfo below

reviseInfo (Refund Response Info)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See Codes)
approvalNo	String	50Byte		Refund Approval Number
approvalDate	String	14Byte	✅	Refund Date/Time (yyyyMMddHHmmss)
refundInfo	Object		✅	Refund Detail Info See refundInfo below
cashReceiptInfo	Object			Cash Receipt Cancel Detail See cashReceiptInfo below

reviseInfo > refundInfo (Refund Details)

Field Name	Type	Length	Required	Description
refundDate	String	14Byte	✅	Expected Refund Date (yyMMddHHmmss)
depositPgCno	String	20Byte	✅	Virtual Account Deposit Transaction ID

reviseInfo > cashReceiptInfo (Cash Receipt Cancel Details)

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code
resMsg	String	1000Byte	✅	Response Message
approvalNo	String	50Byte		Cancellation Approval Number
cancelDate	String	14Byte		Cancellation Date/Time (yyyyMMddHHmmss)

Response Example

{
   "resCd": "0000",
   "resMsg": "Refund Successful",
   "mallId": "{Requested Merchant ID}",
   "shopTransactionId": "{Requested API Idempotency Key}",
   "oriPgCno": "{Original PG Transaction ID}",
   "cancelPgCno": "{Refund PG Transaction ID}",  
   "shopOrderNo": "{Merchant Order No}",
   "cancelAmount": "51004",
   "remainAmount": "0",
   "transactionDate": "20210326090200",
   "statusCode": "RF01",
   "statusMessage": "Refund Requested",
   "reviseInfo": {
      "payMethodTypeCode": "11",
      "approvalDate": "20210326090200",
      "refundInfo": {
         "refundDate": "20210326090200",
         "depositPgCno": "{Deposit Transaction ID}"
      }
   }
}

Change Type Codes (reviseTypeCode)

Code	Service Name	Description
60	Settlement Full Refund	Full Refund for Virtual Account, Mobile Payment
62	Settlement Partial Refund	Partial Refund for Virtual Account, Mobile Payment
63	Real-time Refund	Real-time Refund for Virtual Account, Mobile Payment (Full/Partial distinction is handled by Sub-Type Code)

Change Sub-Type Codes (reviseSubTypeCode)

Type	Code	Service Name	Description
Settlement Refund	RF01	Refund Request	Same code applies for both Full and Partial refunds
Real-time Refund	10	Full Refund (Auth by KICC)	KICC verifies the account then processes refund
	11	Partial Refund (Auth by KICC)	KICC verifies the account then processes refund
	20	Full Refund (Auth by Merchant)	Merchant verifies the account then KICC processes refund
	21	Partial Refund (Auth by Merchant)	Merchant verifies the account then KICC processes refund

Message Authentication Value

The Message Authentication Value is constructed by combining the fields below and hashing the result using HmacSHA256. (See Message Authentication)

pgCno(PG Transaction ID) + “|” + shopTransactionId(Merchant Transaction ID)