> ## 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.

# Checkout

> Whop 체크아웃 세션 API를 기반으로 하나 이상의 플랜에 대한 전체 호스팅 체크아웃을 구동합니다. 항목별 가격 요약, 프로모션 코드, 구매자가 결제하는 통화, 그리고 전체 결제 수집 화면(내부에 구성된 결제 엘리먼트)을 포함합니다. `items`, 단일 `plan`, 또는 직접 작성한 `checkoutConfiguration`으로 마운트하면 엘리먼트가 체크아웃 세션을 직접 엽니다. 세션 자격 증명은 엘리먼트 밖으로 나가지 않습니다. 설정 모드 체크아웃 구성은 같은 엘리먼트를 결제 수단 저장용으로 마운트합니다. 아무것도 청구되지 않고, 나중에 청구할 수 있도록 구매자의 결제 수단이 저장되며, 완료된 체크아웃은 `setup_intent_id`와 함께 리디렉션됩니다. 구매자는 엘리먼트 안에서 결제하며, 완료된 체크아웃은 엘리먼트가 포함된 페이지를 포함해 현재 탭을 `returnUrl`로 리디렉션합니다. 주문 이행은 브라우저 콜백이 아니라 웹훅에서 처리하세요. `returnUrl`이 없으면 구매자는 엘리먼트 자체의 성공 화면에 머뭅니다. 엘리먼트는 3DS나 은행 페이지 같은 외부 결제 단계를 자동으로 진행합니다. whop.com에서는 구매자를 복원된 체크아웃으로 다시 데려오고, 임베드에서는 결과와 관계없이 `payment` 및 `status` 쿼리 매개변수(`succeeded`, `failed`, `canceled`)와 함께 같은 `returnUrl`로 돌아오므로, `returnUrl` 페이지는 방문을 판매로 처리하기 전에 `status`를 읽어야 합니다. 엘리먼트 안에서 실패한 결제는 이유를 표시한 채 같은 체크아웃을 다시 열어 구매자가 다시 결제할 수 있게 합니다. 모든 옵션은 생성 시 설정됩니다. 엘리먼트는 마운트될 때 이 값들로 체크아웃 세션을 생성합니다. 나중에 `update()`나 새 React props로 옵션을 변경하면 기존 주문이 변경되는 대신 실패합니다. 구매 대상을 변경하려면 새 체크아웃을 마운트하세요.

> [!NOTE]
>
> 이 페이지는 `@whop/elements@1.10.0` 및 `@whop/elements-react@1.10.0`을 다룹니다.

*`v1.0.0`부터 지원.*

## Playground

예시 데이터로 엘리먼트를 조합해 보세요. 컨트롤을 조작하고, 엘리먼트를 추가 및 배치하고, 이벤트가 실시간으로 발생하는 것을 확인할 수 있습니다:

```tsx React theme={null}
import { WhopElements, Checkout } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Checkout /* options */>
        {/* mount elements here */}
      </Checkout>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const checkout = window.WhopElements().checkout.create({ /* options */ });
</script>
```

## 옵션

다음 옵션을 `whop.checkout.create({ … })`에 전달하거나, React에서는 `<Checkout>`의 props로 전달합니다.

**plan** `string`

`plan_` 접두사가 붙은 기존 플랜 ID입니다. 이 플랜과 `quantity`를 포함하는 `items` 배열의 축약형입니다. 가격은 플랜이 정의하며, 금액은 클라이언트 측에서 지정할 수 없습니다. `plan`, `items`, `checkoutConfiguration` 중 하나를 전달하세요. 생성 시에만 설정할 수 있습니다. 세션이 이 값으로 생성되며, 나중에 변경하면 거부됩니다.

**quantity** `number`

구매할 수량입니다. 복수 구매를 허용하지 않는 플랜은 1보다 큰 값을 거부합니다. 생성 시에만 설정할 수 있습니다. 세션이 이 값으로 생성되며, 나중에 변경하면 거부됩니다. @default 1

**items** `CheckoutItemInput[]`

