결제 흐름

결제 요청부터 승인, 검증, 웹훅 처리까지 전체 시퀀스를 이해해요.

개별 API 사용법은 결제 요청, 결제 결과 수신, 결제 조회에서 확인해요. 이 문서는 전체 흐름을 한눈에 보여줘요.

인증 vs 승인 — 핵심 구분

PG 결제는 보통 인증​​과 승인 구간을 나눠서 보면 이해하기 쉬워요. PG·결제수단마다 화면과 이벤트 이름은 다르지만, 운영에서는 “아직 돈이 빠지지 않은 승인 전 상태인지”와 “승인이 끝난 결제 완료 상태인지”를 구분해야 CS가 꼬이지 않아요.

분리 승인(extra.separately_confirmed: true)을 쓰면 결제 상태는 4(결제진행중) → 2(입금/승인대기) → 1(결제완료) 순서로 전이돼요. 2 에서 멈춰 있다면 아직 서버 승인 API가 호출되지 않은 상태예요.

두 가지 승인 방식

서버 승인 흐름 (권장)

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

핵심 포인트

1. PG 승인 전에 서버 로직 실행 — onConfirm 시점에서 재고 확인, 쿠폰 차감 등을 처리한 뒤 승인 API를 호출해야 해요
2. 클라이언트에 onDone 없음 — 서버가 승인하므로 클라이언트는 결제 결과를 직접 받지 못해요. 결과 페이지에서 서버 DB를 polling해야 해요
3. 정합성 관리가 쉬움 — 재고 차감과 결제 승인을 서버 흐름 안에서 묶어 처리하므로, 클라이언트 승인 방식보다 주문 정합성을 맞추기 쉬워요

단계별 상세

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

extra.separately_confirmed: true로 결제창을 열어요.

const response = await Bootpay.requestPayment({
    client_key: '[ Client Key ]',
    price: 1000,
    order_name: '상품명',
    order_id: 'order_' + Date.now(), // 테스트용. 실제로는 서버에서 생성한 주문번호 사용
    extra: {
        separately_confirmed: true
    }
})javascript

2단계: 서버 승인 (가맹점 서버)

onConfirm에서 받은 receipt_id를 서버로 전달해야 해요. 서버는 비즈니스 로직을 처리한 뒤 Bootpay 승인 API를 호출해야 해요.

const confirmed = await Bootpay.confirmPayment(receipt_id)

await db.orders.update({
    status: 'done',
    bootpay_receipt_id: receipt_id,
    paid_amount: confirmed.price
}, { where: { id: order_id } })javascript

confirmed = bootpay.confirm_payment(receipt_id)

order.update(
    status='done',
    bootpay_receipt_id=receipt_id,
    paid_amount=confirmed['price'],
)python

$confirmed = BootpayApi::confirmPayment($receiptId);

$order->update([
    'status' => 'done',
    'bootpay_receipt_id' => $receiptId,
    'paid_amount' => $confirmed['price'],
]);php

var confirmed = bootpay.confirm(receiptId);

order.setStatus("done");
order.setBootpayReceiptId(receiptId);
order.setPaidAmount(((Number) confirmed.get("price")).doubleValue());
orderRepository.save(order);java

confirmed = bootpay.confirm(receipt_id).data

order.update(
  status: 'done',
  bootpay_receipt_id: receipt_id,
  paid_amount: confirmed['price']
)ruby

confirmed, err := api.ServerConfirm(receiptId)
if err != nil {
    return err
}

markOrderDone(orderId, receiptId, confirmed["price"])go

var response = await bootpay.Confirm(receiptId);
var confirmed = JsonConvert.DeserializeObject<Dictionary<string, object>>(
    await response.Content.ReadAsStringAsync()
);

order.Status = "done";
order.BootpayReceiptId = receiptId;
order.PaidAmount = Convert.ToDecimal(confirmed["price"]);
await orderRepository.SaveAsync(order);csharp

승인 API 호출에서 자주 만나는 응답이에요.

전체 코드 목록은 오류 코드에서 확인해요.

3단계: 결과 표시 (프론트엔드)

결과 페이지에서 서버에 주문 상태를 조회해야 해요.

// 결과 페이지에서 polling
const checkResult = async (orderId) => {
    const res = await fetch(`/api/orders/${orderId}/status`)
    const data = await res.json()

    if (data.status === 'done') {
        // 결제 완료 표시
    } else {
        // 아직 처리 중 — 재조회
        setTimeout(() => checkResult(orderId), 1000)
    }
}javascript

클라이언트 승인 흐름

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

핵심 포인트

1. SDK가 자동 승인 — 별도 설정 없이 PG 결제가 완료되면 SDK가 바로 승인해요
2. done 이후 서버 검증 필요 — 프론트엔드에서 받은 receipt_id를 백엔드로 전달하여 결제 조회을 수행해야 해요
3. 이벤트 누락에 대비 — 네트워크 문제, 앱 종료 등으로 done 처리가 누락될 수 있으므로 웹훅을 함께 운영해야 해요

웹훅으로 이벤트 누락 보완

[정상]  프론트엔드 onDone → 백엔드 검증 → DB 저장
[누락]  부트페이 웹훅(PAYMENT_COMPLETED) → 서버 검증 → DB 저장

웹훅 본문에는 결제 조회 응답과 같은 필드에 더해 아래 값이 들어와요.

webhook_type 값은 다음과 같아요.