헥토파이낸셜 개발자센터

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-Typeapplication/x-www-form-urlencoded
테스트https://tbnpg.settlebank.co.kr/corp/main.do
운영https://npg.settlebank.co.kr/corp/main.do

Important 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

To use subscription (automatic payment) or sequential payment, use the corresponding merchant ID and set the autoPayType parameter. Upon successful payment, a billKey is issued, which can be used to call the Charge Subscription API.
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

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

Required Parameters

└mchtIdAN(10)Alphanumeric, up to 10 bytes*
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
*Fixed value
└corpPayCodeAN(3)Alphanumeric, up to 3 bytes*
Digital wallet provider code
*KakaoPay: KKP
└trdDtN(8)Numeric, up to 8 bytes*
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Request time (HH24MISS)
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant (no Korean characters)
└mchtNameAHN(100)Alphanumeric + Korean, up to 100 bytes*
Merchant name
└pmtPrdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Product name
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
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
*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
*Browser close and back navigation are not detected.
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
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 bytes
Tax type
N: Taxable Y: Tax-exempt G: Mixed tax
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed tax)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed tax)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-exempt amount (required for mixed tax)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field (returned as-is when result is delivered)
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Merchant customer ID
└custIpAN(15)Alphanumeric, up to 15 bytes
Customer IP address. The customer device's IP, not the merchant server's IP.
*Required for subscription (Subscription Key issuance)
└autoPayTypeA(1)Alphabetic, up to 1 bytes
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)
└appSchemeAN(100)Alphanumeric, up to 100 bytes
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.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

Common Response

└mchtIdAN(10)Alphanumeric, up to 10 bytes*hecto_test
Merchant ID
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Result code
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message
└methodAN(20)Alphanumeric, up to 20 bytes*corp
Payment method
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*KAKAO20211231100000
Merchant order number
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5PaddingHongGilDong
Merchant customer ID
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGPZhecto_test0211129135810M1494620
Hecto Financial transaction number
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesname=HongGilDong&age=25
Field value from the request returned as-is in the response
└authDtN(14)Numeric, up to 14 bytes20211231100000
Approval datetime
└billKeyAN(50)Alphanumeric, up to 50 bytesSBILL_0123456789
Subscription 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.
💬

Need technical support?