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

# DepositElement

> Whop 계정에 자금을 입금합니다. 금액 입력란과 계정에서 현재 사용 가능한 입금 수단을 렌더링합니다. 암호화폐(네트워크별 입금 주소와 QR 코드)와 은행 송금(정산 통화별 송금 정보)을 지원합니다. 비즈니스 계정의 입금 수단은 자격 증명 없이 확인되므로 어떤 페이지에서도 작동합니다. 개인(`user_`) 계정은 입금 수단을 본인에게만 공개하므로 `accessToken`을 전달하세요. 생략하면 뷰어 자신의 동일 출처 세션이 사용됩니다. 카드와 플랫폼 잔액은 선택 사항입니다. `savedCards`, `allowNewCard` 또는 `showPlatformBalance`를 전달하면 엘리먼트가 금액과 선택 항목을 수집한 다음 `cardDepositRequested` / `addCardRequested` / `platformBalanceSelected`를 발생시키고, 자체 화면이 완료되면 `showStep({ step: 'amount' })`을 호출할 때까지 기다립니다.

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

*Since `v1.0.0`.*

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

> [!NOTE]
>
> 이 엘리먼트는 **인라인**으로 마운트(`create`)하거나 **모달** 오버레이로 열 수(`createOverlay`) 있습니다.

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

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Wallet /* options */>
        <DepositElement onDepositInitiated={(e) => console.log(e)} onCardDepositRequested={(e) => console.log(e)} onAddCardRequested={(e) => console.log(e)} onBankSelected={(e) => console.log(e)} onIdentityVerificationRequested={(e) => console.log(e)} onPlatformBalanceSelected={(e) => console.log(e)} onDepositConfirmed={(e) => console.log(e)} onStepChanged={(e) => console.log(e)} onDismissed={(e) => console.log(e)} />
      </Wallet>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const wallet = window.WhopElements().wallet.create({ /* options */ });
  wallet.create('deposit', {
    onDepositInitiated: (e) => console.log(e),
    onCardDepositRequested: (e) => console.log(e),
    onAddCardRequested: (e) => console.log(e),
    onBankSelected: (e) => console.log(e),
    onIdentityVerificationRequested: (e) => console.log(e),
    onPlatformBalanceSelected: (e) => console.log(e),
    onDepositConfirmed: (e) => console.log(e),
    onStepChanged: (e) => console.log(e),
    onDismissed: (e) => console.log(e)
  }).mount('#wallet-deposit');
