腾讯公益开放平台 · 捐赠支付接入指引

适用对象：第三方应用开发人员 | 文档版本：v2.0 | 更新时间：2026-03

一、场景说明

腾讯公益开放平台为第三方机构提供标准化的捐赠支付能力接入，让您无需自建支付系统，即可在自己的小程序或 H5 页面中嵌入公益捐赠功能，帮助用户便捷地完成捐款，并获取完整的捐赠数据回传。

目前支持以下四种接入模式，覆盖不同业务场景：

1.1 乐捐模式

接入方页面跳转用户数据授权&登录页面，完成用户 id 打通且用户同意数据授权后，半屏拉起腾讯公益小程序对应项目项目详情页捐一笔支付浮层。

• 支持用户自选捐款金额
• 支持半屏拉起，无需跳转离开接入方小程序
• 捐款成功后自动回传数据至接入方

1.2 三合一模式

接入方页面跳转用户数据授权&登录页面，完成用户 id 打通且用户同意数据授权后，跳转腾讯公益对应项目三合一页面完成捐一笔支付。

• 自定义金额支付或定额金额
• 同时支持小程序和 H5 两种接入方式
• 捐款成功后自动回传数据至接入方
• 页面支持高度定制：自定义头图、背景色、按钮颜色
• 支持详细版和标准版两种项目卡片样式
  • 详细版卡片：头图比例 16:9，展示项目详细信息
  • 标准版卡片：头图比例 4:3，简洁展示项目核心信息

1.3 一起捐模式

接入方页面跳转用户数据授权&登录页面，完成用户 id 打通且用户同意数据授权后，半屏拉起腾讯公益小程序对应一起捐详情页捐一笔支付浮层。用户可参与该活动并完成捐赠，适合多人共同参与同一公益活动的场景。

• 支持小程序和 H5 两种接入方式
• 需提供一起捐活动 ID（did）
• 支持有登录态和无登录态两种 H5 跳转方式

1.4 月捐模式

接入方页面跳转用户数据授权&登录页面，完成用户 id 打通且用户同意数据授权后，半屏拉起腾讯公益小程序对应项目的项目详情页月捐开通浮层。引导用户开通指定项目的月捐服务，用户授权后每月自动代扣，接入方可查询用户的月捐开通状态和代扣信息。

• 支持小程序半屏拉起开通月捐
• 支持查询用户月捐开通状态
• 支持查询月捐故事数据
• 同时支持普通月捐和一起月捐两种形式

【重要】 以上所有接入模式，如需获取用户捐赠数据回传，必须先完成用户授权登录流程（见第二部分业务流程）。未完成用户授权直接调用支付接口，将导致下单报错，请务必在产品交互流程中提前处理，避免影响用户体验。

二、业务流程

本章节从整体视角说明接入腾讯公益捐赠支付的完整业务流程，帮助产品和技术团队了解各环节的职责划分和数据流转。

2.1 接入前准备

在开始技术对接前，需要完成以下准备工作：

• 邮件申请注册应用及权限（详见第四部分接入申请指引）
• 获取公益平台分配的 bid（业务ID）、appid（应用ID）和密钥（key）
• 配置支付成功通知回调地址（可选，用于接收支付成功通知）
• 小程序接入，如需半屏拉起，需在微信公众平台申请半屏小程序权限

⚠ 注意： bid、appid 和密钥（key）是您的应用凭证，密钥必须仅在后端服务中使用，严禁写入前端代码或小程序代码包中，防止泄露。

2.2 整体业务流程

无论哪种接入模式，整体业务流程均遵循以下步骤：

2.3 用户授权登录流程

更详细说明详见：小程序接入-外 · 公益开放平台接入文档

用户授权登录是获取捐赠数据回传的前提条件。流程如下：

1. 接入方小程序调用 wx.navigateToMiniProgram 或 wx.openEmbeddedMiniProgram 跳转至腾讯公益授权页面
2. 用户在腾讯公益小程序内完成登录并同意数据授权

