> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Astro 适配器

> 使用 @dodopayments/astro package 将 Dodo Payments checkout、Customer Portal 和 webhook endpoints 添加到 Astro 项目中。

`@dodopayments/astro` package 为您的 Astro 项目提供三个 endpoint handlers。`Checkout` 返回 checkout URLs，`CustomerPortal` 将客户发送到 Customer Portal，而 `Webhooks` 验证 webhook events 并将其路由到您的代码。

> **[Checkout Handler](#checkout-route-handler)**
>
> 使用 static、dynamic 和 checkout session flows 创建 checkout URLs。

> **[Customer Portal](#customer-portal-route-handler)**
>
> 让客户管理其 subscriptions 和详细信息。

> **[Webhooks](#webhook-route-handler)**
>
> 接收并处理 Dodo Payments webhook events。

## 安装

**1. Install the Package**

在项目根目录运行此命令：

```bash theme={null}
npm install @dodopayments/astro
```

该 package 将 Astro 4 或 5 以及 `zod` 3.25 或更高版本列为 peer dependencies。

**2. Set Up Environment Variables**

在项目根目录创建一个 `.env` 文件。在 **Developer → API Keys** 下创建 API key。在 **Developer → Webhooks** 下添加 webhook endpoint，并将其 **Signing secret** 复制到 `DODO_PAYMENTS_WEBHOOK_KEY`：

```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
# test_mode or live_mode
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
```

`DODO_PAYMENTS_RETURN_URL` 是客户在 checkout 后到达的位置。如果您不传入 environment，handlers 将使用 `live_mode`。test mode API key 只能与 `test_mode` 配合使用。

> [!WARNING]
>
> 切勿将 `.env` 文件或 secrets 提交到版本控制系统。

## Route Handler 示例

> [!NOTE]
>
> 这些示例是位于 `src/pages/api/` 中的 Astro server endpoints。调用 Dodo Payments 的 endpoints 必须按需渲染，因此请为 Astro 项目添加 server adapter。在 Astro 默认的 `static` output mode 中，endpoints 会在构建时渲染，因此每个示例都会导出 `prerender = false`，以便改为在每次请求时渲染 endpoint。

**Checkout Handler**

> [!NOTE]
>
> 使用此 handler 将 Dodo Payments checkout 添加到您的应用。`GET` handler 提供 static checkout。`POST` handler 提供 checkout sessions；当您将 `type: "dynamic"` 设置为相应值时，也可提供 dynamic checkout。一个 endpoint file 只能导出一个 `POST` handler，因此 dynamic checkout 示例假定您已设置 `type: "dynamic"`。

```typescript Astro Route Handler expandable theme={null}
// src/pages/api/checkout.ts
import { Checkout } from "@dodopayments/astro";

export const prerender = false;

export const GET = Checkout({
    bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
    returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
    environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static", // optional, defaults to 'static'
});

export const POST = Checkout({
    bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
    returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
    environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session", // for checkout sessions, or "dynamic" for dynamic checkout
});
```

```bash Static Checkout cURL Example theme={null}
curl --request GET \
  --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh'
```

```bash Dynamic Checkout cURL Example expandable theme={null}
curl --request POST \
  --url https://example.com/api/checkout \
  --header 'Content-Type: application/json' \
  --data '{
  "billing": {
    "city": "Austin",
    "country": "US",
    "state": "TX",
    "street": "123 Main St",
    "zipcode": "78701"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "metadata": {},
  "payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'
```

```bash Checkout Session cURL Example expandable theme={null}
curl --request POST \
  --url https://example.com/api/checkout \
  --header 'Content-Type: application/json' \
  --data '{
  "product_cart": [
    {
      "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
      "quantity": 1
    }
  ],
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "return_url": "https://example.com/success"
}'
```

**Customer Portal Handler**

> [!NOTE]
>
> 使用此 handler 将客户发送到 Dodo Payments Customer Portal，让他们管理自己的 subscriptions 和详细信息。

```typescript Astro Route Handler expandable theme={null}
// src/pages/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/astro";

export const prerender = false;

export const GET = CustomerPortal({
    bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
    environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
});
```

```bash Customer Portal cURL Example theme={null}
curl --request GET \
  --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true'
```

**Webhook Handler**

> [!NOTE]
>
> 使用此 handler 在 Astro 应用中接收 Dodo Payments webhook events 并验证其 signatures。

```typescript Astro Route Handler expandable theme={null}
// src/pages/api/webhook.ts
import { Webhooks } from "@dodopayments/astro";

export const prerender = false;

export const POST = Webhooks({
    webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        // handle the payload
    },
    // ... other event handlers for granular control
});
```

## Checkout Route Handler

checkout handler 支持使用 Dodo Payments 收款的以下三种方式：

* \*\*Static Payment Links：\*\*无需代码即可收款的可分享 URLs。
* \*\*Dynamic Payment Links：\*\*使用自定义详细信息生成的 payment links。它们使用 deprecated endpoints。
* \*\*Checkout Sessions：\*\*支持 product cart、customer details 和 customization options 的 hosted checkout。这是推荐的流程。

`Checkout` 接受以下 options：

| Option | Type | Description |
| - | - | - |
| `bearerToken` | `string` | 您的 Dodo Payments API key。 |
| `environment` | `string` | `test_mode` 或 `live_mode`。默认为 `live_mode`。 |
| `returnUrl` | `string` | 可选。checkout 在付款后将客户重定向到的 URL。POST body 中的 `return_url` 优先。 |
| `type` | `string` | checkout flow：`static`、`dynamic` 或 `session`。默认为 `static`。 |

该 handler 为 `GET` requests 提供 static checkout。对于 `POST` requests，当 `type` 为 `dynamic` 时，它会创建 dynamic payment link；否则会创建 checkout session。

> **Static Checkout (GET)**
>
> ### 支持的 Query Parameters
>
> **productId** `string` *required*
>
> Product identifier，例如 `?productId=pdt_nZuwz45WAs64n3l07zpQR`。
>
> **quantity** `integer` (default: 1)
>
> Product 的 quantity。
>
> **fullName** `string`
>
> Customer 的 full name。如果提供了 `firstName` 或 `lastName`，则会忽略该字段。
>
> **firstName** `string`
>
> Customer 的 first name。
>
> **lastName** `string`
>
> Customer 的 last name。
>
> **email** `string`
>
> Customer 的 email address。
>
> **country** `string`
>
> Customer 的 country，采用 ISO 3166-1 alpha-2 code。
>
> **addressLine** `string`
>
> Customer 的 street address。
>
> **city** `string`
>
> Customer 的 city。
>
> **state** `string`
>
> Customer 的 state 或 province。
>
> **zipCode** `string`
>
> Customer 的 ZIP 或 postal code。
>
> **disableFullName** `boolean`
>
> 设置为 `true` 可禁用 full name field。
>
> **disableFirstName** `boolean`
>
> 设置为 `true` 可禁用 first name field。
>
> **disableLastName** `boolean`
>
> 设置为 `true` 可禁用 last name field。
>
> **disableEmail** `boolean`
>
> 设置为 `true` 可禁用 email field。
>
> **disableCountry** `boolean`
>
> 设置为 `true` 可禁用 country field。
>
> **disableAddressLine** `boolean`
>
> 设置为 `true` 可禁用 address line field。
>
> **disableCity** `boolean`
>
> 设置为 `true` 可禁用 city field。
>
> **disableState** `boolean`
>
> 设置为 `true` 可禁用 state field。
>
> **disableZipCode** `boolean`
>
> 设置为 `true` 可禁用 ZIP code field。
>
> **paymentCurrency** `string`
>
> Payment currency，例如 `USD`。
>
> **showCurrencySelector** `boolean` (default: true)
>
> 显示或隐藏 currency selector。
>
> **paymentAmount** `number`
>
> 固定以主要货币单位收取的金额，例如 \$12.50 对应 `12.5`。仅适用于 Pay What You Want products；如果低于 product 的 minimum price，则会被忽略。
>
> **showDiscounts** `boolean` (default: true)
>
> 显示或隐藏 discounts section。
>
> **metadata\_**\* `string`
>
> 任何以 `metadata_` 开头的 query parameter 都会作为 metadata 传递给 checkout，例如 `metadata_orderId=123`。
>
> disable flag 仅在匹配的 field 具有值时生效，例如 `email` 与 `disableEmail=true` 配合使用时。handler 会将其 config 中的 `returnUrl` 作为 `redirect_url` 添加到 link 中。
>
> > [!WARNING]
> >
> > 如果缺少 `productId`，handler 将返回 400 response。无效的 query parameters 或账户中不存在的 product 也会返回 400。
>
> ### Response Format
>
> Static checkout 返回包含 checkout URL 的 JSON response。在 test mode 中，URL 使用 `test.checkout.dodopayments.com`：
>
> ```json theme={null}
> {
>   "checkout_url": "https://test.checkout.dodopayments.com/buy/pdt_fqJhl7pxKWiLhwQR042rh?quantity=1&redirect_url=https%3A%2F%2Fyourdomain.com%2Fcheckout%2Fsuccess"
> }
> ```

> **Dynamic Checkout (POST)**
>
> * 在 POST request 中将 parameters 作为 JSON body 发送。
> * 支持 one-time 和 recurring payments。handler 会获取 product，然后在 product 为 recurring 时创建 subscription，否则创建 one-time payment。
> * body 需要 `billing`（包括 `street`、`city`、`state`、`country` 和 `zipcode`）以及 `customer`，另外还需要 `product_id` 或 `product_cart`。Subscriptions 需要 `product_id`。
> * 有关所有受支持的 body fields，请参阅：
>   * [One Time Payment Product 的 Request body](https://docs.dodopayments.com/api-reference/payments/post-payments)
>
>   * [Subscription Product 的 Request body](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)
>
> > [!WARNING]
> >
> > Dynamic checkout 代理已弃用的 `POST /payments` 和 `POST /subscriptions` endpoints。它会继续为现有 integrations 提供支持，但新 integrations 应使用 checkout sessions。
>
> ### Response Format
>
> Dynamic checkout 返回包含 payment link 作为 checkout URL 的 JSON response：
>
> ```json theme={null}
> {
>   "checkout_url": "https://test.checkout.dodopayments.com/cbq"
> }
> ```

> **Checkout Sessions (POST)**
>
> Checkout sessions 为 one-time purchases 和 subscriptions 创建 hosted checkout，并提供完整的 customization 控制。`product_cart` 是唯一必需的 field，并且至少需要一个 product。如果 body 没有 `return_url`，handler 会使用其 config 中的 `returnUrl`。
>
> 每个 `checkout_url` 只能使用一次，并会在 24 小时后过期；传入 `confirm: true` 时，则会在 15 分钟后过期。使用 `payment_method_id` 创建的 session 不会返回 `checkout_url`，因此 handler 会响应 400。
>
> 有关更多详细信息和所有受支持的 fields，请参阅 [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session)。
>
> ### Response Format
>
> Checkout sessions 返回包含 checkout URL 的 JSON response：
>
> ```json theme={null}
> {
>   "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
> }
> ```

## Customer Portal Route Handler

Customer Portal route handler 为您传入的 customer 创建 Customer Portal session，并将 browser 重定向到该 session。`CustomerPortal` 接受与 `Checkout` 相同的 `bearerToken` 和 `environment` options。

> [!WARNING]
>
> handler 不会检查调用者的身份。任何使用 customer ID 请求它的人都可以获得该 customer 的 portal。请使用您自己的 authentication 保护 route，并且只传入已登录用户的 customer ID。

### Query Parameters

**customer\_id** `string` *required*

用于 portal session 的 customer ID，例如 `?customer_id=cus_123`。

**send\_email** `boolean`

如果设置为 `true`，Dodo Payments 还会通过 email 将 portal link 发送给 customer。

如果缺少 `customer_id`，handler 将返回 400；如果无法创建 portal session，则返回 500。

## Webhook Route Handler

webhook route handler 会在运行您的代码之前，使用作为 `webhookKey` 传入的 webhook secret 验证每个 request：

* \*\*Method：\*\*仅支持 POST requests。其他 methods 返回 405。
* \*\*Signature Verification：\*\*使用 `webhookKey` 按照 Standard Webhooks specification 验证 `webhook-id`、`webhook-timestamp` 和 `webhook-signature` headers。验证失败时返回 401。
* \*\*Payload Validation：\*\*使用 Zod 验证 payload。payload 无效时返回 400。
* **Error Handling：**
  * 401：Invalid signature
  * 400：Invalid payload
  * 500：验证期间发生 Internal error
* \*\*Event Routing：\*\*对每个 event 调用 `onPayload`，然后调用该 event type 对应的 handler，并返回 200。

adaptor 不会捕获 handlers 抛出的 errors。这些 errors 会传播到 Astro，并导致 request 失败。

### 支持的 Webhook Event Handlers

每个 handler 都是可选的 async handler，并会接收其 event type 对应的已验证 payload：

```typescript TypeScript expandable theme={null}
onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPaused?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUnpaused?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdatePaymentMethod?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageReset?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
onEntitlementGrantCreated?: (payload: WebhookPayload) => Promise<void>;
onEntitlementGrantDelivered?: (payload: WebhookPayload) => Promise<void>;
onEntitlementGrantFailed?: (payload: WebhookPayload) => Promise<void>;
onEntitlementGrantRevoked?: (payload: WebhookPayload) => Promise<void>;
onPayoutCreated?: (payload: WebhookPayload) => Promise<void>;
onPayoutOnHold?: (payload: WebhookPayload) => Promise<void>;
onPayoutInProgress?: (payload: WebhookPayload) => Promise<void>;
onPayoutFailed?: (payload: WebhookPayload) => Promise<void>;
onPayoutSuccess?: (payload: WebhookPayload) => Promise<void>;
```

有关每个 event 的含义，请参阅 [Webhook Event Guide](/developer-resources/webhooks/intents/webhook-events-guide)。

## LLM 提示词

将此 prompt 复制到您的 AI coding assistant 中，让它将 adaptor 添加到您的项目。要同时向 agent 提供 Dodo Payments docs 和 skills，请安装 [Agent Plugin](/developer-resources/build-with-ai-coding-agents)。

```text expandable theme={null}

You are an expert Astro developer assistant. Your task is to guide a user through integrating the @dodopayments/astro adapter into their existing Astro project.

The @dodopayments/astro adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Astro server endpoints in src/pages/api/.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/astro

The endpoints must render on demand. Make sure the project has an Astro server adapter, and export prerender = false from each endpoint file unless the project uses output: 'server'.

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/astro adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler manages different types of checkout flows. All checkout types (static, dynamic, and sessions) return JSON responses with checkout URLs for programmatic handling.
File Creation: Create a new file at src/pages/api/checkout.ts in your Astro project.

Code Snippet:

// src/pages/api/checkout.ts
import { Checkout } from "@dodopayments/astro";

export const prerender = false;

export const GET = Checkout({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static", // optional, defaults to 'static'
});

export const POST = Checkout({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session", // for checkout sessions, or "dynamic" for dynamic checkout
});

A file can export only one POST handler. To serve both dynamic checkout and checkout sessions, create a second endpoint file.

Configuration & Usage:

    bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.

    returnUrl: (Optional) The URL to redirect the user to after a successful checkout. A return_url in the POST body takes precedence.

    environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.

    type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions.

Static Checkout (GET) Query Parameters:

    productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)

    quantity (optional): Quantity of the product

    Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode

    Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode

    Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts

    Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

    Returns: {"checkout_url": "https://test.checkout.dodopayments.com/buy/pdt_nZuwz45WAs64n3l07zpQR?quantity=1"}

Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. It requires billing and customer, plus product_id or product_cart. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://test.checkout.dodopayments.com/cbq"}. For a complete list of supported POST body fields, refer to:

    Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments

    Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body, and product_cart is required. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.

If Customer Portal Route Handler is selected:

Purpose: This handler redirects a customer to their Dodo Payments customer portal. It does not authenticate the caller, so protect the route and pass only the signed-in user's customer ID.
File Creation: Create a new file at src/pages/api/customer-portal.ts in your Astro project.

Code Snippet:

// src/pages/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/astro";

export const prerender = false;

export const GET = CustomerPortal({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
});

Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at src/pages/api/webhook.ts in your Astro project.

Code Snippet:

// src/pages/api/webhook.ts
import { Webhooks } from "@dodopayments/astro";

export const prerender = false;

export const POST = Webhooks({
  webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // handle the payload
  },
  // ... other event handlers for granular control
});

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls onPayload for every event, then the event handler that matches the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionPaused?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUnpaused?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdatePaymentMethod?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageReset?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    onEntitlementGrantCreated?: (payload: WebhookPayload) => Promise<void>

    onEntitlementGrantDelivered?: (payload: WebhookPayload) => Promise<void>

    onEntitlementGrantFailed?: (payload: WebhookPayload) => Promise<void>

    onEntitlementGrantRevoked?: (payload: WebhookPayload) => Promise<void>

    onPayoutCreated?: (payload: WebhookPayload) => Promise<void>

    onPayoutOnHold?: (payload: WebhookPayload) => Promise<void>

    onPayoutInProgress?: (payload: WebhookPayload) => Promise<void>

    onPayoutFailed?: (payload: WebhookPayload) => Promise<void>

    onPayoutSuccess?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your Astro project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    DODO_PAYMENTS_RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_WEBHOOK_KEY: Your Dodo Payments Webhook Secret (required for Webhook handler).

    DODO_PAYMENTS_ENVIRONMENT: test_mode or live_mode. The handlers default to live_mode.

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_RETURN_URL=your-return-url

Usage in your code:

bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY
webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.