This document explains how to integrate the Checkout using the Hecto Financial JavaScript SDK (SettlePG).
Important Notes
Checkout Timeout
If 10 minutes elapse after entering the Checkout, a 'Transaction time has expired' error will occur. If the customer fails to complete the payment, the Checkout must be invoked again.
Loading the SDK Script
<!-- Sandbox environment --><scriptsrc="https://tbnpg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script><!-- Production environment --><scriptsrc="https://npg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>
SETTLE_PG.pay()
SETTLE_PG.pay(options, callback);
Parameter
Type
Required
Description
options
Object
O
Payment request parameters (see details below)
callback
Function
-
Callback to receive results in iframe mode
Script Parameter Definitions
Parameters passed to the options object of SETTLE_PG.pay(). The SDK checks that env, ui, and the required parameters (mchtId, method, mchtTrdNo, trdDt, trdTm, trdAmt, mchtName, pmtPrdtNm, notiUrl, nextUrl, cancUrl, pktHash) are not empty and that the method value is valid; the remaining parameters are validated on the server.
Required Parameters
└envstring*Payment system environment URLhttps://tbnpg.settlebank.co.kr
└mchtIdstring*Merchant ID assigned by Hecto Financialnxca_jt_il
Merchant ID assigned by Hecto Financial
Parameter
Type
Description
Example
mchtIdRequired
string
Merchant ID assigned by Hecto Financial
nxca_jt_il
└methodstring*Payment method codecard
Payment method code
card: Credit Cardbank: Bank Transfervbank: Virtual Accountvbank010: 010 Virtual Accountmobile: Mobile Paymenttmoney: T-moneypoint: Point Damoacorp: Simple Paymentteencash: Teencashculturecash: CultureCashsmartcash: Smart Book Gift Cardbooknlife: Book Gift Card
*For any value not in this list, the SDK displays a 'method is wrong' error.
Parameter
Type
Description
Example
methodRequired
string
Payment method code
card: Credit Card / bank: Bank Transfer / vbank: Virtual Account / vbank010: 010 Virtual Account / mobile: Mobile Payment / tmoney: T-money / point: Point Damoa / corp: Simple Payment / teencash: Teencash / culturecash: CultureCash / smartcash: Smart Book Gift Card / booknlife: Book Gift Card
* For any value not in this list, the SDK displays a 'method is wrong' error.
card
└trdDtstring*Transaction date (YYYYMMDD format)20240101
Transaction date (YYYYMMDD format)
Parameter
Type
Description
Example
trdDtRequired
string
Transaction date (YYYYMMDD format)
20240101
└trdTmstring*Transaction time (HHMMSS format)153045
Transaction time (HHMMSS format)
Parameter
Type
Description
Example
trdTmRequired
string
Transaction time (HHMMSS format)
153045
└mchtTrdNostring*Merchant order number (unique, no duplicates)ORDER20240101153045
Merchant order number (unique, no duplicates)
Parameter
Type
Description
Example
mchtTrdNoRequired
string
Merchant order number (unique, no duplicates)
ORDER20240101153045
└trdAmtstring*Transaction amount (in KRW)10000
Transaction amount (in KRW)
Parameter
Type
Description
Example
trdAmtRequired
string
Transaction amount (in KRW)
10000
└notiUrlstring*Webhook URL for payment results (Server-to-Server)https://example.com/api/payment/noti
Webhook URL for payment results (Server-to-Server)
Parameter
Type
Description
Example
notiUrlRequired
string
Webhook URL for payment results (Server-to-Server)
https://example.com/api/payment/noti
└nextUrlstring*Redirect URL after payment completionhttps://example.com/payment/success
Redirect URL after payment completion
Parameter
Type
Description
Example
nextUrlRequired
string
Redirect URL after payment completion
https://example.com/payment/success
└pktHashstring*Request signature hash value (SHA-256)abc123...
Request signature hash value (SHA-256)
Parameter
Type
Description
Example
pktHashRequired
string
Request signature hash value (SHA-256)
abc123...
└mchtNamestring*Merchant name (Korean)Hecto Financial
*Use with method='card'. direct also requires cardGb (card company code); for auth request parameters, see the card registration (billing key issuance) checkout document.
Parameter
Type
Description
Example
methodSub
string
Credit card checkout sub-type. If omitted, the standard card checkout (/card/main.do) is called.
* Use with method='card'. direct also requires cardGb (card company code); for auth request parameters, see the card registration (billing key issuance) checkout document.
auth
└mchtENamestringMerchant name (English)Hecto Financial
The iframe method is not recommended due to issues such as local network access restrictions and browser compatibility problems. Use the popup, self, or blank method instead.
Displays the Checkout as a dimmed layer overlay on the current page
Receives payment result via callback function (iframe only)
NOTE
iframe callback is for display purposes
The callback function is only invoked in iframe mode. In popup, self, and blank modes, the callback is not called and the user is redirected to nextUrl.
Callback Response Parameters
Key parameters of the response object passed to the callback function in iframe mode.
Parameter
Type
Description
outStatCd
AN(4)
Transaction status code (0021: Success, 0031: Failure, 0041: Pending, 0051: In Progress)
outRsltCd
AN(4)
Detailed result code
outRsltMsg
AHN(200)
Result message
trdNo
AN(40)
Hecto Financial transaction number
mchtTrdNo
AN(100)
Merchant order number
trdAmt
N(12)
Transaction amount
method
A(10)
Payment method code
For additional parameters per payment method (card company name, virtual account number, etc.), refer to the Checkout Integration document.
NOTE
Order Processing Notice
Actual order processing (inventory deduction, status updates) must be performed at notiUrl. For details, refer to the Webhooks Integration Guide. Webhooks (notiUrl) Integration Guide
The SDK automatically detects errors and displays messages via browser alert. Below are examples of key error messages.
Popup Blocked
When a popup is blocked, the SDK automatically displays a guidance message.
Message from developers.hectofinancial.co.kr
[Hecto Financial] Popup blocking is enabled. Please disable it and try again.
How to unblock popups:
Chrome: Click the popup blocked icon on the right side of the address bar → 'Always allow'
Safari: Preferences → Websites → Pop-up Windows → 'Allow'
Edge: Settings → Cookies and site permissions → Pop-ups and redirects → Allow
Missing Required Parameters
The SDK displays an alert if env, ui, or any required parameter (mchtId, method, mchtTrdNo, trdDt, trdTm, trdAmt, mchtName, pmtPrdtNm, notiUrl, nextUrl, cancUrl, pktHash) is empty, or if the method value is invalid.
NOTE
Server-Side Validation
Detailed parameters per payment method (card number, expiry date, etc.) are validated on the server, not by the SDK. If server-side validation fails, an error message is displayed in the Checkout.
Message from developers.hectofinancial.co.kr
[Hecto Financial] Call parameter error (mchtId is null)
Payment Method-Specific Parameters
The SDK integration method is the same for all payment methods. Refer to the documents below for detailed parameters per payment method.