Payment Approval

This API requests approval for Recurring Payments.

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 to prevent data inconsistency.

Request

Request URL

POST https://{API Domain}/api/trades/approval/batch
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)
shopOrderNo	String	40Byte	✅	Merchant Order No. Must be Unique.
approvalReqDate	String	8Byte	✅	Approval Request Date (yyyyMMdd)
amount	Number		✅	Payment Amount
currency	String	2Byte	✅	Currency Code (KRW: “00”)
orderInfo	Object		✅	Order Info (See orderInfo below)
payMethodInfo	Object		✅	Payment Method Info (See payMethodInfo below)
taxInfo	Object			Complex Tax Info (Required if using Complex Tax) (See taxInfo below)

orderInfo (Order Information)

Field Name	Type	Length	Required	Description
goodsName	String	50Byte	✅	Product Name
customerInfo	Object			Customer Info (See customerInfo below)

orderInfo > customerInfo (Customer Information)

Field Name	Type	Length	Required	Description
customerId	String	20Byte		Customer ID
customerName	String	20Byte		Customer Name
customerMail	String	50Byte		Customer Email
customerContactNo	String	11Byte		Contact Number (Numbers only)
customerAddr	String	200Byte		Customer Address

payMethodInfo (Payment Method Info)

Field Name	Type	Length	Required	Description
billKeyMethodInfo	Object		✅	Billing Key Info (See billKeyMethodInfo below)
cardMethodInfo	Object		✅	Credit Card Info (See cardMethodInfo below)

payMethodInfo > billKeyMethodInfo (Billing Key Info)

Field Name	Type	Length	Required	Description
batchKey	String	60Byte	✅	Billing Key. Use the cardNo value returned in the Billing Key Issuance response.

payMethodInfo > cardMethodInfo (Credit Card Info)

Field Name	Type	Length	Required	Description
installmentMonth	Number		✅	Installment Months
freeInstallmentUsed	Boolean			Interest-free Usage (true: Use, false: Do not use)
joinCd	String	4Byte		Affiliate Service Code

taxInfo (Complex Tax Info)

Field Name	Type	Length	Required	Description
taxAmount	Number		✅	Taxable Amount
freeAmount	Number		✅	Tax-free Amount
vatAmount	Number		✅	VAT Amount

Request Example

{  
    "mallId": "T5102001", 
    "shopOrderNo": "{Merchant Order No}", 
    "shopTransactionId": "{API Idempotency Key}",       
    "approvalReqDate": "{Request Date}",
    "amount": 1000,     
    "currency": "00",    
    "orderInfo": { 
        "goodsName": "Sample Product Name" 
    },
    "payMethodInfo": {
        "billKeyMethodInfo": {
            "batchKey": "{Issued Billing Key}"
        },
        "cardMethodInfo":{
            "installmentMonth": 12
        }
    }
}

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. Same value sent in request.
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)

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)
cardInfo	Object		✅	Credit Card Result Info (See cardInfo 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)
vanSno	String	12Byte		VAN Serial Number

Response Example

{
   "resCd": "0000",
   "resMsg": "Payment Successful",
   "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"
      }
   }
}

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)