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

# PaymentElement

> 사용 가능한 결제 수단을 표시하고 선택한 결제 수단에 필요한 필드와 고지 사항을 수집합니다. `change`를 사용해 결제 버튼을 활성화하세요. 활성화 핸들러에서 `payments.createConfirmationToken()`을 호출하세요. 서버 측에서 토큰을 확인한 다음, 보류 중인 단계가 있으면 `payments.handleNextAction(…)`에 전달하세요. 주소에 따른 업데이트에는 `addressChange`를 사용하세요.

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

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

[`Payments`](https://docs.whop.com/ko/elements/latest/payments/overview) 안에 마운트됩니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다. `select()`를 호출하려면 생성된 핸들 또는 React `ref`를 보관하세요.

> [!NOTE]
>
> **배타적.**`PaymentElement`는 이 Payments 핸들에서 `CardElement` 또는 `CardFields`의 대안입니다. 한 번에 하나만 마운트하세요. 다른 것을 마운트하기 전에 제거하세요.

> [!NOTE]
>
> **`BrandingElement`를 기다립니다.** 이 엘리먼트는 같은 Payments 핸들에 `BrandingElement`가 마운트될 때까지 로딩 상태로 유지됩니다.

`WhopPayments` 스코프 안에 마운트됩니다. 청구에서 제공하는 결제 수단 타일을 렌더링한 다음, 선택한 결제 수단이 수집하는 항목(카드 필드, 결제 수단이 선언한 필드 또는 Apple Pay 버튼)을 렌더링합니다.

청구와 확인 토큰을 소유하는 `<Payments>` 안에 마운트합니다. `<Payments>` 자체는 `<WhopElements>` 안에 마운트됩니다. 청구에 대한 결제 수단 타일을 렌더링하고 선택한 결제 수단이 선언하는 항목을 수집하므로, 카드, 지갑 시트, 은행 리디렉션 모두 같은 한 줄로 처리됩니다.

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <PaymentElement onChange={(e) => console.log(e)} onAddressChange={(e) => console.log(e)} />
        <BrandingElement />
      </Payments>
    </WhopElements>
  );
}
```

```tsx React Native theme={null}
import { useRef, useState } from 'react';
import { Button, ScrollView } from 'react-native';
import { EmailElement, PaymentElement, Payments, type PaymentsHandle } from '@whop/elements-react-native';

export function PaymentStep() {
  const payments = useRef<PaymentsHandle | null>(null);
  const [ready, setReady] = useState(false);

  return (
    <Payments
      ref={payments}
      accountId="biz_xxxxxxxx"
      plan="plan_xxxxxxxx"
      returnUrl="https://example.com/checkout/return"
    >
      <ScrollView>
        <EmailElement />
        <PaymentElement onChange={(p) => setReady(p.complete)} />
      </ScrollView>
      <Button
        title="Pay"
        disabled={!ready}
        onPress={async () => {
          const token = await payments.current!.createConfirmationToken();
          console.log(token.confirmationToken, token.type);
        }}
      />
    </Payments>
  );
}
```

```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 */ });
  payments.create('payment', {
    onChange: (e) => console.log(e),
    onAddressChange: (e) => console.log(e)
  }).mount('#payments-payment');
  payments.create('branding').mount('#payments-branding');
</script>
```

```swift Swift theme={null}
import Elements
import SwiftUI

// .whopElements(environment:) runs once at the app root. See Getting started.
struct CheckoutScreen: View {
    @State private var selection = WhopPaymentSelection(isComplete: false, type: nil, displayName: nil, category: nil)

