--- title: "PortOne 결제 플로우 (Go makitt-payment 서비스)" --- sequenceDiagram actor Customer participant Client as Client
(standard-checkout) participant ShopAPI as Shop API
(makitt-shop-api) participant PaySvc as Payment Service
(makitt-payment, Go) participant PortOne as PortOne Note over Customer, PortOne: 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->>PaySvc: POST /payments/prepare-for-order/{orderId} PaySvc->>PaySvc: resolveChannel(channelId)
→ storeId, channelKey 결정 PaySvc->>PaySvc: Payment 생성, nextActionData 구성 alt 일반 결제 (CARD, BANK_TRANSFER, EASY_PAY 등) PaySvc->>PaySvc: actionData = { storeId, channelKey,
paymentId, payMethod, easyPay?, ... } else PORTONE_PAYPAL_SPB PaySvc->>PaySvc: actionData = { uiType: PAYPAL_SPB, storeId, channelKey, ... } else PORTONE_IDENTITY_VERIFICATION PaySvc->>PaySvc: actionData = { uiType: IDENTITY_VERIFICATION, ... } else PORTONE_ISSUE_BILLING_KEY PaySvc->>PaySvc: actionData = { uiType: ISSUE_BILLING_KEY, ... } end Note right of PaySvc: Payment: ACTION_REQUIRED
nextActionType: CLIENT_SDK PaySvc-->>ShopAPI: PaymentSessionResponse ShopAPI->>ShopAPI: checkout.startPayment() Note right of ShopAPI: Checkout: DONE ShopAPI-->>Client: PaymentSessionResponse Note over Customer, PortOne: Phase 2: 결제 진행 (PortOne SDK) Client->>Client: orchestrator: storeId+channelKey 감지 Client->>Client: launchPortOnePaymentWindow()
packages/payments/src/portone/usePortOnePayment.ts Client->>PortOne: @portone/browser-sdk/v2
.requestPayment({
storeId, channelKey, paymentId,
totalAmount, currency, payMethod,
customer, redirectUrl
}) PortOne->>Customer: PG 결제창 표시
(카카오페이/네이버페이/카드/계좌이체 등) Customer->>PortOne: 결제 인증 & 완료 PortOne->>Client: redirect → redirectUrl 또는 SDK callback Note over Customer, PortOne: Phase 3: Reconcile + Confirm Client->>ShopAPI: POST /payments/{paymentId}/reconcile ShopAPI->>PaySvc: POST /payments/{paymentId}/reconcile PaySvc->>PortOne: GET /payments/{paymentId} PortOne-->>PaySvc: { status: "PAID" } PaySvc->>PaySvc: status 매핑: PAID → CAPTURED Note right of PaySvc: Payment: CAPTURED
Order: PAID
Checkout: COMPLETED PaySvc-->>ShopAPI: PaymentSessionResponse ShopAPI-->>Client: 결제 완료 Note over Customer, PortOne: Phase 3b: Webhook (비동기, 최소 구현) PortOne--)PaySvc: { type: "paid", paymentId } PaySvc->>PaySvc: Payment: CAPTURED (멱등) Note right of PortOne: 지원 이벤트:
paid/succeeded → CAPTURED
failed → FAILED
cancel → CANCELED