Payment Cancellation

This API performs full or partial cancellation of a completed transaction.

Note

• This API is provided for PG payment services.
• For Escrow transactions, please refer to the Escrow Status Change guide.

Request

Request URL

POST https://{API Domain}/easypay/payment/cancel.do
Content-type: application/json; charset=euc-kr

Note

Supports API Idempotency (See API Idempotency)

Critical: Timeout Handling

• Since the final cancellation process takes time, you must set the timeout to 30 seconds.
• If you do not receive a response due to a timeout or network error, you MUST check the status via the Query Transaction Status API using the pgCno and retry the cancellation if necessary.

Parameters

Field Name	Type	Length	Required	Description
mallId	String	8Byte	✅	Merchant ID assigned by KICC
shopTransactionId	String	60Byte	✅	Merchant Transaction ID (API Idempotency Key)
shopOrderNo	String	40Byte	✅	Merchant Order No. used in the approval request
pgCno	String	20Byte	✅	Original PG Transaction ID
cancelTxtype	String	2Byte	✅	Cancel Type Full Cancel: “40” Partial Cancel: “32”
amount	Number			Cancel Request Amount
remainAmount	Number			Remaining Amount (For balance verification)
comTaxAmt	Number			Taxable Amount (For complex tax partial cancel)
comFreeAmt	Number			Tax-free Amount (For complex tax partial cancel)
comVatAmt	Number			VAT Amount (For complex tax partial cancel)
msgAuthValue	String	200Byte	✅	Message Integrity Verification Value (See Message Authentication)
cancelReqDate	String	8Byte	✅	Cancel Request Date (yyyyMMdd)

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopTransactionId": "{API Idempotency Key}", 
    "pgCno": "{Original PG Transaction ID}",
    "cancelTxtype": "40",
    "cancelReqDate": "{Request Date}",
    "msgAuthValue": "{Message Auth Value}"
}

Response

Parameters

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Result Code (Success: “0000”)
resMsg	String	1000Byte	✅	Result 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		New Cancel PG Transaction ID
shopOrderNo	String	40Byte		Merchant Order No.
cancelAmount	Number			Canceled Amount
remainAmount	Number			Remaining Balance after cancellation
transactionDate	String	14Byte		Transaction Date (yyyyMMddHHmmss)
statusCode	String	4Byte		Transaction Status Code (See Status Code)
statusMessage	String	50Byte		Transaction Status Message
paymentInfo	Array			Cancellation Details by Payment Method (See paymentInfo below)

paymentInfo (Cancellation Details)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See PayMethod Code)
cancelAmount	Number		✅	Canceled Amount
remainAmount	Number			Remaining Balance (Returned if requested)
couponAmount	Number			Instant Discount Cancel Amount
cashReceiptInfo	Object			Cash Receipt Cancel Info (See cashReceiptInfo below)

cashReceiptInfo (Cash Receipt Cancel Info)

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

Response Example

{
   "resCd": "0000",
   "resMsg": "Cancel Success",
   "mallId": "{Merchant ID}",
   "shopTransactionId": "{API Idempotency Key}",
   "oriPgCno": "{Original PG Transaction ID}",
   "cancelPgCno": "{Cancel PG Transaction ID}",
   "shopOrderNo": "{Merchant Order No}",
   "cancelAmount": "51004",
   "remainAmount": "0",
   "transactionDate": "20210326090200",
   "statusCode": "TS02",
   "statusMessage": "Approval Cancelled",
   "paymentInfo": [
      {
         "payMethodTypeCode": "11",
         "cancelAmount": 5100
      }
   ]
}

Message Authentication Value

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

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