交易退款流程说明

我的收藏

说明

本文档是对pay-button退款组件接口的对接流程说明，接口字段和详细示例可查看pay-button退款组件

用户视角退款流程

技术接入流程图

第一步：接入pay-button + 传入退款信息（前端组件）

接口文档

开发者前端接入退款组件，并指定退款操作信息

方案名	说明	适用场景	接入方式
全额退商品单	可手动退款商品单全部金额（不包含预约单）	适用非预约品场景	`<pay-button-sdk ... bind:applyrefund={applyRefund} >` `function applyRefund(event) { const { orderId } = event.detail; const extra = { orderId }; // 输入指定退款的订单id return new Promise(resolve => { resolve(extra); }); }`
指定金额退	可手动指定退款商品子单以及退款金额	仅适用融合预约品或非融合所有品	`<pay-button-sdk ... bind:applyrefund={applyRefund} >` `function applyRefund(event) { const { orderId } = event.detail; // 可指定商品子单以及退款金额 // 商品子单，可在预下单回调itemOrderlist里获取，或通过查询券状态接口获取 const itemOrderList = [ {itemOrderId:'ot423412', refundAmount: 100}, {itemOrderId:'ot423413', refundAmount: 200}, ] const extra = { orderId , itemOrderList }; return new Promise(resolve => { resolve(extra); }); }`
协同退	商品单和预约单一起退	仅适用融合预约品	`<pay-button-sdk ... bind:applyrefund={applyRefund} >` // 融合预约订单已预约协同退(预约单+商品单) function applyRefund(event) { const { orderId } = event.detail; const itemOrderList = [ { itemOrderId: 'ot423412',// 商品子单，可在预下单回调itemOrderlist里获取，或通过查询券状态接口获取 refundAmount: 100, // 退款金额必传，如果使用营销，需传原价 deductFeeAmount: 0, // 手续费，作部分退使用。若部分退，需满足deductFeeAmount+refundAmount=totalAmount(订单原价) refundRelatedItemType:2 // 固定传2 } ]; const refundRelatedOrderDetail = [ { orderId: "book_id", // 预约单号 refundAmount: 0, // 预约单金额，如果没有则传0 deductFeeAmount: 0// 手续费金额，如果没有则传0 } ] const extra = { orderId, itemOrderList, refundRelatedOrderDetail }; return new Promise(resolve => { resolve(extra); }); }

第二步：接入退款拓展点（SPI）

接口文档

开发者服务端接入退款拓展点，接收抖音服务端推送过来的退款请求

配置拓展点

指南

开发者接收退款结果

参数说明

{ 
  "app_id": "ttqweqw12312",
  "open_id": "123123",
  "refund_id": "ot123133",
  "order_id": "ot1231312",
  "out_order_no": "213123",
  "refund_total_amount": 100,
  "need_refund_audit": 1,
  "refund_audit_deadline": 151231321231,
  "create_refund_time": 151231321230,
  "refund_source": 1,
  "refund_reason": ["不喜欢"],
  "refund_description": "想退款",
  "cp_extra": "cp_extra",
  "refund_item_detail": {
    "item_order_quantity": 1,
    "item_order_detail": [
      {
        "item_order_id": "ot123134",
        "refund_amount": 100
      }
    ]
  }
}

第三步：响应退款拓展点（SPI）

接口文档

开发者服务端返回退款信息给抖音服务端

{
  "err_no": 0, 
  "err_tips": "123213",
  "data": {
    "out_refund_no": "89876867867087",
    "order_entry_schema": {
      "path": "page/refundDetail/xxx",
      "params": "{\"id\": 1}"
    },
    "notify_url": "https://xxx"
  }
}

第四步：同步退款审核结果（OpenAPI）

接口文档

开发者服务端完成响应退款拓展点后，需再调用本接口返回退款审核结果给抖音服务端
如果退款拓展点返回的need_refund_audit是1才需要调用本接口

curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/refund/merchant_audit_callback' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "out_refund_no": "1123",
        "refund_audit_status": 2,
        "deny_message": "不同意退款",
}'

第五步：退款结果通知（SPI）

接口文档

退款处理完成后，抖音服务端会给向开发者服务端发起请求，将退款结果通知到开发者服务端

// 退款成功回调示例
{ 
    "app_id": "ttcfdbb96650e33350",
    "status": "SUCCESS",
    "order_id": "ot7057422956397562142",
    "cp_extra": "",
    "message": "",
    "event_time": 1643185934447,
    "refund_id": "ot7057422412346034445",
    "out_refund_no": "ext_order_no_1643185898403",
    "refund_total_amount": 1,
    "is_all_settled": false,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "ot7057422956397594910"
            }]
    }
}


// 退款失败回调示例
{
    "app_id": "ttcfdbb96650e33350",
    "status": "FAIL",
    "order_id": "ot7057422956397562142",
    "cp_extra": "xxxxx",
    "message": "XXXXXXXX",
    "event_time": 1643185934447,
    "refund_id": "ot7057422412346034445",
    "out_refund_no": "ext_order_no_1643185898403",
    "refund_total_amount": 1,
    "is_all_settled": true,
    "refund_item_detail": {
            "item_order_quantity": 1,
            "item_order_detail": [{
                    "refund_amount": 1,
                    "item_order_id": "ot7057422956397594910"
            }]
    }
}

FAQ

uniapp下传入applyRefund无效

由于uniapp/taro等三方框架在编译时会将所有组件函数进行编译，编译后的函数无任何返回，这会导致bind:applyrefund中返回的数据无法透传至pay-button组件内。

基于上述情况，开发者需要将bind:applyrefund的返回值传至pay-button的apply-refund-params参数中，参数格式参考上方，demo如下

<pay-button-sdk 
    id="3" 
    order-status="{{1}}" 
    order-id="{{orderIdForRefund}}" 
    refund-total-amount="{{orderIdForRefundAmount}}" 
    apply-refund-params="{{applyRefundParams}}"
    ...
/>

注意：如果传递了apply-refund-params参数，可不用传bind:applyrefund

组件退款提示：is not in appjson 21532报错

请保证ttml文件中，使用了<pay-button-sdk>，而非<pay-button>

请保证index.json文件中引入了以下代码

// index.json
{
  "usingComponents": {
    "pay-button-sdk": "tta5a3d31e3aecfb9b11://pay-button"
  }
}