헥토파이낸셜 개발자센터

Payment Authentication (Checkout)

Authenticates the customer's bank account via the EZAuth hosted checkout. Upon completion, the result is delivered to your callbackUrl, after which you call the capture API to execute the direct debit.

Test Credentials

API Information

POSTCheckout Integration
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbezauth.settlebank.co.kr
운영https://ezauth.settlebank.co.kr

SDK Script

EnvironmentURL
Sandboxhttps://tbezauth.settlebank.co.kr/js/SettlePay.js
Productionhttps://ezauth.settlebank.co.kr/js/SettlePay.js
SettlePay.execute(form);

Request Parameters

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

Required Parameters

└hdInfoAN(50)Alphanumeric, up to 50 bytes*
Message type code.
*Fixed value
└apiVerAN(4)Alphanumeric, up to 4 bytes*
API version.
*Fixed value (2.0 enables redirect phishing protection)
└processTypeA(1)Alphabetic, up to 1 bytes*
Processing type.
*Fixed value
└mercntIdAN(8)Alphanumeric, up to 8 bytes*
Unique merchant identifier assigned by Hecto Financial.
└ordNoAN(100)Alphanumeric, up to 100 bytes*
Merchant-generated order number. Must be unique within the same calendar day.
└custCiAN(192)Alphanumeric, up to 192 bytes*AES-256AES-256/ECB/PKCS5Padding + Hex
Customer CI (Connecting Information). If provided and differs from the registered value, the customer is redirected to cancelUrl.
└trDayN(8)Numeric, up to 8 bytes*
Transaction date generated at order time (yyyyMMdd).
└trTimeN(6)Numeric, up to 6 bytes*
Transaction time generated at order time (HH24MISS).
└trPriceAN(13)Alphanumeric, up to 13 bytes*AES-256AES-256/ECB/PKCS5Padding + Hex
Transaction amount. Setting to 0 issues a recurring billing key without charging.
└productNmAN(95)Alphanumeric, up to 95 bytes*
Product name.
└dutyFreeYnA(1)Alphabetic, up to 1 bytes*
Tax exemption flag.
Y: Tax-exempt N: Taxable G: Mixed taxation
└callbackUrlAN(255)Alphanumeric, up to 255 bytes*
URL the checkout posts the authentication result to. HTTPS recommended. Domain must contain at least two dots (e.g., www.example.com).
*Validate the callback result before calling the capture API.
└cancelUrlAN(255)Alphanumeric, up to 255 bytes
URL invoked when the customer cancels during the checkout flow. Must share the same root domain as callbackUrl.
└signatureAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
SHA-256 hash value for tamper protection.
NOTE

Signature Composition

mercntId + ordNo + trDay + trTime + trPrice (plaintext) + callbackUrl HOST + hashKey
NOTE