</script>
```

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

## Props

**accessToken** `string`

입금 수단을 확인할 때 개인(`user_`) 계정을 읽을 수 있게 하는 범위 지정 토큰입니다. `payout:account:read`가 필요하며, 은행 입금 수단을 프로비저닝하려면 `payout:account:update`도 필요합니다. 서버에서 `POST /api/v1/access_tokens`로 발급하세요. 생략하면 호출에 뷰어 자신의 세션이 사용되며, 이는 동일 출처에서만 응답합니다. 비즈니스 계정은 자격 증명 없이 확인됩니다.

**amount** `string`

금액을 미리 채우고 읽기 전용으로 만듭니다. 지불할 금액을 이미 알고 있는 흐름에 사용하세요. 0 이하의 금액과 정수 부분이 12자리를 넘는 금액은 무시되며, 나머지는 해당 통화의 소수 자릿수로 반올림됩니다. 기본값은 `""`입니다.

**showCrypto** `boolean`

계정에 입금 주소가 있으면 암호화폐 입금 수단을 제공합니다. 기본값은 `true`입니다.

**showBank** `boolean`

은행 송금 입금 수단을 제공합니다. 계정에 은행 정보가 생기기 전에도 표시되며, 이때 이를 선택하면 계정에 아직 신원 인증이 필요한 경우 뷰어에게 신원 인증을 요청하고, 그렇지 않은 경우 해당 입금 수단을 아직 사용할 수 없다고 알립니다. 기본값은 `true`입니다.

**savedCards** `DepositSavedCard[]`

이 결제자에 대해 이미 보유하고 있는 카드로, 입금 수단 행으로 렌더링됩니다. 하나를 선택하면 금액과 함께 `cardDepositRequested`가 발생하며, 엘리먼트가 직접 카드 결제를 수집하지는 않습니다. 기본값은 `[]`입니다.

**속성**

**id** `string` *required*

`cardDepositRequested`에 그대로 반환되는 결제 수단 ID입니다.

**label** `string` *required*

행 레이블입니다(예: `Visa •••• 4242`).

**cardBrand** `string | null`

행 아이콘을 선택하는 데 사용되는 브랜드 키입니다: `visa`, `mastercard`, `amex`, `discover`, `jcb`.

**allowNewCard** `boolean`

`addCardRequested`를 발생시키는 "Add card" 행을 추가하여 자체 카드 수집 흐름을 열 수 있게 합니다. 기본값은 `false`입니다.

**showPlatformBalance** `boolean`

금액 단계 없이 즉시 `platformBalanceSelected`를 발생시키는 "Platform balance" 행을 제공합니다. 기본값은 `false`입니다.

**cardFee** `DepositCardFee | null`

카드 행이 선택되었을 때 금액 아래에 미리 보여 줄 처리 수수료입니다. `percentageFee`는 퍼센트 포인트 단위이며(`2.9`는 2.9%), `fixedFee`와 `radarFee`는 주 통화 단위입니다(`0.3`은 \$0.30). 기본값은 `null`입니다.

**속성**

**percentageFee** `number` *required*

비율이 아닌 퍼센트 포인트입니다. `2.9`는 2.9%를 의미합니다.

**fixedFee** `number` *required*

주 통화 단위의 고정 수수료입니다. `0.3`은 \$0.30을 의미합니다.

**radarFee** `number` *required*

주 통화 단위의 사기 검사 수수료입니다.

**depositRailFees** `Partial\<Record\<"crypto" | "bank", DepositRailFee\>\>`

입금 수단 선택기 아래에 표시되는 계정의 입금 수수료를 입금 수단(`bank`, `crypto`)별로 재정의합니다. 생략된 입금 수단은 계정이 반환하는 수수료를 사용합니다. `percentageFee`는 퍼센트 포인트 단위이며(`1.5`는 1.5%), `fixedFeeUsd`는 입금 통화와 관계없이 USD 주 통화 단위입니다(`2`는 \$2.00). 금액을 입력하기 전에는 요율을, 입력한 후에는 청구 금액을 표시합니다. 기본값은 `{}`입니다.

**속성**

**crypto** `DepositRailFee`

**속성**

**percentageFee** `number` *required*

비율이 아닌 퍼센트 포인트입니다. `1.5`는 1.5%를 의미합니다.

**fixedFeeUsd** `number` *required*

USD 주 통화 단위의 고정 수수료입니다. 입금 통화와 관계없이 `2`는 \$2.00을 의미합니다.

**bank** `DepositRailFee`

**속성**

**percentageFee** `number` *required*

비율이 아닌 퍼센트 포인트입니다. `1.5`는 1.5%를 의미합니다.

**fixedFeeUsd** `number` *required*

USD 주 통화 단위의 고정 수수료입니다. 입금 통화와 관계없이 `2`는 \$2.00을 의미합니다.

**preferredMethodId** `string`

ID(`bank`, `crypto`, `platform_balance` 또는 저장된 카드 ID)로 입금 수단을 미리 선택합니다. 해당 입금 수단이 아직 제공되지 않는 동안에는 다른 수단으로 입금하는 대신 Continue가 비활성화된 상태로 유지됩니다. 기본값은 `""`입니다.

**deferBankToHost** `boolean`

송금 정보를 표시하는 대신 `bankSelected`를 발생시키고 금액 화면에 머뭅니다. 계정에 이미 가상 은행 계좌가 있을 때 자체 단계를 실행하는 호스트에 사용하세요. 기본값은 `false`입니다.

**confirmCryptoDeposit** `boolean`

암호화폐 화면에 `depositConfirmed`를 발생시키는 "I have deposited my funds" 버튼을 표시하여 이체 감시를 시작할 수 있게 합니다. 기본값은 `false`입니다.

**initialStep** `"amount" | "crypto" | "bank"`

선택기 대신 바로 특정 입금 수단 화면으로 엽니다. `crypto`와 `bank`는 금액이 필요 없으며, 그 뒤에 선택기가 없으므로 뒤로 가기 버튼은 `dismissed`를 발생시킵니다. 기본값은 `"amount"`입니다.

## 이벤트

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

### `onDepositInitiated`

결제자가 금액과 입금 수단을 확정했습니다. 모든 입금 수단에 대해 안내가 렌더링되기 전에 발생하며, 분석/퍼널 추적용 훅입니다.

**payload** `object`

**속성**

**method** `"crypto" | "bank" | "card" | "platform_balance"` *required*

**amount** `number` *required*

**currency** `string` *required*

**paymentMethodId** `string`

### `onCardDepositRequested`

저장된 카드가 선택되었습니다. 직접 결제를 수집한 다음 `showStep({ step: "amount" })`를 호출하여 엘리먼트를 선택기로 되돌리세요.

**payload** `object`

**속성**

**amount** `number` *required*

**currency** `string` *required*

**paymentMethodId** `string` *required*

### `onAddCardRequested`

"Add card" 행이 선택되었습니다. 자체 카드 수집 흐름을 여세요.

### `onBankSelected`

`deferBankToHost`가 설정된 상태에서 은행 입금 수단이 선택되었습니다. 자체 단계를 실행한 다음 정보를 직접 표시하거나 `showStep({ step: "bank" })`를 호출하세요.

### `onIdentityVerificationRequested`

이 계정에 가상 은행 계좌가 생기기 전에 뷰어가 은행 송금을 선택했습니다. 엘리먼트는 금액 화면에 머물며 직접 페이지를 이동하지 않습니다. 이에 응답하여 `verifications` 컨트롤러 같은 자체 인증 화면을 마운트하세요.

**payload** `object`

**속성**

**accountId** `string` *required*

### `onPlatformBalanceSelected`

플랫폼 잔액 행이 선택되었습니다. 금액은 포함되지 않으며, 자체 화면에서 금액을 수집합니다.

### `onDepositConfirmed`

결제자가 암호화폐를 보냈다고 알렸습니다. `since`는 들어오는 이체를 매칭하기 시작할 하한 시점(유닉스 초)입니다. 약간 과거 시점을 기준으로 하므로 클릭 직전에 보낸 이체도 매칭됩니다.

**payload** `object`

**속성**

**network** `string` *required*

**token** `string` *required*

**networkLabel** `string` *required*

**since** `number` *required*

### `onStepChanged`

표시되는 화면이 변경되었습니다.

**payload** `object`

**속성**

**step** `"amount" | "crypto" | "bank"` *required*

### `onDismissed`

엘리먼트가 바로 열린 입금 수단 화면에서 결제자가 뒤로 나갔습니다. 엘리먼트를 담고 있는 화면을 닫으세요.

### `onLoaderStart`

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

### `onReady`

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

### `onError`

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

**e** `object`

**속성**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

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

### `showStep`

엘리먼트를 특정 화면으로 이동합니다. 카드 또는 플랫폼 잔액 입금을 직접 처리한 후 `{ step: "amount" }`로 제어권을 엘리먼트에 돌려줍니다.

**매개변수**

**input** `object` *required*

**속성**

**step** `"amount" | "crypto" | "bank"` *required*

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

### `refresh`

계정의 입금 수단을 다시 확인합니다. 은행 온보딩 완료처럼 계정이 제공할 수 있는 수단을 바꾸는 변경이 있은 후 호출하면 캐시 만료를 기다리지 않고 새 입금 수단이 표시됩니다.

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

### `mount`

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

**매개변수**

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

### `destroy`

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

### `update`

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

**매개변수**

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

## 스타일링

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

| 클래스 | 대상 |
| - | - |
| `.whop-DepositSurface` | deposit 엘리먼트 루트 — 한 번에 한 화면 |

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

wallet.update({
  appearance: {
    classes: { 'whop-DepositSurface': { fontWeight: '700' } }
  }
});
```

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