create-entity-app-server 0.0.3

package/src/app/plugins/pg/providers/hecto.ts

@@ -0,0 +1,340 @@
+/**
+ * 헥토파이낸셜(구 세틀뱅크) 결제 클라이언트
+ *
+ * 보안:
+ *   - AES-256/ECB/PKCS5Padding + Base64 (금액/민감정보 암호화)
+ *   - SHA-256 + Hex (pktHash 위변조 방지)
+ *
+ * ref: https://develop.sbsvc.online
+ */
+
+import { createCipheriv, createHash } from "node:crypto";
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+} from "../types/index.ts";
+import { PgError } from "../types/index.ts";
+
+export class HectoClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly merchantId: string;
+    private readonly hashKey: string;
+    private readonly aesKey: Buffer;
+
+    constructor(cfg: PgProviderConfig) {
+        const mid = cfg.mid || cfg.merchant_id || "";
+        if (!mid) throw new Error("hecto: merchant_id (또는 mid)가 필요합니다");
+        if (!cfg.sign_key)
+            throw new Error("hecto: sign_key (hash key)가 필요합니다");
+
+        const aesKeyStr = cfg.aes_key || "pgSettle30y739r82jtd709yOfZ2yK5K";
+        if (aesKeyStr.length !== 32)
+            throw new Error(
+                `hecto: aes_key는 정확히 32바이트여야 합니다 (현재 ${aesKeyStr.length})`,
+            );
+
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://gw.settlebank.co.kr";
+        this.merchantId = mid;
+        this.hashKey = cfg.sign_key;
+        this.aesKey = Buffer.from(aesKeyStr, "ascii");
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    /** SHA-256(parts... + hashKey) → hex */
+    private pktHash(...parts: string[]): string {
+        const data = parts.join("") + this.hashKey;
+        return createHash("sha256").update(data, "utf-8").digest("hex");
+    }
+
+    /** AES-256/ECB/PKCS5Padding + Base64 */
+    private aesEncrypt(plaintext: string): string {
+        const bs = 16;
+        const input = Buffer.from(plaintext, "utf-8");
+        const padLen = bs - (input.length % bs);
+        const padded = Buffer.concat([input, Buffer.alloc(padLen, padLen)]);
+        // ECB: 각 블록 독립 암호화
+        const result = Buffer.alloc(padded.length);
+        for (let i = 0; i < padded.length; i += bs) {
+            const cipher = createCipheriv("aes-256-ecb", this.aesKey, null);
+            cipher.setAutoPadding(false);
+            const block = cipher.update(padded.slice(i, i + bs));
+            block.copy(result, i);
+        }
+        return result.toString("base64");
+    }
+
+    /** 결제수단 문자열을 헥토 2자리 코드로 변환 */
+    private mapMethod(method?: string): string {
+        switch (method) {
+            case "RA":
+            case "bank":
+            case "계좌이체":
+                return "RA";
+            case "VA":
+            case "vbank":
+            case "가상계좌":
+                return "VA";
+            case "MP":
+            case "mobile":
+            case "휴대폰":
+                return "MP";
+            case "PZ":
+            case "easy":
+            case "간편결제":
+                return "PZ";
+            default:
+                return "CA";
+        }
+    }
+
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        const now = new Date();
+        const trdDt = formatDate(now);
+        const trdTm = formatTime(now);
+        const amtStr = String(req.amount);
+
+        // pktHash = 거래일자 + 거래시간 + 상점아이디 + 상점주문번호 + 거래금액(평문) + 해쉬키
+        const hash = this.pktHash(
+            trdDt,
+            trdTm,
+            this.merchantId,
+            req.orderId,
+            amtStr,
+        );
+        const encAmt = this.aesEncrypt(amtStr);
+
+        const body = {
+            params: {
+                mchtId: this.merchantId,
+                ver: "0A19",
+                method: this.mapMethod(req.method),
+                bizType: "B0",
+                encCd: "23",
+                mchtTrdNo: req.orderId,
+                trdDt,
+                trdTm,
+                mobileYn: "N",
+                osType: "W",
+            },
+            data: {
+                pktHash: hash,
+                trdNo: req.paymentKey,
+                trdAmt: encAmt,
+                crcCd: "KRW",
+            },
+        };
+
+        // 거래 조회 URL: nspay.settlebank.co.kr
+        const queryUrl = `https://nspay.settlebank.co.kr/api/pg/${this.merchantId}/transInfo.do`;
+        return this.doRequest(queryUrl, body, "hecto");
+    }
+
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        const now = new Date();
+        const trdDt = formatDate(now);
+        const trdTm = formatTime(now);
+        // 취소 요청의 mchtTrdNo는 신규 고유 번호 (취소거래 식별자)
+        const cancelTrdNo = `CL${trdDt}${trdTm}`;
+
+        // 취소 금액 결정
+        const cancelAmt = req.cancelAmount ?? req.originalAmount ?? 0;
+        const amtStr = String(cancelAmt);
+
+        // pktHash = 취소요청일자 + 취소요청시간 + 상점아이디 + 상점주문번호(취소용) + 취소금액(평문) + 해쉬키
+        const hash = this.pktHash(
+            trdDt,
+            trdTm,
+            this.merchantId,
+            cancelTrdNo,
+            amtStr,
+        );
+        const encAmt = this.aesEncrypt(amtStr);
+
+        const body = {
+            params: {
+                mchtId: this.merchantId,
+                ver: "0A19",
+                method: this.mapMethod(req.method),
+                bizType: "C0",
+                encCd: "23",
+                mchtTrdNo: cancelTrdNo,
+                trdDt,
+                trdTm,
+                mobileYn: "N",
+                osType: "W",
+            },
+            data: {
+                pktHash: hash,
+                orgTrdNo: req.paymentKey,
+                crcCd: "KRW",
+                cnclOrd: "001",
+                cnclAmt: encAmt,
+                cnclRsn: req.cancelReason,
+            },
+        };
+
+        const result = await this.doRequest(
+            `${this.apiUrl}/spay/APICancel.do`,
+            body,
+            "hecto",
+        );
+        return { ...result };
+    }
+
+    async getPayment(
+        _ctx: AbortSignal | null,
+        paymentKey: string,
+    ): Promise<PaymentResult> {
+        const now = new Date();
+        const trdDt = formatDate(now);
+        const trdTm = formatTime(now);
+        // 금액 미지정 시 "0" 사용 (조회는 금액 불필요)
+        const hash = this.pktHash(
+            trdDt,
+            trdTm,
+            this.merchantId,
+            paymentKey,
+            "0",
+        );
+
+        const body = {
+            params: {
+                mchtId: this.merchantId,
+                ver: "0A19",
+                mchtTrdNo: paymentKey,
+                trdDt,
+                trdTm,
+            },
+            data: { pktHash: hash },
+        };
+
+        // 거래 조회 URL: nspay.settlebank.co.kr
+        const queryUrl = `https://nspay.settlebank.co.kr/api/pg/${this.merchantId}/transInfo.do`;
+        return this.doRequest(queryUrl, body, "hecto");
+    }
+
+    async verifyWebhook(
+        _ctx: AbortSignal | null,
+        payload: Buffer,
+        signature: string,
+    ): Promise<boolean> {
+        // 노티 pktHash 검증
+        // SHA256(거래상태코드 + 거래일자 + 거래시간 + 상점아이디 + 상점주문번호 + 거래금액 + 해쉬키)
+        try {
+            const noti = JSON.parse(payload.toString()) as Record<
+                string,
+                string
+            >;
+            const expected = this.pktHash(
+                noti.outStatCd ?? "",
+                noti.trdDt ?? "",
+                noti.trdTm ?? "",
+                noti.mchtId ?? "",
+                noti.mchtTrdNo ?? "",
+                noti.trdAmt ?? "",
+            );
+            return expected === signature;
+        } catch {
+            return false;
+        }
+    }
+
+    private async doRequest(
+        url: string,
+        body: unknown,
+        prefix: string,
+    ): Promise<PaymentResult> {
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const text = await resp.text();
+        if (resp.status >= 400) {
+            throw new Error(
+                `${prefix}: API error (status ${resp.status}): ${text}`,
+            );
+        }
+        const raw = JSON.parse(text) as Record<string, unknown>;
+        const hResp = raw as {
+            params?: {
+                outStatCd?: string;
+                outRsltCd?: string;
+                outRsltMsg?: string;
+                trdNo?: string;
+                mchtTrdNo?: string;
+            };
+            data?: Record<string, unknown>;
+        };
+        const params = hResp.params ?? {};
+        const outStatCd = params.outStatCd ?? "";
+
+        const result = normalizeHectoResponse(raw);
+
+        // 거래 상태 판단: 성공=0021, 실패=0031 등
+        if (outStatCd === "0021") {
+            result.status = "done";
+        } else if (outStatCd !== "") {
+            result.status = "aborted";
+            result.failure = {
+                code: params.outRsltCd ?? "UNKNOWN",
+                message: params.outRsltMsg ?? "",
+            };
+            throw new PgError(
+                params.outRsltCd ?? "UNKNOWN",
+                params.outRsltMsg ?? "",
+            );
+        }
+        return result;
+    }
+}
+
+function normalizeHectoResponse(raw: Record<string, unknown>): PaymentResult {
+    const p = (raw.params ?? {}) as Record<string, unknown>;
+    const d = (raw.data ?? {}) as Record<string, unknown>;
+    return {
+        paymentKey: String(p.trdNo ?? ""),
+        orderId: String(p.mchtTrdNo ?? ""),
+        orderName: String(d.goodsNm ?? ""),
+        status: "done",
+        method: String(d.method ?? p.method ?? ""),
+        totalAmount: Number(d.trdAmt ?? 0),
+        balanceAmount: Number(d.remainAmt ?? d.trdAmt ?? 0),
+        currency: String(d.crcCd ?? "KRW"),
+        type: "PAYMENT",
+        country: "KR",
+        isPartialCancelable: true,
+        _raw: raw,
+    };
+}
+
+function formatDate(d: Date): string {
+    return (
+        d.getFullYear().toString() +
+        String(d.getMonth() + 1).padStart(2, "0") +
+        String(d.getDate()).padStart(2, "0")
+    );
+}
+
+function formatTime(d: Date): string {
+    return (
+        String(d.getHours()).padStart(2, "0") +
+        String(d.getMinutes()).padStart(2, "0") +
+        String(d.getSeconds()).padStart(2, "0")
+    );
+}

