주문 흐름

주문 생성부터 결제, 검증, 웹훅 처리까지 전체 시퀀스를 이해해요.

개별 API 사용법은 주문서 요청, 결제 검증에서 확인해요. 이 문서는 전체 흐름을 한눈에 보여줘요.

전체 시퀀스

참여자: 고객 | 가맹점 프론트 | 가맹점 서버 | Bootpay | PG사

Bootpay 내부 주문 3단계

Bootpay는 내부적으로 주문을 3단계 모델​​로 관리해요. API 응답과 웹훅 데이터를 이해하는 데 도움이 돼요.

흐름 OrderPre / 결제 전 임시 -> Order / 결제 확정 : 결제 완료 Order / 결제 확정 -> OrderPurchase / 이행/배송 : 판매자별 분리

노드

• OrderPre: 결제위젯이 열리기 전 생성되는 임시 주문. 제한 시간(기본 31분) 내에 결제하지 않으면 자동 만료돼요.
• Order: 결제가 완료되면 OrderPre가 Order로 확정돼요. 이 시점부터 order_id, order_number가 발급돼요.
• OrderPurchase: 판매자(셀러)별 이행 단위예요. 멀티셀러 쇼핑몰이면 하나의 Order에 여러 OrderPurchase가 생길 수 있어요.

Bootpay 주문 상태코드 참조

가맹점은 아래 상태코드를 직접 관리할 필요 없지만, API 응답의 status 필드가 이 값을 따라요.

단계별 상세

1단계: 주문 예비 생성 (가맹점 서버)

결제 전에 가맹점 DB에 주문을 먼저 만들어요.

// POST /api/orders — 가맹점 자체 API
app.post('/api/orders', async (req, res) => {
    const { user_id, products } = req.body

    // 가격은 반드시 백엔드에서 계산 (프론트엔드 금액을 믿지 않음)
    const totalPrice = await calculatePrice(products)

    const order = await db.orders.create({
        user_id,
        total_amount: totalPrice,
        status: 'pending',    // 아직 결제 전
        items: products
    })

    res.json({
        order_id: order.id,
        price: totalPrice,
        order_name: formatOrderName(products)
    })
})javascript

2단계: 결제 요청 (프론트엔드)

서버에서 받은 정보로 결제위젯 또는 체크아웃을 호출해요.

// 결제위젯 방식
Bootpay.requestPayment({
    client_key: 'APPLICATION_ID',
    price: orderData.price,           // 서버에서 받은 금액
    order_name: orderData.order_name,
    order_id: String(orderData.order_id),  // 가맹점 주문 ID
    pg: '나이스페이',
    method: '카드',
    user: { id: userId, username: userName }
})
.then(response => {
    // 3단계: 서버로 검증 요청
    verifyPayment(response.receipt_id, orderData.order_id)
})
.catch(error => {
    console.error('결제 실패:', error)
})javascript

3단계: 결제 검증 (가맹점 서버)

가장 중요한 단계​​예요. 프론트엔드 결과만 믿으면 안 돼요.

app.post('/api/orders/verify', async (req, res) => {
    const { receipt_id, order_id } = req.body

    // 가맹점 DB에서 주문 조회
    const order = await db.orders.findByPk(order_id)
    if (!order) return res.status(404).json({ error: '주문을 찾을 수 없음' })

    // Bootpay에서 결제 정보 조회
    const receipt = await Bootpay.receiptPayment(receipt_id)

    // 검증: 상태 + 금액
    if (receipt.status === 1 && receipt.price === order.total_amount) {
        // ✅ 검증 성공 → DB 업데이트
        await db.orders.update(
            {
                status: 'paid',
                bootpay_receipt_id: receipt_id,
                paid_at: new Date()
            },
            { where: { id: order_id } }
        )
        res.json({ success: true })
    } else {
        // ❌ 검증 실패 → 결제 취소
        await Bootpay.cancelPayment({
            receipt_id,
            cancel_price: receipt.price,
            cancel_reason: '금액 위변조 의심'
        })
        res.json({ success: false, message: '검증 실패' })
    }
})javascript

