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

# Uygulama Kurulumları

> Bir hesabın uygulamanızı ne zaman kurduğunu veya kaldırdığını öğrenin ve her kurulumu kendi sisteminizde ait olduğu kayda bağlayın.

Bir uygulama kurulumu, uygulamanızın tek bir Whop hesabına yapılmış tek bir kurulumudur. Bir hesap uygulamanızı kurduğunda uygulamanız `app_installation.created`, kaldırdığında ise `app_installation.deleted` alır. Her kurulum ayrıca yalnızca uygulamanızın değiştirebileceği iki değer saklar. `external_id`, kurulumu sisteminizdeki bir kayda bağlar; `metadata` ise senkronizasyon imleci gibi küçük değerleri tutar.

## Whop üzerinden ödeme alan bir mağaza

Bu kılavuz uydurma bir uygulamayı takip eder. Market Lane bir çevrimiçi mağaza oluşturucusudur ve Whop uygulaması, bir işletmenin Market Lane mağazasında Whop üzerinden ödeme almasını sağlar. Her mağazanın `river-coffee` gibi bir tanıtıcısı (handle) vardır ve Market Lane'deki her ödeme işlemi bu tanıtıcıyla başlar.

Market Lane'in üç şeyi bilmesi gerekir:

1. Bir işletmenin uygulamayı ne zaman kurduğu; böylece işletmenin mağazasını bağlayabilir.
2. Bir mağazada ödeme işlemi başladığında ödemeyi hangi Whop hesabının aldığı.
3. Bir işletmenin uygulamayı ne zaman kaldırdığı; böylece mağazası ödeme sırasında Whop'u sunmayı bırakır.

**1. Uygulamanızın ihtiyaç duyduğu izinleri isteyin**