package/src/app/plugins/pg/providers/index.ts

@@ -0,0 +1,53 @@
+/**
+ * PG 결제 클라이언트 팩토리
+ *
+ * driver 값에 따라 적절한 PgClient 구현체를 반환합니다.
+ *
+ * 지원 드라이버:
+ *   toss_payments, kcp, inicis, danal, hecto, kakaopay, naverpay, payco, wanna, payletter, paypal
+ */
+
+import type { PgClient, PgProviderConfig } from "../types/index.ts";
+import { TossClient } from "./toss.ts";
+import { KcpClient } from "./kcp.ts";
+import { InicisClient } from "./inicis.ts";
+import { DanalClient } from "./danal.ts";
+import { HectoClient } from "./hecto.ts";
+import { KakaoPayClient } from "./kakaopay.ts";
+import { NaverPayClient } from "./naverpay.ts";
+import { PaycoClient } from "./payco.ts";
+import { WannaClient } from "./wanna.ts";
+import { PayletterClient } from "./payletter.ts";
+import { PayPalClient } from "./paypal.ts";
+
+/** PgProviderConfig로부터 PgClient를 생성한다 */
+export function createPgClient(cfg: PgProviderConfig): PgClient {
+    switch (cfg.driver) {
+        case "toss_payments":
+            return new TossClient(cfg);
+        case "kcp":
+            return new KcpClient(cfg);
+        case "inicis":
+            return new InicisClient(cfg);
+        case "danal":
+            return new DanalClient(cfg);
+        case "hecto":
+            return new HectoClient(cfg);
+        case "kakaopay":
+            return new KakaoPayClient(cfg);
+        case "naverpay":
+            return new NaverPayClient(cfg);
+        case "payco":
+            return new PaycoClient(cfg);
+        case "wanna":
+            return new WannaClient(cfg);
+        case "payletter":
+            return new PayletterClient(cfg);
+        case "paypal":
+            return new PayPalClient(cfg);
+        default:
+            throw new Error(`unknown pg driver: ${cfg.driver}`);
+    }
+}
+
+export type { PgClient };

