Skip to main content

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 Request URL
POST https://{API Domain}/easypay/payment/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 NameTypeLengthRequiredDescription
mallIdString8Byte✅Merchant ID assigned by KICC
shopTransactionIdString60Byte✅Merchant Transaction ID (API Idempotency Key)
authorizationIdString60Byte✅Auth Transaction ID (Use the value received from the payment window)
shopOrderNoString40Byte✅Merchant Order No. (Must match the value used in registration)
approvalReqDateString8Byte✅Approval Request Date (yyyyMMdd)
escrowInfoObjectEscrow Info (Required for Escrow Payment)
See escrowInfo below

escrowInfo (Escrow Information)​

Field NameTypeLengthRequiredDescription
escrowTypeCodeString1Byte✅Escrow Type (Fixed "K")
deliveryCodeString4Byte✅Delivery Type ("DE01": Self, "DE02": Courier)
goodsInfoListArray✅Product List (Max 20 items)
See goodsInfoList below
recvInfoObject✅Receiver Info (See recvInfo below)

goodsInfoList (Product Detail List)​

Field NameTypeLengthRequiredDescription
productNoString40Byte✅Product Management No.
productNameString100Byte✅Product Name
productAmountNumber✅Product Amount
Caution

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

recvInfo (Receiver Information)​

Field NameTypeLengthRequiredDescription
recvIdString50ByteReceiver ID
recvNameString50Byte✅Receiver Name
recvMobileNoString11Byte✅Receiver Contact No. (Numbers only)
recvMailString100Byte✅Receiver Email
recvZipCodeString6ByteReceiver Zip Code (Numbers only)
recvAddr1String100ByteReceiver Address 1
recvAddr2String100ByteReceiver Address 2
Request Example
{  
"mallId": "T5102001",
"shopOrderNo": "{Merchant Order No}",
"shopTransactionId": "{API Idempotency Key}",
"authorizationId": "{Auth Transaction ID}",
"approvalReqDate": "{Approval Request Date}"
}

Response​

Parameters​

Field NameTypeLengthRequiredDescription
resCdString4Byte✅Result Code (Success: “0000”)
resMsgString1000Byte✅Result Message
shopTransactionIdString60Byte✅Returns the value sent in the request
mallIdString8ByteMerchant ID assigned by KICC
shopOrderNoString40ByteMerchant Order No.
pgCnoString20BytePG Transaction ID
amountNumberTotal Payment Amount
transactionDateString14ByteTransaction Date (yyyyMMddHHmmss)
statusCodeString4ByteTransaction Status Code (See Status Code)
statusMessageString50ByteTransaction Status Message
msgAuthValueString200ByteMessage Integrity Verification Value (See Message Authentication)
Contact sales for Secret Key
paymentInfoArrayApproval Result by Payment Method (See paymentInfo below)

paymentInfo (Approval Result by Payment Method)​

Field NameTypeLengthRequiredDescription
payMethodTypeCodeString2Byte✅Payment Method Code (See PayMethod Code)
amountNumber✅Payment Amount
approvalNoString100Byte✅Approval Number
approvalDateString14Byte✅Approval Date (yyyyMMddHHmmss)
maskingNoString20Byte✅Masked Payment Method Number (e.g., Card No)
payMethodDetailCodeString3Byte✅Detail Code: Issuer Code (See Card Code) or Bank Code (See Bank Code)
payMethodDetailCodeNameString50ByteDetail Code Name (e.g., Shinhan Card)
cardInfoObjectCredit Card Approval Info (See cardInfo below)
cashReceiptInfoObjectCash Receipt Info (See cashReceiptInfo below)

paymentInfo > cardInfo (Credit Card Approval Info)​

Field NameTypeLengthRequiredDescription
acquirerCodeString3Byte✅Acquirer Code (See Card Code)
acquirerNameString50Byte✅Acquirer Name
installmentMonthNumber✅Installment Months
isFreeInstallmentBoolean✅Interest-free Y/N
cardGubunString1Byte✅Card Type: Credit(“N”), Check(“Y”), Gift(“G”)

paymentInfo > cashReceiptInfo (Cash Receipt Info)​

Field NameTypeLengthRequiredDescription
resCdString4Byte✅Result Code
resMsgString1000Byte✅Result Message
approvalNoString50ByteApproval Number
approvalDateString14ByteApproval 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)