Register Transaction

By registering order information to open the payment screen, you can receive the Payment Window URL in the response.

Request

Request URL

POST https://{API Domain}/api/v2/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
payMethodTypeCode	String	2Byte	✅	Standalone API Payment Method Call Code
currency	String	2Byte	✅	Currency Code (KRW: “00”)
returnUrl	String	256Byte	✅	URL to redirect to after authentication completes.
deviceTypeCode	String	20Byte	✅	Device Type PC: “pc”, Mobile: “mobile”
clientTypeCode	String	2Byte	✅	Fixed at "10"
appScheme	String	256Byte		Merchant App Scheme (Required for iOS App-to-App return) See WebView Guide
orderInfo	Object		✅	Order Info See orderInfo below
payMethodInfo	Object			Payment Method Management Info See payMethodInfo below
taxInfo	Object			Complex Tax Info (Required if using Complex Tax) See taxInfo below
shopValueInfo	Object			Merchant Custom Fields (Returned in Approval/Notify response) See shopValueInfo below
cashInfo	Object			Cash Receipt Info See cashInfo below
depositInfoList	Array			Resource Circulation Deposit List See depositInfoList below
escrowInfo	Object			Escrow Info (Required if using Escrow) See escrowInfo below
basketInfoList	Array			Basket List (Required if using Split Settlement) See basketInfoList 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 (Required for 3D-Secure (Overseas: Visa, Master, JCB, Amex))
customerContactNo	String	11Byte		Contact Number (Numbers only)
customerAddr	String	200Byte		Customer Address

payMethodInfo (Payment Method Management Info)

Field Name	Type	Length	Required	Description
cardMethodInfo	Object			Credit Card Config Info See cardMethodInfo below
mobileMethodInfo	Object			Mobile Config Info See mobileMethodInfo below

payMethodInfo > cardMethodInfo (Credit Card Config)

Field Name	Type	Length	Required	Description
installmentMonthList	Array			List of installment months to display. Empty: Lump-sum for Cards / DB lookup for Simple Pay. Lump-sum only: [0] Up to 6 months: [0, 2, 3, 4, 5, 6]
setFreeInstallment	String	1Byte		Use Interest-free ("Y"/"N") (See Inquiry)
setCardPoint	String	1Byte		Use Card Points ("Y"/"N")
setCouponInfo	String	1Byte		Use Instant Discount Coupon ("Y") (See Inquiry)
chainCode	String	1Byte		Card Window Control Code "3": App Card payment only
onlyCreditCard	String	1Byte		KB Kookmin Card Parameter "1": KB Pay App allows KB Card only
appCode	String	20Byte		Woori Card Control Code Empty: Show all, "WONCARD": Woori Card only, "WONBANK": Woori Bank only
joinCd	String	4Byte		Affiliate Service Code
usedSpayCode	Array			List of Simple Pay providers (See Codes). Only 1 allowed. Must include ["CRD"] if payment method is Credit Card.
cardInfoList	Array			List of Credit Card companies to display See cardInfoList below
couponInfo	Object			Instant Discount Coupon Usage Info See couponInfo below

payMethodInfo > cardMethodInfo > cardInfoList (Credit Card List)

Field Name	Type	Length	Required	Description
cardCd	String	3Byte	✅	Card Company Code to display (See Codes). Only 1 allowed.
cardPoint	String	2Byte		Card Point Value. Fixed at "60" if setCardPoint is "Y".
cardNo	String	20Byte		Card Number for 3D-Secure (Overseas: Visa, Master, JCB, Amex)
expireDate	String	4Byte		Expiry Date for 3D-Secure (YYMM). e.g., Nov 2026 -> "2611"
cardHolderName	String	45Byte		English name of the cardholder for 3D-Secure (Overseas: Visa, Master, JCB, Amex)

payMethodInfo > cardMethodInfo > couponInfo (Instant Discount Coupon Info)

Field Name	Type	Length	Required	Description
cponId	String	10Byte	✅	Coupon Group ID (Use couponGid from Coupon Inquiry API)
cponAmount	Number		✅	Discount Amount (For percentage-based coupons, rounded based on discountRoundingUnit setting)
cponRate	Number			Coupon Discount Rate(Required Only for Percentage coupon)

payMethodInfo > mobileMethodInfo (Mobile Config)

Field Name	Type	Length	Required	Description
mobileCd	String	3Byte	✅	Carrier Code (See Codes)

taxInfo (Complex Tax Info)

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

shopValueInfo (Merchant Custom Fields)

Field Name	Type	Length	Required	Description
value1	String	1000Byte		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

cashInfo (Cash Receipt Info)

Field Name	Type	Length	Required	Description
issueType	String	2Byte	✅	Issue Purpose "01": Tax Deduction, "02": Expenditure Proof, "03": Voluntary
authType	String	1Byte	✅	Auth Type "1": Card No, "3": Mobile No, "4": Biz No
authValue	String	20Byte	✅	Identity Data (Numbers only) Fixed at "0100001234" for Voluntary Issuance.

