Issue Billing Key

This API issues a Billing Key using the Authorization ID (authorizationId) received from the response of the Billing Key Registration Window.

Request

Request URL

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

Note

Supports API Idempotency (See API Idempotency)

Caution

Since the final issuance of the Billing Key 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 registration window. Use the value exactly as received.
shopOrderNo	String	40Byte	✅	Merchant Order No. Use the value exactly as requested.
approvalReqDate	String	8Byte	✅	Request Date (yyyyMMdd)

Request Example

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

Response

Parameters

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code (Success: “0000”)
resMsg	String	1000Byte	✅	Response Message
mallId	String	8Byte	✅	Merchant ID assigned by KICC
shopTransactionId	String	60Byte	✅	Returns the same value sent in the request
shopOrderNo	String	40Byte		Returns the same value sent in the request
pgCno	String	20Byte		PG Transaction ID
transactionDate	String	14Byte		Transaction Date/Time (yyyyMMddHHmmss)
msgAuthValue	String	200Byte		Used to verify response integrity (See Message Authentication) Contact sales representative for the Secret Key
paymentInfo	Object			Result info by Payment Method (See paymentInfo below)

paymentInfo (Result info by Payment Method)

Field Name	Type	Length	Required	Description
payMethodTypeCode	String	2Byte	✅	Payment Method Code (See Payment Method Codes)
cardInfo	Object			Credit Card Result Info (See cardInfo below)

paymentInfo > cardInfo (Credit Card Result Info)

Field Name	Type	Length	Required	Description
cardNo	String	20Byte	✅	Billing Key (Required for Payment Approval Request)
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
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 provided in the response
cardMaskNo	String	40Byte		Masked Card Number (*)

Response Example

{
   "resCd": "0000",
   "resMsg": "Success",
   "mallId": "{Requested Merchant ID}",
   "pgCno": "{PG Transaction ID}",
   "shopTransactionId": "{Requested API Idempotency Key}",
   "shopOrderNo": "{Merchant Order No}",   
   "transactionDate": "20210326090200",   
   "msgAuthValue": "e06540df5ac28ac877fb4f063d06d5f9c3ee2a3a8820a888bfc8db1577a7fe",
   "escrowUsed": "N",
   "paymentInfo": {
      "payMethodTypeCode": "11",
      "cardInfo": {
         "cardNo": "{Billing Key}",
         "issuerCode": "029",
         "issuerName": "Shinhan Card",
         "acquirerCode": "029",
         "acquirerName": "Shinhan Card",         
         "cardGubun": "N",
         "cardBizGubun": "P",
         "partCancelUsed": "Y",
         "cardMaskNo": "54646500******01"
      }
   }
}

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