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

# Payments

> `plan_` ID 또는 인라인 통화와 금액으로 결제를 받거나, `mode: "setup"`으로 결제 없이 결제 수단을 저장합니다. PaymentElement, CardElement 또는 CardFields를 마운트한 다음 청구 정보와 함께 `payments.createConfirmationToken`을 호출합니다. 지갑을 선택하면 시트가 자동으로 열립니다. 계정이 페이지 내 은행 연결(은행 계좌 결제 수단 유형의 `bank_debit.bank_connection`)을 제공하는 경우, 은행 계좌를 선택하면 페이지에서 Plaid Link도 열립니다. 구매자가 둘 중 하나를 닫으면 호출이 `payment_request_cancelled`로 거부되며, 결제 핸들러는 이를 취소로 처리해야 합니다. 서버 측에서 토큰을 확인한 다음, 대기 중인 단계가 있으면 결제 또는 setup intent의 `client_secret`을 `handleNextAction`에 전달합니다.

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

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

## Playground

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

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

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

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

## 옵션

`whop.payments.create({ … })`에 전달하거나, React에서는 `<Payments>`의 props로 전달합니다.

> [!NOTE]
>
> 다음 조합 중 정확히 하나를 전달하세요.
>
> * `accountId` 및 `plan`
> * `accountId`, `currency`, `amount`
> * `accountId`, `mode: "setup"`, `currency`
> * `plan`, `currency`, `amount`, `mode` 모두 없음

**accountId** `string`

`biz_` 접두사가 붙은 계정 ID입니다. 계정 화면 없이 정적 메서드를 호출할 때만 생략하세요.

**mode** `"payment" | "setup"`

마운트 모드이며 기본값은 `payment`입니다. `setup`은 결제 수단을 저장하며 지금이나 나중에나 아무것도 청구하지 않습니다. 저장할 수 있는 결제 수단만 제공되며 금액 한도는 적용되지 않습니다. `createConfirmationToken()`으로 확인한 다음 서버 측에서 setup intent를 생성하세요.

**plan** `string`

`plan_` 접두사가 붙은 플랜 ID입니다. 클라이언트 측에서 통화, 금액, 결제 수단 구성으로 확인됩니다. 플랜 또는 인라인 통화와 금액 중 하나만 전달하고, 둘 다 전달하지 마세요.

**offerAmounts** `object`

체크아웃이 BNPL 같은 수수료 없는 결제 수단에 맞춰 `amount`를 다시 책정할 때 결제 수단을 제한하는 데 사용되는 최소 단위 `feeInclusive` 및 `feeFree` 총액입니다. 각 결제 수단은 해당하는 총액과 비교되므로, 선택한 수수료 없는 결제 수단이 사라지지 않습니다. 생략하면 `amount`가 모든 결제 수단을 제한합니다.

**속성**

**feeInclusive** `number` *required*

**feeFree** `number` *required*

**returnUrl** `string`

외부 은행 또는 3DS 단계를 위한 반환 URL입니다. 기본값은 마운트한 페이지입니다. 결과와 관계없이 구매자는 `payment`(또는 `setup`), `status`(`succeeded`, `failed`, `canceled` 또는 `processing` 같은 대기 중 상태), `client_secret`이 추가된 이 URL로 이동하므로, 성공 페이지를 표시하기 전에 `status`에 따라 분기하세요.

**setupFutureUsage** `"off_session" | "on_session"`

setup은 `off_session` 사용을 위해 결제 수단을 저장하며, 이는 setup이 허용하는 유일한 사용 방식입니다.

**previewWalletAvailability** `WalletAvailability`

결정적인 미리보기를 위한 지갑 사용 가능 여부 재정의입니다. 실제 체크아웃에서는 호스트를 검사합니다.

**속성**

**applePay** `boolean` *required*

**googlePay** `boolean` *required*

**payPal** `boolean`

**order** `("apple_pay" | "google_pay" | "paypal_express")[]`

