헥토파이낸셜 개발자센터

White-Label Payment Checkout (UI)

Invoke the White-Label standard payment checkout to authenticate the customer. After authentication is complete, call the Payment API to process the actual payment.

Sandbox Key Information

Important Notes

Save trdNo

The trdNo (transaction reference number) returned in the payment checkout response is required when calling the Payment API. Store it securely.

Supported Browsers

Only Chrome and Edge browsers are supported. Other browsers may not function correctly.

Production Environment Testing Costs

Any costs incurred from testing in the Production environment are the merchant's responsibility. Always test in the Sandbox environment first.
  • Please refer to the issuance amount parameter handling rules.
    • Example: For a taxable merchant sending a transaction amount of KRW 1,000:
      • Sending only the transaction amount: Processed as taxable KRW 901, VAT KRW 99.
      • Sending taxable amount KRW 900 and VAT KRW 100: Processed as taxable KRW 900, VAT KRW 100.
  • No iframes: Using an iframe to embed the payment checkout may cause malfunctions in certain browsers or devices.
  • Special character restrictions: Do not use special characters (:, &, ?, ', newlines, <, >) or emojis in parameter values.
  • HTTPS required: nextUrl and cancUrl must use HTTPS. Using HTTP may violate browser security policies and cause the payment checkout to malfunction.

API Information

POST/whitelabel/main.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbwl.settlebank.co.kr/whitelabel/main.do
운영https://wl.settlebank.co.kr/whitelabel/main.do

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.
└methodAN(20)Alphanumeric, up to 20 bytes*
White-Label payment method code.
*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).
└pmtPrdtNmAHN(300)Alphanumeric + Korean, up to 300 bytes*
Product name for the payment.
└trdAmtAN(12)Alphanumeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount.
└nextUrlAN(250)Alphanumeric, up to 250 bytes*
URL to receive the payment result and redirect after payment.
└cancUrlAN(250)Alphanumeric, up to 250 bytes*
URL to receive the result and redirect when the customer force-closes the checkout.
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Unique customer ID or unique key sent by the merchant.
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
Hash value generated using SHA-256.
*Merchant ID + Payment method + Merchant order number + Request date + Request time + Transaction amount (plaintext) + Hash key

Optional Parameters

└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant-reserved field for additional order information.
└emailAN(60)Alphanumeric, up to 60 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Email address.
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax exemption status. If blank, the merchant's account setting is used.
N: Taxable Y: Tax-exempt G: Mixed taxation
└taxAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed taxation).
└vatAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed taxation).
└taxFreeAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount (required for mixed taxation).
└svcAmtAN(12)Alphanumeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Credit card service charge.
└themeColorCdAN(10)Alphanumeric, up to 10 bytes
Theme color (hex code).
└custAcntSumryAHN(30)Alphanumeric + Korean, up to 30 bytes
Bank statement descriptor shown on the customer's account.
└cupDepositAmtN(12)Numeric, up to 12 bytes
Resource circulation deposit (cup deposit).
└addDdtTypeCdA(1)Alphabetic, up to 1 bytes
Cash receipt additional deduction type.
Y: Public transportation C: Books / cultural performances
└ciChkYnA(1)Alphabetic, up to 1 bytes
Whether to validate the customer ID using CI. Set mchtCustId to the CI value when enabled.
Y: Enabled (enter CI in mchtCustId) N: Disabled

Response Parameters

Parameters returned from the White-Label payment checkout to the merchant. Sent via POST to nextUrl after authentication is complete.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)Alphanumeric, up to 10 bytes*pg_test
Unique Merchant ID assigned by Hecto Financial.
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code (success/failure).
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Rejection code. A detailed code is returned when the transaction status is '0031'.
*Refer to the rejection code table.
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Success
Result message (URL-encoded, UTF-8).
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20260107143000
Unique order number generated by the merchant (no Korean characters).
└mchtCustIdAN(100)Alphanumeric, up to 100 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_PGCApg_test0000260107143000M1717578
Hecto Financial transaction reference number. Required when calling the Payment API.
└trdAmtAN(12)Alphanumeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesname=HongGilDong&age=25
Value received in the request, bypassed back in the response.

Integration Example

<form id="paymentForm" method="POST" action="https://tbwl.settlebank.co.kr/whitelabel/main.do">
    <input type="hidden" name="mchtId" value="pg_test" />
    <input type="hidden" name="method" value="whitelabel" />
    <input type="hidden" name="trdDt" value="20260107" />
    <input type="hidden" name="trdTm" value="143000" />
    <input type="hidden" name="mchtTrdNo" value="ORDER20260107143000" />
    <input type="hidden" name="pmtPrdtNm" value="Test Product" />
    <input type="hidden" name="trdAmt" value="vqIWIiimsJ5efjSJpfnnTw==" />
    <input type="hidden" name="nextUrl" value="https://example.com/payment/result" />
    <input type="hidden" name="cancUrl" value="https://example.com/payment/cancel" />
    <input type="hidden" name="mchtCustId" value="AES-encrypted-customer-ID" />
    <input type="hidden" name="pktHash" value="hash-value" />
</form>

<script>
document.getElementById('paymentForm').submit();
</script>

Next Steps

After authentication is complete in the payment checkout, call the Payment API to process the actual payment.

Payment API Integration

💳

Payment API

Payment capture (Non-UI)

💬

Need technical support?