4단계: 웹훅 수신 (비동기 후처리)

결제 검증과 별개로, Bootpay가 웹훅을 발송해요. 후처리 로직에 활용해요.

// 웹훅 수신 후 처리 (상세: /webhook/guide)
app.post('/webhooks/bootpay', async (req, res) => {
    res.status(200).json({ success: true })  // 즉시 200 반환

    const { event, data } = req.body
    if (event === 'order.done') {
        // 이메일 발송, 재고 차감, 포인트 적립 등
        await sendOrderConfirmEmail(data.order_number)
        await decrementStock(data.order_number)
    }
})javascript

주문 상태 관리

가맹점 DB의 주문 상태는 아래 흐름을 따른다:

상태

전이 -> pending pending -> paid paid -> confirmed confirmed -> completed paid -> refunded : 환불 pending -> expired : 결제 안 함

취소/환불 흐름

주문 취소는 전체 취소​​와 부분 취소​(금액 또는 상품 단위)로 나뉘어요.

전체 취소 vs 부분 취소

취소 요청 → 승인 → 완료 흐름

참여자: 가맹점 서버 | Bootpay

취소 완료 웹훅 처리

// 웹훅 수신: order.cancelled
async function handleOrderCancelled(data) {
    const { order_number, cancel_price, remain_price } = data

    // 1. 주문 상태 업데이트
    if (remain_price === 0) {
        // 전체 취소
        await db.orders.update(
            { status: 'refunded' },
            { where: { bootpay_order_number: order_number } }
        )
    } else {
        // 부분 취소 — 잔액이 남아있으면 주문은 유지
        await db.orders.update(
            { total_amount: remain_price, status: 'partially_refunded' },
            { where: { bootpay_order_number: order_number } }
        )
    }

    // 2. 재고 복구 (전체 취소 시)
    // 3. 환불 안내 이메일
}javascript

이행(Fulfillment) 흐름

물리적 배송이 있는 커머스에서는 결제 완료 후 이행 단계​​를 관리해야 해요.

이행 상태 흐름

흐름 ready / (발주대기) -> confirmed / (발주확인) confirmed / (발주확인) -> shipped / (배송중) shipped / (배송중) -> delivered / (배송완료)

노드

배송 정보 연동 패턴

// 발주 확인 + 배송 등록 (가맹점 서버에서)
async function shipOrder(orderNumber, trackingInfo) {
    // Bootpay에 배송 정보 전달
    await Bootpay.updateOrderPurchase(orderNumber, {
        delivery_company_code: trackingInfo.company_code,  // 택배사 코드
        tracking_number: trackingInfo.tracking_number       // 운송장 번호
    })

    // 가맹점 DB 업데이트
    await db.order_fulfillments.update(
        {
            progress_status: 'shipped',
            shipped_at: new Date(),
            delivery_company: trackingInfo.company_name,
            tracking_number: trackingInfo.tracking_number
        },
        { where: { bootpay_order_number: orderNumber } }
    )
}javascript

흔한 실수

1검증 없이 프론트엔드 결과만 믿기

// ❌ 절대 하면 안 됨
Bootpay.requestPayment({ ... })
.then(response => {
    // 프론트엔드 결과만으로 주문 완료 처리
    db.orders.update({ status: 'paid' })  // 위험!
})javascript

프론트엔드 응답은 위변조가 가능해요. 반드시 백엔드에서 결제 검증을 수행해요.

2웹훅에만 의존하기

// ❌ 위험 — 웹훅이 지연되면 고객이 결제했는데 서비스를 못 씀
// 웹훅만으로 주문 완료 처리javascript

동기 검증(3단계)​​이 메인 흐름이고, 웹훅은 보조 수단​(이메일, 재고 등 후처리)예요.

3가격을 프론트엔드에서 계산

// ❌ 위험 — 프론트엔드에서 할인 적용
const price = product.price * 0.8  // 20% 할인
Bootpay.requestPayment({ price })  // 변조 가능javascript

가격 계산은 반드시 서버에서 수행하고, 결제 검증 시 서버의 가격과 비교해요.