Full Integration Flow

EZAuth Bank Transfer follows a three-step flow: Checkout Authentication → Callback → Payment Capture.

Overview

Customer

Merchant Frontend

Merchant Server

Hecto Financial

11. Initiate payment

1. Initiate payment

22. Launch checkout (SettlePay.execute)

2. Launch checkout (SettlePay.execute)

33. Display checkout

3. Display checkout

44. Complete identity & account verification

4. Complete identity & account verification

55. Deliver authentication result (callbackUrl)

5. Deliver authentication result (callbackUrl)

66. Call payment capture API

6. Call payment capture API

77. Return payment result

7. Return payment result

88. Finalize order

8. Finalize order

Step 1 — Launch the Checkout (UI)

Load the SettlePay.js SDK on your frontend and invoke the payment checkout.

<!-- Load SDK (Sandbox) -->
<script src="https://tbezauth.settlebank.co.kr/js/SettlePay.js" charset="UTF-8"></script>

<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="[Merchant ID]" />
  <input type="hidden" name="ordNo" value="[Order Number]" />
  <input type="hidden" name="trDay" value="[Transaction Date yyyyMMdd]" />
  <input type="hidden" name="trTime" value="[Transaction Time HH24MISS]" />
  <input type="hidden" name="trPrice" value="[AES-256 Encrypted Amount]" />
  <input type="hidden" name="productNm" value="[Product Name]" />
  <input type="hidden" name="dutyFreeYn" value="N" />
  <input type="hidden" name="callbackUrl" value="https://www.example.com/callback" />
  <input type="hidden" name="signature" value="[SHA-256 Hash]" />
</form>

<script>
  SettlePay.execute(document.getElementById('payForm'));
</script>

NOTE

callbackUrl Domain Requirement

The callbackUrl domain must contain at least two dots (e.g., www.example.com).

Signature Generation

Order	Field
1	mercntId
2	ordNo
3	trDay
4	trTime
5	trPrice (plaintext, before encryption)
6	callbackUrl HOST (domain only, no protocol or port)
7	hashKey

Signature Generation Notes

Use the plaintext value of trPrice (before AES encryption). Extract only the domain from callbackUrl, excluding the protocol and port. Example: https://www.example.com/callback → www.example.com

Step 2 — Receive the Authentication Callback

When the customer completes authentication in the checkout, the result is posted to your callbackUrl. Your server must validate the response before proceeding.

Key Response Parameters

Field	Description
`resultCd`	Result code (`0`: success, `-1`: failure)
`authNo`	Authentication number (required for capture API)
`trPrice`	Transaction amount
`payPrice`	Final settlement amount

Validate Callback Before Capture

Always verify callback parameters before calling the capture API. Confirm that the received amount matches the expected order amount.

Step 3 — Call the Payment Capture API

After validating the callback, your server calls the payment capture API to execute the direct debit.

Item	Value
Sandbox	`https://tbezauthapi.settlebank.co.kr`
Production	`https://ezauthapi.settlebank.co.kr:8081`
URI	`/v3/APIPayApprov.do`
Method	POST

Payment API Reference

Payment Capture

Execute direct debit after authentication

Void / Refund

Cancel or refund a completed payment

Network Void

Cancel a timed-out transaction

Timeout Handling

If the capture API times out (35-second threshold), follow this procedure:

Call the Transaction Result Inquiry API to determine the transaction status.
If the transaction shows as successful → call the Network Void API to cancel it.

Inquiry & Network Void Reference

Transaction Result Inquiry

Check transaction status after a timeout

Network Void

Cancel a timed-out transaction

Parameter Validation Error Response

If request parameter validation fails, the following response is returned:

{
  "resultCd": "-1",
  "errCd": "ST09",
  "resultMsg": "Invalid request message"
}

Additional Features

More Features

Recurring Billing

Issue a billing key for recurring charges

Transaction History

Query full transaction history

Need technical support?

Code Samples

HectoFinancial GitHub