depositInfoList (Resource Circulation Deposit List)

Field Name	Type	Length	Required	Description
dpsType	String	1Byte	✅	Deposit Type (Cup Deposit: “C”)
dpsAmount	Number		✅	Deposit Amount (Total amount per type)

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopOrderNo": "{Merchant Order No}", 
    "amount": 1000, 
    "payMethodTypeCode": "11", // Credit Card
    "currency": "00",
    "clientTypeCode": "10", 
    "returnUrl": "{Merchant Return URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "Sample Product Name" 
    },
    "payMethodInfo": {
        "cardMethodInfo": {
            "usedSpayCode": ["CRD"], // Credit Card
            "installmentMonthList": [0],
            "cardInfoList": [
                {
                    "cardCd": "026",  // Card Company Code
                    "cardPoint": "60"
                }
            ],
        }
    }
}

escrowInfo (Escrow Information)

To use the Escrow Service, please add the following information to your request.

Field Name	Type	Length	Required	Description
escrowTypeCode	String	1Byte	✅	Escrow Type. Fixed at "K".
deliveryCode	String	4Byte	✅	Delivery Type ("DE01": Self, "DE02": Courier)
goodsInfoList	Array		✅	List of Goods Information (Max 20 items)
recvInfo	Object		✅	Recipient Info

escrowInfo > goodsInfoList (List of Goods Information)

Field Name	Type	Length	Required	Description
productNo	String	40Byte	✅	Unique Product No. Must be unique within the basket.
productName	String	50Byte	✅	Product Name
productAmount	Number		✅	Product Amount

CAUTION

The sum of the individual product amounts in the goodsInfoList must match the requested payment amount of Register Transaction.

escrowInfo > recvInfo (Recipient Info)

Field Name	Type	Length	Required	Description
recvName	String	20Byte	✅	Recipient Name
recvMobileNo	String	11Byte	✅	Recipient Contact No. (Numbers only)
recvMail	String	50Byte		Recipient Email
recvZipCode	String	6Byte		Recipient Zip Code
recvAddr1	String	100Byte		Address Line 1
recvAddr2	String	100Byte		Address Line 2

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopOrderNo": "{Merchant Order No}", 
    "amount": 1000, 
    "payMethodTypeCode": "21", 
    "currency": "00",
    "clientTypeCode": "10", 
    "returnUrl": "{Merchant Return URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "Sample Product Name" 
    },
    "escrowInfo": {
        "escrowType": "K",
        "deliveryCode": "DE01",
        "goodsInfoList": [
            {
                "productNo": "{Unique Product No}",
                "productName": "{Product Name}",
                "productAmount": 1000
            }
        ],
        "recvInfo": {
            "recvName": "Recipient Name",
            "recvMobileNo": "01012345678",
            "recvMail": "test@email.com",
            "recvAddr": "Seoul, Korea",
            "recvZipCode": "00000",
            "recvAddr1": "Address Line 1",
            "recvAddr2": "Address Line 2"
        }
    }
}

basketInfoList (Basket List)

To use the Split Settlement Service, please add the following information to your request.

Note

• You must obtain a dedicated Split Settlement Merchant ID to use this service.
• This cannot be used in combination with Escrow or Complex Taxation services.

Field Name	Type	Length	Required	Description
productNo	String	40Byte	✅	Unique Product No. Must be unique within the basket.
productName	String	50Byte	✅	Product Name
productAmount	Number		✅	Product Amount
sellerId	String	50Byte	✅	Seller ID
feeUsed	Boolean		✅	Use Seller Fee (true/false)
feeTypeCode	String	1Byte		Fee Type Code (Required if feeUsed is true) Fixed Amount: "A", Rate: "P"
feeCharge	Number			Seller Fee Amount (Required if feeUsed is true) For Rate("P"): Fee % * 10000 (e.g., 2.12% -> 21200)

Request Example

{  
    "mallId": "{Merchant ID}", 
    "shopOrderNo": "{Merchant Order No}", 
    "amount": 1000, 
    "payMethodTypeCode": "11", 
    "currency": "00",
    "clientTypeCode": "10", 
    "returnUrl": "{Merchant Return URL}", 
    "deviceTypeCode": "mobile",     
    "orderInfo": { 
        "goodsName": "Sample Product Name" 
    },
    "payMethodInfo": {
      "cardMethodInfo": {
        "usedSpayCode": ["CRD"],
        "installmentMonthList": [0],
        "cardInfoList": [
          {
            "cardCd": "026"
          }
        ]
      }
    },
    "basketInfoList": [
        {
            "productNo": "{Unique Product No}",
            "productName": "{Product Name}",
            "productAmount": 1000,
            "sellerId": "{Seller ID}",
            "feeUsed": true,
            "feeTypeCode": "P",
            "feeCharge": 2120
        }
    ]
}

Response

Parameters

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

Response Example

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