이 체크아웃의 플랜과 각 플랜의 구매 수량입니다. 모든 항목은 같은 판매자에 속하고 호환되는 청구 조건을 사용해야 합니다. API는 전체 장바구니를 검증하고 하나의 청구로 가격을 책정합니다. `plan`, `quantity`, `checkoutConfiguration` 대신 전달하세요. 생성 시에만 설정할 수 있습니다. 세션이 정확히 이 장바구니로 생성되며, 나중에 변경하면 거부됩니다.

**속성**

**plan** `string` *required*

`plan_` 접두사가 붙은 기존 플랜 ID입니다.

**quantity** `number`

구매할 수량입니다. 기본값은 1이며, 플랜에 따라 1보다 큰 수량을 허용하지 않을 수 있습니다.

**checkoutConfiguration** `string`

`ch_` 접두사가 붙은 기존 체크아웃 구성 ID입니다. 엘리먼트는 이 구성으로 체크아웃 세션을 생성합니다. 구성은 판매할 플랜을 지정하고(`setup` 모드에서는 플랜 없이 결제 수단만 저장하고 아무것도 청구하지 않음), 자체 제휴 코드, 메타데이터, 리디렉션, 결제 수단 사전 설정을 제공합니다. 여기서 함께 전달한 옵션은 필드별로 구성의 값보다 우선합니다. `plan`은 `quantity`를 설정할 때만 함께 전달하세요. 이 경우 구성 자체의 플랜이어야 하며, 사전 설정에서 플랜을 바꿀 수는 없습니다. 생성 시에만 설정할 수 있습니다.

**promoCode** `string`

구매자가 가격을 보기 전에 적용할 프로모션 코드입니다. 할인은 첫 견적에 반영되며, 구매자는 여전히 코드를 변경하거나 제거할 수 있습니다. 마케팅 링크에 포함된 코드를 전달하세요. 만료되었거나 유효하지 않은 코드는 체크아웃이 열리지 않게 하는 대신, 프로모션 행에 이유를 표시한 채 전체 가격으로 체크아웃을 엽니다. 생성 시에만 설정할 수 있습니다.

**affiliateCode** `string`

이 체크아웃이 귀속되는 제휴사입니다. 생성 시에만 설정할 수 있습니다.

**attribution** `CheckoutAttributionInput`

계정 보고용으로 이 판매의 유입 경로를 나타냅니다. 구매자가 도착한 링크의 캠페인 매개변수(`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`, `utm` 아래의 기타 `utm_*` 매개변수, Whop `trackingLinkId`, `funnelId`, 자체 `source`)입니다. 여기의 모든 값은 주문에 기록되며 구매자에게는 표시되지 않습니다. 생성 시에만 설정할 수 있습니다.

**속성**

**utmSource** `string`

**utmMedium** `string`

**utmCampaign** `string`

**utmTerm** `string`

**utmContent** `string`

**trackingLinkId** `string`

**funnelId** `string`

**source** `string`

**utm** `Record\<string, string\>`

링크에 포함된 기타 `utm_*` 매개변수로, 전체 이름을 키로 사용합니다(`{ utm_funnel: 'spring' }`). `utm_`으로 시작하지 않는 키는 무시되며, 위의 명명된 필드가 여기의 같은 키보다 우선합니다.

**metadata** `Record\<string, string\>`

주문에 기록하고 결제에서 다시 읽을 수 있는 자체 키/값 쌍입니다. 주문 ID, 장바구니 ID 등 대사(reconcile)에 사용하는 모든 값을 넣을 수 있습니다. 최대 40개의 문자열 쌍입니다. 생성 시에만 설정할 수 있습니다.

**returnUrl** `string`

외부 결제 단계 이후 결과와 관계없이 구매자가 도착하는 위치입니다. 탭에는 `payment`(`pay_` ID, 설정 모드 체크아웃의 경우 `sint_` ID와 함께 `setup`)와 `status`(`succeeded`, `failed`, `canceled`)가 추가되며, 기존 쿼리 매개변수는 그대로 유지됩니다. 성공 페이지를 표시하기 전에 `status`로 분기하세요. 거절되었거나 중단된 외부 단계도 여기로 도착합니다. 주문 이행은 이 방문이 아니라 웹훅에서 처리하세요. https만 허용됩니다(localhost는 http 허용). 생성 시에만 설정할 수 있습니다.

**appearance** `Appearance`

