# 下载结算文件

> 按结算日期和结算币种下载 UTF-8 CSV 结算文件。

```yaml
openapi: 3.1.0
info:
  title: 下载结算文件
  version: 1.0.0
  description: 按结算日期和结算币种下载 UTF-8 CSV 结算文件。
paths:
  /v1/settlementFile/download:
    get:
      summary: 下载结算文件
      description: 按结算日期和结算币种下载 UTF-8 CSV 结算文件。
      parameters:
        - name: merchantNo
          in: header
          required: true
          description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
          schema:
            type: string
            description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
        - name: date
          in: header
          required: true
          description: 需要下载结算文件的结算日期。
          schema:
            type: string
            description: 需要下载结算文件的结算日期。
            x-onerway-constraints:
              - kind: rule
                text: 使用 `yyyyMMdd` 格式，不要传 `2021-10-26` 这类带连字符的日期。
        - name: currency
          in: header
          required: true
          description: 需要下载结算文件的结算币种，[ISO
            4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
            三位字母货币代码。
          schema:
            type: string
            description: 需要下载结算文件的结算币种，[ISO
              4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
              三位字母货币代码。
        - name: sign
          in: header
          required: true
          description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
          schema:
            type: string
            description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
            x-onerway-constraints:
              - kind: rule
                text: 本接口请求参数位于 Header；`sign` 字段自身不参与自身签名计算。
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: object
                    properties:
                      Content-Type:
                        type: string
                        description: 结算文件流的响应 MIME 类型。
                      csv:
                        type: object
                        properties:
                          batch:
                            type: object
                            properties:
                              Settlement Date:
                                type: string
                                description: 结算周期对应的结算日期。
                              Settlement Currency:
                                type: string
                                description: 商户结算使用的币种，[ISO
                                  4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                  三位字母货币代码。
                              Transaction Amount:
                                type: string
                                description: 以结算币种计的交易金额。
                              Refund Amount:
                                type: string
                                description: 以结算币种计的成功退款交易金额。
                              Transaction Processing Fee:
                                type: string
                                description: 支付交易处理费。
                              Refund Processing Fee:
                                type: string
                                description: 退款交易处理费。
                              Fee:
                                type: string
                                description: 支付交易费用。
                              Interchange Fee:
                                type: string
                                description: Interchange Fee。
                                x-onerway-value:
                                  empty: true
                                  when: &a1
                                    en: Meaningful only under IC++ pricing; other pricing models may return an empty
                                      CSV cell or `0`.
                                    zh: 仅 IC++ 计费模式下有业务含义；其他模式可能返回空 CSV 单元格或 `0`。
                              Scheme Fee:
                                type: string
                                description: Scheme Fee。
                                x-onerway-value:
                                  empty: true
                                  when: *a1
                              Markup:
                                type: string
                                description: Markup。
                                x-onerway-value:
                                  empty: true
                                  when: *a1
                              Deposit Release:
                                type: string
                                description: 返还的保证金金额。
                              Deposit:
                                type: string
                                description: 保证金金额，到期后返还。
                              Settlement Amount:
                                type: string
                                description: 扣除费用后的净结算金额。
                              Platform fee:
                                type: string
                                description: 平台费用。
                              Fraud  Administration Fee:
                                type: string
                                description: 欺诈管理费用。
                              Decision management Fee:
                                type: string
                                description: 风险决策管理费用。
                              Other charges:
                                type: string
                                description: 其他费用，主要用于代理结算等场景。
                                x-onerway-value:
                                  empty: true
                                  when:
                                    en: Has a value when other charges apply.
                                    zh: 存在其他费用时有值。
                            description: CSV 文件中的结算批次汇总信息，按结算周期聚合展示。
                          details:
                            type: array
                            description: CSV 文件中的结算明细记录，用于对账与报表处理。
                            items:
                              type: object
                              properties:
                                Settlement Date:
                                  type: string
                                  description: 结算周期对应的结算日期。
                                Settlement Batch ID:
                                  type: string
                                  description: 结算批次的唯一标识。
                                Transaction ID:
                                  type: string
                                  description: Onerway 为本次交易生成的交易号，用于跟踪与对账。
                                Merchant Order ID:
                                  type: string
                                  description: 商户系统为本次交易生成的商户交易号，用于交易跟踪和对账。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Empty when no merchant order ID is recorded for this entry.
                                      zh: 该记录未关联商户订单号时为空。
                                Production Type:
                                  type: string
                                  description: 产品类型。`SETTLE` 表示结算相关记录，包括调整、费用及保证金记录。该行的具体操作类型由 `Transaction Type`
                                    表示。
                                Card Type:
                                  type: string
                                  description: 卡类型或本地支付方式。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when a card transaction or local payment method transaction
                                        returns a concrete payment method.
                                      zh: 卡交易或本地支付方式交易返回具体支付方式时有值。
                                APP ID:
                                  type: string
                                  description: 商户应用 ID，商户注册网站时由 Onerway 创建。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when the transaction is associated with a merchant application.
                                      zh: 交易关联商户应用时有值。
                                Transaction URL:
                                  type: string
                                  description: 商户交易网站。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when the transaction records a merchant transaction URL.
                                      zh: 交易记录了商户交易网址时有值。
                                Order_Currency:
                                  type: string
                                  description: 下单币种，[ISO
                                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                    三位字母货币代码。
                                Order Amount:
                                  type: string
                                  description: 下单金额，即原始交易金额。
                                Transaction Type:
                                  type: string
                                  description: 结算文件中记录的交易类型，涵盖支付、退款、拒付、申诉及结算。
                                  enum:
                                    - SETTLE
                                    - MONTHLY_FEE
                                    - SALE
                                    - REFUND
                                    - CB
                                    - CB_CANCEL
                                    - CB_VOID
                                    - CB_APPEAL
                                    - CB_APPEAL_SUCCESS
                                    - CB_APPEAL_SECOND
                                    - CB_APPEAL_SECOND_SUCCESS
                                    - CB_APPEAL_SECOND_FAILURE
                                  x-enum-descriptions:
                                    SETTLE: 结算交易。
                                    MONTHLY_FEE: 月费。
                                    SALE: 支付交易，用于购买商品或服务的标准交易。
                                    REFUND: 退款交易，将此前支付交易的资金退还给客户。
                                    CB: 拒付交易，持卡人通过发卡行对交易提出异议时产生。
                                    CB_CANCEL: 拒付取消交易，取消之前发起的拒付。
                                    CB_VOID: 拒付撤销，撤销之前发起的拒付。
                                    CB_APPEAL: 拒付第一次申诉。
                                    CB_APPEAL_SUCCESS: 拒付第一次申诉成功，拒付被撤销。
                                    CB_APPEAL_SECOND: 首次拒付申诉被拒后发起的仲裁（二次申诉）。
                                    CB_APPEAL_SECOND_SUCCESS: 仲裁成功，拒付已撤销。
                                    CB_APPEAL_SECOND_FAILURE: 仲裁失败，拒付维持。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Empty when no transaction type is recorded for this settlement entry.
                                      zh: 结算记录未记录交易类型时为空。
                                Transaction Status:
                                  type: string
                                  description: 本笔交易的处理状态；结算出款状态见 `Settlement Status`。
                                  enum:
                                    - S
                                    - F
                                    - P
                                    - R
                                    - N
                                    - I
                                    - U
                                  x-enum-descriptions:
                                    S: 交易成功。
                                    F: 交易失败。
                                    P: 交易处理中。
                                    R: 需要跳转以继续支付。
                                    N: 交易已取消（含超时未支付关单）。
                                    I: 交易审核或审批中。
                                    U: 未支付，等待客户完成支付。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Empty when no transaction status is recorded for this settlement entry.
                                      zh: 结算记录未记录交易状态时为空。
                                Settlement Currency:
                                  type: string
                                  description: 商户结算使用的币种，[ISO
                                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                    三位字母货币代码。
                                Transaction Amount:
                                  type: string
                                  description: 以结算币种计的交易金额。
                                Processing Fee:
                                  type: string
                                  description: 处理费。
                                Fee:
                                  type: string
                                  description: 交易费用。
                                Interchange Fee:
                                  type: string
                                  description: Interchange Fee。
                                  x-onerway-value:
                                    empty: true
                                    when: *a1
                                Scheme Fee:
                                  type: string
                                  description: Scheme Fee。
                                  x-onerway-value:
                                    empty: true
                                    when: *a1
                                Markup:
                                  type: string
                                  description: Markup。
                                  x-onerway-value:
                                    empty: true
                                    when: *a1
                                Deposit:
                                  type: string
                                  description: 保证金金额，到期后返还。
                                Settlement Amount:
                                  type: string
                                  description: 单笔交易的扣除费用后的净结算金额。
                                Settlement Status:
                                  type: string
                                  description: 结算出款状态，表示结算资金的转账进度或结果；交易处理状态见 `Transaction Status`。
                                  enum:
                                    - OP
                                    - OPS
                                    - OPF
                                  x-enum-descriptions:
                                    OP: 结算资金正在转入商户账户；这是结算出款流程中的中间状态。
                                    OPS: 结算资金已成功转入商户指定账户；这是最终状态。
                                    OPF: 结算出款失败；最终状态，表示资金未能转账至商户账户，需联系 Onerway 支持协助处理。
                                Wallet Type Code:
                                  type: string
                                  description: 钱包类型代码。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Currently has a value only when the local payment method is Alipay+.
                                      zh: 当前仅本地支付方式为 Alipay+ 时有值。
                                Merchant Order Time:
                                  type: string
                                  description: 商户提供的原始下单时间字符串，不进行时区转换。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Empty when no merchant order time is recorded.
                                      zh: 未记录商户下单时间时为空。
                                Platform type:
                                  type: string
                                  description: 平台类型。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when the transaction records a platform type.
                                      zh: 交易记录平台类型时有值。
                                Platform fee:
                                  type: string
                                  description: 平台费用。
                                Fraud Administration Fee:
                                  type: string
                                  description: 欺诈管理费用。
                                card product:
                                  type: string
                                  description: 卡产品类型。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value for card transactions when a card product type is returned.
                                      zh: 卡交易返回卡产品类型时有值。
                                card category:
                                  type: string
                                  description: 卡类别。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value for card transactions when a card category is returned.
                                      zh: 卡交易返回卡类别时有值。
                                Decision management Fee:
                                  type: string
                                  description: 风险决策管理费用。
                                Fee Percentage:
                                  type: string
                                  description: 费用百分比。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when percentage-based fee pricing applies.
                                      zh: 适用按比例计费时有值。
                                Markup Fixed amount:
                                  type: string
                                  description: 固定 Markup 金额。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when fixed markup amount pricing applies.
                                      zh: 适用固定 Markup 金额时有值。
                                Markup Fixed currency:
                                  type: string
                                  description: 固定 Markup 金额对应的币种。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when fixed markup amount pricing applies.
                                      zh: 适用固定 Markup 金额时有值。
                                Markup Percentage:
                                  type: string
                                  description: Markup 百分比。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when percentage-based markup applies.
                                      zh: 适用按比例收取 Markup 的计费方式时有值。
                                Transaction complete time:
                                  type: string
                                  description: 交易完成时间。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when the transaction is completed and the completion time is
                                        recorded.
                                      zh: 交易已完成并记录完成时间时有值。
                                Original transaction ID:
                                  type: string
                                  description: 被引用的原始交易的 Onerway 交易号。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when a derived transaction references the original transaction.
                                        `REFUND` and `CB` reference the original
                                        `SALE` transaction; `CB_APPEAL` and
                                        `CB_APPEAL_SECOND` reference the
                                        corresponding `CB` transaction.
                                      zh: 衍生交易引用原交易时有值；`REFUND` / `CB` 引用原 `SALE` 交易号，`CB_APPEAL` / `CB_APPEAL_SECOND`
                                        引用对应 `CB` 交易号。
                                Original transaction merchant order ID:
                                  type: string
                                  description: "`REFUND` 交易引用的原 `SALE` 交易商户订单号。"
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Returned when the settlement row references an original `SALE` merchant
                                        order; older exported files may omit
                                        this column or use a different column
                                        name.
                                      zh: 当结算行引用原 `SALE` 商户订单时返回；较旧导出文件可能省略该列或使用不同列名。
                                Remark:
                                  type: string
                                  description: 手工调增或调减结算金额时，显示调整备注。拒付预警计费记录在商户启用服务信息展示时，显示预警服务机构名称。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: For manual adjustments, empty if no remark is recorded. For pre-dispute
                                        billing, empty if the service provider
                                        name is unavailable or its display is
                                        disabled. Empty for all other entry
                                        types.
                                      zh: 手工调整记录未填写备注时为空；拒付预警计费记录未提供服务机构名称或未启用其展示时为空；其他类型记录均为空。
                                Other charges:
                                  type: string
                                  description: 其他费用，主要用于代理结算等场景。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Has a value when other charges apply.
                                      zh: 存在其他费用时有值。
                                Transaction Time (GMT+8):
                                  type: string
                                  description: 交易发生时间，时区为 GMT+8。导出值的日期与时间之间使用 `T` 分隔，值本身不带时区前缀。
                                  x-onerway-value:
                                    empty: true
                                    when:
                                      en: Empty when no transaction time is recorded.
                                      zh: 未记录交易发生时间时为空。
                        description: UTF-8 编码的 CSV 结算文件；文件先包含结算批次汇总信息，随后包含结算明细列表。
                        x-onerway-constraints:
                          - kind: rule
                            text: 每个区段有各自的表头行。请按下载文件中的表头识别列；不同导出文件的列集和列序可能不同。保留表头的拼写、大小写及空格；汇总表头
                              `Fraud  Administration Fee` 的 `Fraud`
                              后有两个空格，明细表头为一个空格。
                          - kind: rule
                            text: 结算明细中未记录的值导出为空单元格。金额保留六位小数，按最接近值舍入，恰好处于中间值时向零舍入（HALF_DOWN）。百分比列保留百分比格式。
                        x-onerway-value:
                          empty: true
                          when:
                            en: When the requested date or currency has no settlement data, the response may
                              be an empty or no-data file; recheck the request
                              date, currency, and download permission.
                            zh: 请求日期或币种没有结算数据时，响应可能为空文件或无数据文件；此时需回查请求日期、币种与下载权限。
                    description: 成功响应返回 `application/octet-stream` 文件流，而不是 JSON body。请将 UTF-8
                      编码内容保存为 `.csv` 文件。
```