# 支付网关集成：开发者指南

> 了解如何规划、构建并上线可在全球规模化运行的支付网关集成，涵盖结账、webhooks、税务和支付后流程。
- **Author**: Ayush Agarwal
- **Published**: 2026-04-13
- **Category**: Developer Guide, Payments
- **URL**: https://dodopayments.com/blogs/zh/payment-gateway-integration-guide

---

支付网关集成听起来很简单，直到你真正超越演示阶段。创建结账页面并不是难点。真正的工作始于你需要可靠的 webhook 处理、支持税务的计费流程、本地化支付方式、幂等的订单创建，以及失败支付的恢复路径。

因此，大多数搜索支付网关集成指南的团队，并不是真的想再看一段按钮代码。他们是在设法避免一次脆弱的上线，以免在六周后产生客服工单、重复扣款或会计清理工作。

本指南将从开发者的角度介绍支付网关集成，涵盖架构、结账方式选择、后端流程设计、webhook 处理、测试，以及与仅提供网关的技术栈相比，使用 Dodo Payments 作为 MoR（名义商户）后会有哪些变化。

如果你还在编写代码前比较供应商，可以先阅读我们的[面向开发者的最佳计费 API](https://dodopayments.com/blogs/best-billing-apis-developers)、[支付网关对比](https://dodopayments.com/blogs/payment-gateway-comparison)、[如何接受在线支付](https://dodopayments.com/blogs/how-to-accept-online-payments)和[SaaS 嵌入式支付](https://dodopayments.com/blogs/embedded-payments-saas)。

## 支付网关集成实际上包含什么

至少，一个适用于生产环境的支付网关集成包含五个层面：

- 发起结账
- 客户与订单映射
- 支付状态管理
- webhook 处理
- 支付后的履约与恢复

只考虑第一层的团队，通常会在上线后重新构建其余部分。成功的集成重点不在结账组件，而在其周围的事件模型。因此，在确定架构前，最好先从头到尾了解[支付网关如何工作](https://dodopayments.com/blogs/how-payment-gateway-works)。

> 支付集成应被视为核心产品基础设施，而不是一次性的前端任务。按钮是最简单的部分。状态转换、重试和权益逻辑，决定了团队是快速推进，还是陷入数月的清理工作。
>
> - Ayush Agarwal，Dodo Payments 联合创始人兼 CPTO

使用 Dodo Payments 时，你可以从[集成指南](https://docs.dodopayments.com/developer-resources/integration-guide)开始，在[覆盖式结账](https://docs.dodopayments.com/developer-resources/overlay-checkout)和[内嵌式结账](https://docs.dodopayments.com/developer-resources/inline-checkout)之间选择，并通过[webhooks](https://docs.dodopayments.com/developer-resources/webhooks)连接下游自动化流程。这样既能缩小集成范围，也能让你自定义体验。

## 先选择合适的结账模式

在编写后端代码前，先决定结账应如何出现在你的产品中。大多数团队会从三种模式中选择一种：

### 托管支付链接

这是最快的上线方式。你创建一个支付会话或链接，然后将买家重定向过去。它非常适合 MVP、内容产品和轻量级结账流程。

### 覆盖式结账

覆盖式结账会在安全的模态窗口中加载支付体验，同时让用户留在你的网站上。对于 SaaS 应用、定价页面和希望减少页面跳转的注册流程，这是一个很好的选择。

### 内嵌式结账

内嵌式结账会将支付界面直接嵌入你的页面布局。当结账需要完全原生的体验，或你希望同时展示价格信息、功能摘要和结账字段时，这种方式最合适。

如果你正在构建产品驱动型 SaaS 流程，覆盖式或内嵌式结账通常比强制重定向表现更好，因为它能在注册、选择方案和计费过程中保留上下文。关于这一选择的更广泛讨论，包括每种模式下由谁承担 PCI 范围，请参阅我们对[托管式与自托管支付网关](https://dodopayments.com/blogs/hosted-vs-self-hosted-payment-gateway)的比较。

## 推荐的集成架构

对大多数团队而言，最清晰的设置是：

- 前端向你的后端请求结账会话
- 后端根据产品和客户上下文创建支付对象
- Dodo 负责收集结账信息并授权支付
- webhook 事件确认最终支付状态
- 只有在权威的成功事件到达后，你的应用才开通访问权限

最后一步很重要。绝不要仅根据前端回调授予访问权限。重定向可能失败，浏览器可能关闭，网络标签页可能中断。webhooks 才是持久可靠的事实来源。

```mermaid
flowchart LR
    A[Customer selects plan] --> B[Frontend calls backend]
    B --> C[Backend creates payment]
    C --> D[Dodo checkout]
    D --> E[Payment authorized]
    E --> F[Webhook delivered]
    F --> G[App provisions access]
    F --> H[CRM or email workflow]
```

这也是我们在[SaaS 嵌入式支付](https://dodopayments.com/blogs/embedded-payments-saas)、[Dodo Payments 的开发者体验](https://dodopayments.com/blogs/developer-experience-dodo-payments)和[结账优化](https://dodopayments.com/blogs/checkout-optimization)中推荐的事件优先方法。

## 分步完成支付网关集成

### 1. 清晰地建模产品和方案

在开始集成前，你应该先确定计费模型。明确你销售的是：

- 一次性支付
- 订阅
- 按用量计费
- 预付额度或预付余额

如果这些还不明确，请阅读[如何为 API 访问收费](https://dodopayments.com/blogs/charge-for-api-access)、[支付 API 指南](https://dodopayments.com/blogs/payment-api-guide)和[适用于 AI 代理的最佳支付 API](https://dodopayments.com/blogs/best-payment-api-ai-agents)。你选择的支付流程取决于你实际要变现的内容。

### 2. 在后端创建支付

使用服务器创建支付对象，这样你就能控制价格、产品映射和客户元数据。

```typescript
import DodoPayments from "dodopayments";

const client = new DodoPayments({
  bearerToken: process.env["DODO_PAYMENTS_API_KEY"],
});

export async function createCheckoutSession(user: {
  email: string;
  name: string;
  productId: string;
}) {
  return client.payments.create({
    payment_link: true,
    customer: {
      email: user.email,
      name: user.name,
    },
    billing: {
      city: "San Francisco",
      country: "US",
      state: "CA",
      street: "Market Street",
      zipcode: 94103,
    },
    product_cart: [{ product_id: user.productId, quantity: 1 }],
  });
}
```

这种模式能将定价逻辑保留在客户端之外，也为以后添加内部订单 ID、试用标记或营销活动归因提供了清晰的位置。

### 3. 将幂等性和重试视为必需项，而不是可选项

支付集成会以各种常见方式失败：用户重复点击、移动网络中断、前端重试发生竞争，或后台任务再次运行。

请为以下情况做好准备：

- 重复创建会话的尝试
- webhook 重复投递
- 延迟的支付确认
- 履约任务运行两次

造成收入流失最快的方式，就是让订单开通流程不具备幂等性。如果你的系统无法安全地接收同一个成功事件两次，就还没有准备好。这也是团队上线后最终会去了解[SaaS 收入流失](https://dodopayments.com/blogs/revenue-leakage-saas)和[催收管理](https://dodopayments.com/blogs/dunning-management)的原因之一。

### 4. 使用 webhooks 作为权威事件流

webhooks 是让集成变得可靠的关键。你可以用它触发以下下游操作：

- 授予产品访问权限
- 激活订阅
- 发送收据
- 更新 CRM
- 启动新手引导邮件
- 在恢复失败或取消后撤销访问权限

下面是一个简单的 Node webhook 处理程序结构：

```typescript
import crypto from "node:crypto";

export async function handleWebhook(req: Request) {
  const body = await req.text();
  const signature = req.headers.get("webhook-signature") || "";

  verifySignature(body, signature, process.env.DODO_WEBHOOK_SECRET!);

  const event = JSON.parse(body);

  if (event.type === "payment.succeeded") {
    await provisionOrder(
      event.data.customer.customer_id,
      event.data.payment_id,
    );
  }

  if (event.type === "payment.failed") {
    await markPaymentAtRisk(event.data.payment_id);
  }

  return new Response("ok", { status: 200 });
}

function verifySignature(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  const expectedBuffer = Buffer.from(expected);
  const receivedBuffer = Buffer.from(signature);

  if (
    expectedBuffer.length !== receivedBuffer.length ||
    !crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
  ) {
    throw new Error("Invalid signature");
  }
}
```

注意比较方式。应使用 `crypto.timingSafeEqual`，而不是对摘要字符串使用 `!==`，因为普通字符串比较会在第一个不匹配的字节处退出，从而泄露签名中有多少内容是正确的。始终比较原始请求正文，而不是解析后重新序列化的对象，因为重新序列化会改变键顺序和空白字符，使原本有效的签名失效。请参考 webhooks 文档，正确配置重试、签名验证和事件处理。

### 5. 将支付成功与履约完成分开

支付完成并不总意味着订单已经完全履约。有些产品还需要额外步骤：

- 创建工作区
- 分配权益
- 生成许可证密钥
- 解锁高级模块
- 在 ERP 中创建发票记录

将这些步骤设计为带有可见内部状态的后台任务，而不是请求周期中隐藏的同步步骤。这样更容易从部分失败中恢复，也更容易追踪事故。

## 仅网关技术栈与 MoR（名义商户）技术栈

如果你直接集成支付网关，你的团队仍需负责税务注册、申报、发票合规、争议处理以及大量恢复流程。如果你希望拥有最大控制权，并且已经具备相应的运营能力，这没有问题。

但许多软件公司并不需要更多支付基础设施，而是需要更少的环节。

使用 Dodo Payments 作为 MoR（名义商户）时，你仍能获得面向开发者的友好集成能力，但法定销售方的责任会从你的团队转移出去。这会显著改变整体实施范围，尤其是当你要向 220 多个国家和地区销售，或之后添加本地化支付方式时。

> 大多数开发者首先根据 API 形式比较支付服务商，之后才会发现真正的成本在 API 之外。税务、合规、失败支付恢复和争议处理，才决定一个技术栈在六个月后是简单还是痛苦。
>
> - Rishabh Goel，Dodo Payments 联合创始人兼 CEO

如需做出更全面的决策，请比较[支付网关对比](https://dodopayments.com/blogs/payment-gateway-comparison)、[支付编排](https://dodopayments.com/blogs/payment-orchestration)、[适用于 SaaS 的 MoR（名义商户）](https://dodopayments.com/blogs/merchant-of-record-for-saas)和[最佳 MoR（名义商户）平台](https://dodopayments.com/blogs/best-merchant-of-record-platforms)。

## 常见的支付网关集成错误

### 根据重定向而不是 webhook 授予访问权限

如果你的前端成功页面将账户从免费切换为付费，最终一定会出现状态不一致。

### 将业务逻辑硬编码在客户端

产品 ID、方案映射和折扣逻辑应放在后端。

### 忽视本地化支付方式

如果你希望提高跨境转化率，结账不能永远只支持银行卡。请阅读[为什么本地化支付方式有助于提高转化率](https://dodopayments.com/blogs/why-localized-payment-methods-are-important-for-higher-conversions)。

### 没有规划恢复流程

失败支付是系统的一部分，而不是例外。确保从第一天起，集成就包含重试、沟通和访问状态规则。

### 将支付基础设施视为一个冲刺任务

你需要可观测性、事件日志、测试用例和运营手册。无论你是在 SaaS 产品中嵌入结账，还是构建[白标支付网关](https://dodopayments.com/blogs/white-label-payment-gateway)体验，都是如此。

## 上线前测试清单

上线前运行以下场景：

- 在桌面端和移动端成功支付
- 用户在完成前关闭结账页面
- 前端重试创建支付请求
- webhook 到达两次
- webhook 延迟到达
- 支付失败后，用户使用新支付方式重试
- 订阅成功续期
- 续期失败触发恢复流程
- 退款或取消正确更新内部状态

还要明确测试身份验证流程，因为[3D Secure](https://dodopayments.com/blogs/3d-secure-3ds-payment-authentication)挑战会引入重定向和延迟确认，而这些在直接使用国内测试卡运行时通常不会出现。如果你需要更简单的验收清单，我们的[如何接受在线支付](https://dodopayments.com/blogs/how-to-accept-online-payments)指南是很好的补充。如果你希望采用可编程性最高的路径，请结合 Dodo 集成指南以及覆盖式结账、内嵌式结账和 webhooks 文档使用。

## 可观测性和运行手册同样重要

支付上线后，下一个问题不是"结账是否渲染成功？"，而是"我们能否在五分钟内解释每一种支付状态？"

至少，你的团队应该能够追踪：

- 从前端请求 ID 到后端订单 ID
- 从后端订单 ID 到支付 ID
- 从支付 ID 到已接收的 webhook 事件
- 从 webhook 事件到履约结果

这能显著加快事故响应。当客户表示已经支付但没有获得访问权限时，也能让客服、财务和工程团队保持一致。如果你的产品正在增长，请将支付可观测性添加到同一个内部仪表板中，在那里监控[SaaS 收入流失](https://dodopayments.com/blogs/revenue-leakage-saas)、[催收管理](https://dodopayments.com/blogs/dunning-management)和[结账优化](https://dodopayments.com/blogs/checkout-optimization)。

优秀的支付集成不仅能在一切正常时成功，也能在出现异常时保持清晰可理解。

## 常见问题

### 开始集成支付网关最简单的方法是什么？

最安全快速的方式是在后端创建支付，启动托管式或覆盖式结账，并使用 webhooks 作为履约的事实来源。这样你可以快速上线，同时避免将业务逻辑绑定到前端。

### 我应该使用重定向式、覆盖式还是内嵌式结账？

如果追求最快上线，请使用重定向式结账；如果是应留在网站内的 SaaS 和新手引导流程，请使用覆盖式结账；如果结账需要直接位于页面布局中，请使用内嵌式结账。Dodo 支持这三种模式，并提供逐步增强的控制能力。

### 为什么 webhooks 在支付集成中如此重要？

因为浏览器重定向并不是可靠的状态来源。即使客户关闭标签页，webhooks 仍能为开通访问权限、发送收据以及处理重试或失败提供持久的支付事件。

### 如何避免重复扣款或重复履约？

让支付创建和履约流程具备幂等性。预期前端和支付平台都会发生重试，并设计订单状态机，使同一事件可以被处理多次而不会产生副作用。

### 什么时候应该选择 MoR（名义商户），而不是仅网关方案？

当你希望获得面向开发者的友好集成，同时将税务、合规和争议处理外包时，可以选择 MoR（名义商户）。对于面向全球销售的 SaaS 和数字产品，这尤其有用。

## 总结

最好的支付网关集成，是上线后依然平稳无感的集成。如果结账成功、webhooks 能协调状态、恢复流程已经定义好，并且你的团队不需要每周手动修复边界情况，那就说明你构建得很好。

如果你希望实现这一结果，而不必自行拼接支付、税务和合规能力，请了解[Dodo Payments](https://dodopayments.com)，并查看[定价](https://dodopayments.com/pricing)。然后使用集成指南，从第一天起构建更清晰的实现。
---
- [More Developer Guide articles](https://dodopayments.com/blogs/category/developer-guide)
- [All articles](https://dodopayments.com/blogs)