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

# 하위 계정 지급 활성화

> 하위 계정이 Whop Elements 또는 호스팅 포털로 자신의 지급을 직접 관리할 수 있도록 하세요

하위 계정이 고객 확인(KYC) 인증을 완료하고, 지급 수단을 추가하고, 자금을 직접 출금할 수 있도록 하세요. [Whop Elements](https://docs.whop.com/ko/elements/latest/getting-started.md) 지갑 화면을 앱에 직접 마운트하거나 사용자를 Whop이 호스팅하는 포털로 리디렉션할 수 있습니다.

## 임베디드 지급 포털

### 서버 측 구현

지갑 엘리먼트를 마운트하려면 서버에서 하위 계정에 대한 액세스 토큰을 생성하세요. 엘리먼트는 이 토큰으로 해당 계정의 잔액과 지급 내역을 읽습니다. 토큰의 범위를 지정하는 방법과 Whop의 다른 자격 증명 유형과의 비교는 [인증 & API 키](https://docs.whop.com/ko/developer/guides/auth-scoping.md)를 참고하세요.

```tsx Next.JS theme={null}
// app/api/token/route.ts
import { WhopClient } from "@whop/sdk";
import type { NextRequest } from "next/server";

const whop = new WhopClient({
	token: process.env.WHOP_API_KEY,
});

export async function GET(request: NextRequest) {
	// Authenticate your user here
	const accountId = request.nextUrl.searchParams.get("accountId");

	if (!accountId) {
		return new Response(null, { status: 400 });
	}
	const tokenResponse = await whop.accessTokens
		.create({
			account_id: accountId,
		})
		.catch(() => {
			return null;
		});
	if (!tokenResponse) {
		return new Response(null, { status: 500 });
	}
	const token = tokenResponse.token;
	return Response.json({
		token,
	});
}
```

```typescript Express.js theme={null}
import express from "express";
import { WhopClient } from "@whop/sdk";

const app = express();
const client = new WhopClient({ token: "Account API Key" });

app.use(express.json());

app.post("/api/access-token", async (req, res) => {
	// Authenticate your user here
	const { accountId } = req.body;

	const { token } = await client.accessTokens.create({
		account_id: accountId,
	});

	res.json({ token });
});

app.listen(3000, () => {
	console.log("Server running on port 3000");
});
```

```python Python theme={null}
from whop_sdk import Whop
from flask import Flask, request, jsonify

app = Flask(__name__)
client = Whop(token="Account API Key")

@app.route('/api/access-token', methods=['POST'])
def create_access_token():
    data = request.get_json()
    # Authenticate your user here
    account_id = data.get('accountId')

    access_token = client.access_tokens.create(
        account_id=account_id
    )

    return jsonify({'token': access_token.token})
```

> [card] [Create Access Token API](https://docs.whop.com/ko/api-reference/legacy/access-tokens/create-access-token.md)
>
> 액세스 토큰 생성 및 사용 가능한 모든 매개변수에 대한
> 전체 API 레퍼런스를 확인하세요

## 클라이언트 측 설정

```bash npm theme={null}
npm install @whop/elements-react @whop/elements
```

```bash pnpm theme={null}
pnpm add @whop/elements-react @whop/elements
```

```html HTML theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
```

## 클라이언트 측 구현

하위 계정에 대한 `Wallet` 핸들을 하나 생성하고 필요한 화면을 그 아래에 마운트하세요. 핸들은 하위의 모든 엘리먼트에 액세스 토큰을 전달하므로, 해당 엘리먼트들이 읽는 모든 범위를 포함하는 토큰 하나를 발급하세요.

```tsx React theme={null}
"use client";

import { useEffect, useState } from "react";
import {
	ActivityElement,
	BalanceElement,
	Balances,
	Wallet,
	WhopElements,
	WithdrawElement,
} from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

export function PayoutPortal({ accountId }: { accountId: string }) {
	const [accessToken, setAccessToken] = useState<string | null>(null);

	useEffect(() => {
		fetch(`/api/token?accountId=${accountId}`)
			.then((res) => res.json())
			.then((data) => setAccessToken(data.token));
	}, [accountId]);

	if (!accessToken) return null;

	return (
		<WhopElements elements={loadWhop()}>
			<Wallet accountId={accountId} accessToken={accessToken}>
				<Balances>
					<BalanceElement />
				</Balances>
				<WithdrawElement />
				<ActivityElement />
			</Wallet>
		</WhopElements>
	);
}
```

```html JavaScript theme={null}
<div id="balance"></div>
<div id="withdraw"></div>
<div id="activity"></div>

<script type="module">
  const accountId = "biz_xxxxxxxxxxxxx";
  const { token } = await (await fetch(`/api/token?accountId=${accountId}`)).json();

  const wallet = window.WhopElements().wallet.create({ accountId, accessToken: token });
  wallet.create("balances").create("balance").mount("#balance");
  wallet.create("withdraw").mount("#withdraw");
  wallet.create("activity").mount("#activity");
</script>
```

> [!NOTE]
>
> iOS에서 지갑 SDK는 `BalanceElement`, `ListElement`, `ActivityElement`를 제공합니다. [Elements 시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md)를 참고하고 Swift 탭을 선택하세요.

### 신원 인증

하위 계정은 출금하기 전에 신원을 인증해야 합니다. 세부 정보를 수집하고, 호스팅된 제공업체 세션을 실행하며, 결과를 보고하는 전체 페이지 내 흐름을 위해 [KYC 엘리먼트](https://docs.whop.com/ko/elements/latest/verifications/kyc.md)를 마운트하세요. 또는 [RequiredActions 엘리먼트](https://docs.whop.com/ko/elements/latest/dashboard/required-actions.md)를 마운트하여 인증을 포함한 모든 미완료 작업을 표시하고 사용자가 각 작업을 시작하도록 하세요.

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

export function VerifyIdentity({ accountId }: { accountId: string }) {
	return (
		<WhopElements elements={loadWhop()}>
			<Verifications
				accountId={accountId}
				getToken={() =>
					fetch(`/api/token?accountId=${accountId}`)
						.then((res) => res.json())
						.then((data) => data.token)
				}
			>
				<KycElement onCompleted={() => console.log("Verified")} />
			</Verifications>
		</WhopElements>
	);
}
```

## `Wallet` 옵션

| 옵션 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `accountId` | `string` | 예 | `biz_` 접두사가 붙은 하위 계정의 ID. |
| `accessToken` | `string` | 예, 자체 도메인에서 | 서버에서 받은 토큰. 이 토큰이 없으면 읽기 작업은 뷰어의 whop.com 세션을 사용하며, 이는 whop.com에서만 작동합니다. |
| `currency` | `string` | 아니요 | 금액 필드의 ISO 4217 코드. 기본값은 `usd`. |
| `appearance` | `Appearance` | 아니요 | 핸들 아래 모든 엘리먼트의 테마 및 부분별 스타일링. [Appearance](https://docs.whop.com/ko/elements/latest/appearance.md)를 참고하세요. |

모든 옵션, 이벤트, 메서드는 [Wallet 레퍼런스](https://docs.whop.com/ko/elements/latest/wallet/overview)에 나열되어 있습니다.

### 범위

엘리먼트는 발급한 토큰으로 데이터를 읽으므로, 필요한 모든 범위를 해당 토큰 하나에 부여하세요:

* [Balances](https://docs.whop.com/ko/elements/latest/wallet/balances)와 [Activity](https://docs.whop.com/ko/elements/latest/wallet/activity.md)는 `company:balance:read`로 읽습니다.
* [Withdraw](https://docs.whop.com/ko/elements/latest/wallet/withdraw.md)는 `payout:withdraw_funds`, `payout:destination:read`가 필요하며, 은행을 추가하려면 `payout:create_destination`이 필요합니다.
* [KYC](https://docs.whop.com/ko/elements/latest/verifications/kyc.md)는 `identity:read`와 `identity:write`가 필요합니다.

`scoped_actions` 없이 생성된 토큰은 API 키의 모든 권한을 상속합니다.

### 토큰 갱신

액세스 토큰은 기본적으로 1시간 후에 만료되며 최대 3시간까지 유지됩니다. 만료되기 전에 핸들에 새 토큰을 설정하세요:

```ts theme={null}
wallet.update({ accessToken: await fetchToken(accountId) });
```

React에서는 새 값을 `accessToken` prop으로 전달하세요.

> [!NOTE]
>
> `accessToken`은 SDK가 호출하는 콜백이 아니라 직접 설정하는 값입니다. `Verifications`는 예외로, `getToken` 콜백을 받아 엘리먼트가 마운트되기 전에 호출합니다.

## 호스팅된 지급 포털

앱에 지급 포털을 임베드하는 대신 사용자를 Whop이 호스팅하는 지급 포털로 리디렉션할 수 있습니다. 사용자 지정 UI를 구축하고 싶지 않거나 빠른 통합이 필요한 경우에 유용합니다.

계정 링크를 생성하고 반환된 URL로 사용자를 리디렉션하세요:

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({
	token: "Account API Key",
});

const accountLink = await client.accountLinks.create({
	account_id: "biz_xxxxxxxxxxxxx",
	use_case: "payouts_portal",
	return_url: "https://yourapp.com/payouts/complete",
	refresh_url: "https://yourapp.com/payouts/refresh",
});

// Redirect the user to the hosted portal
console.log(accountLink.url);
```

```python Python theme={null}
from whop_sdk import Whop

client = Whop(
    token="Account API Key",
)

account_link = client.account_links.create(
    account_id="biz_xxxxxxxxxxxxx",
    use_case="payouts_portal",
    return_url="https://yourapp.com/payouts/complete",
    refresh_url="https://yourapp.com/payouts/refresh",
)

# Redirect the user to the hosted portal
print(account_link.url)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some("Account API Key".to_string()),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");

let account_link = client
    .account_links
    .create(
        &CreateAccountLinksRequest {
            account_id: "biz_xxxxxxxxxxxxx".to_string(),
            use_case: AccountLinkUseCases::PayoutsPortal,
            return_url: "https://yourapp.com/payouts/complete".to_string(),
            refresh_url: "https://yourapp.com/payouts/refresh".to_string(),
        },
        None,
    )
    .await?;

// Redirect the user to the hosted portal
println!("{}", account_link.url);
```

```go Go theme={null}
import (
    "context"
    "fmt"
    "log"

    whopsdk "github.com/whopio/whopsdk-go/v2"
    "github.com/whopio/whopsdk-go/v2/client"
    "github.com/whopio/whopsdk-go/v2/option"
)

client := client.NewWhop(option.WithToken("Account API Key"))

accountLink, err := client.AccountLinks.Create(context.TODO(), &whopsdk.CreateAccountLinksRequest{
    AccountID:  "biz_xxxxxxxxxxxxx",
    UseCase:    whopsdk.AccountLinkUseCasesPayoutsPortal,
    ReturnURL:  "https://yourapp.com/payouts/complete",
    RefreshURL: "https://yourapp.com/payouts/refresh",
})
if err != nil {
    log.Fatal(err)
}

// Redirect the user to the hosted portal
fmt.Println(accountLink.URL)
```

이 예시에서:

* `account_id`는 플랫폼 또는 하위 계정입니다
* `use_case`는 포털 유형을 지정합니다
* `return_url`은 사용자가 사이트로 돌아가려고 할 때 Whop이 사용자를 리디렉션하는 위치입니다
* `refresh_url`은 세션이 만료된 경우 Whop이 사용자를 리디렉션하는 위치입니다

### 사용 가능한 사용 사례

| 사용 사례 | 설명 |
| - | - |
| `account_onboarding` | KYC 및 신원 인증 |
| `payouts_portal` | 지급, 지급 수단, KYC 및 신원 인증 |

계정 링크를 생성한 후 응답으로 반환된 `url`로 사용자를 리디렉션하세요. 사용자는 Whop 호스팅 포털에서 지급 흐름을 완료하며, 이후 Whop이 사용자를 `return_url`로 리디렉션합니다.

## 관련 리소스

> [card] [지갑 엘리먼트](https://docs.whop.com/ko/elements/latest/wallet/overview)
>
> 옵션, 이벤트, 범위를 포함한 모든 지갑 화면

> [card] [하위 계정에 지급](https://docs.whop.com/ko/developer/platforms/collect-payments-for-subaccounts.md)
>
> 하위 계정으로 자금 이체


## Related topics

- [하위 계정에 수동 지급](https://docs.whop.com/ko/developer/platforms/manual-payouts.md)
- [통합 예제](https://docs.whop.com/ko/developer/guides/example-integration.md)
- [하위 계정 등록](https://docs.whop.com/ko/developer/platforms/enroll-subaccounts.md)
