Change Escrow Status

This API is used to change the status of an Escrow transaction.

Note

• Purchase Confirmation and Purchase Rejection are handled via the confirmation email sent to the customer.
• Once the customer confirms or rejects the purchase, the result is sent via Webhook (Notification).
• In case of Purchase Rejection, please contact KICC directly.
• Partial Cancellation and Partial Refund are not supported.

State Diagram

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 processing 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 Fixed at "61" for Escrow Status Change
reviseSubTypeCode	String	4Byte		Change Sub-Type Code (See Sub-Codes)
amount	Number			Cancel Amount.
remainAmount	Number			Remaining Amount.
clientIp	String	20Byte		Requestor IP
clientId	String	32Byte		Requestor ID (Merchant Admin Login ID)
cancelReqDate	String	8Byte	✅	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 Change
escrowInfo	Object			Escrow Info (Required for Shipping Request) See escrowInfo below
taxInfo	Object			Complex Tax Info (Required if using Complex Tax) See taxInfo below
refundInfo	Object			Refund Info (Required for Refund Request) See refundInfo below

escrowInfo (Escrow Information)

Field Name	Type	Length	Required	Description
deliveryCode	String	4Byte	✅	Delivery Type Self-delivery: "DE01", Courier: "DE02"
deliveryCorpCode	String	4Byte	✅	Courier Code (See Courier Codes)
deliveryInvoice	String	30Byte	✅	Tracking Number (Invoice No.)

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

refundInfo (Refund Information)

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

Cancel Auth

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopTransactionId": "{API Idempotency Key}", 
    "pgCno": "{PG Transaction ID}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES02",
    "cancelReqDate": "{Request Date}",
    "msgAuthValue": "{Message Auth Value}"    
}

Request Refund

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopTransactionId": "{API Idempotency Key}", 
    "pgCno": "{PG Transaction ID}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES05",
    "cancelReqDate": "{Request Date}",
    "msgAuthValue": "{Message Auth Value}",
    "refundInfo": {
        "refundBankCode": "008",
        "refundAccountNo": "1231231230",
        "refundDepositName": "Account Holder Name"
    } 
}

Shipping

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopTransactionId": "{API Idempotency Key}", 
    "pgCno": "{PG Transaction ID}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES07",
    "cancelReqDate": "{Request Date}",
    "msgAuthValue": "{Message Auth Value}",
    "escrowInfo": {
        "deliveryCode": "DE02",
        "deliveryCorpCode": "DC01",
        "deliveryInvoice": "12345678901234567890123456"
    } 
}

Response

For the response format of Escrow Status Change, please refer to the Payment Management API Guide.

Change Sub-Type Codes (reviseSubTypeCode)

Code	Service Name	Description
ES02	Cancel Authorization	Cancel Bank Transfer Auth or Virtual Account Issuance
ES05	Request Refund	Refund request for deposited Virtual Account transaction
ES07	Shipping	Request after product shipment
ES08	Cancel during Shipping	Cancel request during shipping
ES09	Complete Cancel (Shipping)	Complete cancellation after product return
ES10	Refund during Shipping	Refund request during shipping
ES11	Complete Refund (Shipping)	Complete refund after product return
ES14	Refund after Confirm	Refund request after purchase confirmation
ES15	Complete Refund (Confirm)	Complete refund after product return
ES16	Cancel after Confirm	Cancel request after purchase confirmation
ES19	Complete Cancel (Confirm)	Complete cancellation after product return

Courier Codes (deliveryCorpCode)

Code	Courier	Code	Courier
DC01	CJ Logistics (Korea Express)	DC02	CJ GLS
DC03	SC Logis	DC04	Yellow Cap
DC05	Logen	DC06	Dongbu Express
DC07	Korea Post	DC08	Hanjin
DC09	Hyundai	DC10	KGB
DC11	Hanaro	DC12	Others

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)