--- title: "PayPal 결제 플로우 (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 PayPal as PayPal Note over Customer, PayPal: 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->>PayPal: POST /v2/checkout/orders
{ intent: CAPTURE, purchase_units, payment_source } PayPal-->>PaySvc: { id: orderId, status, links[] } alt PAYPAL_HOSTED_CHECKOUT PaySvc->>PaySvc: approve link 추출 → redirectUrl Note right of PaySvc: Payment: ACTION_REQUIRED
nextActionType: REDIRECT else PAYPAL_BUTTONS / PAYPAL_CARD_FIELDS PaySvc->>PaySvc: actionData = { orderId, clientId, intent, productType } Note right of PaySvc: Payment: ACTION_REQUIRED
nextActionType: CLIENT_SDK end opt PAYPAL_CARD_FIELDS PaySvc->>PayPal: POST /v1/identity/generate-token PayPal-->>PaySvc: { clientToken } end PaySvc-->>ShopAPI: PaymentSessionResponse ShopAPI->>ShopAPI: checkout.startPayment() Note right of ShopAPI: Checkout: DONE ShopAPI-->>Client: PaymentSessionResponse Note over Customer, PayPal: Phase 2: 결제 진행 alt Hosted Checkout (Redirect) Client->>PayPal: window.location.href = redirectUrl PayPal->>Customer: PayPal Hosted Page Customer->>PayPal: 로그인 & 결제 승인 PayPal->>Client: redirect → returnUrl else Buttons (Client SDK) Client->>Client: paypal.Buttons({ onApprove }) Client->>Customer: PayPal 버튼 표시 Customer->>PayPal: 버튼 클릭 → PayPal 팝업 Customer->>PayPal: 결제 승인 PayPal->>Client: onApprove({ orderID }) else Card Fields (Client SDK) Client->>Client: paypal.CardFields({ onApprove }) Client->>Customer: 카드 입력 폼 표시 Customer->>Client: 카드 정보 입력 & 제출 Client->>PayPal: tokenize & submit PayPal->>Client: onApprove({ orderID }) end Note over Customer, PayPal: Phase 3: Reconcile + Capture Client->>ShopAPI: POST /payments/{paymentId}/reconcile ShopAPI->>PaySvc: POST /payments/{paymentId}/reconcile PaySvc->>PayPal: GET /v2/checkout/orders/{orderId} PayPal-->>PaySvc: { status: "APPROVED" } PaySvc->>PayPal: POST /v2/checkout/orders/{orderId}/capture PayPal-->>PaySvc: { status: "COMPLETED", captureId } PaySvc->>PaySvc: Payment: CAPTURED
processorRefs: { orderId, captureId } Note right of PaySvc: Payment: CAPTURED
Order: PAID
Checkout: COMPLETED PaySvc-->>ShopAPI: PaymentSessionResponse ShopAPI-->>Client: 결제 완료 Note over Customer, PayPal: Phase 3b: Webhook (비동기) PayPal--)PaySvc: PAYMENT.CAPTURE.COMPLETED PaySvc->>PaySvc: Payment: CAPTURED
(이미 처리됨 → 멱등) Note right of PayPal: 기타 웹훅:
CHECKOUT.ORDER.APPROVED
PAYMENT.CAPTURE.DENIED
PAYMENT.CAPTURE.REFUNDED
PAYMENT.AUTHORIZATION.CREATED
PAYMENT.AUTHORIZATION.VOIDED