헥토파이낸셜 개발자센터

Credit Card Payment (Standard Checkout)

Process a credit card payment through Hecto Financial's standard checkout page.

Test Key Information

API Information

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

Important Notes

Checkout flow depends on merchant ID type

If the merchant ID is configured for standard authenticated payment, the card company authentication screen appears. If configured for non-authenticated or legacy-authenticated, the card information entry screen appears.
  • To receive a payment token (billkey), you must separately activate the Payment Token service. A payment token is a stored card reference used for future charges — similar to a Stripe PaymentMethod ID. Contact your account manager to activate.
  • Once a billkey is issued, use it to request the subsequent charge payment API. (See Credit Card Billkey Payment API)
  • To issue a billkey by registering a card only, without an actual payment, use the card registration (billkey issuance) checkout. (zero-amount verification)
  • The amount printed on the sales receipt is based on the parameters sent by the merchant.
    • Example) When a taxable merchant sends a transaction amount of 1,000 KRW:
      • Sending only the transaction amount: displayed as taxable 909, VAT 91
      • Sending taxable amount 900, VAT 100: displayed as taxable 900, VAT 100

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
nxca_jt_il: Authenticated nxca_jt_bi: non-authenticated nxca_ks_gu: legacy-authenticated nxca_jt_hd: Deferred Capture
└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 for payment
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount (multiply by 100 when using USD)
*KRW: 1000 / USD: ex) $1.00 → 100
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
Webhook URL to receive the payment result (server-to-server)
└nextUrlAN(250)Alphanumeric, up to 250 bytes*
URL to redirect to the payment result screen
*Redirected when the button inside the checkout page is clicked. Use the outStatCd value to verify payment success (0021) or failure (0031).
└cancUrlAN(250)Alphanumeric, up to 250 bytes*
URL to redirect when the customer clicks the X button in the checkout page
*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

└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 entering additional order information
└emailAN(60)Alphanumeric, up to 60 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Email address
└prdtTermN(14)Numeric, up to 14 bytes
Product provision period (yyyyMMddHHmmss). If empty, displayed as a general payment
└mchtCustIdAN(50)Alphanumeric, up to 50 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Unique customer ID or unique key sent by the merchant
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status. If blank, follows merchant configuration
N: Taxable Y: Tax-exempt G: Mixed taxation
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed taxation)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed taxation)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed taxation)
└svcAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Credit card service charge
└instmtMonN(2)Numeric, up to 2 bytes
Installment months
00: Full payment 2~12: Number of installment months
*Credit card (standard checkout): If the requested installment month is in the installment list, it is pre-selected and fixed; if not in the list, the installment month list is shown for selection. Credit card - Direct API: Payment is processed with the requested installment month.
└cardTypeN(1)Numeric, up to 1 bytes
Card payment type
3: App card supported card companies [Shinhan/Samsung/Hyundai/KB/NH/Lotte] 6: Hyundai Card PayShot (available after direct partnership agreement with the card company)
└chainUserIdAN(100)Alphanumeric, up to 100 bytes
Hyundai Card PayShot ID. Available after direct partnership agreement with the card company
└cardGbAN(4)Alphanumeric, up to 4 bytes
Specific card company code. Displays only the specified card company
*See the Card Company Code Reference page for card company codes.
└appSchemeAN(100)Alphanumeric, up to 100 bytes
App scheme (AppScheme://~) format. Used when building a proprietary app
└custIpAN(15)Alphanumeric, up to 15 bytes
Customer IP address. The customer device's IP address, not the merchant server IP

Response Parameters

When payment is completed or fails, parameters are delivered via redirect to nextUrl. When the customer clicks the X button inside the checkout page, they are redirected to cancUrl. Browser close and back navigation are not detected.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxca_jt_il
Unique merchant ID assigned by Hecto Financial
nxca_jt_il: Authenticated nxca_jt_bi: non-authenticated nxca_ks_gu: legacy-authenticated
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code (success/failure)
0021: Success 0061: Authentication success (deferred capture method) 0031: Failure
*If you receive outStatCd 0061, authentication is complete but payment is not yet captured. You must call the Deferred Capture API to finalize the charge. See the Deferred Capture API reference for details.
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Decline code. Detailed code provided when transaction status is '0031'
*Refer to the decline 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 unique key sent by the merchant
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCAnxca_jt_il0211129135810M1494620
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 received in the request is returned as-is in the response
└authDtN(14)Numeric, up to 14 bytes20211231100000
Payment approval datetime
└authNoN(15)Numeric, up to 15 bytes30001234
Credit card approval number
└intMonN(2)Numeric, up to 2 bytes00
Credit card installment months
└fnNmAH(20)Alpha + Korean, up to 20 bytesWoori Card
Credit card company name
└fnCdAN(4)Alphanumeric, up to 4 bytesLTC
Credit card company code
└pointTrdNoAN(40)Alphanumeric, up to 40 bytesSTFP_PGCAnxca_jt_il0211129135810M1494620
Point payment transaction number if the customer paid with points
└pointTrdAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding1000
Point payment amount if the customer paid with points
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└cardTrdAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding4000
Credit card payment amount excluding discounts or point amounts
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└billKeyAN(50)Alphanumeric, up to 50 bytesSBILL_0123456789
A stored card token returned only when the payment token (billkey) service is active for your merchant ID. Present only in successful responses with billkey issuance enabled. Store this securely for subsequent charges via the Payment Token API.
*Requires separate activation. Contact your account manager. This token is equivalent to a Stripe PaymentMethod ID or an Adyen recurring contract token.

Webhook (Payment Result)

After a payment is completed, Hecto Financial sends a webhook to your server.

NOTE

Webhook Reference

For credit card payment webhook parameters and processing methods, see the webhook reference.
💬

Need technical support?

무엇이든 물어보세요