package/src/app/plugins/pg/providers/inicis.ts

@@ -0,0 +1,151 @@
+/**
+ * KG 이니시스 결제 클라이언트
+ *
+ * ref: https://manual.inicis.com
+ */
+
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+} from "../types/index.ts";
+import { PgError } from "../types/index.ts";
+
+export class InicisClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly storeId: string;
+    private readonly signKey: string;
+
+    constructor(cfg: PgProviderConfig) {
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://api.inicis.com";
+        this.storeId = cfg.store_id || "";
+        this.signKey = cfg.sign_key || "";
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            Authorization: `SignKey ${this.signKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        const resp = await fetch(`${this.apiUrl}/api/v1/formpay/approval`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                tid: req.paymentKey,
+                oid: req.orderId,
+                price: req.amount,
+                mid: this.storeId,
+            }),
+            signal: _ctx,
+        });
+        return this.parseResponse(resp, "inicis");
+    }
+
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        const body: Record<string, unknown> = {
+            tid: req.paymentKey,
+            msg: req.cancelReason,
+            mid: this.storeId,
+        };
+        if (req.cancelAmount != null) body.price = req.cancelAmount;
+
+        const resp = await fetch(`${this.apiUrl}/api/v1/refund`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: _ctx,
+        });
+        const result = await this.parseResponse(resp, "inicis");
+        return { ...result };
+    }
+
+    async getPayment(
+        _ctx: AbortSignal | null,
+        paymentKey: string,
+    ): Promise<PaymentResult> {
+        const resp = await fetch(
+            `${this.apiUrl}/api/v1/receipt/${paymentKey}?mid=${this.storeId}`,
+            {
+                headers: this.headers(),
+                signal: _ctx,
+            },
+        );
+        return this.parseResponse(resp, "inicis");
+    }
+
+    async verifyWebhook(
+        _ctx: AbortSignal | null,
+        _payload: Buffer,
+        _signature: string,
+    ): Promise<boolean> {
+        return true;
+    }
+
+    private async parseResponse(
+        resp: Response,
+        prefix: string,
+    ): Promise<PaymentResult> {
+        const text = await resp.text();
+        if (resp.status >= 400) {
+            try {
+                const err = JSON.parse(text) as {
+                    resultCode?: string;
+                    resultMsg?: string;
+                };
+                if (err.resultCode && err.resultCode !== "00") {
+                    throw new PgError(err.resultCode, err.resultMsg ?? "");
+                }
+            } catch (e) {
+                if (e instanceof PgError) throw e;
+            }
+            throw new Error(
+                `${prefix}: API error (status ${resp.status}): ${text}`,
+            );
+        }
+        const raw = JSON.parse(text) as Record<string, unknown>;
+        return normalizeInicisResponse(raw);
+    }
+}
+
+function normalizeInicisResponse(raw: Record<string, unknown>): PaymentResult {
+    const code = String(raw.resultCode ?? "");
+    const result: PaymentResult = {
+        paymentKey: String(raw.tid ?? ""),
+        orderId: String(raw.oid ?? ""),
+        orderName: String(raw.goods ?? ""),
+        status: code === "00" ? "done" : "aborted",
+        method: String(raw.payMethod ?? ""),
+        totalAmount: Number(raw.price ?? 0),
+        balanceAmount: Number(raw.price ?? 0),
+        currency: "KRW",
+        type: "PAYMENT",
+        country: "KR",
+        isPartialCancelable: false,
+        _raw: raw,
+    };
+    if (code !== "00" && code !== "") {
+        result.failure = {
+            code,
+            message: String(raw.resultMsg ?? ""),
+        };
+    }
+    return result;
+}