如何用Paddle.com v2 JavaScript API实现自定义价格结账？

问题概述 #

使用Paddle.Checkout.open()的override参数传入动态生成的完整Pay Link URL时，触发错误：

API Error: The transaction id field is required when items is not present.

但直接在浏览器打开该Pay Link可正常进入结账页面，需求是通过Paddle内置弹窗实现自定义价格结账。

核心原因 #

override参数不接受完整的Pay Link URL，而是需要传入Pay Link对应的交易ID（transaction id）。Pay Link本质是指向一个已预创建的交易记录，完整URL中已经包含了该交易ID，只需提取即可。

解决方案 #

方法1：从Pay Link中提取交易ID传入override #

Pay Link的格式通常为https://checkout.paddle.com/checkout/transact/[transaction-id]，可以通过字符串解析提取最后一段的交易ID，再传入override参数：

// 示例Pay Link
const payLink = "https://sandbox-checkout.paddle.com/checkout/transact/txn_01hjs2k565abcdef";
// 提取交易ID
const transactionId = payLink.split("/").pop();

// 打开弹窗结账
Paddle.Checkout.open({
    override: transactionId
});

这样就能正常触发Paddle的弹窗结账，且无需手动创建交易记录。

关于自定义价格的补充（2024年7月更新） #

目前Paddle已支持在自定义价格记录中添加name参数，该参数会显示在购买页面及PDF收据中。注意必须同时包含description字段（尽管官方说明该字段仅用于内部，但缺少会导致请求失败），示例如下（后端创建自定义价格交易时的参数）：

{
    "items": [
        {
            "quantity": 1,
            "price": {
                "name": "自定义服务名称", // 显示给用户的名称
                "description": "内部描述", // 必填字段
                "unit_price": { "currency_code": "USD", "amount": "123" },
                "product_id": "pro_01hjs2k565…"
            }
        }
    ]
}

安全最佳实践 #

虽然前端提取交易ID可以快速解决问题，但不建议在前端直接生成Pay Link或交易记录（如你之前尝试的前端调用API方式），因为会暴露敏感的API密钥。正确的流程应该是：

• 在后端完成交易记录的创建或Pay Link的生成（使用服务器端的API密钥）
• 将生成的交易ID或Pay Link返回给前端
• 前端使用交易ID传入override参数打开弹窗

这种方式既能保证安全性，也符合Paddle的最佳实践。

内容的提问来源于stack exchange，提问作者Thomas Tempelmann