create-entity-app-server 0.0.3

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

@@ -0,0 +1,242 @@
+/**
+ * 카카오페이 결제 클라이언트
+ *
+ * ref: https://developers.kakaopay.com/docs/payment/online/common
+ */
+
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+} from "../types/index.ts";
+import { PgError } from "../types/index.ts";
+
+export class KakaoPayClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly secretKey: string;
+    private readonly cid: string;
+
+    constructor(cfg: PgProviderConfig) {
+        if (!cfg.secret_key)
+            throw new Error("kakaopay: secret_key가 필요합니다");
+        if (!cfg.mid) throw new Error("kakaopay: mid (cid)가 필요합니다");
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://open-api.kakaopay.com";
+        this.secretKey = cfg.secret_key;
+        this.cid = cfg.mid;
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            Authorization: `SECRET_KEY ${this.secretKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        // PaymentKey = "tid:pg_token" 형식 파싱
+        const parts = req.paymentKey.split(":", 2);
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new Error(
+                `kakaopay: invalid PaymentKey format, expected "tid:pg_token", got "${req.paymentKey}"`,
+            );
+        }
+        const [tid, pgToken] = parts;
+
+        const resp = await fetch(`${this.apiUrl}/online/v1/payment/approve`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                cid: this.cid,
+                tid,
+                partner_order_id: req.orderId,
+                partner_user_id: req.orderId, // fallback: orderID를 user id로 사용
+                pg_token: pgToken,
+            }),
+            signal: _ctx,
+        });
+        return this.parseResponse(resp, "kakaopay");
+    }
+
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        // cancelAmount가 없으면 originalAmount로 전액 취소
+        const cancelAmount = req.cancelAmount ?? req.originalAmount ?? 0;
+        const taxFreeAmount = req.taxFreeAmount ?? 0;
+
+        const body: Record<string, unknown> = {
+            cid: this.cid,
+            tid: req.paymentKey,
+            cancel_amount: cancelAmount,
+            cancel_tax_free_amount: taxFreeAmount,
+        };
+
+        const resp = await fetch(`${this.apiUrl}/online/v1/payment/cancel`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: _ctx,
+        });
+        const result = await this.parseResponse(resp, "kakaopay");
+        return { ...result };
+    }
+
+    async getPayment(
+        _ctx: AbortSignal | null,
+        paymentKey: string,
+    ): Promise<PaymentResult> {
+        // 카카오페이 주문 조회: POST /online/v1/payment/order (JSON body)
+        const resp = await fetch(`${this.apiUrl}/online/v1/payment/order`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                cid: this.cid,
+                tid: paymentKey,
+            }),
+            signal: _ctx,
+        });
+        return this.parseResponse(resp, "kakaopay");
+    }
+
+    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 >= 500) {
+            throw new Error(
+                `${prefix}: server error (status ${resp.status}): ${text}`,
+            );
+        }
+        if (resp.status !== 200) {
+            try {
+                const err = JSON.parse(text) as {
+                    error_code?: number;
+                    error_message?: string;
+                };
+                if (err.error_code != null)
+                    throw new PgError(
+                        String(err.error_code),
+                        err.error_message ?? "",
+                    );
+            } 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 normalizeKakaoPayResponse(raw);
+    }
+}
+
+function normalizeKakaoPayResponse(
+    raw: Record<string, unknown>,
+): PaymentResult {
+    const amount = (raw.amount ?? {}) as Record<string, unknown>;
+    const cancelAvailable = (raw.cancel_available_amount ?? {}) as Record<
+        string,
+        unknown
+    >;
+    const cardInfo = raw.card_info as Record<string, unknown> | undefined;
+    const status = mapKakaoStatus(String(raw.status ?? ""));
+
+    const result: PaymentResult = {
+        paymentKey: String(raw.tid ?? ""),
+        orderId: String(raw.partner_order_id ?? ""),
+        orderName: String(raw.item_name ?? ""),
+        status,
+        method: String(raw.payment_method_type ?? ""),
+        totalAmount: Number(amount.total ?? 0),
+        balanceAmount: Number(cancelAvailable.total ?? amount.total ?? 0),
+        currency: "KRW",
+        type: "PAYMENT",
+        country: "KR",
+        isPartialCancelable: Number(cancelAvailable.total ?? 0) > 0,
+        easyPay: {
+            provider: "KAKAOPAY",
+            amount:
+                Number(amount.total ?? 0) -
+                Number(amount.point ?? 0) -
+                Number(amount.discount ?? 0),
+            discountAmount: Number(amount.discount ?? 0),
+        },
+        _raw: raw,
+    };
+
+    if (cardInfo) {
+        let installMonths = 0;
+        const im = cardInfo.install_month;
+        if (typeof im === "string") installMonths = parseInt(im, 10) || 0;
+        else if (typeof im === "number") installMonths = im;
+
+        result.card = {
+            issuerCode: String(cardInfo.kakaopay_issuer_corp_code ?? ""),
+            acquirerCode: String(cardInfo.kakaopay_purchase_corp_code ?? ""),
+            number: String(cardInfo.bin ?? ""),
+            installmentPlanMonths: installMonths,
+            cardType: String(cardInfo.card_type ?? ""),
+            ownerType: "",
+            approveNo: String(cardInfo.approved_id ?? ""),
+            amount: Number(amount.total ?? 0),
+            isInterestFree: cardInfo.interest_free_install === "Y",
+        };
+    }
+
+    return result;
+}
+
+function mapKakaoStatus(s: string): string {
+    switch (s) {
+        case "READY":
+            return "ready";
+        case "SEND_TMS":
+            return "in_progress";
+        case "OPEN_PAYMENT":
+            return "in_progress";
+        case "SELECT_METHOD":
+            return "in_progress";
+        case "ARS_WAITING":
+            return "waiting";
+        case "AUTH_PASSWORD":
+            return "in_progress";
+        case "ISSUED_SID":
+            return "in_progress";
+        case "SUCCESS_PAYMENT":
+            return "done";
+        case "PART_CANCEL_PAYMENT":
+            return "partial_canceled";
+        case "CANCEL_PAYMENT":
+            return "canceled";
+        case "FAIL_AUTH_PASSWORD":
+            return "aborted";
+        case "QUIT_PAYMENT":
+            return "aborted";
+        case "FAIL_PAYMENT":
+            return "aborted";
+        default:
+            return s.toLowerCase() || "aborted";
+    }
+}

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

@@ -0,0 +1,147 @@
+/**
+ * NHN KCP 결제 클라이언트
+ *
+ * ref: https://developers.kcp.co.kr
+ */
+
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+} from "../types/index.ts";
+import { PgError } from "../types/index.ts";
+
+export class KcpClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly siteCD: string;
+    private readonly secretKey: string;
+
+    constructor(cfg: PgProviderConfig) {
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://api.pay.kcp.co.kr";
+        this.siteCD = cfg.site_cd || "";
+        this.secretKey = cfg.secret_key || "";
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            Authorization: `Secret ${this.secretKey}`,
+            "Site-CD": this.siteCD,
+            "Content-Type": "application/json",
+        };
+    }
+
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        const resp = await fetch(`${this.apiUrl}/v1/payment/approve`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                tno: req.paymentKey,
+                order_no: req.orderId,
+                amount: req.amount,
+                site_cd: this.siteCD,
+            }),
+            signal: _ctx,
+        });
+        return this.parseResponse(resp, "kcp");
+    }
+
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        const body: Record<string, unknown> = {
+            tno: req.paymentKey,
+            cancel_reason: req.cancelReason,
+            site_cd: this.siteCD,
+        };
+        if (req.cancelAmount != null) body.cancel_amount = req.cancelAmount;
+
+        const resp = await fetch(`${this.apiUrl}/v1/payment/cancel`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: _ctx,
+        });
+        const result = await this.parseResponse(resp, "kcp");
+        return { ...result };
+    }
+
+    async getPayment(
+        _ctx: AbortSignal | null,
+        paymentKey: string,
+    ): Promise<PaymentResult> {
+        const resp = await fetch(
+            `${this.apiUrl}/v1/payment/${paymentKey}?site_cd=${this.siteCD}`,
+            {
+                headers: this.headers(),
+                signal: _ctx,
+            },
+        );
+        return this.parseResponse(resp, "kcp");
+    }
+
+    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 {
+                    code?: string;
+                    message?: string;
+                    res_msg?: string;
+                };
+                if (err.code)
+                    throw new PgError(
+                        err.code,
+                        err.message ?? err.res_msg ?? "",
+                    );
+            } 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 normalizeKcpResponse(raw);
+    }
+}
+
+function normalizeKcpResponse(raw: Record<string, unknown>): PaymentResult {
+    return {
+        paymentKey: String(raw.tno ?? ""),
+        orderId: String(raw.order_no ?? ""),
+        orderName: String(raw.goods_name ?? ""),
+        status: String(raw.res_cd === "0000" ? "done" : (raw.status ?? "")),
+        method: String(raw.pay_method ?? ""),
+        totalAmount: Number(raw.amount ?? 0),
+        balanceAmount: Number(raw.remain_amount ?? raw.amount ?? 0),
+        currency: "KRW",
+        type: "PAYMENT",
+        country: "KR",
+        isPartialCancelable: true,
+        _raw: raw,
+    };
+}

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

@@ -0,0 +1,299 @@
+/**
+ * 네이버페이 결제 클라이언트 (주문형)
+ *
+ * 인증: HTTP 헤더 방식
+ *   X-Naver-Client-Id     : 가맹점 클라이언트 ID
+ *   X-Naver-Client-Secret : 가맹점 클라이언트 시크릿
+ *   X-NaverPay-Chain-Id   : 가맹점 체인 ID
+ *
+ * 운영 도메인: https://pay.paygate.naver.com
+ *
+ * 주요 API 엔드포인트:
+ *   결제 승인: POST /naverpay-partner/naverpay/payments/v2.2/apply/payment (form-urlencoded)
+ *   결제 취소: POST /naverpay-partner/naverpay/payments/v1/cancel (form-urlencoded)
+ *   결제 조회: POST /naverpay-partner/naverpay/payments/v2.2/list/history/{paymentId} (JSON)
+ *
+ * ref: https://docs.pay.naver.com/docs/onetime-payment/onetime-payment-overview
+ */
+
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+    CardInfo,
+    EasyPayInfo,
+    CancelInfo,
+} from "../types/index.ts";
+
+export class NaverPayClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly clientId: string;
+    private readonly clientSecret: string;
+    private readonly chainId: string;
+
+    constructor(cfg: PgProviderConfig) {
+        if (!cfg.client_key || !cfg.secret_key || !cfg.mid)
+            throw new Error(
+                "naverpay: client_key, secret_key, mid (chain_id)가 필요합니다",
+            );
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://pay.paygate.naver.com";
+        this.clientId = cfg.client_key;
+        this.clientSecret = cfg.secret_key;
+        this.chainId = cfg.mid;
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    private setHeaders(contentType: string): Record<string, string> {
+        return {
+            "X-Naver-Client-Id": this.clientId,
+            "X-Naver-Client-Secret": this.clientSecret,
+            "X-NaverPay-Chain-Id": this.chainId,
+            "Content-Type": contentType,
+        };
+    }
+
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        const params = new URLSearchParams();
+        params.set("paymentId", req.paymentKey);
+
+        const resp = await fetch(
+            `${this.apiUrl}/naverpay-partner/naverpay/payments/v2.2/apply/payment`,
+            {
+                method: "POST",
+                headers: this.setHeaders("application/x-www-form-urlencoded"),
+                body: params.toString(),
+                signal: _ctx,
+            },
+        );
+
+        const raw = await this.parseApiResponse(resp, "naverpay", "confirm");
+        const body = raw.body as {
+            paymentId?: string;
+            detail?: NaverPayDetail;
+        };
+        return this.detailToPaymentResult(
+            body?.paymentId ?? "",
+            body?.detail ?? ({} as NaverPayDetail),
+        );
+    }
+
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        // 취소 금액: cancelAmount 없으면 originalAmount 전액 취소
+        const cancelAmount = req.cancelAmount ?? req.originalAmount ?? 0;
+
+        // 과세/면세 금액
+        let taxScopeAmount = cancelAmount;
+        let taxExScopeAmount = 0;
+        if (req.taxFreeAmount != null) {
+            taxExScopeAmount = req.taxFreeAmount;
+            taxScopeAmount = cancelAmount - taxExScopeAmount;
+        }
+
+        const params = new URLSearchParams();
+        params.set("paymentId", req.paymentKey);
+        params.set("cancelAmount", String(cancelAmount));
+        params.set("cancelReason", req.cancelReason);
+        params.set("cancelRequester", "2"); // 2: 가맹점 관리자
+        params.set("taxScopeAmount", String(taxScopeAmount));
+        params.set("taxExScopeAmount", String(taxExScopeAmount));
+
+        const resp = await fetch(
+            `${this.apiUrl}/naverpay-partner/naverpay/payments/v1/cancel`,
+            {
+                method: "POST",
+                headers: this.setHeaders("application/x-www-form-urlencoded"),
+                body: params.toString(),
+                signal: _ctx,
+            },
+        );
+
+        const raw = await this.parseApiResponse(resp, "naverpay", "cancel");
+        const body = raw.body as {
+            paymentId?: string;
+            payHistId?: string;
+            primaryPayMeans?: string;
+            primaryPayCancelAmount?: number;
+            primaryPayRestAmount?: number;
+            cancelYmdt?: string;
+            totalRestAmount?: number;
+        };
+
+        const payResult: PaymentResult = {
+            paymentKey: body?.paymentId ?? "",
+            orderId: "",
+            orderName: "",
+            status: "canceled",
+            method: body?.primaryPayMeans ?? "",
+            totalAmount: cancelAmount,
+            balanceAmount: body?.totalRestAmount ?? 0,
+            currency: "KRW",
+            type: "PAYMENT",
+            country: "KR",
+            isPartialCancelable: (body?.totalRestAmount ?? 0) > 0,
+            _raw: raw as unknown as Record<string, unknown>,
+        };
+
+        const latestCancel: CancelInfo = {
+            transactionKey: body?.payHistId ?? "",
+            cancelReason: req.cancelReason,
+            cancelAmount,
+            canceledAt: body?.cancelYmdt ?? "",
+            cancelStatus: "DONE",
+            refundableAmount: body?.totalRestAmount ?? 0,
+        };
+
+        return { ...payResult, latestCancel };
+    }
+
+    async getPayment(
+        _ctx: AbortSignal | null,
+        paymentKey: string,
+    ): Promise<PaymentResult> {
+        // 결제 조회: POST (JSON body)
+        const resp = await fetch(
+            `${this.apiUrl}/naverpay-partner/naverpay/payments/v2.2/list/history/${paymentKey}`,
+            {
+                method: "POST",
+                headers: this.setHeaders("application/json"),
+                body: JSON.stringify({
+                    pageNumber: 1,
+                    rowsPerPage: 1,
+                }),
+                signal: _ctx,
+            },
+        );
+
+        const raw = await this.parseApiResponse(resp, "naverpay", "getpayment");
+        const body = raw.body as {
+            list?: NaverPayDetail[];
+            totalCount?: number;
+        };
+        if (!body?.list?.length) {
+            throw new Error(`naverpay: payment not found: ${paymentKey}`);
+        }
+
+        return this.detailToPaymentResult(paymentKey, body.list[0]);
+    }
+
+    async verifyWebhook(
+        _ctx: AbortSignal | null,
+        _payload: Buffer,
+        _signature: string,
+    ): Promise<boolean> {
+        // 네이버페이는 IP 화이트리스트 + HTTPS 기반 신뢰
+        return true;
+    }
+
+    // ─── 내부 헬퍼 ───────────────────────────────────────────
+
+    private async parseApiResponse(
+        resp: Response,
+        prefix: string,
+        op: string,
+    ): Promise<{ code: string; message: string; body: unknown }> {
+        const text = await resp.text();
+        if (resp.status >= 500) {
+            throw new Error(`${prefix}: server error ${resp.status}: ${text}`);
+        }
+
+        const raw = JSON.parse(text) as {
+            code?: string;
+            message?: string;
+            body?: unknown;
+        };
+
+        if (raw.code !== "Success") {
+            throw new Error(
+                `${prefix}: ${op} failed: code=${raw.code}, message=${raw.message}`,
+            );
+        }
+
+        return {
+            code: raw.code ?? "",
+            message: raw.message ?? "",
+            body: raw.body,
+        };
+    }
+
+    private detailToPaymentResult(
+        paymentId: string,
+        d: NaverPayDetail,
+    ): PaymentResult {
+        let status = "done";
+        switch (d.admissionTypeCode) {
+            case "03":
+                status = "canceled";
+                break;
+            case "04":
+                status = "partial_canceled";
+                break;
+        }
+
+        const result: PaymentResult = {
+            paymentKey: paymentId,
+            orderId: d.merchantPayKey ?? "",
+            orderName: d.productName ?? "",
+            status,
+            method: d.primaryPayMeans ?? "",
+            totalAmount: d.totalPayAmount ?? 0,
+            balanceAmount: d.totalPayAmount ?? 0,
+            currency: "KRW",
+            approvedAt: d.admissionYmdt ?? undefined,
+            type: "PAYMENT",
+            country: "KR",
+            isPartialCancelable: true,
+            easyPay: {
+                provider: "NAVER",
+                amount: d.totalPayAmount ?? 0,
+                discountAmount: 0,
+            },
+        };
+
+        if (d.cardAuthNo) {
+            result.card = {
+                issuerCode: d.cardCorpCode ?? "",
+                acquirerCode: "",
+                number: d.cardNo ?? "",
+                installmentPlanMonths: d.cardInstCount ?? 0,
+                cardType: "",
+                ownerType: "",
+                approveNo: d.cardAuthNo,
+                amount: d.totalPayAmount ?? 0,
+                isInterestFree: false,
+            };
+        }
+
+        return result;
+    }
+}
+
+interface NaverPayDetail {
+    paymentId?: string;
+    payHistId?: string;
+    merchantPayKey?: string;
+    merchantUserKey?: string;
+    admissionTypeCode?: string; // 01:원결제, 03:전액취소, 04:부분취소
+    admissionYmdt?: string; // yyyyMMddHHmmss
+    admissionState?: string; // SUCCESS / FAIL
+    totalPayAmount?: number;
+    primaryPayMeans?: string; // CARD / BANK
+    cardCorpCode?: string;
+    cardNo?: string;
+    cardAuthNo?: string;
+    cardInstCount?: number;
+    productName?: string;
+}