后端金融科技【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/yansongda/pay点击查看免费下载导读本篇技术指南聚焦 yansongda/pay 扩展包中的抖音Douyin通用交易系统退款能力完整覆盖退款全生命周期通过Pay::douyin()-refund($order)创建退款、以_action参数分发退款审核、通过query()查询退款单状态以及处理typepre_create_refund退款申请回调并构造同步应答。读完本文你将掌握抖音退款各环节的参数要求、SDK 底层插件调用链与验签原理能直接在自己的 Laravel / ThinkPHP 等项目中落地可用的退款功能。一、能力总览refund() 一个入口两个动作抖音通用交易系统的退款能力在 SDK 中统一收敛到refund()方法通过_action参数在「创建退款」与「退款审核」两个动作之间分发两个动作均返回Collection方法名参数返回值分发动作_actionrefundarray $orderCollectiondefault创建退款/audit退款审核从源码结构看这一分发逻辑由 RefundShortcut 实现它读取$params[_action]默认值为DouyinAction::REFUND_DEFAULT即default命中后返回对应的插件管线传入audit时走退款审核管线其他值则抛出PARAMS_SHORTCUT_ACTION_INVALID异常。DouyinAction常量定义在 DouyinAction.php。refund()的实际入口位于 Douyin Provider它先派发MethodCalled事件再通过__call路由到\Yansongda\Pay\Shortcut\Douyin\RefundShortcut最终由 Artful 管线完成「获取 client_token → 构建请求 → 发送 → 校验响应 → 解析」的全流程。与支付宝、微信不同抖音交易系统不提供cancel()/close()接口Provider 中对这两个方法直接抛出「抖音不支持 cancel/close API」异常见 Douyin.php。二、创建退款_action默认2.1 最小可用示例Pay::config($config); $order [ order_id xxxx, out_refund_no 202408040747147327R, refund_reason [ 测试退款, ], // notify_url https://yansongda.cn/douyin/refund/notify, // 选填默认取配置中的 notify_url ]; $result Pay::douyin()-refund($order);2.2 订单配置参数order_id抖音侧订单号必填标识要对哪笔订单发起退款。out_refund_no商户侧退款单号必填商户系统内全局唯一退款结果查询与回调应答都依赖它。refund_reason[]退款理由必填数组类型具体元素结构如code/text按抖音官方文档填充。notify_url退款结果回调地址选填。不传时 SDK 自动注入配置中的notify_url若配置中也为空则平台使用下单时传入的地址。其余参数与抖音官方接口无任何差别SDK 对业务字段一律透传兼容所有官方能力完整「请求参数」请参考官方「发起退款」API 文档/api/trade_basic/v1/developer/refund_create/。2.3 源码级解析notify_url 的注入规则创建退款由 RefundPlugin 装载其关键行为校验 payload使用filter_params()过滤后为空则抛出「参数异常: 抖音创建退款缺少必要的业务参数」对应异常码PARAMS_NECESSARY_PARAMS_MISSING。合并_method POST、_url /api/trade_basic/v1/developer/refund_create/。notify_url 注入规则仅当业务方未显式传notify_url且配置中的notify_url非空时才把配置值合入 payload——显式传入优先配置值兜底。该规则在 RefundPluginTest.php 中有两个方向相反的测试佐证未传notify_url时自动注入https://yansongda.cn/douyin/notify显式传入时配置值不被覆盖。测试同时断言创建退款请求不注入app_id字段业务接口均无该字段。创建退款完整管线见 RefundShortcut::defaultPlugins()StartPlugin → ObtainClientTokenPlugin → RefundPlugin → AddPayloadBodyPlugin → AddRadarPlugin → ResponsePlugin → ParserPlugin。其中ObtainClientTokenPlugin负责注入access-token支持外部传入_access_token否则自动获取并进程内缓存缓存 key 为app_id提前 60 秒过期见 DouyinTrait::getDouyinClientToken()ResponsePlugin统一校验 HTTP 状态码为 2xx 且响应顶层err_no 0非 0 时抛出业务异常见 ResponsePlugin.php。三、退款审核_action audit3.1 场景说明用户发起退款申请后若退款单状态为「待审核」开发者需通过退款审核接口同步审核结果同意/拒绝此时refund()的_action必须为audit。3.2 代码示例Pay::config($config); $order [ refund_id 7398108028895054107, refund_audit_status 1, // 1同意退款2拒绝退款 // deny_message 商品已核销无法退款, // 拒绝refund_audit_status 为 2时必填 _action audit, ]; $result Pay::douyin()-refund($order);3.3 订单配置参数refund_id抖音侧退款单号必填。refund_audit_status审核状态必填1同意退款 /2拒绝退款。deny_message拒绝原因refund_audit_status为2拒绝时必填。其余参数与官方接口一致SDK 全部透传完整「请求参数」请参考官方「退款审核」API 文档对应接口/api/trade_basic/v1/developer/refund_audit_callback/。3.4 源码级解析审核插件的透传行为退款审核由 AuditPlugin 装载行为特征空 payload过滤后直接抛「参数异常: 抖音退款审核缺少必要的业务参数」。合并_method POST、_url /api/trade_basic/v1/developer/refund_audit_callback/业务字段refund_id/refund_audit_status/deny_message原样透传。不注入app_id、notify_url——AuditPluginTest.php 断言 payload 键值仅为refund_id、refund_audit_status、_method、_url。注意SDK 对deny_message仅透传不做必填强校验官方服务端校验拒绝时务必自行带上。四、查询退款单query()的 refund 动作退款结果的主动查询走query()方法_action为refund与创建退款、退款审核相互配合Pay::config($config); $order [ out_refund_no 202408040747147327R, _action refund, ]; $result Pay::douyin()-query($order);查询退款的参数规则refund_id抖音侧退款单号、out_refund_no商户侧退款单号、order_id抖音侧订单号按订单查询上限 50 条三选一必填其余参数与官方一致对应接口/api/trade_basic/v1/developer/refund_query/。底层由 RefundQueryPlugin 装载同样只合并_method/_url并透传业务字段QueryPluginTest.php 验证了refund_id、out_refund_no、order_id均可透传且不注入app_id/notify_url。query()的_action分发逻辑见 QueryShortcut支持order默认/cps/refund三种动作。五、响应退款申请回调typepre_create_refund5.1 回调机制与同步应答的必要性用户从交易模板组件发起退款后平台会向开发者服务端发送typepre_create_refund的退款申请回调。SDK 统一通过callback()入口处理验签 解析msg同步应答体由业务方自行构造并返回详见 接收抖音回调。:::warning 注意 若不响应未按下方格式应答平台会一直重试并导致用户退款卡单请务必实现同步应答。 :::callback()返回的Collection中会包含refund_id、out_refund_no、need_refund_audit、refund_audit_deadline等退款申请信息其中out_refund_no仅在该退款单已存在时非空因此业务方需要自行生成商户侧退款单号并据此应答。5.2 业务方应答示例Laravel 风格// $result Pay::douyin()-callback($request); // $result 中包含 refund_id、order_id、need_refund_audit、refund_audit_deadline 等退款申请信息 return response()-json([ err_no 0, err_tips success, data [ out_refund_no 202408040747147327R, // 业务方自行生成的商户侧退款单号 order_entry_schema $result-get(order_entry_schema), ], ]);5.3 应答 JSON 结构{ err_no: 0, err_tips: success, data: { out_refund_no: 202408040747147327R, order_entry_schema: { path: pages/refund/detail, params: {\out_refund_no\:\202408040747147327R\} } } }各字段含义请参考抖音官方「退款申请回调」文档。注意order_entry_schema中的params是字符串化的 JSON内部再包一层双引号需按官方格式原样返回。5.4 源码级解析callback() 的验签与解析统一回调入口在 Douyin Provider::callback()仅接受ServerRequestInterface或null传array会抛出「抖音新交易系统回调需要携带回调头信息以完成验签」异常传null时通过ServerRequest::fromGlobals()自动获取请求建议仅在 php-fpm 下使用swoole 请显式传请求实例。CallbackPlugin 负责用douyin_public_key抖音平台公钥验签 → 校验 body 顶层type存在且为非空字符串 → 解析msg为Collection并设置NoHttpRequestDirection不发 HTTP 请求直接返回解析结果。验签细节见 DouyinTrait::verifyDouyinTradeSign()取请求头Byte-Timestamp/Byte-Nonce-Str/Byte-Signature与原始 body拼成{Byte-Timestamp}\n{Byte-Nonce-Str}\n{原始body}\n三行验签串以SHA256withRSA校验。必须使用未经解析的原始 body——body 经框架解析/排序后验签必失败因此请将框架原样的 PSR-7 请求传入。三类回调payment支付结果 /refund退款结果 /pre_create_refund退款申请统一走callback()SDK 仅校验顶层type存在业务方需按 body 的type自行分发处理CallbackPluginTest.php 验证了pre_create_refund回调解析后need_refund_audit等字段可正常读取篡改签名则抛出InvalidSignException异常码SIGN_ERROR。六、配置与运行环境前提抖音退款功能依赖的配置项由 DouyinConfig 承载其中app_id与app_secret为必填缺失时抛出CONFIG_DOUYIN_INVALID见 DouyinConfigTest.php其余常用项配置键说明是否必填app_id抖音小程序 App IDtt开头必填app_secret应用密钥必填app_private_key应用私钥发起请求签名用SHA256-RSA2048视功能需要douyin_public_key抖音平台公钥回调验签用回调必填notify_url退款结果回调地址创建退款未传时自动注入选填mode运行模式PayMode::NORMAL/PayMode::SANDBOX兼容历史 int 写法0/1/2选填请求侧签名由 DouyinTrait::getDouyinTradeSign() 实现按{method}\n{uri}\n{timestamp}\n{nonce}\n{body}\n拼串后用应用私钥做 SHA256 签名产出SHA256-RSA2048 appid...,nonce_str...,timestamp...,key_version1,signature...格式的access-token请求头注意与回调验签串格式不同勿混淆。沙箱模式下请求域名切换为https://open-sandbox.douyin.com见 Douyin Provider::URL便于联调。七、常见问题与注意事项退款申请回调必须同步应答不按err_no0格式应答平台会持续重试并卡单。order_entry_schema必须原样透传callback()返回的 Collection 中已包含该字段直接$result-get(order_entry_schema)即可不要自行构造。out_refund_no自行生成退款申请回调里该字段可能为空商户侧退款单号由业务方生成并回传。回调请求不要手动解析重建验签依赖原始 body 与Byte-*请求头请直接传入框架原样的 PSR-7 请求。拒绝退款时带上deny_messageSDK 仅透传不校验缺了会被官方服务端拒绝。_action非法值会抛异常refund()只接受default/auditquery()只接受order/cps/refund。关联文档退款审核audit查询退款单query接收抖音回调与验签说明确认回调应答success抖音更多方便的插件赞分享后端金融科技【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/yansongda/pay点击查看免费下载相关推荐Yansongda Pay 抖音小程序退款实战退款创建、退款审核与退款申请回调完整指南Yansongda Pay 抖音小程序退款实战退款创建、退款审核与退款申请回调完整指南 本篇指南以 Yansongda Pay 开源支付 SDK 中抖音通用交金融科技后端WeiXinMPSDK 微信支付退款实战TenPayOldV3.Refund 申请退款与 RefundNotifyUrl 回调解密全流程WeiXinMPSDK 微信支付退款实战TenPayOldV3.Refund 申请退款与 RefundNotifyUrl 回调解密全流程 本文基于 WeiXi后端即时通讯金融科技yansongda/pay 翼支付Bestpay退款实战指南refund 方法、订单参数与异步退款回调全流程解析yansongda/pay 翼支付Bestpay退款实战指南refund 方法、订单参数与异步退款回调全流程解析 本文围绕 yansongda/pay 开后端金融科技上一篇从行为 NFT 到匿名信用评估Dapp-Learning 仓库中的链上数字身份设计下一篇网盘下载卡在99%这个开源网盘直链下载助手脚本帮你拿到真实下载地址创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考