SvelteKit 适配器

Checkout Handler

将 Dodo Payments 结账集成到您的 SvelteKit 应用中。

Customer Portal

允许客户管理订阅和详情。

Webhooks

接收并处理 Dodo Payments 的 webhook 事件。

安装

Install the package

在项目根目录运行以下命令：

npm install @dodopayments/sveltekit

Set up environment variables

在项目根目录创建一个 .env 文件：

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success

切勿将 .env 文件或密钥提交到版本控制。

路由处理器示例

所有示例都假设您正在使用 SvelteKit App Router。

Checkout Handler
Customer Portal Handler
Webhook Handler

使用此处理程序将 Dodo Payments 结账集成到您的 SvelteKit 应用中。支持静态（GET）、动态（POST）和会话（POST）付款流程。

// src/routes/api/checkout/+server.ts
import { Checkout } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

const checkoutGetHandler = Checkout({
    bearerToken: DODO_PAYMENTS_API_KEY,
    returnUrl: DODO_PAYMENTS_RETURN_URL,
    environment: DODO_PAYMENTS_ENVIRONMENT,
    type: "static",
});

const checkoutPostHandler = Checkout({
    bearerToken: DODO_PAYMENTS_API_KEY,
    returnUrl: DODO_PAYMENTS_RETURN_URL,
    environment: DODO_PAYMENTS_ENVIRONMENT,
    type: "session", // or "dynamic" for dynamic link
});

export const GET = checkoutGetHandler.GET;
export const POST = checkoutPostHandler.POST;

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{ 
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "test@example.com",
  	"name": "test"
},
"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
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{ 
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

使用此处理程序允许客户通过 Dodo Payments 客户门户管理他们的订阅和详细信息。

// src/routes/api/checkout/+server.ts
import { CustomerPortal } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

const customerPortalHandler = CustomerPortal({
    bearerToken: DODO_PAYMENTS_API_KEY,
    environment: DODO_PAYMENTS_ENVIRONMENT,
});

export const GET = customerPortalHandler.GET;

使用此处理程序在您的 SvelteKit 应用中安全地接收并处理 Dodo Payments 的 webhook 事件。

// src/routes/api/webhook/+server.ts
import { Webhooks } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_WEBHOOK_KEY } from '$env/static/private';

export const POST = Webhooks({
    webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        console.log(payload);
    }
});

结账路由处理器

Dodo Payments 支持三种类型的支付流程将支付集成到您的网站中，此适配器支持所有类型的支付流程。

静态支付链接： 可即时分享的 URL，用于快速、无代码的支付收集。
动态支付链接： 使用 API 或 SDK 程序化生成带有自定义详细信息的支付链接。
结账会话： 创建安全、可自定义的结账体验，预配置产品购物车和客户详细信息。

Static Checkout (GET)

支持的查询参数

string

必填

产品标识符（例如，?productId=pdt_nZuwz45WAs64n3l07zpQR）。

integer

产品数量。

string

Customer 的全名。

string

Customer 的名字。

string

Customer 的姓氏。

string

Customer 的电子邮件地址。

string

Customer 的国家/地区。

string

Customer 的地址行。

string

Customer 的城市。

string

Customer 的州/省。

string

Customer 的邮政编码。

boolean

禁用全名字段。

boolean

禁用名字字段。

boolean

禁用姓氏字段。

boolean

禁用电子邮件字段。

boolean

禁用国家/地区字段。

boolean

禁用地址行字段。

boolean

禁用城市字段。

boolean

禁用州/省字段。

boolean

禁用邮政编码字段。

string

指定支付货币（例如，USD）。

boolean

显示货币选择器。

number

固定收取的金额，以主要货币单位表示（例如，12.5 表示 $12.50）。仅适用于 Pay What You Want 产品；如果金额低于产品最低价格，则会忽略此参数。

boolean

显示折扣字段。

string

任何以 metadata_ 开头的查询参数都会作为 metadata 传递。

如果缺少 productId，处理程序将返回 400 响应。无效的查询参数也会导致 400 响应。

响应格式

静态结账返回一个包含结账 URL 的 JSON 响应：

{
  "checkout_url": "https://checkout.dodopayments.com/"
}

Dynamic Checkout (POST)

将参数作为 POST 请求的 JSON 正文发送。
支持一次性和周期性付款。
有关支持的 POST 正文字段的完整列表，请参阅：
- 一次性付款产品的请求正文
- 订阅产品的请求正文

Dynamic Checkout 代理已弃用的 POST /payments 和 POST /subscriptions endpoints。它会继续支持现有集成，但新集成应使用下方的 Checkout Sessions。

Response Format

Dynamic checkout 返回包含 checkout URL 的 JSON response：

{
  "checkout_url": "https://checkout.dodopayments.com/"
}

Checkout Sessions (POST)

Checkout sessions 提供更安全的 hosted checkout experience，可为一次性购买和 subscriptions 处理完整的 payment flow，同时支持全面的 customization control。有关更多详细信息以及完整的 supported fields 列表，请参阅 Checkout Sessions Integration Guide。

Response Format

Checkout sessions 返回包含 checkout URL 的 JSON response：

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

Customer Portal Route Handler

Customer Portal Route Handler 让你能够将 Dodo Payments customer portal 无缝集成到 SvelteKit application 中。

Query Parameters

string

必填

portal session 的 customer ID（例如 ?customer_id=cus_123）。

boolean

如果设置为 true，则会向 customer 发送包含 portal link 的 email。

如果缺少 customer_id，则返回 400。

Webhook Route Handler

Method: 仅支持 POST requests。其他 methods 返回 405。
Signature Verification: 使用 webhookKey 验证 webhook signature。验证失败时返回 401。
Payload Validation: 使用 Zod 进行验证。payload 无效时返回 400。
Error Handling:
- 401：Invalid signature
- 400：Invalid payload
- 500：验证期间发生 Internal error
Event Routing: 根据 payload type 调用相应的 event handler。

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>;
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>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Handler

Customer Portal

Webhooks

安装

路由处理器示例

结账路由处理器

支持的查询参数

响应格式

Response Format

Response Format

Customer Portal Route Handler

Query Parameters

Webhook Route Handler

Supported Webhook Event Handlers

Prompt for LLM

Checkout Handler

Customer Portal

Webhooks

​安装

​路由处理器示例

​结账路由处理器

​支持的查询参数

​响应格式

​Response Format

​Response Format

​Customer Portal Route Handler

​Query Parameters

​Webhook Route Handler

​Supported Webhook Event Handlers

​Prompt for LLM

安装

路由处理器示例

结账路由处理器

支持的查询参数

响应格式

Response Format

Response Format

Customer Portal Route Handler

Query Parameters

Webhook Route Handler

Supported Webhook Event Handlers

Prompt for LLM