Open Registration Window

Transaction Registration (Request Window URL)

To open the registration screen, you must first register the customer information and receive the Billing Key Registration Window URL as a response.

The flow is as follows:

Request

Request URL

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

Parameters

Field Name	Type	Length	Required	Description
mallId	String	8Byte	✅	Merchant ID assigned by KICC
shopOrderNo	String	40Byte	✅	Merchant Order No. Must be Unique.
amount	Number		✅	Payment Amount. Fixed at 0.
payMethodTypeCode	String	2Byte	✅	Fixed at "81" for Recurring Payment.
currency	String	2Byte	✅	Currency Code (KRW: “00”)
returnUrl	String	256Byte	✅	URL to redirect to after authentication completes.
deviceTypeCode	String	20Byte	✅	Client Device Type PC: “pc”, Mobile: “mobile”
clientTypeCode	String	2Byte	✅	Window Type Code (Fixed at "00" for Integrated)
langFlag	String	3Byte		KOR: Korean, ENG: English, JPN: Japanese, CHN: Chinese
orderInfo	Object		✅	Order Info (See orderInfo below)
payMethodInfo	Object			Payment Method Info (See payMethodInfo below)
shopValueInfo	Object			Merchant Custom Fields (Do not include PII/Sensitive Data)

orderInfo (Order Information)

Field Name	Type	Length	Required	Description
goodsName	String	50Byte	✅	Product Name
goodsTypeCode	String	1Byte		Product Type Code Physical: "0", Digital/Content: "1"
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		✅	Input Option Info (See billKeyMethodInfo below)

payMethodInfo > billKeyMethodInfo (Input Option Info)

Field Name	Type	Length	Required	Description
certType	String	1Byte	✅	Credit Card Auth Type (Determines displayed fields) "0": Card No, Expiry, DOB, Password "1": Card No, Expiry, DOB "2": Card No, Expiry

shopValueInfo (Merchant Custom Fields)

Field Name	Type	Length	Required	Description
value1	String	64Byte		Field 1
value2	String	64Byte		Field 2
value3	String	32Byte		Field 3
value4	String	32Byte		Field 4
value5	String	64Byte		Field 5
value6	String	64Byte		Field 6
value7	String	64Byte		Field 7

Request Example

{  
    "mallId": "T5102001", 
    "shopOrderNo": "{Merchant Order No}", 
    "amount": 0, 
    "payMethodTypeCode": "81", 
    "currency": "00",
    "clientTypeCode": "00", 
    "returnUrl": "{Merchant Return URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "Sample Product Name" 
    }
}

Response

Parameters

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code (Success: “0000”)
resMsg	String	1000Byte	✅	Response Message
authPageUrl	String	256Byte		Billing Key Registration Window URL

Response Example

{
   "resCd": "0000",
   "resMsg": "Success",
   "authPageUrl": "{Registration Window URL}"
}

Handle Registration Result (Return URL)

After authentication is complete, the result is sent to the merchant's returnUrl via POST.

Request (Incoming to Merchant)

Incoming Request

POST {Merchant Return URL}
Content-type: application/x-www-form-urlencoded

Parameters (Response Data)

Field Name	Type	Length	Required	Description
resCd	String	4Byte	✅	Response Code (Success: “0000”)
resMsg	String	1000Byte	✅	Response Message
shopOrderNo	String	40Byte		Merchant Order No. Returns the value sent during registration.
authorizationId	String	60Byte		Authorization ID. (Required for Billing Key Issuance API)
shopValue1	String	64Byte		Field 1, Returns the value sent during registration
shopValue2	String	64Byte		Field 2, Returns the value sent during registration
shopValue3	String	32Byte		Field 3, Returns the value sent during registration
shopValue4	String	32Byte		Field 4, Returns the value sent during registration
shopValue5	String	64Byte		Field 5, Returns the value sent during registration
shopValue6	String	64Byte		Field 6, Returns the value sent during registration
shopValue7	String	64Byte		Field 7, Returns the value sent during registration