支付宝对账单包含哪些字段和业务类型字段值？

结论

支付宝对账单没有一套适用于所有产品的固定字段。通过 alipay.data.dataservice.bill.downloadurl.query 下载的账单通常分为两类：

• trade：支付宝交易账单，记录交易、退款等业务。
• signcustomer：签约商户账务账单，记录账户资金收支和账务流水。

常见的交易账单字段包括支付宝交易号、商户订单号、业务类型、商品名称、交易时间、交易金额、商家实收、优惠金额、服务费、分润和备注等。

“业务类型”的常见值如下：

商户的账单中不一定会出现所有类型。实际字段和业务类型取决于账单类型、商户签约产品、交易渠道、接口版本以及支付宝后续调整，解析时应以下载文件中的表头和数据为准。

交易账单常见字段

trade 类型账单经常包含以下字段：

每份账单包含的列可能不同。门店、券核销、商家红包和分润等字段，通常只会在开通相应能力后出现。

关键金额字段如何理解

“订单金额”、“商家实收”和”服务费”不是同一个统计口径：

• 订单金额是订单的原始金额。
• 商家实收通常是计算商户承担的优惠等因素后，商户对应的收入金额。
• 服务费是支付服务产生的费用。
• 优惠金额需要区分由支付宝承担还是由商户承担。
• 发生退款后，需要结合原交易、退款流水和账务流水计算最终净收入。

不同业务中，金额列的正负号和统计口径可能不同，不能只看”业务类型”来判断资金方向。解析时应同时检查金额列、备注，以及账务账单中的收入和支出字段。

账务账单可能包含的字段

signcustomer 账单主要记录账户资金变化，可能包含以下字段：

交易账单用于确认发生了什么业务，账务账单则用于核对账户资金增加或减少的原因。进行严格的财务对账时，通常需要结合这两类账单。

推荐的对账步骤

1. 调用账单下载接口取得下载地址。
2. 下载并解压账单文件。
3. 动态读取 CSV 表头，不按固定列下标解析。
4. 去除文件中的汇总行、说明行和空行。
5. 使用支付宝交易号关联支付流水和退款流水。
6. 使用商户订单号关联本地订单。
7. 按业务类型分类统计，但不将其作为判断资金方向的唯一条件。
8. 使用十进制定点数处理金额。
9. 将未知业务类型写入异常表，等待人工确认。
10. 使用账务账单复核交易净额、手续费和实际资金变化。

Java 解析示例

下面的示例演示如何动态识别字段，并保留对未知业务类型的兼容能力。生产环境应使用成熟的 CSV 解析库，正确处理引号、逗号和换行。

import java.math.BigDecimal;
import java.util.Map;
import java.util.Set;

public class AlipayBillRow {

    private static final Set<String> KNOWN_BUSINESS_TYPES = Set.of(
        "交易",
        "退款",
        "转账",
        "收费",
        "充值",
        "提现",
        "跨境结算",
        "其他"
    );

    public static void process(Map<String, String> row) {
        String alipayTradeNo = value(row, "支付宝交易号");
        String outTradeNo = value(row, "商户订单号");
        String businessType = value(row, "业务类型");

        BigDecimal orderAmount = money(row, "订单金额（元）");
        BigDecimal merchantReceipt = money(row, "商家实收（元）");
        BigDecimal serviceFee = money(row, "服务费（元）");

        if (!businessType.isEmpty()
                && !KNOWN_BUSINESS_TYPES.contains(businessType)) {
            recordUnknownBusinessType(businessType, row);
        }

        System.out.printf(
            "alipayTradeNo=%s, outTradeNo=%s, type=%s, " +
            "orderAmount=%s, merchantReceipt=%s, serviceFee=%s%n",
            alipayTradeNo,
            outTradeNo,
            businessType,
            orderAmount,
            merchantReceipt,
            serviceFee
        );
    }

    private static String value(Map<String, String> row, String field) {
        String value = row.get(field);
        return value == null ? "" : value.trim();
    }

    private static BigDecimal money(
            Map<String, String> row,
            String field
    ) {
        String value = value(row, field);

        if (value.isEmpty() || "-".equals(value)) {
            return BigDecimal.ZERO;
        }

        return new BigDecimal(value.replace(",", ""));
    }

    private static void recordUnknownBusinessType(
            String businessType,
            Map<String, String> row
    ) {
        // 写入异常记录或告警系统，不要直接丢弃整行账单。
        System.err.println(
            "发现未知业务类型: " + businessType + ", row=" + row
        );
    }
}

业务类型不适合定义为封闭的 Java enum 并直接反序列化。如果支付宝新增类型，封闭枚举可能导致整批账单导入失败。更安全的处理方式是保留原始字符串，并将无法识别的值标记为待确认。

调用账单下载接口示例

账单下载接口返回的是临时下载地址，不是账单正文：

AlipayDataDataserviceBillDownloadurlQueryRequest request =
    new AlipayDataDataserviceBillDownloadurlQueryRequest();

request.setBizContent("""
{
  "bill_type": "trade",
  "bill_date": "2026-09-08"
}
""");

AlipayDataDataserviceBillDownloadurlQueryResponse response =
    alipayClient.execute(request);

if (!response.isSuccess()) {
    throw new IllegalStateException(
        response.getCode() + ": " + response.getSubMsg()
    );
}

String downloadUrl = response.getBillDownloadUrl();

示例日期只用于说明参数格式。账单日期范围、可下载期限和接口权限，应以商户当前签约能力及对应接口文档为准。

注意事项

• 解析时以实际 CSV 表头为准，不要长期写死字段顺序。
• CSV 可能带有 BOM，字段内容也可能包含逗号、双引号或换行。
• 下载文件可能包含明细文件、汇总文件和说明文件，不要将汇总行识别为交易。
• 金额必须使用 BigDecimal 或等价的十进制定点类型，不能使用 float、double。
• 空金额和 0.00 的含义不同，是否将空值按零处理，需要根据具体字段判断。
• 一笔订单可能对应多笔退款，不能假设商户订单号或退款记录是一一对应关系。
• 支付宝交易号适合关联支付宝侧流水，商户订单号适合关联商户订单，两者都需要保存。
• 对账时还要校验交易状态、完成时间、手续费、优惠承担方和退款金额。
• 下载地址通常有时效性，不宜保存后长期复用。
• 对方账户等信息可能属于敏感数据，需要限制访问，并避免写入普通日志。
• 出现新的业务类型时，应先保留原始记录并告警，不能默认归类为交易，也不能直接丢弃。

备注：内容仅供参考。