    var body: some View {
        WhopPayments(accountID: "biz_xxxx", charge: .plan(id: "plan_xxxx")) { payments in
            ScrollView {
                VStack(alignment: .leading, spacing: 20) {
                WhopPaymentElement(selection: $selection)
                    WhopBrandingElement()
                }
                .padding()
            }
        }
    }
}
```

예시 데이터입니다. [Playground 열기](https://docs.whop.com/ko/elements/latest/payments/overview#playground).

[React Native 예제 앱의 Android에서 실행 중인 PaymentElement](https://app.revyl.ai/embed/c05028fb-0d33-4f36-b6f9-5339a4b9a054?controls=0)

## Props

**order** `string[]`

두 레이아웃 모두에서 표시 순서를 제어합니다. 나열된 유형이 순서대로 먼저 표시됩니다. 나열되지 않은 유형은 상대적 순서를 유지합니다. 사용 가능 여부에는 영향을 주지 않습니다. 기본값은 `[]`입니다.

**wallets** `object`

엘리먼트가 제공하는 지갑을 제어합니다. 각 키의 기본값은 `'auto'`이며, 계정, 구매자의 기기, 청구가 지원하는 곳이면 어디서든 지갑을 제공합니다. `'never'`는 해당 지갑을 결제 수단 목록에서 제거합니다. 페이지에서 `paymentRequest`로 자체 Apple Pay, Google Pay 또는 PayPal 버튼을 그리는 경우 이를 사용하면 구매자에게 각 지갑이 한 번씩만 표시됩니다. `payPal: 'never'`는 PayPal 결제 수단을 제거합니다. 저장된 결제 수단에는 영향을 주지 않습니다. 기본값은 `{}`입니다. `v1.8.0`부터 지원.

**속성**

**applePay** `"never" | "auto"`

**googlePay** `"never" | "auto"`

**payPal** `"never" | "auto"`

**fields** `object`

청구 정보 수집을 제어합니다. `billingDetails: 'minimal'`(기본값)은 각 결제 수단의 매트릭스를 따릅니다. 결제 수단은 기본적으로 이름과 국가별 전체 형식을 수집합니다. 재정의를 통해 선언된 최소 항목만 수집하거나 아무것도 수집하지 않을 수 있습니다. 카드의 경우 최소 항목은 카드상의 이름, 국가, 우편번호입니다. `'full'`은 모든 새 결제 수단에 이름과 국가별 전체 형식을 요구합니다. `'never'`는 블록을 숨깁니다. `address: 'minimal'`은 각 결제 수단이 선언한 최소 항목과 함께, 그 최소 항목에 국가가 없으면 국가를 수집합니다(`billingDetails: 'full'`이 체크아웃에 세금이 부과된다고 나타내면 우편번호도 수집). 단, 지갑, 암호화폐, 은행 직불, 은행 송금, 카드 현장 결제, 인앱 구매는 주소를 전혀 수집하지 않으며, 제공업체가 전체 청구지 주소를 요구하는 결제 수단(`requires_full_billing_address`)은 해당 타일이 플래그가 없는 체크아웃과 같은 규칙을 따릅니다. 그 외에는 `billingDetails: 'full'`보다 우선합니다. 판매자가 전체 청구지 주소를 수집하지 않을 때 사용하세요. `phone: 'never'`는 양식에서 이미 전화번호를 수집하는 경우 청구지 전화번호 입력만 숨깁니다. 전화번호가 필요한 결제 수단에는 `billingDetails.phone`을 `createConfirmationToken`에 전달하세요. 대신 주소를 `createConfirmationToken`에 전달하세요. 국가 선택기에는 결제 수단과 결제 통화가 지원하는 국가만 포함됩니다. 할부 플랜이 선택된 경우 플랜이 제공되는 국가로 좁혀집니다. 청구지 국가는 청구가 처리되는 거래 국가입니다. 하나만 사용 가능하면 고정됩니다. 기본값은 `{"billingDetails":"minimal"}`입니다.

**속성**

**billingDetails** `"minimal" | "full" | "never"`

**address** `"minimal" | "auto"`

**phone** `"never" | "auto"`

**defaultValues** `object`

각 결제 수단의 청구 블록이 처음 렌더링될 때 청구 정보를 미리 채웁니다. 구매자는 미리 채워진 모든 필드를 편집할 수 있습니다. `address.country`는 ISO 3166-1 alpha-2 코드이며 선택한 결제 수단이 허용하는 경우에만 적용됩니다. `phone`은 전화번호를 수집하는 결제 수단의 청구지 전화번호 입력을 `+14155552671` 같은 E.164 형식으로 채웁니다. 결제 수단이 지원하는 전화 국가 외의 번호는 무시됩니다. 블록이 렌더링하는 필드만 미리 채워지고 전송됩니다. 그 외의 항목은 `billingDetails`에 담아 `createConfirmationToken`에 전달하세요. `v1.1.0`부터 지원.

**속성**

**billingDetails** `object`

**속성**

**name** `string`

**phone** `string`

**address** `object`

**속성**

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**layout** `"accordion" | "horizontal"`

선택기 레이아웃입니다. `accordion`(기본값)은 결제 수단을 세로로 쌓고 세부 정보를 인라인으로 펼칩니다. `horizontal`은 너비가 같고 스크롤되지 않는 타일을 표시하며 선택한 세부 정보를 아래에 표시합니다. 결제 수단이 네 개를 넘으면 More 타일이 네이티브 선택기를 엽니다. 거기서 선택한 결제 수단은 다음 선택 전까지 마지막 타일을 차지합니다. 선택과 확인은 동일하게 동작합니다. 기본값은 `"accordion"`입니다.

**separated** `boolean`

`accordion` 전용입니다. 결제 수단 사이에 간격과 별도의 카드 스타일을 추가합니다. `layout`이 `horizontal`이면 무시됩니다. 기본값은 `false`입니다.

**autoSelect** `boolean`

해석 후 첫 번째로 제공되는 결제 수단을 선택할지 여부입니다. 기본값 `true`는 `order`를 따르며 구매자 상호작용처럼 `selected`와 `change`를 전달합니다. 구매자 상호작용 전에 한 번 실행되며, 제공되는 결제 수단이 없으면 아무 작업도 하지 않습니다. 선택되지 않은 상태로 마운트하려면 `false`로 설정하세요. 이와 별개로, 업데이트로 선택된 결제 수단이 제거되면 선택은 첫 번째로 제공되는 결제 수단으로 대체됩니다. 이미 선택되지 않은 엘리먼트는 선택되지 않은 상태로 유지됩니다. 기본값은 `true`입니다.

## 이벤트

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

### `onChange`

선택이 변경될 때 실행됩니다. `complete: true`는 구매자가 결제 수단을 선택하고 카드 필드 또는 필수 입력을 완료했음을 의미합니다. 이를 사용해 확인을 활성화하세요. `paymentMethod`는 저장된 결제 수단이든 새 결제 수단이든 선택된 결제 수단이며, 아무것도 선택되지 않은 동안에는 `null`입니다. `displayName`과 `icons`는 엘리먼트가 표시하는 방식대로 선택 항목의 이름을 나타내고(`balance.imageUrl`은 잔액 소유자의 이미지), `card`는 카드의 네트워크, 마지막 네 자리, 자금 유형을 담고, `requiresBillingPhone`은 결제 수단이 청구 정보에 전화번호를 필요로 하는지 나타내며, `countries`는 청구 통화로 해당 결제 수단을 사용해 결제할 수 있는 국가를 나열합니다. 최상위 수준의 `type`, `requiresBillingPhone`, `method`는 더 이상 사용되지 않으므로 `paymentMethod`에서 읽으세요. 최상위 수준의 `supportsBuyerFee`도 대체 항목 없이 더 이상 사용되지 않습니다. Whop이 구매자 서비스 수수료를 직접 책정합니다.

**payload** `PaymentElementChangeEvent`

**속성**

**complete** `boolean` *required*

구매자가 결제 수단을 선택하고 카드 필드 또는 필수 입력을 완료했는지 여부입니다. 이를 사용해 확인을 활성화하세요.

**paymentMethod** `PaymentElementPaymentMethod | null` *required*

선택된 결제 수단이며, 아무것도 선택되지 않은 동안에는 `null`입니다.

**속성**

**id** `string | null` *required*

구매자가 선택한 저장된 결제 수단이며, 구매자가 지금 입력하는 결제 수단이나 잔액인 경우에는 `null`입니다.

**type** `string` *required*

결제 수단 유형: `card`, `klarna`, `apple_pay`, `balance` 등입니다.

**category** `string` *required*

`card`, `wallet`, `bnpl`, `balance` 같은 유형이 속한 계열입니다.

**displayName** `string` *required*

선택 항목의 이름: 저장된 결제 수단 자체의 레이블("Visa •••• 4242", "Cash App \$tag"), 잔액의 이름("Acme", "Personal Balance"), 구매자가 입력하는 카드의 네트워크와 마지막 네 자리, 또는 결제 수단 자체의 이름("Klarna")입니다.

**icons** `PaymentMethodIcons`

선택 항목의 아이콘 이미지: 저장된 결제 수단 자체의 아이콘, 입력한 카드의 네트워크 이미지, 또는 결제 수단의 아이콘입니다. 항상 SVG 및 PNG 버전이 포함된 아이콘 세트입니다.

**속성**

**square** `PaymentMethodIconVariants | null`

**속성**

**light** `object` *required*

**속성**

**svg** `string` *required*

**dark** `object` *required*

**속성**

**svg** `string` *required*

**card** `PaymentMethodIconVariants | null`

**속성**

**light** `object` *required*

**속성**

**svg** `string` *required*

**dark** `object` *required*

**속성**

**svg** `string` *required*

**balance** `object`

유형 외에 잔액 선택 항목에 대해 알려진 정보: `imageUrl`은 잔액 소유자의 이미지로, 아이콘 세트가 아닌 단일 래스터 이미지 URL이며 `icons` 대신 표시합니다. 다른 결제 수단과 소유자에게 이미지가 없는 잔액에는 없습니다.

**속성**

**imageUrl** `string`

**card** `object`

카드 선택 항목에 대해 알려진 정보: 저장된 카드의 세부 정보, 또는 구매자가 입력하는 동안의 입력 카드 정보입니다. 다른 결제 수단에는 없습니다.

**속성**

**network** `string`

**last4** `string`

**funding** `string`

**requiresBillingPhone** `boolean` *required*

결제 수단이 청구 정보에 전화번호를 필요로 하는지 여부이며, `fields.phone`이 엘리먼트 자체의 전화번호 입력을 비활성화한 경우도 포함됩니다.

**countries** `string[]` *required*

청구 통화로 해당 결제 수단을 사용해 결제할 수 있는 국가의 소문자 두 글자 코드입니다.

**type** `string` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `paymentMethod.type`을 사용하세요.

**supportsBuyerFee** `boolean` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. Whop이 구매자 서비스 수수료를 직접 책정하므로 페이지에서 사용할 일이 없습니다. 다음 메이저 버전에서 제거됩니다.

**requiresBillingPhone** `boolean` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `paymentMethod.requiresBillingPhone`을 사용하세요.

**method** `object` *deprecated*

> [!WARNING]
>
> 더 이상 사용되지 않습니다. `paymentMethod`를 사용하세요. 구매자가 저장된 결제 수단을 선택하면 없습니다.

**속성**

**type** `string` *required*

**category** `string` *required*

**template** `string` *required*

**display\_name** `string` *required*

**countries** `object[]` *required*

**속성**

**country** `string` *required*

**min\_amount** `number | null` *required*

**max\_amount** `number | null` *required*

**min\_amount** `number | null` *required*

**max\_amount** `number | null` *required*

### `onAddressChange`

내부 청구지 주소가 변경되고 약 300ms 후에 실행됩니다. 세금, 배송 또는 기타 주소에 따른 업데이트에 사용하세요. `country`는 ISO 3166-1 alpha-2 코드입니다. 페이로드는 비어 있거나 해당 국가에서 사용되지 않는 다른 주소 키를 생략합니다. `complete: true`는 청구 블록이 유효하고 완료되었음을 의미합니다. 이 이벤트는 결제 엘리먼트가 주소 수집을 담당하는 동안에만 실행됩니다. `fields.billingDetails: 'never'`인 경우 자체 주소 소스를 사용하세요. `AddressElement`가 마운트된 경우 해당 엘리먼트의 `change` 이벤트를 사용하세요.

**payload** `object`

**속성**

**complete** `boolean` *required*

**address** `object` *required*

**속성**

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string` *required*

