### Request Example

Source: https://developers.hectofinancial.co.kr/docs/api/easy-cash/getting-started/01-basic-flow

This is a general example of a request structure used in Easy Cash APIs. Ensure all required fields are populated correctly.

```json
{
  "mchtId": "가맹점 ID",
  "ver": "0A19",
  "method": "RA",
  "bizType": "B0",
  "encCd": "23",
  "mchtTrdNo": "ORDER20240101100000",
  "trdDt": "20240101",
  "trdTm": "100000",
  "pktHash": "SHA256 해쉬값",
  "trdAmt": "AES 암호화된 금액"
}
```

--------------------------------

### Prepaid Wallet Use Failure Response Example (Insufficient Balance)

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/wallet/02-use

This example shows a failure response when the prepaid balance is insufficient for the requested transaction.

```json
{
  "rsltCd": "T-009",
  "rsltMsg": "원거래금액/요청금액을 확인하세요"
}
```

--------------------------------

### Prepaid Wallet Use Failure Response Example (Incorrect PIN)

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/wallet/02-use

This example shows a failure response when the provided payment PIN is incorrect.

```json
{
  "rsltCd": "T-010",
  "rsltMsg": "결제 비밀번호가 일치하지 않습니다 (2회)"
}
```

--------------------------------

### Prepaid Wallet Use Success Response Example

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/wallet/02-use

This is an example of a successful response from the Prepaid Wallet Use API. It includes transaction details, updated balances, and confirmation codes.

```json
{
  "rsltCd": "0000",
  "rsltMsg": "성공",
  "rsltObj": {
    "custNo": "2400001605",
    "mtrdNo": "ORDER20240716",
    "trdNo": "24071616270200002193",
    "trdDt": "20240716",
    "trdTm": "164101",
    "trdAmt": "10000",
    "mnyAmt": "9000",
    "pntAmt": "1000",
    "mnyBlc": "11000",
    "pntBlc": "0",
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05de5ba815f463f00429061c"
  }
}
```

--------------------------------

### Payment Approval Request Example

Source: https://developers.hectofinancial.co.kr/docs/api/ezauth/payment/02-payment-approval

This JSON object demonstrates the required parameters for initiating a payment approval request. Ensure all fields, including the signature generated using SHA-256, are correctly populated.

```json
{
  "hdInfo": "IA_APPROV",
  "apiVer": "3.0",
  "mercntId": "ms00003t",
  "authNo": "PAR20190220000000001",
  "reqDay": "20260107",
  "reqTime": "143000",
  "custParam1": "",
  "custParam2": "",
  "custParam3": "",
  "custParam4": "",
  "signature": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
}
```

--------------------------------

### Prepaid Wallet Use Request Example

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/wallet/02-use

This is an example of a request payload for the Prepaid Wallet Use API. Ensure all required fields, including encrypted values for sensitive data, are correctly formatted.

```json
{
  "custNo": "2400001605",
  "mTrdNo": "NSTEST20240715000006",
  "trdAmt": "OtHHsG793ox9XewbvX21Lw==",
  "mnyBlc": "2fISihtRzzKJZZay2s8LFQ==",
  "pntBlc": "ceBxI7xbssp9mlz9hRzTJw==",
  "blcUseOrd": "M",
  "reqDt": "20240826",
  "reqTm": "160010",
  "csrcIssReqYn": "Y",
  "stlMId": "R0L4ColX2RqUDQyo5lWTPQ==",
  "storCd": "HF0001",
  "storNm": "헥토파이낸셜",
  "pinNo": "6NykSPILA01QdAh6sTGaBA==",
  "pktHash": "eb19306c05c1fd19c0fb185358243512d0ffad44ab299e629d89428ad6134f46"
}
```

--------------------------------

### White Label Integration

Source: https://developers.hectofinancial.co.kr/docs/api/pg/virtual-account/03-virtual-account

Guides for integrating the White Label solution, covering payment, inquiry, and reference information.

