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

# GoHighLevel

> 使用无代码支付链接、叠加式结账或内嵌式结账，将 Dodo Payments 与 GoHighLevel (GHL) 集成，并通过 webhooks 自动化履约。

## 简介

将 Dodo Payments 连接到 [GoHighLevel](https://www.gohighlevel.com/) (GHL)，即可通过 GHL 漏斗、网站、电子邮件和 SMS 销售，并使用 GHL 自动化来履行订单。GHL 是一个 CRM 和营销平台，提供漏斗、网站、电子邮件和 SMS，以及自动化功能（**Workflows**）。GHL 没有将 Dodo Payments 列为内置支付处理器，因此你需要通过三种方式之一连接两者。请根据你希望结账流程的嵌入程度以及团队可编写的代码量进行选择。

每种方式的履行流程都相同：Dodo Payments 将 [webhook events](/developer-resources/webhooks) 发送到 GHL 的 **Inbound Webhook** workflow，该 workflow 会为联系人添加标签、授予访问权限并发送确认信息。

## 选择方式

三种方式在所需代码以及客户付款位置方面有所不同：

| 方式 | 所需代码 | 结账体验 | 适用对象 |
| - | - | - | - |
| **A. Payment Links** | 无（无需代码） | 客户进入 Dodo Payments 托管的结账页面 | 大多数 GHL 用户，最快上线 |
| **B. Overlay Checkout** | 自定义代码和后端 | 在 GHL 页面上方打开模态窗口 | 希望结账流程留在页面中、不离开漏斗的团队 |
| **C. Inline Checkout** | 自定义代码和后端 | 结账表单嵌入页面 | 需要完全嵌入且具有品牌样式的结账流程 |

> [!NOTE]
>
> 如果你刚开始使用 Dodo Payments，请从 **方式 A（Payment Links）** 开始。它无需代码，适用于所有 GHL 用户。方式 B 和 C 需要后端创建 [checkout sessions](/api-reference/checkout-sessions/create)，因此更适合熟悉代码的团队。

## 前提条件

开始之前，你需要准备：

* 一个至少包含一个 **product** 的 Dodo Payments 账户。
* 一个包含漏斗、网站或 workflow 的 GoHighLevel 账户。
* 访问 Dodo Payments 控制面板中 **Developer → Webhooks** 的权限；如果需要 API key，还需要访问 **Developer → API Keys**。
* 对于方式 B 和 C：一个用于创建 checkout sessions 的小型 **backend 或 serverless endpoint**。

> [!NOTE]
>
> GHL 要求使用**已连接的域名**才能*发布*漏斗。在构建期间，请使用漏斗的 **Preview** 进行测试。自定义 JavaScript（方式 B 和 C）通常仅在**真实域名上的已发布页面**中运行，而不会在 Preview 中运行。

## 使用 Webhooks 履行订单（所有方式）

webhook workflow 是自动化层。设置一次后，它适用于所有结账方式。

**1. Create the Workflow**

在 GHL 的**子账户**中，打开左侧菜单中的 **Automation**。页面会在 **Workflows** 标签页中打开。点击 **Create workflow**，然后选择 **Start from Scratch**。

**2. Add the Inbound Webhook Trigger**

在构建器中，点击 **Add new trigger**。在 **Add trigger** 面板中搜索 **webhook**，然后选择 **Inbound webhook**，它位于 **Triggers → Events** 下。复制生成的 **Webhook URL**。

**3. Register the Webhook in Dodo Payments**

在 Dodo Payments 控制面板中，前往 **Developer → Webhooks** 并点击 **Add endpoint**。将 GHL Inbound Webhook URL 粘贴到 **Endpoint URL** 中，然后点击 **Create endpoint**。接着向 GHL 提供一个示例 payload，用于映射客户电子邮件、产品、金额和状态等字段。你可以完成一次测试购买，也可以打开 endpoint 的 **Testing** 标签页，选择事件类型，然后点击 **Send example**。

**4. Add Fulfillment Actions**

在 GHL workflow 中，为该事件添加操作，例如 **按电子邮件查找/创建联系人**、**添加标签**、**授予课程/会员资格访问权限**以及**发送确认电子邮件**。然后**发布**该 workflow。

> [!WARNING]
>
> Dodo Payments 负责处理付款，因此付款不会出现在 GHL 的 **Payments** 标签页中。请使用上述 webhook workflow 在 GHL 中记录付款。请通过 **webhook** 授予访问权限，而不要依赖浏览器重定向，因为客户可能会在重定向完成前关闭标签页。

## 方式 A：Payment Links（无需代码）

将 Dodo Payments payment link 添加到任意 GHL 按钮、漏斗 call to action、订单页面按钮、电子邮件或 SMS 中。客户将在 Dodo Payments 托管的结账页面付款。有关结账流程支持的功能，请参阅 [Checkout Features](/features/checkout)。

**1. Create a Product and Copy Its Payment Link**

在 Dodo Payments 控制面板中，前往 **Products** 并点击 **Add Product**。设置 **name** 和 **price**，选择**一次性**或**订阅**，然后保存产品。在产品所在行点击 **Share**，再点击 **Copy payment link**。链接格式为 `https://checkout.dodopayments.com/buy/{product_id}`。

**2. Add the Link to Your GHL Button**

编辑漏斗或网站页面，然后选择 **Buy / Checkout button**。将其操作设置为 **Open URL / Website**，并粘贴你的 payment link。

**3. Set a Success Page (Optional)**

如果希望客户付款后返回你的漏斗，请在复制链接之前，在产品的 **Share** 面板中将 GHL thank-you 页面输入到 **Redirect URL**。之后，链接会将其作为 `redirect_url` 参数携带。

> [!TIP]
>
> payment link query parameters 可以预填并锁定客户详细信息，也可以添加跟踪信息。例如，将漏斗或优惠 ID 作为 `metadata_*` 参数传递，并从 webhook 中读取。有关所有参数，请参阅 [Static Payment Links](/developer-resources/integration-guide#static-payment-links)。

## 方式 B：Overlay Checkout（自定义代码）

方式 B 使用 CDN 中的 [Checkout SDK](/developer-resources/overlay-checkout)，在 GHL 页面上以**模态覆盖层**的形式打开 Dodo Payments checkout。它需要一个后端来创建 [checkout session](/api-reference/checkout-sessions/create)，并返回其 `checkoutUrl`。

**1. Create a Backend Endpoint That Calls the Checkout Sessions API**

此步骤是**必需的**。SDK 需要 checkout session URL，而创建 session 需要你的**secret API key**。GHL 只能托管页面，无法代你执行此 server-side 调用。切勿在浏览器中调用 [Create Checkout Session API](/api-reference/checkout-sessions/create)，因为这会将 secret key 暴露在页面源代码中。因此，Overlay 和 inline checkout **无法仅使用 GHL 实现**：你需要控制一个能够创建 session 并仅返回 URL 的后端。

任何小型后端都可以：serverless function（Cloudflare Workers、Vercel Functions、AWS Lambda、Supabase Edge Functions 等），或你已经运行的服务器上的 endpoint。每个平台的逻辑都相同：接收请求，使用 secret key 调用 Dodo Payments API，然后返回 `checkout_url`。

下面是需要根据你的平台进行调整的 handler 逻辑示例：

```js theme={null}
async function createCheckout(env) {
  const res = await fetch("https://test.dodopayments.com/checkouts", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${env.DODO_PAYMENTS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product_cart: [{ product_id: "pdt_your_product_id", quantity: 1 }],
    }),
  });

  const data = await res.json();
  return { checkoutUrl: data.checkout_url };
}
```

将 API key 作为 secret 存储在部署平台的 `DODO_PAYMENTS_API_KEY` environment variable 中，切勿将其提交到代码库。允许来自 GHL 域名的请求（CORS），并从你控制的域名提供该 endpoint，例如 `https://api.example.com/create-checkout`。切换到 live mode 时，将 URL 更改为 `https://live.dodopayments.com/checkouts`。

**2. Add a Custom Code Element in the GHL Page Builder**

在 GHL 页面构建器中打开漏斗步骤或网站页面，然后执行以下操作：

1. 点击构建器左上角的 **+** 图标，打开 **Quick Add**。
2. 从左侧类别列表中选择 **Elements**。
3. 找到 **Custom Code**（也显示为 HTML），并将其拖到页面上。
4. 将下面的代码粘贴到该元素的代码编辑器中，然后保存。

```html theme={null}
<!-- Load the Dodo Checkout SDK -->
<script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
<script>
  DodoPaymentsCheckout.DodoPayments.Initialize({
    mode: "test", // change to "live" in production
    displayType: "overlay",
    onEvent: (event) => console.log("Checkout event:", event),
  });

  async function openDodoCheckout() {
    // calls the backend endpoint from the previous step, creating a fresh session per click
    const res = await fetch("https://api.example.com/create-checkout", { method: "POST" });
    const { checkoutUrl } = await res.json();

    DodoPaymentsCheckout.DodoPayments.Checkout.open({ checkoutUrl });
  }
</script>

<button onclick="openDodoCheckout()">Pay Now</button>
```

**3. Publish and Test on Your Domain**

自定义 JavaScript 仅在已连接域名上的**已发布**页面中运行，可能不会在 Preview 中运行。发布页面，然后点击 **Pay Now**，确认覆盖层是否打开。

## 方式 C：Inline（嵌入式）Checkout

方式 C 将 checkout 表单**嵌入** GHL 页面中，无需重定向，也不会弹出窗口。它使用相同的 SDK，并通过容器元素挂载。与方式 B 一样，它需要后端创建 session。

**1. Create a Backend Endpoint That Calls the Checkout Sessions API**

此步骤是**必需的**，Overlay Checkout 也同样如此。创建 session 需要 secret API key，因此必须在服务器上完成，GHL 无法独立完成此操作。请复用上文 **Overlay Checkout** 部分中的后端 endpoint：任何由你控制、能够调用 [Create Checkout Session API](/api-reference/checkout-sessions/create) 并返回 `{ checkoutUrl }` 的小型 serverless function 或服务器均可。

**2. Add a Container and SDK via Custom Code**

在 GHL 页面构建器中：

1. 点击构建器左上角的 **+** 图标，打开 **Quick Add**。
2. 从左侧类别列表中选择 **Elements**。
3. 找到 **Custom Code**（也显示为 HTML），并将其拖到希望显示 checkout 表单的位置。
4. 将下面的代码粘贴到该元素的代码编辑器中，然后保存。

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>

<div id="dodo-inline-checkout"></div>

<script>
  DodoPaymentsCheckout.DodoPayments.Initialize({
    mode: "test",
    displayType: "inline",
    onEvent: (event) => console.log("Checkout event:", event),
  });

  async function mountDodoCheckout() {
    // calls the backend endpoint from the previous step
    const res = await fetch("https://api.example.com/create-checkout", { method: "POST" });
    const { checkoutUrl } = await res.json();

    DodoPaymentsCheckout.DodoPayments.Checkout.open({
      checkoutUrl,
      elementId: "dodo-inline-checkout",
    });
  }

  mountDodoCheckout();
</script>
```

**3. Verify Your Domain for Wallets (Apple Pay)**

要在内嵌式结账中提供 Apple Pay，请[验证您的域名](/features/payment-methods/digital-wallets#apple-pay)。在 Dodo Payments 仪表板中，转到 **Settings → Payment Methods**，然后在 **Apple Pay** 行点击 **Manage domains**。下载域名关联文件，将其托管在您的域名下，然后注册该域名。Apple Pay 不适用于叠加式结账（方法 B）。

GHL 托管的域名无法托管域名关联文件。内嵌式结账中的 Apple Pay 需要一个由您控制且能够提供 `/.well-known/apple-developer-merchantid-domain-association` 的域名。在 GHL 托管的页面上，请使用 Payment Links 中的托管式结账（方法 A），或跳过 Apple Pay。

> [!WARNING]
>
> 内嵌式结账是 GHL 中涉及最多的选项。它需要自定义代码、后端、真实域名上的已发布页面，以及 Apple Pay 所需的域名验证。如果您不需要完全嵌入式的表单，请改用方法 A 或 B。

## 要处理的事件

将 GHL 端点订阅到您的工作流会执行操作的事件。下表为每个事件建议了相应的 GHL 操作：

| Dodo Payments 事件 | 触发时机 | 建议的 GHL 操作 |
| - | - | - |
| `payment.succeeded` | 付款成功时 | 将联系人标记为已付款、授予访问权限、发送确认信息 |
| `subscription.active` | 订阅激活时 | 授予会员资格、启动入门工作流 |
| `subscription.renewed` | 订阅续订至下一个计费周期时 | 延长下一个周期的访问权限 |
| `subscription.past_due` | 续订失败且宽限期开始时。客户在截止时间前仍保有访问权限 | 在客户仍有访问权限期间启动催收或提醒工作流 |
| `subscription.on_hold` | 续订失败后订阅被暂停时 | 暂停访问权限，升级提醒序列 |
| `subscription.cancelled` / `subscription.expired` | 订阅结束时 | 移除访问权限，将其标记为流失 |

付款和订阅事件会在 `data.customer.email` 中包含 **customer email**。使用 GHL 的 **find/create contact by email** 操作，将付款匹配到正确的联系人。有关每个事件的详情，请参阅 [Webhook Event Guide](/developer-resources/webhooks/intents/webhook-events-guide)。

## 测试与上线

**1. Test in Test Mode**

保持 Dodo Payments 侧边栏中的 **Live Mode** 开关关闭，以便在测试模式下操作。使用测试卡 `4242 4242 4242 4242`（有效期 `06/32`，CVV `123`）完成一次购买，并确认 GHL 工作流已运行且应用了相应标签或访问权限。

**2. Go Live**

打开 **Live Mode** 开关，并将 GHL Inbound Webhook URL 作为端点添加到实时模式中。其他需要更改的内容取决于您采用的方法：

* **Payment Links（A）：** 将链接替换为该产品的**实时**付款链接。
* **叠加式结账（B）：** 使用您的**实时** API 密钥，将后端指向 `https://live.dodopayments.com/checkouts`，并在 SDK 的 `Initialize` 调用中将 `mode` 设置为 `"live"`。
* **内嵌式结账（C）：** 进行与叠加式结账相同的更改，因为它使用相同的后端端点和 SDK 初始化。

然后从头到尾进行一次真实购买，以确认设置正确。

## 提示

> [!TIP]
>
> 将 **webhook 视为授予访问权限的事实来源**。根据 `payment.succeeded` 或 `subscription.active` 执行操作，而不是根据浏览器重定向执行。

> [!TIP]
>
> GHL Inbound Webhook 无法验证 `webhook-signature` 标头。为确保只有真实的 Dodo Payments 事件会在 GHL 中触发履行操作，请将 Dodo Payments webhook 端点指向您自己的后端，在那里验证每个事件（[Webhooks](/developer-resources/webhooks)），然后将其转发到 GHL Inbound Webhook URL。

## 故障排除

> **Payment succeeded but nothing happened in GHL**
>
> 检查 Dodo Payments webhook 端点是否指向正确的 GHL Inbound Webhook URL，工作流是否已**发布**，以及触发器是否捕获了示例负载，以确保字段映射存在。

> **Overlay or inline button does nothing**
>
> 自定义 JavaScript 通常只会在**真实域名上的已发布页面**中运行，而不会在预览中运行。确认页面已发布、SDK `<script>` 已加载，并且 `checkoutUrl` 是来自您后端的有效会话 URL。

> **Contact not created or not matched**
>
> 检查您的工作流是否使用 **find/create contact by email**，以及电子邮件字段是否映射自 webhook 负载。

> **Payment isn't showing in GHL's Payments tab**
>
> 这是预期行为。Dodo Payments 负责处理付款，因此请通过 webhook 工作流将其记录在 GHL 中。


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