JavaScript SDK Integration API

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 -->
<script src="https://tbnpg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>

<!-- Production environment -->
<script src="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 validates only env, mchtId, method, and ui; the remaining parameters are validated on the server.

Required Parameters

└envstring*Payment system environment URLhttps://tbnpg.settlebank.co.kr

Payment system environment URL

Sandbox: https://tbnpg.settlebank.co.kr Production: https://npg.settlebank.co.kr

└mchtIdstring*Merchant ID assigned by Hecto Financialnxca_jt_il

Merchant ID assigned by Hecto Financial

└methodstring*Payment method codeCA

Payment method code

CA: Credit Card VA: Virtual Account RA: Bank Transfer MP: Mobile Payment

└trdDtstring*Transaction date (YYYYMMDD format)20240101

Transaction date (YYYYMMDD format)

└trdTmstring*Transaction time (HHMMSS format)153045

Transaction time (HHMMSS format)

└mchtTrdNostring*Merchant order number (unique, no duplicates)ORDER20240101153045

Merchant order number (unique, no duplicates)

└trdAmtstring*Transaction amount (in KRW)10000

Transaction amount (in KRW)

└notiUrlstring*Webhook URL for payment results (Server-to-Server)https://example.com/api/payment/noti

Webhook URL for payment results (Server-to-Server)

└nextUrlstring*Redirect URL after payment completionhttps://example.com/payment/success

Redirect URL after payment completion

└pktHashstring*Request signature hash value (SHA-256)abc123...

Request signature hash value (SHA-256)

└uiobject*UI configuration object (type, width, height){ type: "popup", width: 430, height: 660 }

UI configuration object (type, width, height)

Optional Parameters

└mchtNamestringMerchant name (Korean)Hecto Financial

Merchant name (Korean)

└mchtENamestringMerchant name (English)Hecto Financial

Merchant name (English)

└pmtPrdtNmstringPayment product nameLaptop Purchase

Payment product name

└mchtCustNmstringCustomer nameHong Gil-dong

Customer name

└custAcntSumrystringCustomer account summary informationShinhan 1234-56-7890

Customer account summary information

└cancUrlstringRedirect URL on payment cancellationhttps://example.com/payment/cancel

Redirect URL on payment cancellation

└mchtParamstringMerchant-specific parameter (passed through to notiUrl and nextUrl)name=Hong&age=25

Merchant-specific parameter (passed through to notiUrl and nextUrl)

└custIpstringCustomer IP address127.0.0.1

Customer IP address

ui Object Parameters

└ui.typestring*Checkout display modepopup

Checkout display mode

popup: Popup window iframe: Layer overlay self: Current window blank: New window

└ui.widthstringPopup window width (px, used only with popup/iframe mode)430

Popup window width (px, used only with popup/iframe mode)

└ui.heightstringPopup window height (px, used only with popup/iframe mode)660

Popup window height (px, used only with popup/iframe mode)

UI Type Behavior

Specify the Checkout display mode using the SDK's ui.type option.

SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "popup", width: 430, height: 660 },
    // ... payment method-specific parameters
}, null);

Displays the Checkout in a separate popup window
Shows a guidance message if the popup is blocked
Redirects to nextUrl after payment completion

iframe (Layer) ⚠️

Avoid iframe method

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.

SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "iframe", width: 430, height: 660 },
    // ... payment method-specific parameters
}, function(response) {
    // Receive result
    if (response.outStatCd === "0021") {
        console.log("Success:", response.trdNo);
    } else {
        console.log("Failure:", response.outRsltMsg);
    }
});

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

self (Current Window)

SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "self" },
    // ... payment method-specific parameters
}, null);

Navigates to the payment page within the current window
Redirects to nextUrl after payment completion
Navigates to cancUrl when going back

blank (New Window)

SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "blank" },
    // ... payment method-specific parameters
}, null);

Displays the Checkout in a new tab/window
Similar to popup but uses the browser's default new window behavior

Server-Side Processing

Before invoking the SDK, the backend must generate the transaction amount encryption (AES-256) and request signature hash (SHA-256).

Details: Before You Begin — Encryption and Request Signature (pktHash)

Error Handling

The SDK automatically detects errors and displays messages via browser alert. Below are examples of key error messages.

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 automatically validates basic common parameters (mchtId, env, ui, etc.) and displays an alert if any are missing.

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.

Details: Checkout Integration — Payment Method-Specific Parameters (Credit card, bank transfer, virtual account, mobile payment, and 16 other payment methods)

Need technical support?

Code Samples

HectoFinancial GitHub

JavaScript SDK Integration API

Important Notes

Checkout Timeout

Loading the SDK Script

SETTLE_PG.pay()

Script Parameter Definitions

Required Parameters

Optional Parameters

ui Object Parameters

UI Type Behavior

popup

iframe (Layer) ⚠️

Avoid iframe method

iframe callback is for display purposes

Callback Response Parameters

Order Processing Notice

self (Current Window)

blank (New Window)

Server-Side Processing

Error Handling

Popup Blocked

Missing Required Parameters

Server-Side Validation

Payment Method-Specific Parameters