이 브라우저에 네이티브인 시트 기준으로 순위를 매긴 지갑 목록입니다. WebKit에서는 Apple Pay가 먼저, 그 외에서는 Google Pay가 먼저, PayPal은 마지막이므로 익스프레스 버튼을 가장 적합한 순서로 쌓을 수 있습니다. 사용자가 지정한 사용 가능 여부(미리보기)나 이 필드보다 오래된 전송 형식에는 없습니다. payment-request의 WalletSheetType이 아닌 인라인 유니언입니다. 해당 모듈이 이미 이 모듈을 가져오기 때문입니다.

**wallets** `object`

사용 가능한 각 지갑의 세부 정보이며, 지갑 유형을 키로 사용합니다. 사용자가 지정한 사용 가능 여부(미리보기)에는 없습니다.

**속성**

**apple\_pay** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 아트입니다. 게시된 것이 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**google\_pay** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 아트입니다. 게시된 것이 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**paypal\_express** `WalletDetails`

**속성**

**button** `WalletButtonArt`

지갑의 공식 버튼 아트입니다. 게시된 것이 없으면 없습니다.

**속성**

**light** `object` *required*

밝은 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**dark** `object` *required*

어두운 페이지용입니다.

**속성**

**color** `string` *required*

**image** `string` *required*

**currency** `string`

소문자 세 글자 ISO 4217 통화 코드입니다. 결제 수단 매트릭스를 필터링합니다.

**amount** `number`

최소 단위로 표시한 결제 금액입니다. 한도에서 이 금액을 제외하는 결제 수단은 제공되지 않습니다.

**paymentMethodConfiguration** `object`

API의 `enabled`, `disabled`, `include_platform_defaults` 형식으로 된 계정 결제 수단 필터입니다. `disabled`는 유형을 제거하고, `enabled`는 제공되는 유형을 복원하며, `include_platform_defaults: false`는 활성화된 유형만 남깁니다. 플랜은 자체 구성을 제공합니다.

**속성**

**enabled** `string[]`

**disabled** `string[]`

**include\_platform\_defaults** `boolean`

**appearance** `Appearance`

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

**locale** `WhopElementsLocale`

이 그룹 엘리먼트 UI 텍스트의 로캘입니다. 전역 구성을 재정의하려면 앱에 빌드된 로캘 중 하나로 설정하세요. 그 외의 값은 기본 로캘로 대체됩니다.

## 이벤트

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

### `onLoadingChange`

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

**loading** `boolean`

## 메서드

`whop.payments.create({ … })` 또는 `usePayments()`에서 얻은 Payments 핸들에서 호출합니다.

### `createConfirmationToken`