Extracting callbackUrl HOST (apiVer 2.0)

  • Use only the domain, excluding the protocol (https://, http://) and port number.
  • Example: https://develop.sbsvc.online:60001/callback/success → develop.sbsvc.online
  • Example: https://www.example.com/callback → www.example.com

Optional Parameters

└taxPriceAN(13)Alphanumeric, up to 13 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
Taxable amount. Required when dutyFreeYn is G (mixed taxation).
└vatPriceAN(13)Alphanumeric, up to 13 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
VAT amount. Typically 10% of taxable amount.
└dutyFreePriceAN(13)Alphanumeric, up to 13 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
Tax-exempt amount. Required when dutyFreeYn is G (mixed taxation).
└containerDepositAN(5)Alphanumeric, up to 5 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
Container deposit amount. Excluded from cash receipt.
└criPsblYnA(1)Alphabetic, up to 1 bytes
Cash receipt issuance eligibility. Defaults to Y if omitted.
Y: Eligible N: Not eligible
└addDeductionYnA(1)Alphabetic, up to 1 bytes
Additional tax deduction category.
Y: Public transit C: Books/cultural events N: None
└shopNmAN(10)Alphanumeric, up to 10 bytes
Store name.
└cphoneNoAN(11)Alphanumeric, up to 11 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
Customer mobile number (digits only, no hyphens).
└emailAN(30)Alphanumeric, up to 30 bytesAES-256AES-256/ECB/PKCS5Padding + Hex
Customer email address.
└regularpayYnA(1)Alphabetic, up to 1 bytes
Recurring billing enrollment flag. Set to Y with trPrice=0 for a billing-key-only enrollment (zero-amount auth), or Y with a non-zero trPrice for a combined payment and enrollment.
Y: Enroll recurring billing N: One-time payment
└mercntParam1AN(1000)Alphanumeric, up to 1000 bytes
Merchant-defined data field 1. Echoed back in the response and transaction history.
└mercntParam2AN(1000)Alphanumeric, up to 1000 bytes
Merchant-defined data field 2. Echoed back in the response and transaction history.
└payLimitCdAN(10)Alphanumeric, up to 10 bytes
Payment limit code. Controls customer spending limits per EZAuth policy.

Response Parameters (Callback)

Parameters delivered to callbackUrl upon authentication completion.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└resultCdN(1)Numeric, up to 1 bytes*0
Result code.
0: Success -1: Failure
└errCdAN(5)Alphanumeric, up to 5 bytes*0000
Error code. See error code reference.
└resultMsgAN(200)Alphanumeric, up to 200 bytes*Success
Human-readable result message.
└mercntIdAN(8)Alphanumeric, up to 8 bytes*ms00003t
Merchant ID assigned by Hecto Financial.
└ordNoAN(100)Alphanumeric, up to 100 bytes*OID201902210001
Order number from the original request.
└authNoAN(20)Alphanumeric, up to 20 bytes*PAR20190220000000001
Authentication number. Required when calling the capture API.
*Must be passed to the capture API
└trPriceN(13)Numeric, up to 13 bytes*15000
Original requested transaction amount.
└discntPriceN(13)Numeric, up to 13 bytes*1000
Promotional discount amount applied.
└payPriceN(13)Numeric, up to 13 bytes*14000
Final settlement amount (after discounts).
└trDayN(8)Numeric, up to 8 bytes*20190221
Transaction date (yyyyMMdd).
└trTimeN(6)Numeric, up to 6 bytes*142120
Transaction time (HH24MISS).
└mercntParam1AN(1000)Alphanumeric, up to 1000 bytes
Merchant-defined data field 1 from the original request.
└mercntParam2AN(1000)Alphanumeric, up to 1000 bytes
Merchant-defined data field 2 from the original request.

Integration Example

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>EZAuth Bank Transfer</title>
</head>
<body>
    <form id="payForm" name="payForm">
        <input type="hidden" name="hdInfo" value="IA_AUTHPAGE_1.0_1.0" />
        <input type="hidden" name="apiVer" value="2.0" />
        <input type="hidden" name="processType" value="D" />
        <input type="hidden" name="mercntId" value="ms00003t" />
        <input type="hidden" name="ordNo" value="OID201902210001" />
        <input type="hidden" name="trDay" value="20190221" />
        <input type="hidden" name="trTime" value="142120" />
        <input type="hidden" name="trPrice" value="[AES-256 encrypted amount]" />
        <input type="hidden" name="productNm" value="Test Product" />
        <input type="hidden" name="dutyFreeYn" value="N" />
        <input type="hidden" name="callbackUrl" value="https://www.example.com/callback" />
        <input type="hidden" name="cancelUrl" value="https://www.example.com/cancel" />
        <input type="hidden" name="signature" value="[SHA-256 hash]" />
    </form>

    <!-- Load SDK -->
    <script src="https://tbezauth.settlebank.co.kr/js/SettlePay.js" charset="UTF-8"></script>
    <script>
        SettlePay.execute(document.getElementById('payForm'));
    </script>
</body>
</html>
💬

Need technical support?