### `onLoaderStart`

로딩 스켈레톤이 처음 그려진 후, `onReady` 전에 실행됩니다.

### `onReady`

엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.

### `onError`

엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 `code`를 사용하세요. `sourceKey`는 실패한 호스트 상태 소스를 식별합니다.

**e** `object`

**속성**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

`create`가 반환한 핸들에서, 또는 React `ref`를 통해 호출합니다.

### `select`

구매자 상호작용과 같은 경로로 결제 수단을 선택합니다. 예를 들어 `select('cashapp')`은 타일을 펼치고 `selected`와 `change`를 전달합니다. 카드는 필드가 완료될 때까지 `complete: false`로 유지됩니다. 알 수 없거나, 사용할 수 없거나, 금액으로 제한된 결제 수단은 `METHOD_NOT_OFFERED` 코드로 거부됩니다. `select(null)`은 선택을 해제하고 `complete: false`와 함께 `change`를 전달합니다. 외부에서 완전히 제어하려면 `autoSelect={false}`와 함께 사용하세요.

**매개변수**

**input** `string | null` *required*

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

### `mount`

`target`에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.

**매개변수**

**target** `string | HTMLElement` *required*

### `destroy`

엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.

### `update`

마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.

**매개변수**

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

## 스타일링

`appearance.classes`를 통해 다음 부분의 스타일을 지정합니다. 속성 이름은 카멜 케이스 또는 케밥 케이스를 사용하고 단위를 포함하세요. 페이지 스타일시트는 엘리먼트의 프레임에 적용되지 않습니다. 프레임워크는 각 선언을 삽입하기 전에 유효성을 검사합니다.