1. 腾讯公益小程序关闭，通过 App.onShow 的 referrerInfo.extraData 回传 code
2. 接入方后端使用 code 换取 access_token（用户凭证）
3. 后续调用需要用户身份的接口时，携带 access_token

【提示】 授权页面同时包含「登录」和「用户授权」两个功能，用户无论同意或拒绝，都会直接关闭腾讯公益小程序并回到业务侧。需在 App.onShow 中注册监听，判断是否有 code 回传来确认授权是否成功。若用户已授权但 token 过期，重新唤起授权页时会自动跳过授权步骤，直接回传新的 code。

2.4 接入方式选择

仅适用于乐捐模式、三合一模式、一起捐模式

一个应用只能选择一种接入方式，不能同时使用两种方式，需在申请时与对接人确认：

更详细说明，详见：概述 · 公益开放平台接入文档

2.5 支付结果获取

仅适用于乐捐模式、三合一模式、一起捐模式

为保证业务完整获取到所有捐款成功的通知，平台提供三重保障机制：

⚠ 注意：

• 对于大部分业务来说，使用第一重策略即可，用户支付成功后，公益侧24小时内会做阶梯式回调（即不断重试），直到业务侧响应成功，具体重试策略详见：支付通知 · 公益开放平台接入文档
• 对于需要保证强一致性的业务，则必须采用第三重（账单对齐）的方式，来保证数据的最终一致性。
• 第二重策略，仅作为补充手段，适用于少量查询场景，仅在回调通知链路故障，或者需要查询某笔超出回调周期订单时进行主动查询，要求至少跳转到腾讯公益1分钟以上再查询。
• 错误使用场景： 跳转到腾讯公益，使用第二重策略轮询支付结果，严令禁止这样使用。
• 正确使用场景： 跳转到腾讯公益后，等待回调通知（第一重策略），如有必要，隔天进行账单下载对账（第三重策略）；在未进行隔天对账之前，若有用户反馈已支付，但未收到回调，则可进行主动查询（第二重策略）。

【提示】 回调通知的 URL 必须是后端服务地址，不能是前端页面地址。无论哪种接入方式，仅支付成功后才会收到回调通知，支付失败不会触发回调。回调地址在申请接入时配置，如需修改请联系对接人。

三、技术流程

本章节面向开发人员，详细说明各接入模式的技术实现流程，包括接口调用方式、参数说明和代码示例。

🔐 安全要求： 所有服务端 API 调用均需要在 HTTP 请求头中携带应用签名（Gy-H-Api-Sign）。签名使用 HMAC-SHA256 算法，需要用到应用密钥（key）。密钥必须仅在后端服务中使用，严禁在前端代码、小程序代码包、配置文件中明文存储。详细签名算法说明请参考：接口调用凭证

3.1 乐捐模式技术流程

接口文档：乐捐-支付接入

乐捐模式仅支持小程序接入，通过半屏方式拉起腾讯公益项目详情页完成捐款。

3.1.1 前置：用户授权登录

如需获取捐赠数据回传，必须先完成用户授权。

跳转小程序示例，详见：小程序接入-外 · 公益开放平台接入文档

3.1.2 获取下单票据（票据验证接入模式）

若使用票据验证接入，每次下单前需由后端调用接口获取 ticket：

🔐 安全要求： ticket 接口包含签名，必须在后端服务中调用，不能在小程序前端直接调用。

接口文档：获取下单 ticket

3.1.3 跳转公益小程序完成捐款

前端调用微信 API 跳转至腾讯公益项目详情页：

详见：支付接入 · 公益开放平台接入文档

3.1.4 接收支付结果

支付完成后通过两种方式获取结果：

方式一：前端回传（type=mp 时）

用户支付完成后，小程序会返回第三方小程序，并携带相关订单信息的参数，详见：支付接入 · 公益开放平台接入文档

方式二：后端支付通知回调

