데이터 모델 설계

이 문서는 “이 스키마 그대로 만들라”는 정답지가 아니에요. Bootpay 결제 SDK를 붙일 때 가맹점 서버가 어떤 값을 확인하고, 어떤 값을 DB에 남겨야 하는지​​를 예시 코드와 테이블로 표현한 안내예요.

이미 주문 테이블이 있다면 그대로 쓰고, 아래 필드는 서비스 상태·정산·CS·취소 처리에 필요한 만큼만 매핑해요.

먼저 나눌 책임

결제 API는 결제 트랜잭션을 처리하고, 주문·상품·회원·구독 회차 같은 서비스 로직은 가맹점 서버가 관리해요.

가맹점 DB에 보통 남기는 값

주문 테이블에 결제 필드를 더하는 예시

아래 SQL은 기존 주문 테이블에 결제 식별값을 붙이는 예시​​예요. 실제 컬럼명, 금액 타입, 인덱스, 상태값은 서비스의 주문 모델에 맞게 바꿔요.

-- 예시: 기존 orders 테이블에 결제 처리에 필요한 필드 추가
ALTER TABLE orders
    ADD COLUMN bootpay_receipt_id VARCHAR(100),   -- Bootpay 영수증 ID
    ADD COLUMN paid_amount        INTEGER,        -- 실제 결제 금액(KRW 기준 예시)
    ADD COLUMN payment_status     INTEGER,        -- Bootpay 원문 status 저장용
    ADD COLUMN payment_method     VARCHAR(30),    -- card, bank, vbank 등
    ADD COLUMN pg                 VARCHAR(50),
    ADD COLUMN paid_at            DATETIME,
    ADD INDEX idx_bootpay_receipt (bootpay_receipt_id);sql

CREATE TABLE orders (
    id                 BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id            BIGINT NOT NULL,
    order_id           VARCHAR(100) NOT NULL,        -- 가맹점 주문번호
    order_name         VARCHAR(200),
    total_amount       INTEGER NOT NULL,             -- 가맹점이 계산한 주문 금액
    order_status       VARCHAR(30) DEFAULT 'pending',

    bootpay_receipt_id VARCHAR(100),
    paid_amount        INTEGER,
    payment_status     INTEGER,
    payment_method     VARCHAR(30),
    pg                 VARCHAR(50),
    paid_at            DATETIME,

    created_at         DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_user (user_id),
    UNIQUE INDEX idx_order_id (order_id),
    INDEX idx_bootpay_receipt (bootpay_receipt_id)
);sql

저장 시점​​은 결제 흐름에 따라 달라요.

// 예시: 결제 조회/검증 성공 후 내부 주문 상태를 갱신
// price 는 잔액이므로, 최초 검증 시점의 원금은 price + cancelled_price 로 복원해요
const originalPrice = receipt.price + (receipt.cancelled_price ?? 0)

if (receipt.status === 1 && originalPrice === order.total_amount) {
    await db.orders.update({
        bootpay_receipt_id: receipt.receipt_id,
        paid_amount: originalPrice,          // 원금을 남기고 싶다면 복원값을 저장해요
        cancelled_amount: receipt.cancelled_price ?? 0,
        payment_status: receipt.status,
        payment_method: receipt.method_symbol,
        pg: receipt.pg,
        order_status: 'paid',
        paid_at: receipt.purchased_at ? new Date(receipt.purchased_at) : new Date(),
    }, { where: { order_id: order.order_id } })
}javascript

결제 조회 응답에서 확인할 값

결제 조회 응답은 주문 확정의 근거로 사용해요. 모든 필드를 저장할 필요는 없고, 주문 처리·CS·취소에 필요한 값만 남겨요.

자주 만나는 status 값

빌링키 테이블 예시

빌링키는 카드번호 원본이 아니라, 저장 결제수단으로 결제를 요청할 때 쓰는 식별값이에요. 가맹점은 billing_key와 표시용 마스킹 정보만 저장하고, 카드번호 전체·비밀번호·CVC·유효기간은 저장하지 않아요.

CREATE TABLE billing_keys (
    id                  BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id             BIGINT NOT NULL,
    billing_key         VARCHAR(100) NOT NULL,
    status              VARCHAR(20) DEFAULT 'active',
    card_company        VARCHAR(50),
    masked_card_no      VARCHAR(50),
    billing_expire_at   DATETIME,
    created_at          DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_user_status (user_id, status),
    UNIQUE INDEX idx_billing_key (billing_key)
);sql

저장하면 안 되는 것

데이터 흐름 요약

결제 API — Receipt → 주문 상태

빌링 — BillingKey → 청구/예약