| 클래스 | 대상 |
| - | - |
| `.whop-Address` | 주소 양식 루트 |
| `.whop-AddressErrorSummary` | 유효성 검사에서 누락되거나 잘못된 필드가 드러날 때 표시되는 요약 줄 |
| `.whop-AddressField` | 주소 양식의 필드 셀 하나 |
| `.whop-AddressFieldError` | 주소 필드의 오류 줄: 전체 레이아웃에서는 필드 아래, 컴팩트 레이아웃에서는 작성기 메시지용으로 그룹 아래에 표시 |
| `.whop-AddressFieldInput` | 주소 양식의 텍스트 입력 |
| `.whop-AddressFieldInputInvalid` | 주소 입력이 유효성 검사에 실패하는 동안 추가됨 |
| `.whop-AddressFieldInvalid` | 컴팩트 필드 셀이 유효성 검사에 실패하는 동안 추가됨 |
| `.whop-AddressFieldLabel` | 주소 필드 레이블: 필드 위, 또는 플로팅 레이블 사용 시 필드 안 |
| `.whop-AddressFieldSelect` | 주소 양식의 선택 항목(국가, 주, 조직 유형) |
| `.whop-AddressGroup` | 컴팩트 레이아웃에서 모든 필드를 담는 테두리 그룹 |
| `.whop-AddressLine2Toggle` | 접힌 주소 2행 토글 |
| `.whop-AddressManualEntry` | 접힌 양식 아래의 "Enter address manually" 텍스트 버튼 — 국가별 전체 형식을 펼침 |
| `.whop-AddressSearchButton` | 휴대폰에서 거리 필드 끝에 있는 검색 버튼 |
| `.whop-AddressSuggestion` | 자동 완성 오버레이의 제안 행 하나 |
| `.whop-AddressSuggestionActive` | 키보드/포인터로 활성화된 제안 행에 추가됨 |
| `.whop-AddressSuggestionManual` | 제안 목록을 마무리하는 "Enter address manually" 행 |
| `.whop-AddressSuggestions` | 주소 1행 필드에 고정된 자동 완성 제안 오버레이 |
| `.whop-AddressSuggestionsEmpty` | 검색어 입력이 끝났지만 일치하는 주소가 없을 때 표시되는 조용한 안내 줄 |
| `.whop-CardField` | 카드 번호, 만료일 또는 보안 코드 필드 |
| `.whop-CardFieldError` | 카드 유효성 검사 메시지 |
| `.whop-CardFieldGroup` | 그룹화된 카드 필드 — 위에는 번호, 아래에는 만료일과 보안 코드 |
| `.whop-CardFieldInput` | 테두리가 있는 PCI 입력 컨테이너 |
| `.whop-CardFieldInputFocused` | 포커스된 PCI 입력 컨테이너 |
| `.whop-CardFieldInputInvalid` | 잘못되었거나 불완전한 PCI 입력 컨테이너 |
| `.whop-CardLabel` | 카드 정보 레이블 |
| `.whop-Payment` | 결제 엘리먼트 루트 |
| `.whop-PaymentBalance` | 잔액 타일의 지갑 하나 |
| `.whop-PaymentBalanceHint` | 청구 통화 기준 지갑의 사용 가능 금액 |
| `.whop-PaymentBalanceList` | 잔액 타일에서 구매자의 지갑을 스크롤할 수 있는 목록 |
| `.whop-PaymentBalanceMore` | 화면에 스크롤되어 들어오면 잔액을 더 불러오는 감시용 행 |
| `.whop-PaymentBalanceRow` | 클릭 가능한 잔액 행 |
| `.whop-PaymentBalanceRowSelected` | 선택된 잔액 행 |
| `.whop-PaymentBalanceRowUnavailable` | 현재 결제할 수 없는 지갑 — 차단되었거나 비어 있음 — 회색으로 비활성화됨 |
| `.whop-PaymentBillingBlock` | 결제 엘리먼트 내부의 청구지 주소 블록 |
| `.whop-PaymentCardFields` | 인라인 카드 필드 패널 |
| `.whop-PaymentCompactBalance` | 컴팩트 직접 체크아웃에서 선택된 잔액 |
| `.whop-PaymentCompactSavedMethod` | 컴팩트 직접 체크아웃에서 선택된 저장된 결제 수단 |
| `.whop-PaymentCurrencyFallback` | 제공되는 결제 수단이 없을 때 대체 통화로 전환하는 컨트롤 |
| `.whop-PaymentDetailIcon` | 세부 영역 설명 옆의 템플릿 아이콘 |
| `.whop-PaymentDetailRegion` | 선택된 결제 수단의 펼쳐진 세부 영역 — 수집 영역(인라인 카드 필드, 선언된 입력)이 먼저 오고, 설명과 고지 줄이 하단 블록으로 표시됨 |
| `.whop-PaymentDetailSubtext` | 지갑 결제 수단에서 설명 아래에 표시되는 동의 보조 문구 |
| `.whop-PaymentDetailText` | 세부 영역의 설명 줄 |
| `.whop-PaymentError` | 사용 가능한 결제 수단 없음 오류 패널 |
| `.whop-PaymentFieldError` | 선언된 입력 아래의 Invalid 메시지 |
| `.whop-PaymentFieldInput` | 세부 영역의 선언된 결제 수단 입력 |
| `.whop-PaymentFieldInputInvalid` | 선언된 입력의 값이 선언된 형식에 맞지 않는 동안 추가됨 |
| `.whop-PaymentFieldLabel` | 선언된 결제 필드 레이블 |
| `.whop-PaymentInstallmentDetail` | 할부 옵션 행의 회차별 금액 |
| `.whop-PaymentInstallmentLabel` | 할부 옵션 행의 레이블 |
| `.whop-PaymentInstallmentList` | 할부 선택기의 옵션 목록 |
| `.whop-PaymentInstallmentRadio` | 할부 옵션 행의 라디오 표시기 |
| `.whop-PaymentInstallmentRow` | 할부 옵션 행 하나 |
| `.whop-PaymentInstallmentRowSelected` | 선택된 할부 옵션 행 |
| `.whop-PaymentInstallments` | 결제 수단 할부 선택기 |
| `.whop-PaymentInstallmentsLabel` | 할부 선택기의 제목 |
| `.whop-PaymentInstallmentsNotice` | 수수료가 선언되지 않은 선택 단계 아래의 발급사 수수료 고지 |
| `.whop-PaymentMandateLink` | 위임(mandate) 안내 안의 위임 약관 링크 |
| `.whop-PaymentMandateNotice` | 매트릭스 구성에서 위임을 선언한 결제 수단의 위임 승인 안내 |
| `.whop-PaymentMethod` | 결제 수단 하나 — 행과 펼쳐지는 세부 영역 |
| `.whop-PaymentMethodDetail` | 선택된 결제 수단의 세부 정보를 보여 주는 펼침 영역 — 인라인 카드 필드, 설명 또는 선언된 입력 |
| `.whop-PaymentMethodIcon` | 행의 결제 수단 아이콘 |
| `.whop-PaymentMethodLabel` | 행의 결제 수단 표시 이름 |
| `.whop-PaymentMethodMoreSelect` | More 타일 위에 펼쳐진 보이지 않는 네이티브 선택 항목 |
| `.whop-PaymentMethodMoreTile` | 결제 수단 아이콘과 네이티브 선택기가 있는 초과 항목 타일 |
| `.whop-PaymentMethodPanel` | 타일 행 아래에 있는 선택된 결제 수단의 세부 패널(가로 레이아웃) |
| `.whop-PaymentMethodRadio` | 결제 수단 행의 라디오 표시기 |
| `.whop-PaymentMethodRadioSelected` | 선택된 결제 수단 라디오 |
| `.whop-PaymentMethodRow` | 클릭 가능한 결제 수단 행 |
| `.whop-PaymentMethodRowSelected` | 선택된 결제 수단 행 |
| `.whop-PaymentMethods` | 결제 수단 목록 |
| `.whop-PaymentMethodSelected` | 선택된 결제 수단에 추가됨 — 해당 행과 펼쳐진 세부 영역 |
| `.whop-PaymentMethodSeparated` | 결제 수단 항목 또는 추가 결제 수단 확장 행이 별도 카드로 렌더링되는 동안 추가됨 |
| `.whop-PaymentMethodsSeparated` | 분리된 아코디언 결제 수단 목록 |
| `.whop-PaymentMethodTile` | 가로 타일 행의 결제 수단 타일 하나 |
| `.whop-PaymentMethodTileRow` | 마지막 More 타일에 초과 결제 수단이 들어가는 가로 결제 수단 타일 행 |
| `.whop-PaymentMethodTileSelected` | 선택된 결제 수단 타일 |
| `.whop-PaymentMoreRow` | "N more payment methods" 확장 행 |
| `.whop-PaymentPayerDocument` | 통화별 구매자 신원 문서 필드 |
| `.whop-PaymentPayerDocumentError` | 구매자 신원 문서 오류 |
| `.whop-PaymentPayerDocumentLabel` | 구매자 신원 문서 레이블 |
| `.whop-PaymentPayerDocumentType` | 구매자 신원 문서 유형 선택기 |
| `.whop-PaymentSavedMethod` | 저장된 결제 수단 하나 전용 — PaymentMethod도 함께 가짐 |
| `.whop-PaymentSavedMethodHint` | 저장된 결제 수단의 후행 세부 정보 — 카드 만료일 |
| `.whop-PaymentSavedMethodRow` | 저장된 결제 수단 전용의 클릭 가능한 행 — PaymentMethodRow도 함께 가짐 |
| `.whop-PaymentSavedMethodRowSelected` | 선택된 저장된 결제 수단 행 |
| `.whop-PaymentSavedMethods` | 저장된 결제 수단 목록 전용 — PaymentMethods도 함께 가지므로 하나의 규칙으로 두 목록의 스타일을 모두 지정 |
| `.whop-PaymentSavedMethodSeparated` | 저장된 결제 수단 전용의 분리 표시 |
| `.whop-PaymentSavedMore` | 저장된 결제 수단의 다음 페이지를 가져오는 컨트롤 |
| `.whop-PaymentSavedMoreSpinner` | 저장된 결제 수단의 다음 페이지를 불러오는 동안 표시되는 스피너 |
| `.whop-PaymentSettlementNotice` | 매트릭스 구성에서 정산 기간을 선언한 결제 수단의 정산 기간 힌트 |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Address': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressErrorSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressField': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// 90 classes use this shape
payments.update({
  appearance: { classes: { 'whop-Address': { fontWeight: '700' } } }
});
```

React에서는 `appearance`를 `<Payments>`에 전달합니다. 전역으로 설정하려면 `WhopElements({ appearance })`를 사용하세요.

## 매개변수

**order** `[WhopPaymentMethodType]`

이 마운트의 타일 순서로, 컨트롤러의 `methodOrder`를 재정의합니다. 나열된 유형은 목록의 위치를 따르고, 나머지는 그 뒤에서 들어온 순서를 유지합니다.

**selection** `Binding\<WhopPaymentSelection\>?`

현재 선택과 완료 여부를 다시 읽어 옵니다. 컨트롤러는 어느 쪽이든 둘 다 추적합니다.

## `WhopPaymentSelection`

선택 시 반환되는 값:

* `isComplete: Bool`: 선택한 결제 수단에 필요한 모든 항목이 있음
* `type: WhopPaymentMethodType?`: 선택한 결제 수단
* `displayName: String?`: 매트릭스에 표기된 레이블
* `category: String?`: `card`, `wallet`, `bank_debit`, …

## 상태

결제 수단 매트릭스가 로드되는 동안 스켈레톤 타일을 표시하고, 읽기에 실패하면 실패 메시지를 표시합니다. 이 빌드에서 실행할 수 없는 카테고리의 결제 수단은 깨진 타일로 렌더링하지 않고 건너뜁니다. 지갑을 선택하면 확인 영역이 Apple Pay로 바뀝니다.

## 알아두면 좋은 점

* Apple Pay는 앱에서 아무것도 필요로 하지 않습니다. 판매자 식별자나 `In-App Payments` 기능이 필요 없습니다. 판매자는 Whop 계정에 등록된 판매자이며, 기기가 결제할 수 있으면 언제든 타일이 렌더링됩니다.
* `secure` 필드를 선언하는 결제 수단은 이를 호스팅 입력으로 렌더링합니다. 해당 값은 앱 프로세스에 절대 들어오지 않습니다.
* 로그인한 구매자의 저장된 결제 수단은 새 결제 수단 위에 표시됩니다. 자격 증명을 생성하는 로그인을 제공하려면 [`WhopEmailElement`](https://docs.whop.com/ko/elements/latest/payments/email#swift)를 마운트하세요. 저장된 행을 선택하면 아무것도 수집하지 않고 참조를 생성합니다.
* 할부 단계를 게시하는 카드 청구는 카드 패널 안에 플랜 선택기를 표시합니다. 구매자의 카드로 이용할 수 없는 플랜은 흐리게 표시되지 않고 접히며, 지역이 청구지 국가와 맞지 않는 플랜은 토크나이저가 실행되기 전에 거부됩니다.
* 신분 문서가 필요한 시장(현재는 `ars` 청구)은 패널 안에 유형 선택기와 번호 필드를 렌더링합니다. 이 번호는 카드와 달리 토크나이저로 가는 도중 앱을 거치지만, 여전히 Whop에는 도달하지 않습니다.
* 카드 및 보안 필드 값은 토큰 생성 전에 토큰화되므로, 앱을 거치는 것은 확인 토큰뿐입니다.
* 결제 수단에 청구지 국가가 필요한 경우 [`WhopAddressElement`](https://docs.whop.com/ko/elements/latest/payments/address#swift)를 옆에 마운트하세요. 타일 목록이 해당 국가에서 허용하는 결제 수단으로 좁혀집니다.

## 설치

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/whopio/elements-swift.git", from: "0.1.0")
]
```

