> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 일회성 결제 받기

> iOS 앱에서 실물 상품과 오프라인 서비스에 대한 일회성 Apple Pay 결제를 받으세요.

[Whop으로 iOS에서 일회성 결제 받기](https://www.youtube.com/embed/K2e_sht1P1I?rel=0)

`Checkout.ApplePayButton`을 사용해 Apple Pay로 실물 상품이나 오프라인 서비스에 대한 일회성 결제를 받으세요. Whop은 Apple의 15–30% 인앱 구매 수수료 대신 **2.7% + \$0.30**으로 결제를 처리합니다.

> [!TIP]
>
> 웹 판매에는 [체크아웃 링크 또는 Checkout 요소](https://docs.whop.com/ko/developer/guides/accept-payments.md)를 사용해 **195개국**에서 **100가지 이상의 결제 수단**을 지원하세요.

> [!WARNING]
>
> **Apple Pay는 디지털 콘텐츠용이 아닙니다.** 앱이 실물 상품(굿즈, 음식, 하드웨어)이나 오프라인 서비스(이벤트 티켓, 배달)를 판매하는 경우에만 `Checkout.ApplePayButton`을 사용하세요. 프리미엄 기능, 구독, 인앱 화폐, 콘텐츠 잠금 해제 같은 디지털 콘텐츠를 판매하는 앱은 StoreKit을 사용해야 합니다. 자세한 내용은 [Apple Pay 사용 자격](https://docs.whop.com/ko/developer/guides/ios/checkout-reference.md#apple-pay-eligibility) 섹션을 참고하세요.

## 만들 것

* 네이티브 Apple Pay 버튼이 있는 상품 상세 화면
* 성공, 실패, 취소를 처리하는 구매 흐름
* 실물 상품을 위한 Whop 대시보드의 변형 구성

## 사전 요구 사항

* [WhopCheckout SDK 설치하기](https://docs.whop.com/ko/developer/guides/ios/installation.md)
* `iap:read` 범위의 API 키. [API 키 만들기](https://docs.whop.com/ko/developer/guides/ios/installation.md#step-3-create-an-api-key)를 참고하세요
* 일회성 변형이 있는 Whop 상품([5단계](#step-5-set-up-your-variant) 참고)

## 1단계: SDK 구성하기

앱 실행 시 SDK를 초기화하세요. 일회성 실물 상품에는 호환성 속성 `planMappings`가 필요하지 않습니다. 이 속성은 구독에서 StoreKit으로 대체할 때만 사용됩니다.

```swift theme={null}
import SwiftUI
import WhopCheckout

@main
struct DropsApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(Checkout.shared)
                .task {
                    try? await Checkout.shared.configure(
                        // companyId: find in Dashboard URL (starts with biz_)
                        companyId: "biz_xxxxxxxxxxxxxx",
                        // apiKey: create in Dashboard > Developer with iap:read permission
                        apiKey: "your_api_key_here"
                    )
                }
        }
    }
}
```

전체 설정과 API 키 보안 참고 사항은 [설치 가이드](https://docs.whop.com/ko/developer/guides/ios/installation.md)를 참고하세요.

## 2단계: `Apple Pay` 버튼 추가하기

상품 뷰에 `Checkout.ApplePayButton`을 넣으세요. 이 컴포넌트는 Human Interface Guidelines를 준수하는 Apple의 공식 Apple Pay 버튼을 렌더링하며, 사용자 지정 스타일 버튼으로 대체할 수 없습니다.

```swift theme={null}
import SwiftUI
import WhopCheckout

struct ProductDetailView: View {
    let product: MerchItem
    @State private var purchaseComplete = false

    var body: some View {
        ScrollView {
            // product image, title, price, size picker...

            Checkout.ApplePayButton(
                // planId: find in Dashboard > Products > [product] > Variants
                planId: product.planId,
                label: .buy,
                onCompletion: { result in
                    switch result {
                    case .success(let purchase):
                        // purchase.receiptId, purchase.membership
                        purchaseComplete = true
                    case .failure(let error):
                        print("Purchase failed: \(error.localizedDescription)")
                    }
                }
            )
            .frame(height: 48)
            .padding(.horizontal)
        }
    }
}
```

사용자가 탭하면 네이티브 Apple Pay 시트가 표시됩니다. Face ID 또는 더블 클릭으로 확인하면 결제가 Whop을 통해 처리됩니다.

> [!NOTE]
>
> 사용자가 취소하면 `onCompletion`은 **호출되지 않으며** 시트만 닫힙니다. 정리 작업은 필요하지 않습니다.

## 3단계: 버튼 레이블 선택하기

`label` 매개변수는 버튼의 텍스트를 제어합니다. 동작에 맞는 것을 선택하세요:

| 레이블 | 버튼 텍스트 | 용도 |
| - | - | - |
| `.buy` | Buy with Apple Pay | 일회성 굿즈 및 실물 상품 |
| `.checkout` | Check out with… | 장바구니 방식의 체크아웃 흐름 |
| `.order` | Order with Apple Pay | 음식, 배달, 주문 제작 상품 |
| `.book` | Book with Apple Pay | 예약, 약속, 이벤트 |
| `.continue` | Continue with… | 이 단계가 마지막이 아닌 다단계 흐름 |
| `.plain` | (Apple Pay 로고) | 적합한 동사가 없을 때의 대체 |

전체 목록은 Apple의 `PayWithApplePayButtonLabel`에서 가져옵니다. 모든 옵션은 [Apple 문서](https://developer.apple.com/documentation/passkit/paywithapplepaybuttonlabel)를 참고하세요.

## 4단계: 구매 결과 처리하기

`onCompletion`은 `Result<CheckoutPurchaseResult, Error>`를 받습니다. 성공하면 다음을 반환받습니다:

| 속성 | 타입 | 설명 |
| - | - | - |
| `receiptId` | `String` | 이 구매의 고유 영수증 ID |
| `membership` | `CheckoutMembership?` | Whop이 구매에 대해 생성한 멤버십 |

이를 사용해 확인 화면을 표시하거나, 배송을 시작하거나, 자체 기록용으로 영수증을 저장하세요.

```swift theme={null}
onCompletion: { result in
    switch result {
    case .success(let purchase):
        // Persist the receipt for your fulfillment flow
        OrderStore.shared.record(
            receiptId: purchase.receiptId,
            membershipId: purchase.membership?.id,
            product: product
        )
        showConfirmation = true
    case .failure(let error):
        showError(error.localizedDescription)
    }
}
```

## 5단계: 변형 설정하기

구매 가능한 각 항목에는 Whop 대시보드의 변형이 필요합니다:

**1. 변형 만들기**

[대시보드](https://whop.com/dashboard) > Products > 상품 선택 > **Variants** > **Create variant**로 이동하세요.

**2. 일회성으로 설정하기**

**One-time payment**를 선택하고 가격을 설정하세요.

**3. (선택 사항) 재고 한도 설정하기**

한정 판매의 경우 재고 상한을 설정하세요. 체크아웃이 이를 자동으로 적용하며, 재고가 소진되면 구매가 중단됩니다.

**4. 변형 ID 복사하기**

ID는 `plan_` 접두사를 유지합니다. 호환성 매개변수 `Checkout.ApplePayButton(planId:)`를 통해 전달하세요.

## 웹훅으로 주문 처리하기

실물 상품의 경우 구매 성공 후 배송을 시작하려면 서버 측 웹훅이 필요합니다. `payment.succeeded` 이벤트를 수신하세요:

```typescript theme={null}
import { unwrapWebhook } from "@whop/sdk/helpers";

export async function POST(request: Request) {
  const body = await request.text();
  const headers = Object.fromEntries(request.headers);
  const event = unwrapWebhook(body, { headers, key: process.env.WHOP_WEBHOOK_SECRET });

  if (event.type === "payment.succeeded") {
    // Trigger your shipping/fulfillment flow
    await fulfillOrder(event.data);
  }

  return new Response("OK", { status: 200 });
}
```

> [!NOTE]
>
> 클라이언트 측 `onCompletion` 콜백은 사용자에게 결제를 확인해 주지만, 주문 처리는 **서버**가 웹훅으로 처리해야 합니다. 클라이언트에만 의존하지 마세요. 설정 방법은 전체 [웹훅 가이드](https://docs.whop.com/ko/developer/guides/webhooks.md)를 참고하세요.

## 전체 예제

사이즈 선택과 Apple Pay가 있는 최소한의 굿즈 상세 뷰:

```swift theme={null}
import SwiftUI
import WhopCheckout

struct ProductDetailView: View {
    let product: MerchItem
    @State private var selectedSize: String?
    @State private var showConfirmation = false

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 16) {
                AsyncImage(url: product.imageURL) { image in
                    image.resizable().scaledToFit()
                } placeholder: {
                    Color.gray.opacity(0.1)
                }
                .frame(maxWidth: .infinity)

                Text(product.title)
                    .font(.title)
                    .bold()

                Text(product.price, format: .currency(code: "USD"))
                    .font(.title2)

                // Size picker
                HStack {
                    ForEach(product.sizes, id: \.self) { size in
                        Button(size) {
                            selectedSize = size
                        }
                        .buttonStyle(.bordered)
                        .tint(selectedSize == size ? .accentColor : .secondary)
                    }
                }

                Checkout.ApplePayButton(
                    planId: product.planId,
                    label: .buy,
                    onCompletion: { result in
                        switch result {
                        case .success(let purchase):
                            print("Receipt: \(purchase.receiptId)")
                            showConfirmation = true
                        case .failure(let error):
                            print("Purchase failed: \(error.localizedDescription)")
                        }
                    }
                )
                .frame(height: 48)
                .disabled(selectedSize == nil)
            }
            .padding()
        }
        .sheet(isPresented: $showConfirmation) {
            OrderConfirmationView(product: product, size: selectedSize ?? "")
        }
    }
}
```

## 다음 단계

> [card] [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 결제 이벤트를 처리하고 주문 처리를 시작하세요

> [card] [Apple Pay 사용 자격](https://docs.whop.com/ko/developer/guides/ios/checkout-reference.md#apple-pay-eligibility)
>
> 앱이 App Store 심사 지침에 따라 자격을 갖추었는지 확인하세요

> [card] [페이월 만들기](https://docs.whop.com/ko/developer/guides/ios/build-a-paywall.md)
>
> 일회성 구매 대신 구독을 판매하세요

> [card] [API 레퍼런스](https://docs.whop.com/ko/developer/guides/ios/checkout-reference.md)
>
> 전체 SDK 문서