이 그룹 엘리먼트의 시각적 사용자 지정입니다. 전역 `WhopElements({ appearance })`보다 우선합니다. `update({ appearance })`로 실시간 변경할 수 있습니다.

**locale** `WhopElementsLocale`

이 그룹 엘리먼트 UI 텍스트의 로케일입니다. 앱에 빌드된 로케일 중 하나로 설정하면 전역 구성보다 우선합니다. 그 외의 값은 기본 로케일로 대체됩니다.

## 이벤트

생성 옵션 또는 React props로 콜백을 전달합니다.

### `onComplete`

체크아웃이 완료되고 결과가 확정되면 마운트당 한 번 실행됩니다. `result`는 확정된 결과를 나타냅니다. `payment`(구매자가 결제함 — `paymentId`), `waitlist_entry`(구매자가 대기자 명단에 가입함 — `entryId`), 또는 `setup`(설정 모드 체크아웃이 결제 수단을 저장함 — `setupIntentId`)이며, 어느 경우든 `sessionId`는 체크아웃 세션입니다. `returnUrl` 이동 전에 실행되므로 자체 분석 도구나 광고 픽셀이 구매를 기록하기에 적합한 위치입니다. 주문 이행은 이 콜백이 아니라 웹훅에서 처리하세요. 이후 페이지 로드에서 복원된 체크아웃은 같은 결과에 대해 이 콜백을 다시 실행합니다.

**payload** `CheckoutPaymentCompletion | CheckoutWaitlistCompletion | CheckoutSetupCompletion`

**CheckoutPaymentCompletion**

**sessionId** `string` *required*

`chs_` 접두사가 붙은 체크아웃 세션입니다.

**result** `"payment"` *required*

**paymentId** `string` *required*

`pay_` 접두사가 붙은 결제로, 구매를 기록할 때 사용할 ID입니다.

**CheckoutWaitlistCompletion**

**sessionId** `string` *required*

`chs_` 접두사가 붙은 체크아웃 세션입니다.

**result** `"waitlist_entry"` *required*

**entryId** `string` *required*

`ent_` 접두사가 붙은 대기자 명단 항목입니다.

**CheckoutSetupCompletion**

**sessionId** `string` *required*

`chs_` 접두사가 붙은 체크아웃 세션입니다.

**result** `"setup"` *required*

**setupIntentId** `string` *required*

`sint_` 접두사가 붙은 저장된 설정입니다.

### `onLoadingChange`

그룹의 로딩 상태가 변경될 때 실행됩니다. 마운트된 엘리먼트 중 하나라도 로딩 중이면 값은 `true`입니다.

**loading** `boolean`

## 메서드

`whop.checkout.create({ … })` 또는 `useCheckout()`에서 받은 Checkout 핸들에서 호출합니다.

### `update`

마운트된 모든 엘리먼트에 새 핸들 옵션을 병합합니다. React에서는 대신 네임스페이스 props를 변경하세요.

**매개변수**

**options** `Partial\<CheckoutOptions\>` *required*

### `destroy`

이 핸들이 생성한 모든 엘리먼트와 하위 컨트롤러를 제거하고, 컨트롤러 프레임을 제거하며, 구독을 해제합니다. 여러 번 호출해도 되지만, 제거된 핸들은 다른 모든 호출을 거부합니다. 다시 시작하려면 새 핸들을 생성하세요. React는 프로바이더가 언마운트될 때 그룹을 자동으로 제거합니다.

## 리소스

엘리먼트를 마운트하지 않고 다음 SDK 객체를 생성합니다. 각각 별도 페이지가 있습니다:

