헥토파이낸셜 개발자센터

Register Card (Billkey Checkout)

Register a card through the checkout page with a zero-amount verification — no actual charge — and receive a billkey (payment token) for recurring payments.

Test Key Information

API Information

POST/card/cardAuth.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbnpg.settlebank.co.kr/card/cardAuth.do
운영https://npg.settlebank.co.kr/card/cardAuth.do

Important Notes

NOTE

Billkey Service Activation

To receive a billkey, you must separately activate the Payment Token service. Contact your account manager.
  • This is a zero-amount verification: the card is authenticated only and no actual charge (approval) occurs. The transaction amount (trdAmt) is fixed to "0".
  • Once a billkey is issued, use it to request the subsequent charge API. (See Credit Card Billkey Payment API)
  • To issue a billkey together with an actual payment, use the Credit Card Checkout instead.

Request Parameters

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

Required Parameters

└mchtIdAN(10)Alphanumeric, up to 10 bytes*
Unique merchant ID issued by Hecto Financial
└methodAN(20)Alphanumeric, up to 20 bytes*
Payment method code for the PG service
*Fixed value
└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 (Korean)
└mchtENameAN(100)Alphanumeric, up to 100 bytes*
Merchant name (English)
└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. Fixed to 0 for zero-amount verification
*Fixed value
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
URL that receives the result after card registration (server-to-server webhook URL)
└nextUrlAN(250)Alphanumeric, up to 250 bytes*
URL the customer is redirected to with the registration result
*Redirected when the customer clicks the button in the checkout window. Check outStatCd for success (0021) or failure (0031).
└cancUrlAN(250)Alphanumeric, up to 250 bytes*
URL the customer is redirected to when clicking the X button in the checkout window
*Closing the browser or navigating back is not detected.
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
SHA256 hash value
NOTE

Hash Generation Combination

mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt(plaintext) + hashKey

Optional Parameters

└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer name
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field for additional order information
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Unique customer ID or key provided by the merchant
└custIpAN(15)Alphanumeric, up to 15 bytes
Customer device IP address (not the merchant server IP)

Response Parameters

On completion or failure the customer is redirected to nextUrl, and to cancUrl when the X button is clicked in the checkout window, with the parameters below. Closing the browser or navigating back is not detected.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxca_jt_gu
Unique merchant ID issued by Hecto Financial
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code (success/failure)
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Rejection code. Detailed code delivered when the status is '0031'
*See the rejection code table
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message (URL Encoding, UTF-8)
└methodAN(20)Alphanumeric, up to 20 bytes*card
Payment method code for the PG service
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Unique order number generated by the merchant (no Korean characters)
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5PaddingHongGilDong
Unique customer ID or key provided by the merchant
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCAnxca_jt_il0211129135810M1494620
Hecto Financial transaction number
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesname=HongGilDong&age=25
Field values from the request, passed back in the response
└authDtN(14)Numeric, up to 14 bytes20211231100000
Date and time the card was authenticated
└cardNoMaskingAN(20)Alphanumeric, up to 20 bytes532312******8756
Masked card number
└cardKindAHN(50)Alphanumeric + Korean, up to 50 bytesBC check card
Card kind
└fnNmAH(20)Alpha + Korean, up to 20 bytesBC (Paybooc)
Card company name
└fnCdAN(4)Alphanumeric, up to 4 bytesBCC
Card company code
└billKeyAN(50)Alphanumeric, up to 50 bytes*SBILL_0123456789
Recurring payment key issued with the Payment Token service. Used for subsequent charges
*Requires separate service activation via your account manager

Webhook (Notification)

When card registration completes successfully, Hecto Financial sends a notification to the merchant. The business type (bizType) is delivered as A8 (billkey issuance).

NOTE

Webhook Reference

For credit card notification parameters and handling, see the webhook documentation.
💬

Need technical support?

무엇이든 물어보세요