一次性支付集成指南

前提条件

要集成 Dodo Payments API，您需要：

一个 Dodo Payments 商户账户
从仪表板获取的 API 凭证（API 密钥和 webhook 密钥）

仪表板设置

访问 Dodo Payments 仪表板
创建一个产品（一种一次性支付或订阅）。订阅产品的定价至少应为 $1（或您选择的货币的等值金额）；不支持低于此最低金额的金额。
生成您的 API 密钥：
- 前往开发者 > API
- 详细指南
- 将 API 密钥复制到名为 DODO_PAYMENTS_API_KEY 的环境变量中
配置 webhooks：
- 前往开发者 > Webhooks
- 创建用于支付通知的 webhook URL
- 将 webhook 密钥复制到环境变量中

集成

支付链接

选择适合您用例的集成路径：

结账会话（推荐）：适用于大多数集成。在您的服务器上创建会话，将客户重定向到安全的托管结账页面。
覆盖结账：当您需要在页面内体验可以将结账作为模态覆盖打开时使用。
内嵌结账：将结账直接嵌入页面布局中，以实现完全集成和品牌化的结账体验。
静态支付链接：无需编码，即可立即共享 URL 以快速收款。
动态支付链接：以编程方式创建链接。然而，推荐使用结账会话，提供更多灵活性。

1. 结账会话

使用结账会话创建一个安全的托管结账体验，用于一次性支付或订阅。您在服务器上创建会话，然后将客户重定向到返回的 checkout_url。

缺省情况下，结账会话有效期为24小时。如果您传递 confirm=true，会话有效期为15分钟，所有必填字段都必须提供。

Create a checkout session

选择您偏好的 SDK 或调用 REST API。

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customer: { email: 'customer@example.com', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "prod_123", "quantity": 1}],
    customer={"email": "customer@example.com", "name": "John Doe"},
    return_url="https://yourapp.com/checkout/success",
)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
  },
  body: JSON.stringify({
    product_cart: [{ product_id: 'prod_123', quantity: 1 }],
    customer: { email: 'customer@example.com', name: 'John Doe' },
    return_url: 'https://yourapp.com/checkout/success',
  }),
});
const session = await response.json();

Redirect customer to checkout

创建会话后，重定向到 checkout_url 开始托管流程。

// Example in a browser context
window.location.href = session.checkout_url;

对于最快、最可靠的收款方式，首选结账会话。有关高级自定义的信息，请参阅完整的结账会话指南和API 参考。

2. 覆盖结账

如需无缝的页面内结账体验，请探索我们的覆盖结账集成，允许客户在不离开您的网站的情况下完成支付。

3. 内嵌结账

如需将结账体验完全嵌入到您的页面中，请使用我们的内嵌结账集成。这使您可以自定义订单摘要，并完全控制结账布局，同时 Dodo Payments 安全地处理支付收款。

4. 静态支付链接

静态支付链接通过共享简单的 URL 可以快速接受支付。您可以通过传递查询参数来自定义结账体验，以预填充客户详细信息、控制表单字段并添加自定义元数据。

Construct your payment link

从基本 URL 开始，并附加您的产品 ID：

https://checkout.dodopayments.com/buy/{productid}

Add core parameters

包含必要的查询参数：

integer
默认值:"1"
购买的商品数量。
string
必填
支付完成后的重定向 URL。

重定向 URL 将包含支付详情作为查询参数，例如：
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

如果产品启用了许可证密钥，还会添加一个 license_key 参数（对于多个密钥以逗号分隔）：
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

Pre-fill customer information (optional)

添加客户或账单字段作为查询参数，以简化结账。

Supported Customer Fields

string
客户的全名（如果提供了 firstName 或 lastName 则忽略）。
string
客户的名字。
string
客户的姓氏。
string
客户的电子邮件地址。
string
客户的国家/地区。
string
街道地址。
string
城市。
string
州或省。
string
邮政编码/邮政编码。
boolean
真或假

Control form fields (optional)

您可以禁用特定字段，使其为只读状态。这在您已拥有客户详细信息时特别有用（例如，已登录用户）。

要禁用某个字段，请提供其值并将相应的 disable… 标志设置为 true：

&email=alice@example.com&disableEmail=true

Disable Flags Table

字段	禁用标志	必需参数
全名	`disableFullName`	`fullName`
名字	`disableFirstName`	`firstName`
姓氏	`disableLastName`	`lastName`
电子邮件	`disableEmail`	`email`
国家	`disableCountry`	`country`
地址行	`disableAddressLine`	`addressLine`
城市	`disableCity`	`city`
州	`disableState`	`state`
邮政编码	`disableZipCode`	`zipCode`

禁用字段有助于防止意外更改并确保数据一致性。

设置 showDiscounts=false 将禁用和隐藏结账表单中的折扣部分。如果您想防止客户在结账过程中输入优惠券或促销代码，请使用此选项。

Add advanced controls (optional)

string
指定付款货币。默认为账单国家的货币。
boolean
默认值:"true"
显示或隐藏货币选择器。
integer
金额为分（仅适用于“随心支付”定价）。
string
自定义元数据字段（例如，metadata_orderId=123）。

Share the link