```APIDOC
## White Label Integration

### Description
Integrate the White Label solution, which allows for customized payment experiences. This includes payment processing, transaction inquiries, and accessing reference data.

### Operations
- **Payment**: Integrate the payment window and process payment authorizations and cancellations.
- **Inquiry**: Retrieve transaction details.

### References
- **Error Codes**: List of possible error codes.
- **Financial Institution Codes**: Codes for financial institutions.
- **Bank Inspection Times**: Information on bank maintenance schedules.
```

--------------------------------

### Simple Payment Integration

Source: https://developers.hectofinancial.co.kr/docs/api/pg/virtual-account/03-virtual-account

Guides for integrating various simple payment methods like Payco, Samsung Pay, Kakao Pay, Naver Pay, and Toss Pay.

```APIDOC
## Simple Payment Integration

### Description
Integrate various simple payment methods, including their payment windows, notification handling, and cancellation processes. Also covers recurring payments.

### Supported Methods
- **Payco**: Payment window and test environment.
- **Samsung Pay**: Payment window.
- **Kakao Pay**: Payment window.
- **Naver Pay**: Payment window.
- **Toss Pay**: Payment window.

### Operations
- **Notifications**: Handle real-time notifications for simple payments.
- **Cancellation**: Cancel simple payments.
- **Recurring Payments**: Manage simple recurring payments, including status inquiries and key deletion.
```

--------------------------------

### Request Example for Withdrawal Balance Inquiry

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/inquiry/05-withdrawal-balance

This snippet shows the JSON payload required to request the withdrawal balance and monthly withdrawal count for a prepaid member.

```json
{
  "custNo": "2400001605",
  "ci": "AES암호화된CI값"
}
```

--------------------------------

### Ansim Prepaid Integration

Source: https://developers.hectofinancial.co.kr/docs/api/pg/virtual-account/03-virtual-account

Guides for integrating the Ansim Prepaid service, covering UI integration, wallet management, inquiries, and charging/withdrawal.

```APIDOC
## Ansim Prepaid Integration

### Description
Integrate the Ansim Prepaid service, which includes UI integration for user interfaces, wallet management for funds, various inquiry options, and charging/withdrawal functionalities.

### UI Integration
- **Member Registration Screen**: Integrate the user registration screen.
- **My Information Screen**: Integrate the user information screen.

### Wallet Management
- **Prepaid Fund Usage**: Use prepaid funds.
- **Usage Cancellation**: Cancel prepaid fund usage.
- **Money Gifting**: Send prepaid funds as gifts.
- **Point Recovery**: Recover points.

### Inquiries
- **Balance Inquiry**: Check current balances (various options and details).
- **Chargeable Money Inquiry**: Check available money for withdrawal.
- **Transaction History Inquiry**: View transaction history (including details for merchants and members).
- **Member Information Inquiry**: Retrieve member information.
- **Expiring Points Inquiry**: Check points that are about to expire.
- **Charging Method Inquiry**: Inquire about available charging methods.

### Charging/Withdrawal
- **Charging**: Add funds to the prepaid account.
- **Charging Cancellation**: Cancel a charging transaction.
- **Money Withdrawal Waiting**: Manage withdrawal requests.
- **Money Withdrawal**: Withdraw funds from the prepaid account.

### References
- **Error Codes**: List of possible error codes.
- **Transaction Type Codes**: Codes representing different transaction types.
```

--------------------------------

### Load SDK and Initiate Payment UI

Source: https://developers.hectofinancial.co.kr/docs/api/ezauth/getting-started/01-full-flow

Load the SettlePay.js SDK and prepare the payment form with necessary hidden fields. Call SettlePay.execute to display the payment UI. Ensure callbackUrl has at least two domain levels.

