--- title: "Toss Payments 결제 플로우 (SDK requestPayment → Redirect)" --- sequenceDiagram actor Customer participant Client as Client
(standard-checkout) participant ShopAPI as Shop API
(makitt-shop-api) participant PayAPI as Payment API
(makitt-payment-api) participant Toss as Toss Payments Note over Customer, Toss: Phase 1: 결제 준비 (Prepare) Customer->>Client: 결제 버튼 클릭 Client->>ShopAPI: POST /checkout/{id}/payments/prepare ShopAPI->>ShopAPI: checkoutApp.resolveOrderForPayment()
→ Order 생성/조회 Note right of ShopAPI: Order: PAYMENT_PENDING ShopAPI->>PayAPI: POST /payments/prepare-for-order/{orderId} PayAPI->>PayAPI: Payment 생성 PayAPI->>Toss: createPaymentWindow() Toss-->>PayAPI: { clientKey, orderId, method, ... } PayAPI->>PayAPI: Payment.attachProcessorReference() Note right of PayAPI: Payment: REQUIRES_ACTION
nextActionType: TOSS_PAYMENT_WINDOW PayAPI-->>ShopAPI: { nextActionType, nextActionData, paymentId } ShopAPI->>ShopAPI: checkout.startPayment() Note right of ShopAPI: Checkout: DONE ShopAPI-->>Client: PaymentSessionResponse Note over Customer, Toss: Phase 2: 결제 진행 (Toss SDK) Client->>Client: orchestrator: TOSS_PAYMENT_WINDOW 감지 Client->>Client: launchTossPaymentWindow()
packages/payments/src/toss/useTossPayment.ts Client->>Toss: TossPayments(clientKey).payment()
.requestPayment({ method, amount, orderId, ... }) Toss->>Customer: Toss 결제창 표시 (카드/계좌이체/간편결제) Customer->>Toss: 결제 수단 선택 & 인증 Toss->>Client: redirect → successUrl?paymentKey=xxx&orderId=xxx&amount=xxx Note over Customer, Toss: Phase 3: Reconcile + Confirm (Client-initiated) Client->>ShopAPI: POST /payments/{paymentId}/reconcile
{ processorPaymentId: paymentKey } ShopAPI->>PayAPI: POST /payments/{paymentId}/reconcile PayAPI->>Toss: POST /confirm
{ paymentKey, orderId, amount } Toss-->>PayAPI: { status: "DONE" } PayAPI->>PayAPI: Payment.markSucceeded()
Order.markOrderPaid()
Checkout.complete() Note right of PayAPI: Payment: SUCCEEDED
Order: PAID
Checkout: COMPLETED PayAPI-->>ShopAPI: PaymentSessionResponse ShopAPI-->>Client: 결제 완료 Note over Customer, Toss: Webhook: 현재 미구현 (Reconcile에 100% 의존)