Payment Approval

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

Critical Warnings

• Timeout & Network Errors: If you do not receive a response due to a timeout or network error, you MUST verify the status using the Transaction Status Check API and cancel the transaction if a valid PG Transaction ID exists.
• Amount Mismatch: If the payment amount in the approval result differs from your merchant's 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.
• UnionPay (China UnionPay): For UnionPay transactions, you must request approval within 30 minutes of receiving the authentication response at your returnUrl. Otherwise, the provider will force cancellation.
• Test Transactions (KakaoPay, TossPay): Test transactions for KakaoPay and TossPay (Carrier Billing) may result in actual charges. You MUST cancel them immediately after testing.

Request

Request URL

POST https://{API Domain}/api/v2/trades/approval
Content-type: application/json; charset=utf-8

Note

Supports API Idempotency (See API Idempotency)

Caution

Since final payment approval 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	✅	Authorization ID received after calling the payment window. Use the value exactly as received.
shopOrderNo	String	40Byte	✅	Merchant Order No. Use the value exactly as requested during registration.
approvalReqDate	String	8Byte	✅	Approval Request Date (yyyyMMdd)

Request Example

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

Response

Parameters

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code (Success: “0000”)
resMsg	String	1000Byte	✅	Response Message
shopTransactionId	String	60Byte		Same value sent in request. Not sent for Webhook (Notify) requests.
mallId	String	8Byte		Merchant ID assigned by KICC
shopOrderNo	String	40Byte		Merchant Order No. Returns the value sent during registration.
pgCno	String	20Byte		PG Transaction ID
amount	Number			Total Payment Amount
transactionDate	String	14Byte		Transaction Date/Time (yyyyMMddHHmmss)
statusCode	String	4Byte		Transaction Status Code (See Status Codes)
statusMessage	String	50Byte		Transaction Status Message
msgAuthValue	String	200Byte		Used to verify response integrity (See Message Authentication) Contact sales for the Secret Key.
escrowUsed	String	1Byte		Escrow Usage (Y/N)
paymentInfo	Object			Approval Info by Payment Method See paymentInfo below
basketInfoList	Array			Basket List (Returned for Split Settlement) See basketInfoList below

paymentInfo (Approval Info by Payment Method)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See Payment Method Codes)
approvalNo	String	100Byte	✅	Approval Number
approvalDate	String	14Byte	✅	Approval Date/Time (yyyyMMddHHmmss)
cpCode	String	4Byte		Service Provider Code (Returned for Simple Pay or Points) (See CP Codes)
multiCardAmount	Number			Card Amount for Payco/KakaoPay/NaverPay
multiPntAmount	Number			Point Amount for Payco/KakaoPay/NaverPay
multiCponAmount	Number			Coupon Amount for Payco/KakaoPay/NaverPay
cardInfo	Object			Credit Card Result Info See cardInfo below
bankInfo	Object			Bank Transfer Result Info See bankInfo below
virtualAccountInfo	Object			Virtual Account Issuance Info See virtualAccountInfo below
mobInfo	Object			Mobile Payment Info See mobInfo below
cashReceiptInfo	Object			Cash Receipt Info See cashReceiptInfo below

paymentInfo > cardInfo (Credit Card Result Info)

Field Name	Type	Length	Required	Description
cardNo	String	20Byte	✅	Card Number (Masked *)
issuerCode	String	3Byte	✅	Issuer Code (See Card Codes)
issuerName	String	50Byte	✅	Issuer Name
acquirerCode	String	3Byte	✅	Acquirer Code (See Card Codes)
acquirerName	String	50Byte	✅	Acquirer Name
installmentMonth	Number		✅	Installment Months
freeInstallmentTypeCode	String	2Byte	✅	Interest-free Type General: “00”, Merchant-paid: “02”, Card-company-paid: “03”
cardGubun	String	1Byte	✅	Card Type: Credit(“N”), Check(“Y”), Gift(“G”)
cardBizGubun	String	1Byte	✅	Card Owner Type: Personal(“P”), Corporate(“C”), Other(“N”)
partCancelUsed	String	1Byte	✅	Partial Cancellation Availability (Y/N)
subCardCd	String	3Byte		BC Affiliate Card Code (Returned for Billing Key Issuance)
couponAmount	Number			Instant Discount Amount
vanSno	String	12Byte		VAN Serial Number

paymentInfo > bankInfo (Bank Transfer Result Info)

Field Name	Type	Length	Required	Description
bankCode	String	3Byte	✅	Bank Code (See Bank Codes)
bankName	String	20Byte	✅	Bank Name

paymentInfo > virtualAccountInfo (Virtual Account Issuance Info)

Field Name	Type	Length	Required	Description
bankCode	String	3Byte	✅	Bank Code (See Bank Codes)
bankName	String	20Byte	✅	Bank Name
accountNo	String	20Byte	✅	Issued Account Number
depositName	String	20Byte	✅	Depositor Name
expiryDate	String	14Byte	✅	Expiration Date

paymentInfo > mobInfo (Mobile Payment Info)

Field Name	Type	Length	Required	Description
authId	String	20Byte	✅	Auth ID
billId	String	20Byte	✅	Bill ID
mobileNo	String	11Byte	✅	Mobile Number
mobileCd	String	3Byte	✅	Carrier Code

paymentInfo > cashReceiptInfo (Cash Receipt Info)

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

basketInfoList (Basket List for Split Settlement)

Field Name	Type	Length	Required	Description
productNo	String	20Byte	✅	Unique Product No. Same value sent during registration.
sellerId	String	50Byte	✅	Seller ID
productPgCno	String	20Byte	✅	Product PG Transaction ID (Used for partial/product cancellation)

Response Example

{
   // Credit Card Payment Approval Response
   "resCd": "0000",
   "resMsg": "Success",
   "mallId": "{Requested Merchant ID}",
   "pgCno": "{PG Transaction ID}",
   "shopTransactionId": "{Requested API Idempotency Key}",
   "shopOrderNo": "{Merchant Order No}",
   "amount": "51004",
   "transactionDate": "20210326090200",
   "statusCode": "TS03",
   "statusMessage": "Capture Requested",
   "msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
   "escrowUsed": "N",
   "paymentInfo": {
      "payMethodTypeCode": "11",
      "approvalNo": "00017177",
      "approvalDate": "20210326090200",
      "cardInfo": {
         "cardNo": "45184211******81",
         "issuerCode": "029",
         "issuerName": "Shinhan Card",
         "acquirerCode": "029",
         "acquirerName": "Shinhan Card",
         "installmentMonth": 0,
         "freeInstallmentTypeCode": "00",
         "cardGubun": "N",
         "cardBizGubun": "P",
         "partCancelUsed": "Y",
         "couponAmount": 0
      }
   }
}

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(Payment Amount) + “|” + transactionDate(Transaction Date/Time)