> [!NOTE]
>
> 컨트롤러를 생성하여 콘텐츠에 전달하는 `WhopPayments(accountID:charge:)` 스코프 안에 마운트하세요. 이메일 로그인으로 구매자가 확인되면 `payments.buyer`는 로그인한 구매자입니다. Whop은 이러한 판매의 판매 대행자이며 `createConfirmationToken`은 `WhopBrandingElement` 없이는 거부되므로, 이 엘리먼트도 화면에 있어야 합니다. 스타일은 `.whopElementsAppearance(_:)`로 지정합니다. 모듈은 지갑 SDK의 `WhopElements`가 아니라 `Elements`입니다. [시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md) 및 [Appearance](https://docs.whop.com/ko/elements/latest/appearance.md)를 참고하세요.

## Props

**order** `string[]`

Stripe의 `paymentMethodOrder`와 같은 의미의 결제 수단 표시 순서입니다. 나열되지 않은 유형은 나열된 유형 뒤에서 들어온 상대적 순서를 유지합니다. `<Payments>`에서 한 번 설정할 수도 있습니다.

**onChange** `(payload: PaymentChangePayload) =\> void`

선택과 완료 여부가 변경될 때마다 실행됩니다. 제출 버튼은 `complete`로 제어하세요.

**style** `StyleProp\<ViewStyle\>`

엘리먼트의 외부 `View`에 적용됩니다. 테마 지정에는 이 화면의 모든 엘리먼트에 적용되는 프로바이더의 `appearance.parts`를 사용하는 것이 좋습니다. 현재 React Native 파트 이름은 웹의 `whop-*` 클래스 이름과 별개의 체계이므로, 웹 appearance 객체를 그대로 옮겨 쓸 수 없습니다.

**fallback** `ReactNode`

엘리먼트가 로드되는 동안 기본 스켈레톤 대신 렌더링됩니다.

**onReady** `() =\> void`

엘리먼트가 상호작용 가능해지면 한 번 실행됩니다. `<Payments>`가 이를 그룹화하므로 보통은 `<Payments>` 자체의 `onLoadingChange`를 사용하는 것이 좋습니다.

**onError** `(error: \{ message: string; code?: string \}) =\> void`

이 엘리먼트의 로드 또는 구성 실패입니다. 어떤 경우든 엘리먼트는 자체 오류 화면을 렌더링합니다.

## `PaymentChangePayload`

`onChange`가 반환하는 값:

* `complete: boolean`: 선택한 결제 수단에 필요한 모든 항목이 있음
* `type?: string`: 선택한 결제 수단 유형(예: `card`)
* `method?: { type, category, template, display_name }`: 선택한 결제 수단의 매트릭스 항목

## 상태

결제 수단 매트릭스가 도착할 때까지 세 개의 스켈레톤 행이 표시된 후 타일이 표시됩니다. 타일을 선택하면 그 아래에 세부 영역이 펼쳐집니다. 선택한 결제 수단에 필요한 모든 항목이 있으면 `onChange`가 `complete`를 보고하며, 이것이 제출 버튼을 제어합니다. 사용 가능한 결제 수단이 없는 청구는 아무것도 렌더링하지 않는 대신 설명이 담긴 빈 상태를 렌더링합니다.

## 알아두면 좋은 점

* 카드 번호는 절대 코드를 거치지 않습니다. 필드는 PCI 격리된 네이티브 입력이고 SDK는 Whop에 토큰을 전달하므로, 앱은 PCI 범위 밖에 머뭅니다.
* Apple Pay와 Google Pay는 모두 플랫폼 자체의 시트를 표시합니다. 둘 다 아무것도 필요로 하지 않습니다. Apple Pay는 Whop 계정에 등록된 판매자를 사용하므로 전달할 판매자 식별자나 Xcode에서 추가할 기능이 없으며, `googlePayMerchantName`은 시트에 표시되는 이름만 설정하고 기본값은 Whop입니다.
* 리디렉션 결제 수단과 3D Secure는 iOS에서는 `ASWebAuthenticationSession`을, Android에서는 Custom Tabs를 엽니다. WebView가 아닌 시스템 브라우저를 사용하므로 발급사의 페이지는 앱의 신뢰 경계 밖에 머뭅니다.
* `<Payments>`의 `returnUrl`을 직접 호스팅하는 **https** URL로 설정하세요. API는 https 또는 루프백 외에는 모두 거부하므로(`PaymentsApi::ValidateReturnUrl`) 커스텀 앱 스킴은 사용할 수 없습니다. 딥 링크를 등록할 필요는 없습니다. 발급사가 리디렉션한 후 `handleNextAction`이 결제가 확정될 때까지 폴링하고 브라우저를 직접 닫습니다.

> [!NOTE]
>
> 앱을 `<WhopElements getToken={…}>`로 한 번 감싼 다음, 엘리먼트를 `<Payments>`로 감싸 마운트하세요. [시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md) 및 [Appearance](https://docs.whop.com/ko/elements/latest/appearance.md)를 참고하세요.