```html
<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="상점 ID" />
  <input type="hidden" name="ordNo" value="주문번호" />
  <input type="hidden" name="trDay" value="거래일자(yyyyMMdd)" />
  <input type="hidden" name="trTime" value="거래시각(HH24MISS)" />
  <input type="hidden" name="trPrice" value="AES 암호화된 금액" />
  <input type="hidden" name="productNm" value="상품명" />
  <input type="hidden" name="dutyFreeYn" value="N" />
  <input type="hidden" name="callbackUrl" value="https://www.example.com/callback" />
  <input type="hidden" name="signature" value="SHA256 해쉬값" />
</form>

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

--------------------------------

### JavaScript SDK 스크립트 로드 및 결제 호출

Source: https://developers.hectofinancial.co.kr/docs/api/pg/sdk/00-overview

JavaScript SDK를 사용하여 결제창을 호출하는 방법입니다. SDK 스크립트를 로드한 후, pay 함수에 결제 관련 파라미터를 전달하여 결제를 진행합니다.

```javascript
// SDK 스크립트 로드
<script src="https://tbnpg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>

// 결제 호출
SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "popup", width: 430, height: 660 },
    mchtId: "nxca_jt_il",
    method: "card",
    // ... 결제수단별 파라미터
}, callback);

```

--------------------------------

### Transaction Result Inquiry API Request Example

Source: https://developers.hectofinancial.co.kr/docs/api/easy-cash/ob/inquiry/01-transaction-result

This is an example of the request body for the Transaction Result Inquiry API. Ensure all required parameters are correctly formatted.

```json
{
  "hdInfo": "SPAY_LT00_1.0",
  "mchtId": "midtest",
  "pktDivCd": "RP",
  "mchtTrdNo": "OID201902210001",
  "mchtTrdDt": "20191231",
  "reqDt": "20191231",
  "reqTm": "120000",
  "pktHash": "해시값"
}
```

--------------------------------

### Response Example for Parameter Validation Failure

Source: https://developers.hectofinancial.co.kr/docs/api/easy-cash/getting-started/01-basic-flow

This example shows the response structure when a parameter validation fails. It includes status codes and a message indicating the error.

```json
{
  "outStatCd": "0031",
  "outRsltCd": "ST09",
  "outRsltMsg": "유효하지 않는 요청전문"
}
```

--------------------------------

### 가상계좌 수취 조회 처리 로직 샘플 코드 (Node.js)

Source: https://developers.hectofinancial.co.kr/docs/api/pg/virtual-account/06-virtual-account-deposit-inquiry

가맹점에서 수취 조회 요청을 받아 유효성을 검증하고 결과를 응답하는 Node.js 샘플 코드입니다. 해쉬 검증, 주문 조회, 입금기한 및 금액 확인 로직을 포함합니다.

```javascript
app.post('/api/receipt-inquiry', (req, res) => {
  const { mchtTrdNo, trdAmt, vAcntNo, pktHash } = req.body;

  // 1. 해쉬 검증
  if (!verifyHash(req.body, pktHash)) {
    return res.json({ rsltCd: '0009', rsltMsg: '해쉬 검증 실패' });
  }

  // 2. 주문 조회
  const order = findOrderByTrdNo(mchtTrdNo);
  if (!order) {
    return res.json({ rsltCd: '0001', rsltMsg: '계좌없음' });
  }

  // 3. 입금기한 확인
  if (new Date() > order.expireDate) {
    return res.json({ rsltCd: '0002', rsltMsg: '입금기한 만료' });
  }

  // 4. 금액 확인
  if (order.amount !== parseInt(trdAmt)) {
    return res.json({ rsltCd: '0003', rsltMsg: '금액오류' });
  }

  // 5. 성공 응답
  return res.json({ rsltCd: '0000', rsltMsg: '정상' });
});
```

--------------------------------

### 010 Virtual Account Deposit Notification Example

Source: https://developers.hectofinancial.co.kr/docs/api/pg/vbank010/08-noti

This is an example of the deposit notification payload sent from Hecto Financial to merchants. It includes transaction details and must be processed by the merchant's notiUrl.

```text
outStatCd=0021&trdNo=STBK0123456789&method=VA&bizType=B1&mchtId=nxva_sb_il&mchtTrdNo=ORDER20211231100000&mchtCustNm=홍길동&mchtName=헥토파이낸셜&pmtprdNm=테스트상품&trdDtm=20211231010101&trdAmt=1000&bankCd=089&bankNm=K뱅크&vAcntNo=01012345678&expireDt=20211231235959&AcntPrintNm=010가상계좌&dpstrNm=홍길동&mchtCustId=HongGilDong&pktHash=해시값
```

--------------------------------

### Mobile Payment Notification Example

Source: https://developers.hectofinancial.co.kr/docs/api/pg/mobile-payment/02-mobile-noti

This example shows the POST request format for a mobile payment notification sent from HectoFinancial to a merchant's notiUrl. It includes various transaction details.

```http
POST /your-noti-url HTTP/1.1