> [card] [CheckoutSession](https://docs.whop.com/ko/elements/latest/checkout/checkoutSession.md)
>
> 자체 PayPal 버튼을 그리는 페이지를 위한 저수준 헤드리스 체크아웃 세션입니다. `load()`는 `lineItems`로 체크아웃 세션을 생성하고, `show("paypal", { termsAccepted: true })`는 구매자를 PayPal로 보냅니다(데스크톱에서는 팝업 창, 휴대폰에서는 탭 전체). 구매자가 승인하면 결제와 함께 resolve됩니다. `paymentMethodOptions.paypal.requestShipping`을 사용하면 PayPal이 구매자에게 배송 주소를 요청하고, 구매자가 PayPal에 있는 동안 `shipping_address.changed`를 구독한 계정의 웹훅이 서버에서 각 주소의 가격을 책정합니다. 결제는 구매자가 승인한 후에만 해당 가격으로 생성됩니다. 전체 페이지 리디렉션 후에는 promise가 settle되지 않으므로 대신 `redirectUrl`의 `payment` 및 `status` 쿼리 매개변수에서 결과를 읽으세요.

## 엘리먼트

이 그룹이 마운트하는 엘리먼트입니다. 각각 별도 페이지가 있습니다:

**대안.** 한 번에 하나만 마운트하세요. 다른 엘리먼트를 마운트하기 전에 제거하세요:

> [card] [CheckoutElement](https://docs.whop.com/ko/elements/latest/checkout/checkout.md)
>
> 전체 체크아웃 화면입니다. 실시간 견적이 포함된 주문 요약, 프로모션 코드 입력, 구매자가 결제하는 통화, 이 체크아웃에서 구매자로부터 수집해야 하는 모든 항목, 결제 수단 화면, 결제 흐름을 함께 제공합니다. 수집하는 항목은 판매자가 설정한 내용(이메일, 판매자 자체 질문, 전화번호, 실물 상품의 배송 주소, 판매자 약관에 대한 명시적 동의)이며, 판매자가 정한 순서대로 한 화면에 함께 렌더링됩니다. 따라서 판매자가 새 항목을 요청하기 시작해도 여기서 변경할 것은 없습니다. 구매 전체를 렌더링하며, 세션과 자격 증명은 체크아웃 컨트롤러가 소유합니다. 외부 단계가 필요한 결제 후 구매자가 돌아오면 이 화면이 서버가 보고한 결과를 렌더링합니다.

> [card] [ExpressCheckoutElement](https://docs.whop.com/ko/elements/latest/checkout/expressCheckout.md)
>
> 체크아웃을 위한 원터치 Apple Pay, Google Pay, PayPal 버튼입니다. 지갑이 세션에 아직 필요한 항목(구매자 이메일, 실물 상품의 배송 주소, Apple Pay와 Google Pay에서 판매자가 수집하는 경우 전화번호, Apple Pay에서 판매자가 입력을 허용하는 경우 프로모션 코드)을 수집하며, 한 번의 탭으로 구매가 완료됩니다. 전체 체크아웃 엘리먼트와 체크아웃의 진입 슬롯을 공유하므로 하나의 핸들은 둘 중 정확히 하나만 마운트합니다. 시트로 마무리할 수 있을 만큼 구매가 단순하면 이 버튼만, 그 외에는 전체 체크아웃 화면을 사용합니다. 구매자의 기기에서 실제로 결제할 수 있고 체크아웃의 결제 수단 구성에서 허용하는 지갑만 제공된 버튼 이미지로 렌더링하며, 사용 가능한 지갑이 없으면 아무것도 렌더링하지 않습니다. PayPal은 판매자가 허용하는 경우 표시되고, 별도 창에서 열리며, 구매와 함께 구매자의 PayPal 계정을 저장하므로 갱신, 무료 체험, 이후 판매자의 청구가 저장된 카드처럼 작동합니다. 세 지갑 모두 페이지 도메인에 Apple Pay가 필요합니다. 퍼스트 파티 whop.com 페이지는 사전 승인되어 있으며, 그 외 사이트는 버튼이 렌더링되기 전에 [Domains API](https://docs.whop.com/ko/api-reference/beta/domains/domain)를 통해 도메인에 Apple Pay를 추가해야 합니다. 자체 사이트에서 Google Pay를 제공하는 경우 Google Pay API 서비스 약관이 적용됩니다. 대기자 명단 가입, 이전, 페이지에서만 물을 수 있는 양식 질문 등 시트로 제대로 마무리할 수 없는 체크아웃은 실패할 버튼을 렌더링하는 대신 명확하게 거부합니다.


## Related topics

- [Checkout Configuration](https://docs.whop.com/ko/api-reference/legacy/checkout-configurations/checkout-configuration.md)
- [CheckoutSession](https://docs.whop.com/ko/elements/latest/checkout/checkoutSession.md)
- [CheckoutElement](https://docs.whop.com/ko/elements/latest/checkout/checkout.md)
