对接文档

Appearance

Return to top
On this page

广告平台对接接口文档

文档版本

  • 版本号：v1.0
  • 发布日期：2026-03-26
  • 文档状态：正式版

一、背景

本文档旨在规范广告平台与广告主之间的支付对接流程，明确双方接口调用规范、数据格式、安全机制等技术细节，确保支付业务的稳定、安全运行。

二、角色划分

角色职责描述
平台方提供流量入口，调用下游支付能力，接收回传
广告主提供支付接口和查询接口，完成支付业务逻辑，并回传转化

三、环境配置

3.1 域名配置

环境域名说明
生产环境https://ss.beautiadse.cn正式业务使用
测试环境https://excpay-test.jxchmx.cn对接测试使用

3.2 对接前置步骤

  1. 密钥申请：广告主向平台方申请对接密钥
  2. 密钥下发：平台方为广告主分配以下信息：
    • secret：用于签名验证的密钥
    • secret_serial：密钥序列号，回传场景使用，具体参考接口安全性说明
  3. 上传接口: 广告主提供支付，查询2个接口URL
  4. 上传其他参数：支付完成页链接

四、接口介绍

4.1 广告主提供接口

4.1.1 支付接口

接口说明：平台方调用此接口发起支付请求

项目说明
请求URL由广告主提供
请求方式POST
Content-Typeapplication/json
请求参数
参数名类型必填说明示例值
d_idString是上游订单唯一标识"177718358100000000"
amountLong是支付金额（单位：分）10000
currencyString否货币单位，默认 CNY"CNY"
pay_success_urlString是支付完成页 URL"https://example.com/success"
subjectString是商品标题"购买商品"
descriptionString是商品描述"购买商品"
ext_paramString否附加参数"{\"ad_id\":\"123\"}"
versionString否版本号，默认 1.0"1.0"
请求示例
json
{
  "d_id": "177718358100000000",
  "amount": 10000,
  "currency": "CNY",
  "pay_success_url": "https://example.com/success",
  "subject": "广告投放服务",
  "description": "广告投放服务费用",
  "ext_param": "{\"ad_id\":\"123\"}",
  "version": "1.0"
}

响应结构：

基础字段：

参数名类型说明示例值
codeint状态码，0 表示成功0
msgString返回描述信息，code不为0时可查看该字段内容"非法请求"
dataObject业务数据—

data 字段：

参数名类型说明示例值
pay_dataString支付参数"支付相关参数"
pay_order_idString订单号"PAY123456789"
响应示例
json
{
  "code": 0,
  "msg": "success",
  "data": {
    "pay_data": "支付链接",
    "pay_order_id": "PAY123456789"
  }
}

4.1.2 查询接口

接口说明：平台方调用此接口查询支付订单状态

项目说明
请求URL由广告主提供
请求方式POST
Content-Typeapplication/json
请求参数
参数名类型必填说明示例值
pay_order_idString是支付订单号"PAY123456789"
请求示例
json
{
  "pay_order_id": "PAY123456789"
}

基础字段：

参数名类型说明示例值
codeint状态码，0 表示成功0
msgString返回描述信息，code不为0时可查看该字段内容"非法请求"
dataObject业务数据—

data 字段：

参数名类型说明示例值
statusString状态"success"
pay_order_idString订单号"PAY123456789"
  • success 成功
  • pending 支付中
  • 其他状态 可传fail
响应示例
json
{
  "code": 0,
  "msg": "success",
  "data": {
    "pay_order_id": "PAY123456789",
    "status": "success"
  }
}

4.2 平台方提供接口

4.2.1 回传接口

接口说明：广告主调用此接口向平台方回传结果（如转化、退款等事件）。

项目说明
请求URL/api/fa/tc/advertiser/callback
请求方式POST
Content-Typeapplication/json
请求参数
参数名类型必填说明示例值
d_idString是下单时由平台传入的唯一订单标识（对应支付接口中的 d_id）"177718358100000000"
event_typeString是事件类型：
1 - 转化（即支付成功）
2 - 退款		"1"
请求示例
json
{
  "d_id": "177718358100000000",
  "event_type": "1"
}
响应参数
参数名类型必填说明示例值
codeint是状态码，0 表示接收成功0
msgString是返回描述信息"success"
响应示例
json
{
  "code": 0,
  "msg": "success"
}
错误码说明
错误码说明
10000验签失败
10001请求参数不可为空
10002参数格式或取值不合法

五、接口安全性说明

5.1 安全机制概述

本接口采用共享密钥加签验签机制，确保接口调用的安全性和数据完整性。通过时间戳、随机数和签名 的组合，有效防止重放攻击和数据篡改。

5.2 加签流程

5.2.1 广告主调用平台接口时的加签

广告主在调用平台接口时，需要在请求头中添加以下三个字段：

请求头字段说明
D-Timestamp请求时间戳，单位为秒（Unix 时间戳），用于防止重放攻击和时效验证。
D-Nonce随机字符串（如 UUID），确保每次请求唯一，配合时间戳防止重放攻击。
D-Signature请求签名，使用 HMAC-SHA256 算法对 requestBody + timestamp + nonce 和密钥 secret进行签名
D-Serial平台下发的序列号

代码示例

java
// 生成时间戳（秒级）
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);

// 生成随机数
String nonce = IdUtil.fastSimpleUUID();

// 生成签名
String signature = generateSignature(requestBody, timestamp, nonce, secret);

// 设置请求头
request.header("D-Timestamp",timestamp);
request.header("D-Nonce",nonce);
request.header("D-Signature",signature);
request.header("D-Serial",serial);

签名生成规则：

java
signature = HMAC-SHA256(requestBody + timestamp + nonce, secret);

其中：

  • requestBody 为原始 JSON 请求体（不进行任何格式化或排序）
  • timestamp 为十进制秒级 Unix 时间戳
  • nonce 为唯一随机字符串
  • secret 为广告主申请的密钥

5.2.2 平台调用广告主接口时的加签

平台在调用广告主接口时，采用相同的加签方式，使用广告主申请的 secret 进行签名。

5.2.3 验签流程

广告主验签：

  • 使用自己申请的 secret 进行验签
  • 验证 D-Signature、D-Timestamp 和 D-Nonce 的有效性

代码示例

java
String timestamp = request.getHeader("D-Timestamp");
String nonce = request.getHeader("D-Nonce");
String signature = request.getHeader("D-Signature");
String serial = request.getHeader("D-Serial");

String canonical =  requestBody + timestamp + nonce;
byte[] rawHmac = SecureUtil.hmacSha256(advertiser.getSecretKey()).digest(canonical.getBytes(StandardCharsets.UTF_8));
String calculatedSignature = Base64.encode(rawHmac);
if (!calculatedSignature.equals(signature)) {
    log.error("验签失败");
}

平台验签：

  • 除了验证签名外
  • 还需要验证 secret_serial，确定使用哪个 secret 进行验签，所以外部调用接口请求头中需要额外添加：
text
D-Serial: <secret_serial>