> ## 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 API 빠른 시작

> 샌드박스에서 첫 Whop API 호출을 하고, 체크아웃을 만들고, 테스트 카드로 결제한 뒤 웹훅을 받아 보세요. 그런 다음 프로덕션으로 전환하세요.

이 빠른 시작은 돈이 절대 이동하지 않는 별도의 Whop 환경인 샌드박스에서 진행됩니다. 샌드박스 API 키를 발급받고, 첫 호출을 하고, 체크아웃을 만들고, 테스트 카드로 결제한 뒤 서버에서 `payment.succeeded` 웹훅을 받게 됩니다. 라이브 전환은 마지막 단계이며, 대부분 키를 바꾸는 작업입니다.

> [!TIP]
>
> 코딩 에이전트를 사용한다면 이 페이지를 Markdown(`https://docs.whop.com/developer/quickstart.md`)으로 제공하거나 [개요](https://docs.whop.com/ko/developer/start.md#build-with-your-coding-agent)의 프롬프트를 붙여 넣으세요.

## 샌드박스와 프로덕션

Whop은 아무것도 공유하지 않는 두 가지 환경을 운영합니다. 계정, 키, 상품, 웹훅 중 어느 것도 공유되지 않습니다. 샌드박스에서 빌드하고 프로덕션에서 출시합니다. 아래의 모든 값은 두 환경 간에 달라집니다.

| | 샌드박스: 빌드 및 테스트 | 프로덕션: 출시 |
| - | - | - |
| 돈 | 절대 이동하지 않음 | 실제 돈 |
| 대시보드 | [sandbox.whop.com](https://sandbox.whop.com) | [whop.com](https://whop.com) |
| API 키 및 웹훅 | [sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer) | [whop.com/dashboard/developer](https://whop.com/dashboard/developer) |
| API 기본 URL | `https://sandbox-api.whop.com/api/v1` | `https://api.whop.com/api/v1` |
| SDK 환경 | `Sandbox` | `Production`, SDK 기본값 |
| 체크아웃 페이지 | `sandbox.whop.com/checkout/...` | `whop.com/checkout/...` |
| `WHOP_ENVIRONMENT` | `sandbox` | `production` |

> [!WARNING]
>
> 샌드박스와 프로덕션 API 키는 생김새가 똑같아서, 키만 보고는 어느 환경에 속하는지 알 수 없습니다. 이 페이지의 스니펫은 환경을 하드코딩하지 않고 `WHOP_ENVIRONMENT` 변수에서 선택하므로, 같은 코드가 두 환경 모두에서 실행됩니다. [Whop MCP 서버](https://docs.whop.com/ko/developer/ai/overview.md#mcp-server)는 프로덕션 데이터에서만 작동합니다.

## 샌드박스 API 키 받기

**1. 샌드박스에 가입하기**

[sandbox.whop.com](https://sandbox.whop.com)으로 이동해 계정을 만드세요. 이 계정은 whop.com에 있는 계정과는 별개입니다. 가입 과정에서 첫 비즈니스가 생성되며, 이것이 API 키, 상품, 웹훅, 결제를 소유하는 계정입니다.

**2. 계정 API 키 만들기**

[sandbox.whop.com/dashboard/developer](https://sandbox.whop.com/dashboard/developer)를 여세요. **Account API Keys**에서 **Create**를 선택하고, 키 이름을 `Local development`처럼 지정하세요.

이 빠른 시작에서는 Admin 역할을 사용하세요. 프로덕션 전에는 호출하는 엔드포인트만 포함하는 사용자 지정 권한 세트로 전환하세요.

**3. 서버에 키 저장하기**

Whop이 키를 보여 줄 때 복사하고, 해당 키가 속한 환경과 함께 로컬 `.env` 파일에 넣으세요.

```bash theme={null}
WHOP_ENVIRONMENT=sandbox
WHOP_API_KEY=your_sandbox_key
```

![키 이름, 마스킹된 값, Create 버튼이 표시된 Whop 대시보드의 Account API Keys 섹션](https://mintcdn.com/whop/xuW6TKFlagvnbmV0/images/developer-api-key-field.png?fit=max\&auto=format\&n=xuW6TKFlagvnbmV0\&q=85\&s=699bf36af18f7a12dfd855eb0684b38e)

> [!NOTE]
>
> `WHOP_API_KEY`는 서버에 보관하세요. API 키를 브라우저 코드, 모바일 앱, 공개 저장소에 넣지 마세요. 샌드박스와 프로덕션 키는 생김새가 똑같으므로 구분할 수 있도록 이름을 지정하세요.

계정 API 키는 서버가 자신의 비즈니스를 대신해 작동할 때 적합합니다. 다른 비즈니스가 설치하는 앱을 빌드하거나 사용자가 Whop으로 로그인하게 하려면 [인증 및 API 키](https://docs.whop.com/ko/developer/guides/auth-scoping.md)를 참고하세요.

## SDK 설치하기

```bash TypeScript theme={null}
pnpm add @whop/sdk
```

```bash Python theme={null}
pip install whop-sdk
```

```bash Ruby theme={null}
gem install whop_sdk
```

> [!NOTE]
>
> 이 페이지에는 SDK 2.7.0 이상이 필요합니다. 이전 버전은 체크아웃 구성에서 인라인 `variant`를 허용하지 않습니다.

## 첫 호출하기

클라이언트가 `WHOP_ENVIRONMENT`에 지정된 환경을 가리키도록 하고 키에 연결된 계정을 조회하세요. 이렇게 하면 키가 작동하는지 확인되고, `biz_`로 시작하는 계정 ID가 출력됩니다.

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

const apiKey = process.env.WHOP_API_KEY;

if (!apiKey) {
  throw new Error("Set WHOP_API_KEY");
}

const client = new WhopClient({
  token: apiKey,
  environment: process.env.WHOP_ENVIRONMENT === "production" ? WhopEnvironment.Production : WhopEnvironment.Sandbox,
});

const account = await client.accounts.me();

console.log(account.id);
```

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

client = Whop(
    token=os.environ["WHOP_API_KEY"],
    environment=WhopEnvironment.PRODUCTION if os.environ.get("WHOP_ENVIRONMENT") == "production" else WhopEnvironment.SANDBOX,
)

account = client.accounts.me()

print(account.id)
```

```ruby Ruby theme={null}
require "whop_sdk"

whop = Whop_sdk::Client.new(
  token: ENV.fetch("WHOP_API_KEY"),
  environment: ENV["WHOP_ENVIRONMENT"] == "production" ? Whop_sdk::Environment::PRODUCTION : Whop_sdk::Environment::SANDBOX,
)

account = whop.accounts.me

puts account.id
```

```bash curl (sandbox) theme={null}
curl https://sandbox-api.whop.com/api/v1/accounts/me \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-11-04-1"
```

```json Response (trimmed) theme={null}
{
	"id": "biz_XXXXXXXX",
	"title": "Acme Studio",
	"route": "acme-studio",
	"status": "active"
}
```

> [!TIP]
>
> 이것이 샌드박스 계정입니다. 키가 작동합니다.

## 체크아웃 만들기

한 번의 호출로 변형을 만들고 `sandbox.whop.com`에서 호스팅되는 체크아웃 페이지인 `purchase_url`을 반환합니다.

```typescript TypeScript theme={null}
const checkout = await client.checkoutConfigurations.create({
	variant: {
		title: "Starter",
		billing_type: "one_time",
		initial_price: 10.0,
		currency: "usd",
	},
});

console.log(checkout.purchase_url);
```

```python Python theme={null}
checkout = client.checkout_configurations.create(
    variant={
        "title": "Starter",
        "billing_type": "one_time",
        "initial_price": 10.0,
        "currency": "usd",
    },
)

print(checkout.purchase_url)
```

```ruby Ruby theme={null}
checkout = whop.checkout_configurations.create(
  variant: {
    title: "Starter",
    billing_type: "one_time",
    initial_price: 10.0,
    currency: "usd",
  },
)

puts checkout.purchase_url
```

이 URL은 결제 단계에서 열게 됩니다. 이미 변형이 있다면 인라인 `variant` 대신 해당 ID를 `variant_id`로 전달하세요. 둘 다 보낼 수는 없습니다. [체크아웃 구성 만들기](https://docs.whop.com/ko/api-reference/checkout-configurations/create-a-checkout-configuration.md)에는 반복 가격, 체험, 리디렉션 URL을 포함한 모든 옵션이 나와 있습니다.

## 웹훅 수신하기

결제하기 전에 엔드포인트를 설정해 `payment.succeeded` 이벤트가 도착할 곳을 마련하세요.

**1. 엔드포인트 추가하기**

서명을 검증하고 이벤트를 기록하는 `POST` 라우트를 추가하세요. 검증에는 원시 요청 본문이 필요하므로 JSON 파싱 전에 읽어야 합니다.

```typescript TypeScript + Next.js theme={null}
import { unwrapWebhook } from "@whop/sdk/helpers";
import type { NextRequest } from "next/server";

export async function POST(request: NextRequest): Promise<Response> {
  const event = unwrapWebhook<{ type: string; data: { id: string } }>(await request.text(), {
    headers: Object.fromEntries(request.headers),
    key: process.env.WHOP_WEBHOOK_SECRET!,
  });

  console.log(event.type, event.data.id);

  return new Response("OK", { status: 200 });
}
```

```python Python + FastAPI theme={null}
import os

from fastapi import FastAPI, Request, Response
from whop_sdk.lib.verify_webhook import unwrap

app = FastAPI()

@app.post("/api/webhooks/whop")
async def whop_webhook(request: Request):
    event = unwrap(await request.body(), headers=dict(request.headers), key=os.environ["WHOP_WEBHOOK_SECRET"])

    print(event["type"], event["data"]["id"])

    return Response(status_code=200)
```

```ruby Ruby on Rails theme={null}
class Api::WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def whop
    event = WhopSDK::Helpers::VerifyWebhook.unwrap(
      request.raw_post,
      headers: {
        "webhook-id" => request.headers["webhook-id"],
        "webhook-timestamp" => request.headers["webhook-timestamp"],
        "webhook-signature" => request.headers["webhook-signature"],
      },
      key: ENV.fetch("WHOP_WEBHOOK_SECRET"),
    )

    Rails.logger.info("#{event[:type]} #{event[:data][:id]}")

    head :ok
  end
end
```

개발하는 동안에는 ngrok, Cloudflare Tunnel 또는 다른 터널로 라우트를 HTTPS로 노출하세요.

**2. 샌드박스 대시보드에서 웹훅 만들기**

샌드박스 대시보드에서 **Developer > Webhooks**를 연 다음 **Create webhook**을 선택하세요. 엔드포인트의 HTTPS 주소를 붙여 넣고, API 버전은 `v1`으로 유지한 채 `payment.succeeded`를 선택하세요.

![이벤트 목록에서 payment\_succeeded 이벤트가 선택된 웹훅 만들기 양식](https://mintcdn.com/whop/RLIxcN4GVU-CLB5B/images/create-webhook-select-events.png?fit=max\&auto=format\&n=RLIxcN4GVU-CLB5B\&q=85\&s=079887392e21e4680a82415244aeaea4)

**3. 서명 시크릿 저장하기**

웹훅의 **Secret** 열에서 시크릿을 복사하고, `ws_` 접두사를 포함해 표시된 그대로 `.env`에 추가하세요.

```bash theme={null}
WHOP_WEBHOOK_SECRET=ws_your_secret
```

새 값이 반영되도록 서버를 다시 시작하세요.

## 테스트 카드로 결제하기

체크아웃 단계에서 받은 `purchase_url`을 열고 다음 정보로 결제하세요.

| 필드 | 값 |
| - | - |
| 카드 번호 | `4242 4242 4242 4242` |
| 만료일 | `12/34`처럼 미래의 아무 날짜 |
| CVC | `123`처럼 아무 3자리 숫자 |
| 청구지 주소 | 아무 주소 |

몇 초 안에 서버가 `payment.succeeded`와 `pay_`로 시작하는 결제 ID를 기록합니다.

> [!TIP]
>
> 결제를 받고 해당 웹훅을 처음부터 끝까지 처리했습니다. 실제로 청구된 금액은 없습니다.

거절된 카드나 3D Secure를 테스트하려면 [테스트 카드](https://docs.whop.com/ko/developer/guides/sandbox.md#test-cards)의 다른 번호를 사용하세요. 아무것도 도착하지 않으면 대시보드에서 웹훅의 전송 로그와 [웹훅 전송](https://docs.whop.com/ko/developer/troubleshooting.md#webhook-delivery)을 확인하세요.

## 라이브로 전환하기

샌드박스와 프로덕션은 아무것도 공유하지 않으므로, 라이브 전환은 프로덕션 자격 증명으로 whop.com에서 설정을 반복하는 것을 의미합니다. 코드는 바뀌지 않습니다. 환경의 값만 바뀝니다.

**1. 프로덕션 키 만들기**

[whop.com](https://whop.com/start)에 로그인하고 [whop.com/dashboard/developer](https://whop.com/dashboard/developer)를 연 다음, 통합에서 사용하는 권한만 가진 계정 API 키를 만드세요.

**2. 모든 값을 프로덕션 값으로 바꾸기**

프로덕션 환경에서 세 변수를 모두 프로덕션 값으로 설정하세요. 샌드박스 키나 시크릿을 프로덕션에서 재사용하거나 그 반대로 하지 마세요.

```bash Sandbox theme={null}
WHOP_ENVIRONMENT=sandbox
WHOP_API_KEY=your_sandbox_key
WHOP_WEBHOOK_SECRET=ws_your_sandbox_secret
```

```bash Production theme={null}
WHOP_ENVIRONMENT=production
WHOP_API_KEY=your_production_key
WHOP_WEBHOOK_SECRET=ws_your_production_secret
```

API를 직접 호출한다면 기본 URL을 `https://api.whop.com/api/v1`로 바꾸세요.

**3. 샌드박스에서 만든 것 다시 만들기**

상품, 변형, 체크아웃 구성, 웹훅은 이전되지 않습니다. 프로덕션 URL로 프로덕션 웹훅을 만들고 새 서명 시크릿을 저장하세요.

**4. API 버전 고정하기**

SDK는 빌드 기준이 된 버전을 전송합니다. API를 직접 호출한다면 이후 변경 사항이 응답을 바꾸지 않도록 모든 요청에 `Api-Version-Date`를 보내세요. [API 버전 관리](https://docs.whop.com/ko/developer/api/versioning.md)를 참고하세요.

> [!WARNING]
>
> 프로덕션 체크아웃 링크는 실제 돈을 받습니다. 청구를 만들거나 잔액을 이동시키는 작업을 실행하기 전에 어떤 키를 사용하고 있는지 확인하세요.

## 이제 원래 만들려던 것을 빌드하세요

> [card] [구독 또는 일회성 상품을 판매합니다](https://docs.whop.com/ko/developer/guides/accept-payments.md)
>
> 체크아웃 링크, Checkout 엘리먼트, 변형, 체험.

> [card] [다른 사람들에게 돈을 지급해야 합니다](https://docs.whop.com/ko/developer/platforms/manual-payouts.md)
>
> 지급, 이체, 잔액, 지급 포털.

> [card] [다른 사람들의 판매에서 수수료를 받습니다](https://docs.whop.com/ko/developer/platforms/quickstart.md)
>
> 하위 계정, 대신 수금하기, 지급하기.

> [card] [인프라뿐 아니라 유통도 원합니다](https://docs.whop.com/ko/developer/guides/app-views.md)
>
> 인증, 뷰, CLI를 갖추고 Whop 안에서 실행되는 앱.

> [card] [제품에 사람들 간의 대화가 필요합니다](https://docs.whop.com/ko/developer/guides/chat/quickstart.md)
>
> 임베드할 수 있는 채팅, DM, 포럼.

> [card] [레퍼런스만 읽고 싶습니다](https://docs.whop.com/ko/api-reference/overview.md)
>
> 각 엔드포인트에 플레이그라운드가 있는 Current API의 모든 리소스.


## Related topics

- [채팅 빠른 시작](https://docs.whop.com/ko/developer/guides/chat/quickstart.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [Whop API 핵심 개념](https://docs.whop.com/ko/developer/concepts.md)
