说明

1.接口说明

• 白标自研服务通过白标后台设置webhook地址。后续指定的事件发生时，会对此接口进行数据推送
• 推送数据失败后，会每隔3秒进行再次推送，推送失败5次后将不在进行推送。
• 设置的webhook地址需先提供给UPay进行验证，才能进行成功推送

2.请求方式

请求方式	POST
请求体	以content-type=application/json ;charset=UTF-8形式传输

3.Header参数

参数	类型	是否必填项	描述
X-UPA-REQUESTID	String	是	全局唯一请求ID，保持唯一便于后续定位问题
X-UPA-TIMESTAMP	Long	是	13位时间戳，请求发起时间
X-UPA-SIGN	String	是	签名值

4.请求体参数

• 请求体说明
  请求体内容通过白标后台设置的公钥进行加密。
• 卡webhook事件和数据格式
  参考 卡
• 钱包Webhook事件和数据格式
  参考 钱包

5.签名

1. 将 event + timestamp + body 以 | 分割，拼成字符串。
   示例：CC_CONSUME|1755248905430|xxxxxx
2. 使用SecretKey对拼接后的字符串进行Hmac.SHA256签名。
   注：SecretKey可通过白标后台获取。
3. 对签名之后的数据进行 base64

参数	类型	是否必须	示例值	描述
event	String	是	CC_CONSUME	解密body数据获取
timestamp	Long	是	1755248905430	Header参数中的X-UPA-TIMESTAMP
body	String	是	xxxxxx	Webhook数据

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.util.Base64;
import java.util.Objects;

public class HMACSHA256Signer{
	private String generateHmacSha256(String data , String secretKey) throws Exception {
    // 获取 Mac 实例
    Mac mac = Mac.getInstance("HmacSHA256");
    // 创建 SecretKeySpec 对象
    byte[] keyBytes = secretKey.getBytes();
    SecretKeySpec signingKey = new SecretKeySpec(keyBytes , "HmacSHA256");
    // 初始化 Mac 实例
    mac.init(signingKey);
    // 执行 HMAC-SHA256
    byte[] rawHmac = mac.doFinal(data.getBytes());
    // 将结果转换为 Base64 字符串
    return Base64.getEncoder().encodeToString(rawHmac);
	}
}

6.返回参数

白标自研服务接到请求,需在5秒内响应.

• 成功：Http状态码等于200并且响应内容为SUCCESS
• 失败：超时、HTTP状态码不等于200或返回结果不是SUCCESS会被UPay判定为失败。

如果响应判定为失败，会进行重发，每隔3秒重试1次，重发次数上限5次。白标自研服务需要做好幂等处理，防止业务异常。