Uygulamanızın [izinlerinde](https://docs.whop.com/tr/developer/guides/permissions.md), hesapta ödeme yapılandırmaları oluşturmak için `checkout_configuration:create` ve bunların ne zaman ödendiğini öğrenmek için `webhook_receive:payments` isteyin. İşletme, uygulamayı kurduğunda her ikisini de onaylar.

**2. Uygulamanızın webhook'una abone olun**

Hesabınıza değil, uygulamanıza ait bir webhook oluşturun: `resource_id` değerini uygulamanızın kimliği olarak ayarlayın. Bu webhook, uygulamanızı kuran her hesap için kurulum olaylarını ve bu hesapların izin verdiği ödeme olaylarını alır.

```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"]
  }'
```

Anahtarın, uygulamaya sahip olan hesapta `developer:manage_webhook` iznine sahip olması gerekir. Yanıttaki `webhook_secret` değerini saklayın ve her teslimatı [Webhook'lar](https://docs.whop.com/tr/developer/guides/webhooks.md) bölümünde açıklandığı şekilde doğrulayın.

Kurulum olaylarını yalnızca uygulamanızın kendi webhook'ları alır. Bir hesabın webhook'ları, o hesapta kurulu uygulamalar için bile bu olayları asla almaz.

**3. Bir işletme uygulamayı kurduğunda mağazayı bağlayın**

`app_installation.created`, kurulumu `data` içinde taşır. Zarfın `account_id` değeri, uygulamayı kuran işletmedir:

```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 işletmeye hangi mağazanın bağlanacağını sorar. İşletme `river-coffee` seçtiğinde, Market Lane tanıtıcıyı kurulumda `external_id` olarak saklar:

```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. Bir ödeme işlemi başladığında hesabı bulun**

Bir alışverişçi `river-coffee` üzerinde ödeme yapar. İstek yalnızca mağaza tanıtıcısını taşır, bu nedenle Market Lane kurulumu `external_id` ile arar:

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

Sonuçta en fazla bir kurulum bulunur ve bunun `account.id` değeri ödemeyi alan hesaptır. Market Lane, `POST /checkout_configurations` ile o hesapta bir ödeme yapılandırması oluşturur, kendi sipariş kimliğini `metadata` içine koyar ve alışverişçiyi `purchase_url` adresine gönderir. Market Lane, mağaza tanıtıcıları ile Whop hesaplarını eşleyen bir tablo tutmaz, çünkü eşleme kurulumun kendisidir.

**5. Siparişi ödendi olarak işaretleyin**

`payment.succeeded` aynı webhook'a gelir. Bunun `account_id` değeri mağazanın işletmesidir ve ödeme, ödeme yapılandırmasındaki `metadata` değerini taşır; böylece Market Lane siparişi kimliğiyle bulur ve ödendi olarak işaretler.

**6. İşletme uygulamayı kaldırdığında Whop ödemelerini kapatın**

`app_installation.deleted`, bir işletme uygulamanızı kaldırır kaldırmaz gelir. Market Lane, `river-coffee` üzerinde ödeme sırasında Whop'u sunmayı hemen bırakır; böylece hiçbir alışverişçi başarısız olacak bir ödeme sayfasına ulaşmaz. Kurulum artık `GET /app_installations` içinde görünmez ve uygulamanız artık o hesapta işlem yapamaz.

**7. Yeniden kurulumda yeniden bağlanın**

İşletme uygulamayı yeniden kurarsa, başka bir `app_installation.created` alırsınız. Bu aynı kurulumdur: `id`, `created_at`, `external_id` ve `metadata` değerlerinin tümü geri gelir. Market Lane, yükte `external_id: "river-coffee"` değerini görür ve işletmeden mağazayı yeniden bağlamasını istemeden o mağaza için Whop ödemelerini yeniden açar.

## Bir kurulumda kendi kimliğinizi saklayın

* **`external_id`, uygulamanızın kurulumları arasında benzersizdir.** Başka bir kurulumun zaten sahip olduğu bir değeri ayarlamak `409` döndürür, bu nedenle iki işletme asla aynı mağazayı sahiplenemez. Değerler büyük/küçük harfe duyarlıdır: `River-Coffee` ve `river-coffee` farklıdır.
* **`metadata` birleştirilir.** Gönderdiğiniz anahtarlar ayarlanır, `null` olarak ayarlanan bir anahtar kaldırılır, göndermediğiniz anahtarlar değişmez ve `{}` tüm anahtarları temizler. Değerler dizedir.
* **Kaldırılmış bir kurulum `external_id` değerini korur.** Bir işletmede uygulamanız kaldırılmış durumdayken, uygulamanızın başka hiçbir kurulumu bu değeri alamaz. İşletme uygulamayı yeniden kurarsa, değer de onunla birlikte geri gelir.
* **Gizli bilgileri saklamayın.** Geliştirici hesabınız `metadata` ve `external_id` değerlerini okuyabilir.

## Tekrarlanan olayları işleyin

* **Tekrarları bekleyin.** Bir işletme uygulamanızı kurabilir, kaldırabilir ve yeniden kurabilir. Zaten bildiğiniz bir kurulum için gelen `app_installation.created` olayını yeniden kurulum olarak değerlendirin.
* **Yinelenenleri `webhook-id` ile yok sayın.** Whop, `2xx` yanıtı almayan teslimatları yeniden dener ve bir yeniden deneme aynı `webhook-id` değerini korur.

## Kurulumları kimler okuyabilir

| Çağıran | Erişim |
| - | - |
| Uygulamanızın API anahtarı | `metadata` ve `external_id` dahil olmak üzere uygulamanızın kurulumlarını listeler, getirir ve günceller. Anahtarın okumak için `developer:app_installation:read`, güncellemek için `developer:app_installation:update` iznine ihtiyacı vardır. |
| Geliştirici hesabınız | `GET /app_installations?app_id=app_XXXXXXXX` ile uygulamanızın her kurulumunu listeler. `developer:basic:read` gerektirir. |
| Uygulamanın kurulu olduğu hesap | Üzerinde kurulu uygulamaları listeler. `metadata` ve `external_id` değerlerini her zaman `null` olarak görür. |

## Sonraki adımlar

> [card] [Webhook'lar](https://docs.whop.com/tr/developer/guides/webhooks.md)
>
> İmzaları doğrulayın, yeniden denemeleri işleyin ve tüm olayları görün.

> [card] [Uygulama Kurulumları API referansı](https://docs.whop.com/tr/api-reference/app-installations/app-installation)
>
> Uygulama kurulumları için tüm alanlar ve uç noktalar.

> [card] [Ödeme alın](https://docs.whop.com/tr/developer/guides/accept-payments.md)
>
> Ödeme yapılandırmaları oluşturun ve siparişleri `payment.succeeded` üzerinden karşılayın.

> [card] [İzinler](https://docs.whop.com/tr/developer/guides/permissions.md)
>
> Uygulamanızın kurulum sırasında istediği izinleri tanımlayın.


## Related topics

- [Zamanlanmış Çalıştırmalar](https://docs.whop.com/tr/developer/guides/scheduled-runs.md)
- [Webhooks](https://docs.whop.com/tr/developer/guides/webhooks.md)
- [Uygulama](https://docs.whop.com/tr/api-reference/legacy/apps/app.md)