outStatCd=0021
&trdNo=STFP_PGMPnxhp_sb_il0211231100000M1234567
&method=MP
&bizType=B0
&mchtId=nxhp_sb_il
&mchtTrdNo=ORDER20211231100000
&mchtCustNm=홍길동
&mchtName=헥토파이낸셜
&pmtprdNm=테스트상품
&trdDtm=20211231100000
&trdAmt=10000
&telecomCd=SKT
&telecomNm=SK Telecom
&email=test@example.com
&mchtCustId=customer123
&mchtParam=
&pktHash=a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1


```

--------------------------------

### 출금 가능 머니 조회

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/inquiry/05-withdrawal-balance

조회 API는 POST 메소드를 사용하여 출금 가능한 머니 금액과 해당 월의 출금 횟수를 조회합니다. 요청 본문에는 고객 번호(`custNo`)와 고객 식별 정보(`ci`)가 포함됩니다. 응답은 성공 또는 실패 코드, 메시지, 그리고 출금 가능 금액(`wdMnyAmt`) 및 출금 횟수(`mwCount`)를 포함하는 객체를 반환합니다.

```APIDOC
## POST /v1/wallet/balance/withdrawal

### Description
출금 가능한 머니 금액과 해당 월의 출금 횟수를 조회하는 API입니다.

### Method
POST

### Endpoint
/v1/wallet/balance/withdrawal

### Parameters
#### Request Body
- **custNo** (AN(20)) - Required - 선불 회원번호 (헥토파이낸셜에서 부여하는 고유 선불 회원 번호)
- **ci** (AN(255)) - Required - 선불 회원 CI (고객의 고유한 CI 값. AES-256/ECB/PKCS5Padding 암호화 후 Base64 인코딩 필요)

### Request Example
```json
{
  "custNo": "2400001605",
  "ci": "AES암호화된CI값"
}
```

### Response
#### Success Response (200)
- **rsltCd** (AN(4)) - 응답코드 (`0000`: 성공, 그 외: 실패)
- **rsltMsg** (AN) - 응답 메시지 (`성공`)
- **rsltObj** (object) - 응답 객체
  - **custNo** (AN(20)) - 선불 회원번호 (`2400001605`)
  - **wdMnyAmt** (AN(7)) - 출금 가능 머니 금액 (`500000`) (대기머니 제외)
  - **mwCount** (N(3)) - 해당 월 출금 횟수 (`2`)

#### Response Example (Success)
```json
{
  "rsltCd": "0000",
  "rsltMsg": "성공",
  "rsltObj": {
    "custNo": "2400001605",
    "wdMnyAmt": "500000",
    "mwCount": "2"
  }
}
```

#### Response Example (Failure)
```json
{
  "rsltCd": "1001",
  "rsltMsg": "회원 정보가 존재하지 않습니다."
}
```

