> ## 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 계정에 앱을 한 번 설치한 것을 의미합니다. 계정이 앱을 설치하면 앱은 `app_installation.created`를 받고, 계정이 앱을 제거하면 `app_installation.deleted`를 받습니다. 각 설치에는 앱만 변경할 수 있는 두 가지 값도 저장됩니다. `external_id`는 설치를 자체 시스템의 레코드에 연결하고, `metadata`는 동기화 커서 같은 작은 값을 보관합니다.

## Whop을 통해 결제를 받는 스토어프론트

이 가이드는 가상의 앱을 예로 듭니다. Market Lane은 온라인 스토어 빌더이며, Market Lane의 Whop 앱을 사용하면 비즈니스가 Market Lane 스토어에서 Whop을 통해 결제를 받을 수 있습니다. 모든 스토어에는 `river-coffee` 같은 핸들이 있으며, Market Lane의 모든 체크아웃은 이 핸들로 시작합니다.

Market Lane은 세 가지를 알아야 합니다:

1. 비즈니스가 앱을 설치하는 시점. 그래야 비즈니스의 스토어를 연결할 수 있습니다.
2. 스토어에서 체크아웃이 시작될 때 어떤 Whop 계정이 결제를 받는지.
3. 비즈니스가 앱을 제거하는 시점. 그래야 해당 스토어가 체크아웃에서 Whop 제공을 중단할 수 있습니다.

**1. 앱에 필요한 권한 요청하기**

앱의 [권한](https://docs.whop.com/ko/developer/guides/permissions.md)에서 계정에 체크아웃을 생성하기 위한 `checkout_configuration:create`와, 결제 완료 시점을 알기 위한 `webhook_receive:payments`를 요청하세요. 비즈니스는 앱을 설치할 때 두 권한을 모두 승인합니다.

**2. 앱의 웹훅 구독하기**

계정이 아닌 앱에 속하는 웹훅 하나를 생성하세요. `resource_id`를 앱의 ID로 설정합니다. 이 웹훅은 앱을 설치하는 모든 계정의 설치 이벤트와, 해당 계정들이 허용한 결제 이벤트를 받습니다.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketlane.example/webhooks/whop",
    "resource_id": "app_XXXXXXXX",
    "events": ["app_installation.created", "app_installation.deleted", "payment.succeeded"]
  }'
```

키에는 앱을 소유한 계정에 대한 `developer:manage_webhook` 권한이 필요합니다. 응답의 `webhook_secret`을 저장하고, [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)에 설명된 대로 모든 전송을 검증하세요.

설치 이벤트는 앱 자체의 웹훅만 받습니다. 계정의 웹훅은 해당 계정에 설치된 앱의 이벤트라도 절대 받지 않습니다.

**3. 비즈니스가 앱을 설치하면 스토어 연결하기**

`app_installation.created`는 `data`에 설치 정보를 담고 있습니다. 엔벨로프의 `account_id`는 앱을 설치한 비즈니스입니다:

```json theme={null}
{
  "type": "app_installation.created",
  "account_id": "biz_J8n2R5p9T1w4Kx",
  "data": {
    "id": "aag_T4k8M2p6W9r3Qx",
    "app": { "id": "app_XXXXXXXX", "name": "Market Lane" },
    "account": { "id": "biz_J8n2R5p9T1w4Kx", "title": "River Coffee" },
    "external_id": null,
    "metadata": {},
    "requesting_reauthorization": false
  }
}
```

Market Lane은 비즈니스에 어떤 스토어를 연결할지 묻습니다. 비즈니스가 `river-coffee`를 선택하면 Market Lane은 해당 핸들을 설치의 `external_id`로 저장합니다:

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/app_installations/aag_T4k8M2p6W9r3Qx" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "river-coffee",
    "metadata": { "connected_at": "2026-10-26T00:00:00Z" }
  }'
```

**4. 체크아웃이 시작되면 계정 찾기**

쇼핑객이 `river-coffee`에서 결제를 진행합니다. 요청에는 스토어 핸들만 포함되므로 Market Lane은 `external_id`로 설치를 조회합니다:

```bash theme={null}
curl "https://api.whop.com/api/v1/app_installations?external_id=river-coffee" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY"
```

결과에는 최대 하나의 설치가 포함되며, 그 `account.id`가 결제를 받는 계정입니다. Market Lane은 `POST /checkout_configurations`로 해당 계정에 체크아웃을 생성하고, 자체 주문 ID를 `metadata`에 넣은 다음, 쇼핑객을 `purchase_url`로 보냅니다. 설치 자체가 매핑 역할을 하므로 Market Lane은 스토어 핸들과 Whop 계정의 테이블을 따로 보관하지 않습니다.