公益侧支付成功后，异步请求业务配置的回调地址。详细字段说明见：支付通知

3.2 三合一模式技术流程

接口文档：小程序接入 | H5接入

三合一模式支持小程序和 H5 两种接入方式，整体流程与乐捐模式相似，区别在于跳转的目标页面不同，且支持更多的页面定制能力。

【提示】 三合一模式与乐捐模式的前置授权流程、获取 ticket 流程完全相同，此处不再重复。两者区别仅在于跳转的目标页面 URL 和参数不同。

3.2.1 小程序接入

跳转至腾讯公益三合一支付页面：

详见：小程序接入 · 公益开放平台接入文档

3.2.2 H5 接入

H5 跳转至腾讯公益支付中间页：

详见：H5接入 · 公益开放平台接入文档

⚠ 注意： H5 接入如果是在小程序内嵌 webview 中使用，还需要额外配置业务域名（h5域名和ref_url域名都需要配置），并在域名根目录放置校验文件。请联系对接人配置。

3.2.3 页面定制说明

三合一模式支持以下页面定制能力（需在申请时提供）：

项目卡片详细版规范及示意：

项目卡片标准版规范及示意：

3.3 一起捐模式技术流程

接口文档：跳转一起捐详情页支付

一起捐模式需要额外提供一起捐活动 ID（did），用户将捐款关联至特定的一起捐活动。支持小程序和 H5 两种接入方式。

3.3.1 小程序接入

详见：跳转一起捐详情页支付 · 公益开放平台接入文档小程序部分说明

3.3.2 H5 接入

一起捐 H5 提供两种跳转方式：

有登录态跳转（需要用户授权）：

详见：跳转一起捐详情页支付 · 公益开放平台接入文档「跳转公益侧一起捐详情页支付（需登录）」部分说明

无登录态跳转（不需要用户提前授权）：

详见：跳转一起捐详情页支付 · 公益开放平台接入文档「跳转公益侧一起捐详情页支付（无登录态）」部分说明

3.4 月捐模式技术流程

接口文档：月捐小程序接入

月捐模式与单笔捐赠有所不同，核心是引导用户开通月捐签约，之后每月自动代扣。流程更复杂，需要查询用户状态并处理多种情况。

3.4.1 完整流程步骤

1. 用户授权登录（必须，月捐数据查询依赖用户凭证）
2. 查询用户月捐开通状态
   • 已开通：展示「我的月捐」入口，进入月捐故事页
   • 未开通：展示「开通月捐」入口，引导用户开通
3. 开通月捐：后端生成签约票据，前端半屏拉起公益小程序
4. 监听半屏关闭事件，重新查询月捐开通状态
5. 状态确认后，进入开通结果页或月捐故事页

3.4.2 查询月捐开通状态

🔐 安全要求： 此接口需要在后端调用（携带应用签名），同时需要用户凭证（access_token）。

详见：小程序接入 · 公益开放平台接入文档「查询月捐/一起月捐开通状态」接口

3.4.3 生成签约票据并拉起月捐开通

🔐 安全要求： 生成签约票据的接口必须在后端调用（包含应用签名），前端只负责使用 ticket 拉起半屏小程序。

步骤1：后端生成签约票据

调用：生成呼起半屏小程序的签约票据接口，获取 ticket 后返回给前端。

步骤2：前端使用 ticket 拉起月捐半屏小程序

步骤3：监听半屏关闭事件

具体接口说明，详见：小程序接入 · 公益开放平台接入文档

⚠ 注意： 回传的 extraData.status='open' 仅作通知用途，不代表月捐一定已成功开通；必须通过查询接口确认开通状态，避免因未收到回传而导致流程不闭环。

四、接入申请指引

在开始技术对接前，需要通过邮件向腾讯公益平台申请应用注册和接口权限。

4.1 申请方式

发送申请邮件至以下地址：

4.2 申请内容清单

邮件正文需包含以下信息：

