데이터 모델 설계

"내 DB에 뭘 저장해야 해?" — Bootpay 연동 시 가맹점이 관리해야 하는 데이터를 정리해요.

이럴 때 필요해요​: DB 설계 시 어떤 테이블이 필요한지, API 응답에서 뭘 저장해야 하는지 파악할 때

Bootpay ↔ 가맹점 모델 매핑

Bootpay API 사용 시 데이터를 가맹점 DB에 동기화해요. Receipt는 orders 테이블에 포함​​시키면 돼요.

흐름 Receipt / 결제 영수증 -> orders / 주문 + 결제 정보 : 검증 API Order / 주문 -> orders / 주문 + 결제 정보 : 조회 API / 웹훅 OrderSubscription / 구독 계약 -> subscriptions / 구독 기록 : 구독 API / 웹훅 BillingKey / 빌링키 -> billing_keys / 저장 결제수단 : 조회 API

노드

API별 데이터 책임 경계

사용하는 API에 따라 데이터 책임 범위가 달라져요.

결제 API — 데이터 책임 경계 {#payment-api}

결제 API는 결제 트랜잭션만 Bootpay가 처리해요. 주문, 구독, 이행 등 비즈니스 로직은 가맹점이 직접 구현해요.

가맹점이 직접 관리

Bootpay가 관리 → 가맹점이 동기화

Bootpay만 관리

주문 테이블에 추가할 결제 필드

결제 API만 사용하는 경우, 자체 주문 시스템이 이미 있을 가능성이 높아요. 기존 주문 테이블에 아래 결제 필드만 추가하면 돼요.

-- 기존 주문 테이블에 결제 필드 추가
ALTER TABLE orders
    ADD COLUMN bootpay_receipt_id VARCHAR(100),  -- Bootpay 영수증 ID (검증·취소용)
    ADD COLUMN amount          INTEGER,          -- 결제 금액
    ADD COLUMN method          VARCHAR(20),      -- card, bank, phone 등
    ADD COLUMN paid_at         DATETIME,
    ADD INDEX idx_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),
    bootpay_receipt_id VARCHAR(100),           -- Bootpay 영수증 ID
    amount          INTEGER NOT NULL,
    method          VARCHAR(20),
    status          VARCHAR(20) DEFAULT 'pending',  -- pending → paid → refunded
    paid_at         DATETIME,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_user (user_id),
    INDEX idx_order (order_id),
    INDEX idx_receipt (bootpay_receipt_id)
);sql

저장 시점​: 결제 검증 성공 후 — 이후 상태 변경(취소, 환불)은 웹훅으로 동기화

// 결제 검증 성공 → 주문에 결제 정보 업데이트
if (receipt.status === 1 && receipt.price === expectedPrice) {
    await db.orders.update({
        bootpay_receipt_id: receipt.receipt_id,
        amount: receipt.price,
        method: receipt.method_symbol,  // "card", "bank", "phone"
        status: 'paid',
        paid_at: new Date(receipt.purchased_at)
    }, { where: { order_id: orderId } })
}javascript

결제 검증 응답에서 저장할 필드

