Payment Approval

This API requests payment approval using the Authorization Transaction ID (authorizationId) received from the payment authentication window.

info

• This API is provided for PG payments.

Critical Integrity Checks

• Timeout/Network Error: If you do not receive a response, you MUST check the status via the Query Transaction Status API using the pgCno and cancel the transaction if necessary.
• Amount Mismatch: If the approved amount differs from your requested amount, you MUST cancel the transaction immediately.
• DB Update Failure: If you fail to update your internal database after receiving a successful approval result, you MUST cancel the transaction.

Request

General Payment

General Payment Request URL

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

Escrow Payment

Escrow Payment Request URL

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

Note

Supports API Idempotency (See API Idempotency)

Caution

Since the final approval process 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)
authorizationId	String	60Byte	✅	Auth Transaction ID (Use the value received from the payment window)
shopOrderNo	String	40Byte	✅	Merchant Order No. (Must match the value used in registration)
approvalReqDate	String	8Byte	✅	Approval Request Date (yyyyMMdd)
escrowInfo	Object			Escrow Info (Required for Escrow Payment) See escrowInfo below

escrowInfo (Escrow Information)

Field Name	Type	Length	Required	Description
escrowTypeCode	String	1Byte	✅	Escrow Type (Fixed "K")
deliveryCode	String	4Byte	✅	Delivery Type ("DE01": Self, "DE02": Courier)
goodsInfoList	Array		✅	Product List (Max 20 items) See goodsInfoList below
recvInfo	Object		✅	Receiver Info (See recvInfo below)

goodsInfoList (Product Detail List)

Field Name	Type	Length	Required	Description
productNo	String	40Byte	✅	Product Management No.
productName	String	100Byte	✅	Product Name
productAmount	Number		✅	Product Amount

Caution

The sum of productAmount in goodsInfoList must match the total payment amount requested during transaction registration.

recvInfo (Receiver Information)

Field Name	Type	Length	Required	Description
recvId	String	50Byte		Receiver ID
recvName	String	50Byte	✅	Receiver Name
recvMobileNo	String	11Byte	✅	Receiver Contact No. (Numbers only)
recvMail	String	100Byte	✅	Receiver Email
recvZipCode	String	6Byte		Receiver Zip Code (Numbers only)
recvAddr1	String	100Byte		Receiver Address 1
recvAddr2	String	100Byte		Receiver Address 2

General Payment

Request Example

{  
    "mallId": "T5102001", 
    "shopOrderNo": "{Merchant Order No}", 
    "shopTransactionId": "{API Idempotency Key}",    
    "authorizationId": "{Auth Transaction ID}",
    "approvalReqDate": "{Approval Request Date}"
}

Escrow Payment

Request Example

{  
   "mallId": "T5102001", 
   "shopOrderNo": "{Merchant Order No}", 
   "shopTransactionId": "{API Idempotency Key}",    
   "authorizationId": "{Auth Transaction ID}",
   "approvalReqDate": "{Approval Request Date}",    
   "escrowInfo": {
      "escrowType": "K",
      "deliveryCode": "DE01",
      "goodsInfoList": [
        {
          "productNo": "{Product ID}",
          "productName": "{Product Name}",
          "productAmount": 1000
        }
      ],
      "recvInfo": {
        "recvName": "John Doe",
        "recvMobileNo": "01012345678",
        "recvMail": "test@email.com",
        "recvAddr": "Seoul, Korea",
        "recvZipCode": "12345",
        "recvAddr1": "Gangnam-gu",
        "recvAddr2": "Teheran-ro"
      }
   }
}

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
shopOrderNo	String	40Byte		Merchant Order No.
pgCno	String	20Byte		PG Transaction ID
amount	Number			Total Payment Amount
transactionDate	String	14Byte		Transaction Date (yyyyMMddHHmmss)
statusCode	String	4Byte		Transaction Status Code (See Status Code)
statusMessage	String	50Byte		Transaction Status Message
msgAuthValue	String	200Byte		Message Integrity Verification Value (See Message Authentication) Contact sales for Secret Key
paymentInfo	Array			Approval Result by Payment Method (See paymentInfo below)

paymentInfo (Approval Result by Payment Method)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See PayMethod Code)
amount	Number		✅	Payment Amount
approvalNo	String	100Byte	✅	Approval Number
approvalDate	String	14Byte	✅	Approval Date (yyyyMMddHHmmss)
maskingNo	String	20Byte	✅	Masked Payment Method Number (e.g., Card No)
payMethodDetailCode	String	3Byte	✅	Detail Code: Issuer Code (See Card Code) or Bank Code (See Bank Code)
payMethodDetailCodeName	String	50Byte		Detail Code Name (e.g., Shinhan Card)
cardInfo	Object			Credit Card Approval Info (See cardInfo below)
cashReceiptInfo	Object			Cash Receipt Info (See cashReceiptInfo below)

paymentInfo > cardInfo (Credit Card Approval Info)

Field Name	Type	Length	Required	Description
acquirerCode	String	3Byte	✅	Acquirer Code (See Card Code)
acquirerName	String	50Byte	✅	Acquirer Name
installmentMonth	Number		✅	Installment Months
isFreeInstallment	Boolean		✅	Interest-free Y/N
cardGubun	String	1Byte	✅	Card Type: Credit(“N”), Check(“Y”), Gift(“G”)

paymentInfo > cashReceiptInfo (Cash Receipt Info)

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

Response Example

{
   "resCd": "0000",
   "resMsg": "MPI Payment Success",
   "mallId": "{Merchant ID}",
   "pgCno": "{PG Transaction ID}",
   "shopTransactionId": "{API Idempotency Key}",
   "shopOrderNo": "{Merchant Order No}",
   "amount": "51004",
   "transactionDate": "20210326090200",
   "statusCode": "TS03",
   "statusMessage": "Acquisition Requested",
   "msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
   "escrowUsed": "N",
   "paymentInfo": [
      {
         "payMethodTypeCode": "11",
         "amount": "51004",
         "approvalNo": "00017177",
         "approvalDate": "20210326090200",
         "maskingNo": "45184211******81",
         "payMethodDetailCode": "029",
         "payMethodDetailCodeName": "Shinhan Card",
         "cardInfo": {
            "acquirerCode": "029",
            "acquirerName": "Shinhan Card",
            "installmentMonth": 0,
            "isFreeInstallment": false,
            "cardGubun": "N"
         }
      }
   ]
}

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) + “|” + amount(Total Amount) + “|” + transactionDate(yyyyMMddHHmmss)