### Notes
- 출금 가능 금액은 대기머니를 제외한 일반 머니 잔액입니다.
- 출금 횟수 제한이 있을 수 있으므로 `mwCount`를 확인하세요.
```

--------------------------------

### Transaction Result Inquiry API Response Example

Source: https://developers.hectofinancial.co.kr/docs/api/easy-cash/ob/inquiry/01-transaction-result

This is an example of a successful response from the Transaction Result Inquiry API. It includes transaction status, result codes, and HectoPay transaction details.

```json
{
  "outStatCd": "0021",
  "outRsltCd": "0000",
  "outRsltMsg": "정상처리되었습니다.",
  "trdNo": "STFP_FIRM12345678901234567890",
  "bankCd": "011",
  "svcDivCd": "2"
}
```

--------------------------------

### Failed Trade Inquiry Response

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/inquiry/07-trade-detail

Example of a failed response when trade information is not found.

```json
{
  "rsltCd": "1001",
  "rsltMsg": "거래 정보가 존재하지 않습니다."
}
```

--------------------------------

### POST /v1/api/auth/pwdcnf

Source: https://developers.hectofinancial.co.kr/docs/api/easy-cash/firm/auth/12-password-confirm

가맹점 서버에서 헥토파이낸셜 서버로 결제비밀번호 확인을 요청하는 API입니다. 고객 아이디와 입력된 결제 비밀번호가 일치하는지 확인합니다.

```APIDOC
## POST /v1/api/auth/pwdcnf

### Description
가맹점 서버에서 헥토파이낸셜 서버로 결제비밀번호 확인을 요청합니다. 해당 고객아이디에 대해 입력된 결제비밀번호가 등록된 결제비밀번호와 일치하는지 확인합니다.

### Method
POST

### Endpoint
/v1/api/auth/pwdcnf

### Parameters
#### Request Body
- **hdInfo** (AN(50)) - Required - 전문정보 코드 (고정값)
- **mchtId** (AN(8)) - Required - 상점아이디
- **mchtTrdNo** (AN(100)) - Required - 상점 주문번호 (한글 제외)
- **mchtCustId** (AN(100)) - Required - 고객아이디 (AES-256 암호화)
- **reqDt** (AN(8)) - Required - 요청일자 (yyyyMMdd)
- **reqTm** (AN(6)) - Required - 요청시간 (HH24MISS)
- **pmtPwd** (AN(24)) - Required - 결제비밀번호 (고객이 설정한 6자리 숫자, AES-256 암호화)
- **custIp** (AN(15)) - Optional - 고객 IP 주소
- **pktHash** (AN(200)) - Required - SHA-256 해쉬값

### Request Example
```json
{
  "hdInfo": "고정값",
  "mchtId": "상점아이디",
  "mchtTrdNo": "상점 주문번호",
  "mchtCustId": "암호화된 고객아이디",
  "reqDt": "요청일자",
  "reqTm": "요청시간",
  "pmtPwd": "암호화된 결제비밀번호",
  "custIp": "고객 IP 주소",
  "pktHash": "SHA-256 해쉬값"
}
```

### Response
#### Success Response (200)
- **outStatCd** (AN(4)) - 거래상태코드 (`0021`: 성공, `0031`: 실패)
- **outRsltCd** (AN(4)) - 거절코드 (`0000`: 정상)
- **outRsltMsg** (AN(300)) - 결과메시지
- **mchtCustId** (AN(100)) - 고객아이디 (AES-256 암호화된 값, 복호화 후 사용)
- **mchtTrdNo** (AN(100)) - 상점 주문번호
- **trdNo** (AN(40)) - 헥토파이낸셜 거래번호

#### Response Example
```json
{
  "outStatCd": "0021",
  "outRsltCd": "0000",
  "outRsltMsg": "정상처리 되었습니다.",
  "mchtCustId": "복호화된 고객아이디",
  "mchtTrdNo": "OLD20190221001",
  "trdNo": "SFP_FRIM12345678901234567890"
}
```

