KakaoPay Digital Wallet Payment (Checkout)
KakaoPay digital wallet payment is a service that processes payments through KakaoPay.
Test Key Information
API Information
POST/corp/main.do
Content-Type
application/x-www-form-urlencodedSandbox
https://tbnpg.settlebank.co.kr/corp/main.doProduction
https://npg.settlebank.co.kr/corp/main.doImportant Notes
KakaoPay sandbox notice
Actual payments are processed even in the sandbox environment. Transactions made in the sandbox are automatically cancelled.
- Actual payments are processed in the sandbox environment, so please take care.
- Transactions made in the sandbox are automatically cancelled.
- Available payment methods differ by tax type:
- Taxable / Tax-exempt: Credit card, Money, Money + Points combined payment
- Mixed tax: Credit card only
NOTE
Subscription and sequential payment notice
General, subscription, and sequential payments cannot share a merchant ID. Get a separate merchant ID for each purpose through your sales representative, and set autoPayType for subscription or sequential payments. Upon successful payment, a billKey is issued, which can be used to call the Charge Subscription API. See merchant IDs by purpose
NOTE
What is sequential payment?
Sequential payment is a method where, if payment with a registered payment method fails, the system automatically attempts payment using another payment method registered by the user in KakaoPay.
Request Parameters
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
Required Parameters
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Unique merchant ID assigned by Hecto Financial
Unique merchant ID assigned by Hecto Financial
hecto_test: KakaoPay general payment nxkkp_auto: KakaoPay subscription (automatic payment) nxkkp_seq: KakaoPay sequential payment└methodAN(20)Alphanumeric, up to 20 bytes*Payment method code
Payment method code
*Fixed value
└corpPayCodeAN(3)Alphanumeric, up to 3 bytes*Digital wallet provider code
Digital wallet provider code
*KakaoPay: KKP
└trdDtN(8)Numeric, up to 8 bytes*Request date (yyyyMMdd)
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HH24MISS)
Request time (HH24MISS)
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant (no Korean characters)
Unique order number generated by the merchant (no Korean characters)
└mchtNameAHN(100)Alphanumeric + Korean, up to 100 bytes*Merchant name
Merchant name
└pmtPrdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Product name
Product name
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amountTransaction amount
*For subscription or sequential payment key issuance (autoPayType=A or S), requesting KRW 0 issues a billKey without a charge.
└notiUrlAN(250)Alphanumeric, up to 250 bytes*Webhook endpoint URL for server-to-server payment result delivery
Webhook endpoint URL for server-to-server payment result delivery
└nextUrlAN(250)Alphanumeric, up to 250 bytes*URL to redirect to after the payment result screen
URL to redirect to after the payment result screen
*Redirected when a button inside the checkout is clicked. Use the outStatCd value to check whether the payment succeeded (0021) or failed (0031).
└cancUrlAN(250)Alphanumeric, up to 250 bytes*URL to redirect to when the customer clicks the X button in the checkout
URL to redirect to when the customer clicks the X button in the checkout
*Browser close and back navigation are not detected.
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256Hash value generated using SHA256(auto-generated)Hash value generated using SHA256
NOTE
Hash generation combination
mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt (plaintext) + hashKey
Optional Parameters
└taxTypeCdA(1)Alphabetic, up to 1 bytesTax type
Tax type
N: Taxable Y: Tax-exempt G: Mixed tax└taxAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Taxable amount (required for mixed tax)Taxable amount (required for mixed tax)
└vatAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64VAT amount (required for mixed tax)VAT amount (required for mixed tax)
└taxFreeAmtN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Tax-exempt amount (required for mixed tax)Tax-exempt amount (required for mixed tax)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field (returned as-is when result is delivered)
Merchant reserved field (returned as-is when result is delivered)
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Merchant customer IDMerchant customer ID
*Required for subscription or sequential payments (autoPayType=A or S). When charging with the billKey, send the same value (the original value before encryption) in mUserId of the Charge Subscription API.
└custIpAN(15)Alphanumeric, up to 15 bytesCustomer IP address. The customer device's IP, not the merchant server's IP. Must be in IPv4 format (IPv6 not supported).
Customer IP address. The customer device's IP, not the merchant server's IP. Must be in IPv4 format (IPv6 not supported).
*Required for subscription (Subscription Key issuance)
└autoPayTypeA(1)Alphabetic, up to 1 bytesAutomatic payment type
Automatic payment type
A: Automatic payment (subscription) S: Sequential payment*Required when using the subscription merchant ID (nxkkp_auto) or sequential payment merchant ID (nxkkp_seq). A billKey is not issued with a general payment merchant ID.
└appSchemeAN(100)Alphanumeric, up to 100 bytesApp scheme used when building a proprietary app
App scheme used when building a proprietary app
Response Parameters
When payment is completed or fails, the parameters below are delivered via redirect to nextUrl. When the customer clicks the X button inside the checkout, they are redirected to cancUrl. Browser close and back navigation are not detected.
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
Common Response
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Merchant ID
hecto_testMerchant ID
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code
0021Transaction status code
0021: Success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Result code
0000Result code
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message
Processed successfully.Result message
└methodAN(20)Alphanumeric, up to 20 bytes*Payment method
corpPayment method
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number
KAKAO20211231100000Merchant order number
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes
AES-256AES-256/ECB/PKCS5PaddingMerchant customer IDHongGilDongMerchant customer ID
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└trdNoAN(40)Alphanumeric, up to 40 bytes*Hecto Financial transaction number
STFP_PGPZhecto_test0211129135810M1494620Hecto Financial transaction number
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingTransaction amount1000Transaction amount
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesField value from the request returned as-is in the response
name=HongGilDong&age=25Field value from the request returned as-is in the response
└authDtN(14)Numeric, up to 14 bytesApproval datetime
20211231100000Approval datetime
└billKeyAN(50)Alphanumeric, up to 50 bytesSubscription Key or sequential payment key (issued for subscription/sequential payment)
SBILL_0123456789Subscription Key or sequential payment key (issued for subscription/sequential payment)
*Issued when using the subscription merchant ID (nxkkp_auto) or sequential payment merchant ID (nxkkp_seq). Requires separate application through a sales representative.
Webhook (Payment Result)
After payment is completed, Hecto Financial sends a webhook to your server.
NOTE
Webhook reference
For KakaoPay payment result webhook parameters and processing method, see the Webhook document.