**5. 주문을 결제 완료로 표시하기**

`payment.succeeded`가 같은 웹훅으로 도착합니다. 그 `account_id`는 스토어의 비즈니스이며, 결제에는 체크아웃의 `metadata`가 포함되어 있으므로 Market Lane은 ID로 주문을 찾아 결제 완료로 표시합니다.

**6. 비즈니스가 앱을 제거하면 Whop 결제 끄기**

비즈니스가 앱을 제거하는 즉시 `app_installation.deleted`가 도착합니다. Market Lane은 `river-coffee`의 체크아웃에서 Whop 제공을 바로 중단하므로, 쇼핑객이 실패할 체크아웃에 도달하지 않습니다. 설치는 더 이상 `GET /app_installations`에 나타나지 않으며, 앱은 더 이상 해당 계정에서 작업할 수 없습니다.

**7. 재설치 시 다시 연결하기**

비즈니스가 앱을 다시 설치하면 또 다른 `app_installation.created`를 받습니다. 이는 같은 설치입니다. `id`, `created_at`, `external_id`, `metadata`가 모두 그대로 돌아옵니다. Market Lane은 페이로드에서 `external_id: "river-coffee"`를 확인하고, 비즈니스에 다시 연결을 요청하지 않고 해당 스토어의 Whop 결제를 다시 켭니다.

## 설치에 자체 ID 저장하기

* **`external_id`는 앱의 설치 전체에서 고유합니다.** 다른 설치가 이미 가진 값을 설정하면 `409`가 반환되므로, 두 비즈니스가 같은 스토어를 차지할 수 없습니다. 값은 대소문자를 구분합니다. `River-Coffee`와 `river-coffee`는 다릅니다.
* **`metadata`는 병합됩니다.** 전송한 키는 설정되고, `null`로 설정한 키는 제거되며, 생략한 키는 변경되지 않고, `{}`는 모든 키를 지웁니다. 값은 문자열입니다.
* **제거된 설치는 `external_id`를 유지합니다.** 비즈니스가 앱을 제거한 상태인 동안에는 앱의 다른 설치가 그 값을 사용할 수 없습니다. 비즈니스가 앱을 다시 설치하면 값도 함께 돌아옵니다.
* **비밀 정보를 저장하지 마세요.** 개발자 계정은 `metadata`와 `external_id`를 읽을 수 있습니다.

## 반복 이벤트 처리하기

* **반복을 예상하세요.** 비즈니스는 앱을 설치, 제거한 뒤 다시 설치할 수 있습니다. 이미 알고 있는 설치에 대한 `app_installation.created`는 재설치로 처리하세요.
* **`webhook-id`로 중복을 무시하세요.** Whop은 `2xx` 응답을 받지 못한 전송을 재시도하며, 재시도 시 같은 `webhook-id`가 유지됩니다.

## 설치를 읽을 수 있는 주체

| 호출자 | 접근 권한 |
| - | - |
| 앱의 API 키 | `metadata`와 `external_id`를 포함하여 앱의 설치를 나열, 조회, 업데이트합니다. 읽기에는 `developer:app_installation:read`, 업데이트에는 `developer:app_installation:update` 권한이 필요합니다. |
| 개발자 계정 | `GET /app_installations?app_id=app_XXXXXXXX`로 앱의 모든 설치를 나열합니다. `developer:basic:read` 권한이 필요합니다. |
| 앱이 설치된 계정 | 계정에 설치된 앱을 나열합니다. `metadata`와 `external_id`는 항상 `null`로 표시됩니다. |

## 다음 단계

> [card] [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 서명을 검증하고, 재시도를 처리하고, 모든 이벤트를 확인하세요.

> [card] [App Installations API 레퍼런스](https://docs.whop.com/ko/api-reference/app-installations/app-installation)
>
> 앱 설치의 모든 필드와 엔드포인트.

> [card] [결제 받기](https://docs.whop.com/ko/developer/guides/accept-payments.md)
>
> 체크아웃을 생성하고 `payment.succeeded`로 주문을 처리하세요.

> [card] [권한](https://docs.whop.com/ko/developer/guides/permissions.md)
>
> 앱이 설치 시 요청하는 권한을 선언하세요.


## Related topics

- [앱 뷰](https://docs.whop.com/ko/developer/guides/app-views.md)
- [App Installations API](https://docs.whop.com/ko/api-reference/app-installations/app-installation.md)
- [예약 실행](https://docs.whop.com/ko/developer/guides/scheduled-runs.md)