커머스 API — 데이터 책임 경계 {#commerce-api}

커머스 API는 주문 · 구독 · 이행까지 Bootpay가 관리해요. 가맹점은 상품과 회원만 관리하면 돼요.

가맹점이 직접 관리

Bootpay가 관리 → 가맹점이 동기화

Bootpay만 관리

Bootpay 내부 모델 구조

커머스 API가 내부적으로 관리하는 데이터 모델이에요. 가맹점이 직접 접근하지는 않지만, API 응답과 웹훅 데이터가 이 구조를 따르므로 이해해두면 연동이 수월해요.

Project (가맹점 프로젝트)
├── User (고객, 개인정보 암호화)
│   └── UserWallet (저장 결제수단, 빌링키)
│
├── Product (상품)
│   ├── ProductOption (옵션: 색상, 사이즈 등)
│   ├── ProductSnapshot (주문 시점 가격 고정)
│   └── SubscriptionSetting (구독 정책: 주기, 재시도, 해지)
│
├── OrderPre (결제 전 임시 주문)
│   └── Order (결제 완료 확정 주문)
│       ├── OrderPurchase (판매자별 이행/배송 단위)
│       └── OrderCancellationRequestHistory (취소/환불 이력)
│
├── OrderSubscription (구독 계약)
│   └── OrderSubscriptionBill (회차별 과금)
│       └── OrderSubscriptionTransaction (결제 실행)
│
└── WebhookJob → WebhookLog (이벤트 발송/이력)

도메인별 상세

주문 영역

구독 영역

고객 영역

최소 DB 스키마

주문 + 결제

CREATE TABLE orders (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id         BIGINT NOT NULL,
    bootpay_order_id    VARCHAR(100),     -- Bootpay 주문 ID
    bootpay_order_number VARCHAR(100),    -- Bootpay 주문 번호
    order_name      VARCHAR(200),
    total_amount    INTEGER NOT NULL,
    status          VARCHAR(20) DEFAULT 'pending',
    -- pending → paid → confirmed → completed → refunded
    paid_at         DATETIME,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_user (user_id),
    INDEX idx_bootpay_order (bootpay_order_id)
);

CREATE TABLE order_items (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    order_id        BIGINT NOT NULL,
    product_id      BIGINT NOT NULL,      -- 가맹점 상품 ID
    product_name    VARCHAR(200),
    quantity        INTEGER DEFAULT 1,
    unit_price      INTEGER NOT NULL,

    FOREIGN KEY (order_id) REFERENCES orders(id)
);sql

저장 시점​:

1. 주문서 요청 전 → orders 레코드 생성 (status: pending)
2. 서버 검증 성공 후 → status를 paid로 변경, bootpay_order_id 저장
3. 웹훅 order.cancelled 수신 → status를 refunded로 변경

주문 + 이행/배송 관리

물리적 배송이 있는 쇼핑몰이라면 이행(Fulfillment) 상태를 추적하는 테이블을 추가해요.

CREATE TABLE order_fulfillments (
    id                  BIGINT PRIMARY KEY AUTO_INCREMENT,
    order_id            BIGINT NOT NULL,
    bootpay_order_number VARCHAR(100) NOT NULL,   -- Bootpay 주문 번호
    progress_status     VARCHAR(20) DEFAULT 'ready',
    -- ready → confirmed → preparing → shipped → delivered
    confirmed_at        DATETIME,                 -- 발주 확인
    shipped_at          DATETIME,                 -- 배송 시작
    delivered_at        DATETIME,                 -- 배송 완료
    delivery_company    VARCHAR(50),              -- 택배사명
    tracking_number     VARCHAR(100),             -- 운송장 번호

    FOREIGN KEY (order_id) REFERENCES orders(id),
    INDEX idx_order (order_id),
    INDEX idx_status (progress_status)
);sql

Bootpay 이행 상태와의 매핑​:

구독 결제

CREATE TABLE subscriptions (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id         BIGINT NOT NULL,
    bootpay_subscription_id VARCHAR(100) NOT NULL,  -- Bootpay 구독 ID
    plan_name       VARCHAR(100),         -- "Pro", "Enterprise" 등
    amount          INTEGER NOT NULL,     -- 회차 결제 금액
    service_active  BOOLEAN DEFAULT FALSE,-- 서비스 접근 허용 여부
    status          VARCHAR(20) DEFAULT 'pending',
    -- pending → active → paused → terminated
    current_period_end DATETIME,          -- 현재 구독 기간 종료일
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_user (user_id),
    INDEX idx_bootpay_sub (bootpay_subscription_id)
);sql

저장 시점​:

1. 구독 신청 시 → subscriptions 레코드 생성 (status: pending)
2. 웹훅 subscription.approved → service_active = true, status: active
3. 웹훅 subscription.terminated → service_active = false, status: terminated

주문 조회 응답에서 저장할 필드

저장하면 안 되는 것

데이터 흐름 상세

결제 API — Receipt → orders

참여자: 가맹점 DB | 서버 | BOOTPAY

필드 매핑

커머스 API — Order → orders

참여자: 가맹점 DB | 서버 | BOOTPAY

필드 매핑

주문 상태 코드

상태

전이 -> 주문 생성 (0) : 주문서 생성 주문 생성 (0) -> 결제 진행 (1) : 결제 시작 결제 진행 (1) -> 결제 완료 (2) : 결제 성공 결제 완료 (2) -> 취소 요청 (3) : 취소 요청 취소 요청 (3) -> 취소 완료 (4) : 취소 승인

커머스 API — OrderSubscription → subscriptions

참여자: 가맹점 DB | 서버 | BOOTPAY

필드 매핑

구독 상태 코드

상태

전이 -> 대기 (0) : 주문서 결제 대기 (0) -> 구독 중 (1) : 승인 구독 중 (1) -> 일시정지 (2) : 정지 요청 일시정지 (2) -> 구독 중 (1) : 재개 구독 중 (1) -> 해지 (3) : 해지 구독 중 (1) -> 만료 (4) : 기간 만료

빌링 — BillingKey → billing_keys

참여자: 가맹점 DB | 서버 | BOOTPAY

필드 매핑

Bootpay 내부 모델 구조

커머스 API가 내부적으로 관리하는 모델의 관계예요. 가맹점이 직접 접근하지는 않지만, API 응답과 웹훅이 이 구조를 따르므로 이해해두면 연동이 수월해요.

흐름 Product / 상품 -> Order / 주문 : 주문서 결제 Product / 상품 -> OrderSubscription / 구독 계약 : 구독 상품 Order / 주문 -> Receipt / 결제 영수증 : 결제 Order / 주문 -> OrderPurchase / 이행·배송 : 이행 OrderSubscription / 구독 계약 -> SubscriptionBill / 회차 과금 : 매 회차

노드