#### Error Handling
- **ST01**: 결제비밀번호가 없는 경우 해당 응답코드가 리턴됩니다.
```

--------------------------------

### Initiate Bank Transfer

Source: https://developers.hectofinancial.co.kr/docs/api/pg/bank-transfer/01-bank-transfer

This section describes how to initiate a bank transfer. It involves sending a POST request with form data to the bank transfer endpoint. The provided HTML form and JavaScript can be used to directly call the payment window.

```APIDOC
## POST /bank/main.do

### Description
Initiates a bank transfer payment by submitting form data to the SettleBank payment gateway.

### Method
POST

### Endpoint
https://tbnpg.settlebank.co.kr/bank/main.do

### Parameters
#### Request Body (Form Data)
- **mchtId** (string) - Required - Merchant ID.
- **method** (string) - Required - Specifies the payment method, should be 'bank'.
- **trdDt** (string) - Required - Transaction date (YYYYMMDD).
- **trdTm** (string) - Required - Transaction time (HHMMSS).
- **mchtTrdNo** (string) - Required - Merchant's transaction number.
- **mchtName** (string) - Required - Merchant name (Korean).
- **mchtEName** (string) - Required - Merchant name (English).
- **pmtPrdtNm** (string) - Required - Product name.
- **trdAmt** (string) - Required - Transaction amount, potentially encrypted.
- **notiUrl** (string) - Required - Notification URL for payment results.
- **nextUrl** (string) - Required - URL to redirect after successful payment.
- **cancUrl** (string) - Required - URL to redirect if payment is cancelled.
- **pktHash** (string) - Required - Packet hash for security verification.
- **taxTypeCd** (string) - Required - Tax type code (e.g., 'N' for non-taxable).

### Request Example
```html
<form id="paymentForm" method="POST" action="https://tbnpg.settlebank.co.kr/bank/main.do" target="paymentPopup">
    <input type="hidden" name="cancUrl" value="https://developers.hectofinancial.co.kr/api/cancUrl" />
    <input type="hidden" name="mchtEName" value="Hecto Financial" />
    <input type="hidden" name="mchtId" value="nx_mid_il" />
    <input type="hidden" name="mchtName" value="헥토파이낸셜" />
    <input type="hidden" name="mchtTrdNo" value="BANK20260522002923" />
    <input type="hidden" name="method" value="bank" />
    <input type="hidden" name="nextUrl" value="https://developers.hectofinancial.co.kr/api/nextUrl" />
    <input type="hidden" name="notiUrl" value="https://example.com/notiUrl" />
    <input type="hidden" name="pktHash" value="3879761a8bae25738a71fe35387da4573f2aaa032362d155e0218b88ff836125" />
    <input type="hidden" name="pmtPrdtNm" value="테스트상품" />
    <input type="hidden" name="taxTypeCd" value="N" />
    <input type="hidden" name="trdAmt" value="AntV/eDpxIaKF0hJiePDKA==" />
    <input type="hidden" name="trdDt" value="20260522" />
    <input type="hidden" name="trdTm" value="002923" />
    <button type="submit">결제하기</button>
</form>
```

### Response
This endpoint typically redirects the user to a payment gateway or returns a response indicating the initiation of the payment process. Specific success or error responses depend on the gateway's implementation and are not detailed here.
```

--------------------------------

### Successful Trade Inquiry Response

Source: https://developers.hectofinancial.co.kr/docs/api/prepaid/inquiry/07-trade-detail

Example of a successful response when querying trade details.

```json
{
  "rsltCd": "0000",
  "rsltMsg": "성공",
  "rsltObj": {
    "custNo": "2400001605",
    "mtrdNo": "ORDER20240717",
    "trdNo": "24071716270200002194",
    "trdDt": "20240717",
    "trdTm": "100000",
    "trdDivCd": "MW",
    "trdSumry": "987",
    "trdAmt": "50000",
    "mnyAmt": "50000",
    "pntAmt": "0",
    "mnyBlc": "0",
    "pntBlc": "0",
    "waitMnyBlc": "0",
    "status": "1"
  }
}
```