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

# CheckoutSession

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

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

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

엘리먼트를 마운트하지 않고 이 [`Checkout`](https://docs.whop.com/ko/elements/latest/checkout/overview) 리소스를 생성합니다. 바닐라 JS에서는 `whop.checkout.checkoutSession.create({ … })`, React에서는 `useWhop().checkout.checkoutSession.create({ … })`를 사용합니다.

## 옵션

다음 옵션을 `whop.checkout.checkoutSession.create({ … })`에 전달합니다.

**accountId** `string` *required*

항목을 판매하는 계정 ID로, `biz_` 접두사가 붙습니다.

**lineItems** `CheckoutSessionLineItem[]` *required*

구매자가 구매하는 항목입니다. 각 항목은 변형(`plan_…`)과 선택적 `quantity`(기본값 1)를 지정합니다. 여러 항목을 넣으면 장바구니가 됩니다.

**속성**

**variant** `string` *required*

**quantity** `number`

**redirectUrl** `string` *required*

탭이 리디렉션된 경우 PayPal 이후 구매자가 도착하는 위치로, `payment`와 `status`가 추가됩니다. `status`는 `succeeded`, `canceled`, `failed`, 또는 Whop이 아직 청구를 마무리하는 동안에는 `processing`입니다(정산 결과를 확인하려면 서버에서 결제를 조회하세요). 데스크톱에서는 대신 팝업이 닫히고 `show()`가 settle됩니다.

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

최대 40개의 자체 문자열 키와 값으로, 체크아웃 세션에 보관되고 생성되는 결제에 복사됩니다. 따라서 결제와 해당 웹훅에 다시 포함되며, 광고 및 제휴 어트리뷰션 등에 활용할 수 있습니다. 구매자의 브라우저에서 설정되므로 가격이나 주문 이행에 절대 의존하지 마세요.

**setupFutureUsage** `"off_session"`

`off_session`으로 설정하면 구매자의 PayPal 계정을 저장하여, 나중에 서버가 구매자 없이 청구할 수 있습니다(예: 원클릭 업셀). PayPal은 구매자가 승인할 때 향후 결제에 동의하도록 요청합니다. 구매자에게 PayPal 계정이 저장된다는 사실을 알린 후에만 설정하세요.

**email** `string`

결제와 멤버십이 속하는 구매자의 이메일입니다. 생략하면 승인하는 PayPal 계정의 이메일을 사용합니다.

**paymentMethodOptions** `CheckoutSessionPaymentMethodOptions`

하나의 결제 수단에 대한 옵션입니다. `paypal.requestShipping`을 사용하면 PayPal이 구매자에게 배송 주소를 요청합니다. 계정에 `shipping_address.changed`를 구독한 활성화된 `https` 웹훅이 있으면 Whop은 각 주소마다 웹훅을 호출하고 응답받은 합계를 청구합니다. 기본값은 `false`입니다.

**속성**

**paypal** `CheckoutSessionPayPalOptions`

**속성**

**requestShipping** `boolean`

## 메서드

리소스에서 호출합니다.

> [!WARNING]
>
> `show`는 사용자 활성화 중에 동기적으로 호출하세요. 선행 작업은 먼저 await하세요.

### `load`

`lineItems`로 체크아웃 세션을 생성합니다. 다시 호출하면 같은 세션을 반환합니다. 아직 로드되지 않았다면 `show()`가 먼저 로드합니다. `terms`는 구매자가 결제함으로써 동의하는 내용입니다. 버튼 옆에 `links`(판매자가 게시한 정책과 Whop 구매자 약관)를 표시하고, `terms.required`가 `true`이면 체크박스 등으로 구매자가 적극적으로 동의하도록 하세요. `requirements`는 세션을 결제하기 전에 필요한 항목을 나열합니다. `email`, `terms`, 그리고 `paypal.requestShipping` 사용 시 `shipping_address` 외의 항목은 여기서 수집할 수 없으므로 `show()`가 거부합니다.

**반환값** `Promise<CheckoutSessionLoaded>`

**id** `string` *required*

**status** `string` *required*

**requirements** `string[]` *required*

**terms** `CheckoutSessionTerms` *required*

**속성**

**required** `boolean` *required*

**links** `CheckoutSessionTermsLink[]` *required*

**속성**

**kind** `string` *required*

`"terms_of_service"`, `"privacy_policy"`, `"return_policy"`, `"eula"`, `"whop_buyer_terms"`, `"whop_privacy_policy"` 중 하나입니다.

**url** `string` *required*

### `show`

PayPal 버튼의 클릭 핸들러에서 동기적으로 호출하세요. 데스크톱에서는 그 자리에서 팝업을 열며, 나중에 열린 팝업은 차단됩니다. `termsAccepted: true`는 이번 클릭에 대해 `load()`의 `terms.links`가 버튼 옆에 표시되었고, `terms.required`가 `true`인 경우 구매자가 적극적으로 동의했을 때만 전달하세요. 구매자가 승인하고 Whop이 청구하면 `{ payment }`와 함께 resolve됩니다. 다음과 같은 `code`의 오류와 함께 reject됩니다: `termsAccepted` 없이 호출하면 `attestation_required`, 세션에 PayPal이 수집할 수 없는 항목이 필요하면 `requirements_unsupported`(`load()`의 `requirements` 참고), 구매자가 PayPal을 취소하거나 닫으면 `payment_request_cancelled`, 계정이 웹훅을 통해 이 결제의 가격을 책정할 수 없으면 `seller_pricing_unavailable`(자체 세금을 처리하지 않거나, 장바구니에 프로모션 코드, 구매자 수수료, 마켓플레이스 분할 또는 갱신되는 플랜이 있는 경우), 그 외에는 `payment_failed`. 휴대폰에서는 탭이 PayPal로 이동하며 promise는 settle되지 않습니다. 사용자 활성화 중에 동기적으로 호출하세요. 브라우저는 비동기 단계를 거치면 활성화를 취소하므로 선행 작업은 먼저 await하세요.

**매개변수**

**paymentMethod** `"paypal"` *required*

**options** `CheckoutSessionShowOptions`

**속성**

**termsAccepted** `boolean`

**반환값** `Promise<CheckoutSessionConfirmResult>`

**payment** `CheckoutSessionPayment` *required*

**속성**

**id** `string` *required*

**status** `string` *required*


## Related topics

- [Checkout](https://docs.whop.com/ko/elements/latest/checkout/overview.md)
- [이전 버전에서 마이그레이션하기](https://docs.whop.com/ko/developer/api/migrate-from-previous-versions.md)
- [레거시 인보이스에서 마이그레이션하기](https://docs.whop.com/ko/developer/guides/migrate-from-legacy-invoices.md)