• 需求背景： 描述申请接入捐赠支付的需求背景及申请原因，使用时间
• 应用场景： 介绍需接入捐赠支付的具体应用场景，附交互或截图
• 申请接口类型： 单笔捐赠乐捐模式/单笔捐赠三合一模式/一起捐捐赠/月捐接入
• 申请接口名称： 如月捐+小程序接入
• 接入方信息：
  • 机构名称、机构 id、公益项目 id
  • 业务名称
  • 小程序 appid：（如接入 H5 则不需要提供该项）
  • 业务域名：（前端跳转页面的域名，接入类型为 H5 时需为 http 或 https 开头的地址，跳转小程序不用填）
  • 调用量级（qps）：（超过100时请提供推导步骤及相关数据）
  • 回调地址：（指用户捐款后跳转的页面）
  • 支付结果通知地址：（指用户捐款后用户数据回传的地址，如果需要回传数据/状态请填写，必须为 http 或 https 开头的地址）
  • 是否需要支付前置条件判断：是/否（指是否需要回调具体金额、捐款时间等用户数据）
  • 数据回传类型：全量/部分/成功状态（全量及部分数据的差异如下图，成功状态指仅告知用户捐款是否成功）

• 三合一页面定制（如适用）：
  • 是否需要自定义三合一页面：是/否（如选否将使用公益平台默认背景样式）
  • 项目卡片类型：详细版/标准版
  • 三合一自定义头图：详细版项目卡片 16:9，标准版项目卡片 4:3，其余尺寸不支持。不提供时使用平台默认头图
  • 自定义背景色：提供一个纯色色号用于操作按钮及页面背景，如 #ED3142。不提供时使用平台默认背景色
  • 是否固定金额：是否限制用户下单金额，是需附上金额数字
  • 自定义金额是否配置默认金额：提供金额数字，需 ≥ 0.01，未提供时则为空
• 额外需要的接口列表：（除下单接口外，还需要接入的接口列表）
• 机构侧对接人名称及联系方式

4.3 所需证明材料

1. 机构申请接入的小程序主体需与申请机构一致： 邮件附小程序后台认证截图
2. 机构签署并提供数据保护承诺书： 数据保护承诺书，邮件附扫描件并线下寄送纸质版
   • 数据承诺书是由接入主体方来承诺：
   • 公募为申请主体，也就是小程序主体是公募的话，就是公募盖章
   • 非公募为申请主体，小程序主体是非公募就是非公募盖章
3. 如申请机构为非公募则需要提供公募机构的授权文件： 公益项目合作确认函，邮件附扫描件并线下寄送纸质版
4. 机构申请接入应用的项目需要是民政部备案的正式项目， 且是在腾讯公益平台上线的对应项目，在腾讯公益平台上线项目的善款接收/执行机构需与小程序接入主体机构一致。

备注说明：

1. 与公募合作的筹款合同如未涉及授权小程序接入和数据传输的内容，不可等同于公募授权确认函，所以还是需要公募同意授权小程序接入和数据传输的文档——公益项目合作确认函
2. 暂不支持子计划申请，根据合规要求，需要是民政部备案的正式项目，且是在腾讯公益平台上线的对应项目

线下材料邮寄地址：

邮寄地址：广东省深圳市南山区腾讯滨海大厦，收件人：陈先生，手机 18666211675

4.4 申请后流程

1. 公益平台评估申请并完成内部权限开通
2. 回复邮件，提供：公益平台应用 appid、业务 bid、密钥（key）、渠道标识等
3. 接入方调用相关接口，公益平台配合联调

4.5 半屏小程序权限申请

小程序接入需要申请半屏小程序权限（乐捐、三合一小程序、一起捐小程序、月捐均需要）：

1. 登录微信公众平台：https://mp.weixin.qq.com
2. 进入「设置 → 第三方设置 → 半屏小程序管理 → 添加」
3. 输入腾讯公益小程序 appid：wxfdcee92a299bcaf1，提交申请

附录：接口速查表

附录：常见问题