Cancel Payment

This API is used to fully or partially cancel a completed transaction.

Note

For cancelling Escrow approval transactions, please refer to Escrow Status Change.

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 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
amount	Number			Cancellation Amount. Required for Partial Cancellation.
remainAmount	Number			Remaining Amount. Used for validation during Partial Cancellation.
clientIp	String	20Byte		Requestor IP
clientId	String	32Byte		Requestor ID (Merchant Admin Login ID)
cancelReqDate	String	8Byte	✅	Cancellation 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 Cancellation
refundQueryFlag	String	1Byte		Refund Result Query Flag ('Y': Query). Required in case of timeout. Retry if response is "VTIM" or "VT00".
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

taxInfo (Complex Tax Info)

Field Name	Type	Length	Required	Description
taxationAmount	Number		✅	Cancelled Taxable Amount
taxFreeAmount	Number		✅	Cancelled Tax-free Amount
vatAmount	Number		✅	Cancelled 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"
}

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 Payment PG Transaction ID
cancelPgCno	String	20Byte		Cancellation 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)
multiCardAmount	String	12Byte		Payco Card Cancellation Amount
multiPntAmount	String	12Byte		Payco Point Cancellation Amount
multiCponAmount	String	12Byte		Payco Coupon Cancellation Amount
reviseInfo	Object			Cancellation Response Info See reviseInfo below

reviseInfo (Cancellation Response Info)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See Codes)
approvalNo	String	50Byte		Approval Number
approvalDate	String	14Byte	✅	Cancellation Date/Time (yyyyMMddHHmmss)
cardInfo	Object			Credit Card Cancellation Details See cardInfo below
cashReceiptInfo	Object			Cash Receipt Cancellation Details See cashReceiptInfo below

reviseInfo > cardInfo (Credit Card Cancel Details)

Field Name	Type	Length	Required	Description
couponAmount	Number		✅	Cancelled Instant Discount Amount

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": "Cancellation Successful",
   "mallId": "{Requested Merchant ID}",
   "shopTransactionId": "{Requested API Idempotency Key}",
   "oriPgCno": "{Original PG Transaction ID}",
   "cancelPgCno": "{Cancellation PG Transaction ID}",  
   "shopOrderNo": "{Merchant Order No}",
   "cancelAmount": "51004",
   "remainAmount": "0",
   "transactionDate": "20210326090200",
   "statusCode": "TS02",
   "statusMessage": "Approval Cancelled",
   "reviseInfo": {
      "payMethodTypeCode": "11",
      "approvalNo": "00017177",
      "approvalDate": "20210326090200",
      "cardInfo": {
         "couponAmount": 0
      }
   }
}

Change Type Codes (reviseTypeCode)

Code	Service Name	Description
20	Capture	Manual Capture processing for authorized transactions
32	Partial Cancel	Partial cancellation for Credit Card (including Simple Pay)
33	Partial Cancel	Partial cancellation for Bank Transfer, Mobile Payment
40	Full Cancel	Full cancellation of approved transactions (including Virtual Account issuance cancellation)
51	Cash Receipt Cancel	Cancellation of standalone Cash Receipt transaction
52	Cash Receipt Partial	Partial cancellation of standalone Cash Receipt transaction

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)