결제 버튼에서 선택한 결제 수단의 확인 토큰을 생성합니다. 체크아웃의 청구 정보를 전달하세요. `email`이 반드시 포함되어야 합니다. 청구 정보 수집이 비활성화된 경우 `phone`이 필요한 결제 수단에는 이를 제공하세요. 카드는 `name`과 `line1` 및 `country`가 포함된 주소도 필요합니다. 지갑을 선택하면 결제 버튼 상호작용 중에 시트가 열립니다. 계정이 페이지 내 은행 연결(은행 계좌 결제 수단 유형의 `bank_debit.bank_connection`)을 제공하는 경우, 은행 계좌를 선택하면 이 과정에서 Plaid Link도 열리며, 구매자가 계좌를 연결하면 호출이 완료됩니다. 이를 위해서는 whop.com 페이지 또는 [Domains API](https://docs.whop.com/ko/api-reference/beta/domains/domain)를 통해 Apple Pay가 준비된 도메인과, `contentSecurityPolicy()`가 반환하는 Plaid 호스트를 허용하는 콘텐츠 보안 정책이 필요합니다. 그렇지 않으면 구매자는 제출 후에 계좌를 연결합니다. 구매자가 시트나 Link를 닫으면 호출은 `payment_request_cancelled`로 거부됩니다. 이를 결제 오류가 아닌 취소로 처리하고 구매자가 다시 결제할 수 있게 하세요. 반환된 `confirmationToken`을 서버 측에서 확인한 다음 `WhopElements.payments.handleNextAction(…)`을 호출하세요. 컨트롤러 iframe이 아닌 사용자 페이지(호스트 측)에서 실행됩니다.

**매개변수**

**input** `object` *required*

**속성**

**billingDetails** `object`

**속성**

**email** `string`

**name** `string`

**phone** `string`

**address** `object`

**속성**

**country** `string`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

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

**confirmationToken** `string` *required*

**type** `string` *required*

### `update`

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

**매개변수**

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

### `destroy`

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

## 정적 메서드

마운트 없이 호출합니다. 바닐라에서는 `whop.payments.<method>(…)`, React에서는 `useWhop().payments.<method>(…)`를 사용합니다.

### `handleNextAction`

엘리먼트를 마운트하지 않고 확인된 결제의 대기 중인 단계를 완료합니다. `clientSecret`이 결제를 식별하므로 결제 ID는 필요하지 않습니다. 인라인 단계는 대화 상자에서 열리며 `redirected: false`로 완료됩니다. 대화 상자를 닫으면 결제의 현재 상태가 반환되며, 이 상태는 대기 중으로 남아 있을 수 있습니다. 전체 페이지 단계는 `redirected: true`와 함께 `return_url`로, 결제에 반환 URL이 없으면 호스팅 영수증으로 리디렉션됩니다. iframe 안에서는 최상위 탭을 이동시킵니다. 임베딩 페이지가 이 이동을 거부하면 `TAB_NAVIGATION_BLOCKED` 코드로 거부되며, 결제는 대기 상태로 유지됩니다. 표시 전에 목적지를 업데이트하려면 `returnUrl`을 설정하세요. 업데이트에 실패하면 어떤 단계도 실행되기 전에 거부됩니다. 인라인 단계는 해당 URL로 이동하지 않습니다. 청구 결과가 아직 결정 중인 결제는 단계가 나타나거나 확정될 때까지 폴링되며, 단계 없이 결정된 결제는 즉시 완료됩니다.

**매개변수**

**input** `object` *required*

**속성**

**clientSecret** `string` *required*

**returnUrl** `string`

**pollIntervalMs** `number`

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

**status** `string` *required*

**redirected** `boolean` *required*

**lastPaymentError** `object | null` *required*

**속성**

**code** `string | null`

**decline\_code** `string | null`

**message** `string | null`

## 리소스

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

> [card] [PaymentRequest](https://docs.whop.com/ko/elements/latest/payments/paymentRequest.md)
>
> 사용자 지정 버튼, 익스프레스 체크아웃, 배송 콜백을 위한 저수준 Apple Pay, Google Pay 또는 PayPal 시트입니다. 지갑 타일은 `payments.createConfirmationToken`을 통해 이 흐름을 자동화합니다. 사용 가능 여부를 확인하고 지갑을 준비하려면 `canMakePayment()`를 await한 다음, 사용자 상호작용 핸들러에서 `show(type)`을 동기적으로 호출하세요. 확인된 `ctok`은 `ctok_` 접두사가 붙은 확인 토큰입니다. 엘리먼트가 발급한 토큰과 마찬가지로 서버 측에서 확인하세요. PayPal 토큰은 PayPal이 구매자에게 표시한 총액을 초과하여 청구하지 않습니다.

## Content security policy

이 그룹의 일부 작업은 프레임이 아닌 사용자 페이지에서 실행됩니다. 콘텐츠 보안 정책이 있는 페이지에는 다음 소스가 필요합니다. `@whop/elements`의 `contentSecurityPolicy()`는 이 표의 모든 소스를 반환합니다. 샌드박스 소스는 `environment: "sandbox"`일 때 적용됩니다.

| 요구 사항 | 지시문 | 프로덕션 소스 | 샌드박스 소스 |
| - | - | - | - |
| Plaid Link 스크립트 | `script-src` | `https://cdn.plaid.com` | 동일 |
| ↳ Plaid 스크립트가 여는 Plaid Link 프레임 | `frame-src` | `https://cdn.plaid.com` | 동일 |
| ↳ Plaid 스크립트가 호출하는 Plaid API | `connect-src` | `https://production.plaid.com` | `https://sandbox.plaid.com` |

## 엘리먼트

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

> [card] [AddressElement](https://docs.whop.com/ko/elements/latest/payments/address.md)
>
> 청구지 또는 배송 주소를 수집합니다. 필드, 순서, 유효성 검사는 선택한 국가를 따릅니다. 거리 주소 자동 완성(휴대폰에서는 전체 화면)과 주소를 읽거나 검증하는 메서드를 포함합니다.

> [card] [EmailElement](https://docs.whop.com/ko/elements/latest/payments/email.md)
>
> 구매자의 이메일을 수집하고, 마운트되어 있는 동안 `payments.createConfirmationToken()`에 전달합니다. 명시적으로 지정한 `billingDetails.email`이 우선합니다. 일치하는 Whop 계정이 있으면 코드 인증 또는 계정에 패스키가 있는 경우 패스키를 사용한 선택적 로그인이 표시됩니다. 로그인에 성공하면 payment 엘리먼트에서 저장된 결제 수단을 사용할 수 있습니다. 구매자는 게스트로 계속 진행할 수 있습니다.

> [card] [TaxIdElement](https://docs.whop.com/ko/elements/latest/payments/taxId.md)
>
> API에서 허용하는 사업자 세금 등록 정보를 수집합니다. 레이블은 구매자에게 친숙한 이름을 사용합니다. 플레이스홀더는 선택한 형식과 일치합니다. `country`는 유형을 미리 선택합니다. `onChange`는 확정된 쌍을 전달합니다. API 유효성 검사 오류는 호스트가 제공합니다.

> [card] [BrandingElement](https://docs.whop.com/ko/elements/latest/payments/branding.md)
>
> **필수 — `AddressElement`, `EmailElement`, `TaxIdElement`를 제외한 다른 엘리먼트는 이 엘리먼트를 기다립니다.** Whop의 판매 대행자(merchant of record) 고지입니다. Whop 구매자 서비스 약관 및 개인정보 처리방침에 대한 구매자의 동의를 Whop 워드마크와 함께 표시합니다. 필수 항목입니다. 이 엘리먼트가 마운트될 때까지 payment, card, card fields 엘리먼트는 로딩 상태로 유지되며, 이 엘리먼트 없이는 결제를 확인할 수 없습니다.

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

> [card] [PaymentElement](https://docs.whop.com/ko/elements/latest/payments/payment.md)
>
> 사용 가능한 결제 수단을 표시하고 선택한 결제 수단에 필요한 필드와 고지 사항을 수집합니다. `change`를 사용해 결제 버튼을 활성화하세요. 활성화 핸들러에서 `payments.createConfirmationToken()`을 호출하세요. 서버 측에서 토큰을 확인한 다음, 대기 중인 단계가 있으면 `payments.handleNextAction(…)`에 전달하세요. 주소에 따른 업데이트에는 `addressChange`를 사용하세요.

> [card] [CardElement](https://docs.whop.com/ko/elements/latest/payments/card.md)
>
> 카드 번호, 만료일, 보안 코드 필드가 미리 배치된 엘리먼트입니다. `payments.create("card")`로 생성하고, `onChange`에서 결제 버튼을 활성화한 뒤 `payments.createConfirmationToken()`으로 확인합니다. 카드 번호는 PCI로 격리된 호스팅 필드에 유지됩니다. `layout`은 `stacked`(기본값)와 `compact`를 지원합니다.

> [card] [CardFields](https://docs.whop.com/ko/elements/latest/payments/cardFields)
>
> 사용자 지정 레이아웃을 위해 별도로 마운트할 수 있는 세 개의 PCI 격리 카드 필드(번호, 만료일, 보안 코드)입니다. `payments.create("cardFields")`로 생성하고, 각 필드를 배치한 뒤, `onChange`에서 결제 버튼을 활성화하고 `payments.createConfirmationToken()`으로 확인합니다. 카드 번호는 호스팅 필드에 유지됩니다. *(하위 컨트롤러, 엘리먼트 3개)*


## Related topics

- [Payment](https://docs.whop.com/ko/api-reference/legacy/payments/payment.md)
- [Payments API](https://docs.whop.com/ko/api-reference/payments/payment.md)
- [Retry Payment](https://docs.whop.com/ko/api-reference/payments/retry-payment.md)