将完整的支付链接发送给您的客户。当他们访问时，所有查询参数将被收集并存储在会话 ID 中。然后，URL 将简化为仅包括会话参数（例如，?session=sess_1a2b3c4d）。存储的信息在页面刷新时持续存在，并可在整个结账过程中访问。

客户的结账体验现已根据您的参数流线化和个性化。

4. 动态支付链接

大多数用例中首选结账会话，它们提供更多的灵活性和控制。

通过带有客户详细信息的 API 调用或我们的 SDK 创建。以下是一个示例：有两个用于创建动态支付链接的 API：

一次性支付链接 API API 参考
订阅支付链接 API API 参考

以下指南是针对一次性支付链接创建的。有关集成订阅的详细说明，请参考此订阅集成指南。

确保您传递 payment_link = true 以获取支付链接

Node.js SDK
Python SDK
Go SDK
Api Reference

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: 'email@email.com', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted (if using same name `DODO_PAYMENTS_API_KEY`)
environment="test_mode",  # defaults to "live_mode"
)
payment = client.payments.create(
payment_link=True,
billing={
    "city": "city",
    "country": "AF",
    "state": "state",
    "street": "street",
    "zipcode": 0,
},
customer={
    "email": "email@email.com",
    "name": "name",
},
product_cart=[{
    "product_id": "product_id",
    "quantity": 0,
}],
)
print(payment.payment_link)

package main

import (
"context"
"fmt"

"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)

func main() {
client := dodopayments.NewClient(
option.WithBearerToken("My Bearer Token"), // defaults to os.LookupEnv("DODO_PAYMENTS_API_KEY")
)
payment, err := client.Payments.New(context.TODO(), dodopayments.PaymentNewParams{
PaymentLink: dodopayments.F(true),
Billing: dodopayments.F(dodopayments.PaymentNewParamsBilling{
  City: dodopayments.F("city"),
  Country: dodopayments.F(dodopayments.CountryCodeAf),
  State: dodopayments.F("state"),
  Street: dodopayments.F("street"),
  Zipcode: dodopayments.F(int64(0)),
}),
Customer: dodopayments.F(dodopayments.PaymentNewParamsCustomer{
  Email: dodopayments.F("email"),
  Name: dodopayments.F("name"),
}),
ProductCart: dodopayments.F([]dodopayments.PaymentNewParamsProductCart{dodopayments.PaymentNewParamsProductCart{
  ProductID: dodopayments.F("product_id"),
  Quantity: dodopayments.F(int64(0)),
}}),
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", payment.PaymentLink)
}

import { NextRequest, NextResponse } from "next/server";      

export async function POST(request: NextRequest) {
try {
const body = await request.json();
const { formData, cartItems } = paymentRequestSchema.parse(body);

const response = await fetch(`${process.env.NEXT_PUBLIC_DODO_TEST_API}/payments`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.DODO_API_KEY}`, // Replace with your API secret key generated from the Dodo Payments Dashboard
  },
  body: JSON.stringify({
    billing: {
      city: formData.city,
      country: formData.country,
      state: formData.state,
      street: formData.addressLine,
      zipcode: parseInt(formData.zipCode),
    },
    customer: {
      email: formData.email,
      name: `${formData.firstName} ${formData.lastName}`,
      phone_number: formData.phoneNumber || undefined,
    },
    payment_link: true,
    product_cart: cartItems.map((id) => ({
      product_id: id,
      quantity: 1,
    })),
    return_url: process.env.NEXT_PUBLIC_RETURN_URL,
  }),
});

if (!response.ok) {
  const errorData = await response.json().catch(() => null);
  return NextResponse.json(
    { error: "Payment link creation failed", details: errorData },
    { status: response.status }
  );
}

const data = await response.json();
return NextResponse.json({ paymentLink: data.payment_link });
} catch (err) {
console.error("Payment error:", err);
return NextResponse.json(
  {
    error: err instanceof Error ? err.message : "An unknown error occurred",
  },
  { status: 500 }
);
}
}

创建支付链接后，让您的客户完成支付。

实施 Webhooks

设置一个 API 端点以接收支付通知。以下是使用 Next.js 的示例：

import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}

我们的 webhook 实现遵循标准 Webhooks 规范。有关 webhook 类型定义，请参阅我们的 Webhook 事件指南。您可以参考此项目，在 GitHub 上使用 Next.js 和 TypeScript 进行演示实现。您可以在这里查看实时实施。

Create Checkout Session

创建安全托管结账会话以进行一次性支付和订阅的 API 参考

Create Payment Link

以编程方式创建动态支付链接的 API 参考

Integration Guides

Billing Deconstructions

Cookbooks

前提条件

仪表板设置

集成

支付链接

1. 结账会话

2. 覆盖结账

3. 内嵌结账

4. 静态支付链接

4. 动态支付链接

实施 Webhooks

相关 API 参考

Create Checkout Session

Create Payment Link

​前提条件

​仪表板设置

​集成

​支付链接

​1. 结账会话

​2. 覆盖结账

​3. 内嵌结账

​4. 静态支付链接

​4. 动态支付链接

​实施 Webhooks

​相关 API 参考

Create Checkout Session

Create Payment Link

前提条件

仪表板设置

集成

支付链接

1. 结账会话

2. 覆盖结账

3. 内嵌结账

4. 静态支付链接

4. 动态支付链接

实施 Webhooks

相关 API 参考