> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # 获取交易单列表 > 查询交易单列表 查询交易单列表 ## OpenAPI ````yaml openapi/v1-zh.yaml GET /api/v1/trades openapi: 3.0.3 info: title: Subotiz API description: Subotiz OpenAPI version: 1.0.0 servers: - url: https://{api}.subotiz.com variables: api: default: api security: - sec0: [] tags: - name: 折扣 description: 折扣 - name: 发票 description: 发票 - name: 退款 description: 退款 - name: 商品管理 description: 商品管理 - name: 订阅 description: 订阅 - name: 商品定价 description: 商品定价方案 - name: 交易单 description: 交易单 - name: 支付流水 description: 支付流水 - name: 结账会话 description: 结账会话 - name: 顾客 description: 顾客 - name: 顾客门户 description: 顾客门户 - name: Webhook description: Webhook - name: 争议 description: 争议订单 paths: /api/v1/trades: get: tags: - 交易单 summary: 获取交易单列表 description: 查询交易单列表 operationId: v1-trade-list-trade parameters: - name: trade_ids in: query description: trade 单的 id 数组，筛选 id 属于这个数组 trade 单 schema: type: array items: type: string - name: status in: query description: |- 状态： - requires_payment_method：待支付 - payment_failed：支付失败 - processing：支付处理中 - succeeded：支付成功 - closed：已关闭 schema: type: string - name: starting_after in: query description: >- 用于分页的游标。`starting_after` 是定义您在列表中位置的对象 ID。例如，如果想获取下一页，可以在第一次获取对象列表之后，使用最后一个对象的 id 作为参数值。不能和 `ending_before 同时使用 schema: type: string - name: ending_before in: query description: >- 用于分页的游标 `ending_before` 是定义您在列表中位置的对象 ID。例如，如果想获取上一页，可以在第一次获取对象列表之后，使用第一个对象的 id 作为参数值。不能和 `starting_after` 同时使用 schema: type: string - name: limit in: query description: 分页参数，每页数量，默认：10，接口默认按创建时间倒序排序。限制：[1, 100] schema: type: integer format: int32 - name: order_ids in: query description: 接入方订单号 schema: type: array items: type: string - name: created_at.gt in: query description: 用于过滤的最小值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.gte in: query description: 用于过滤的最小值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.lt in: query description: 用于过滤的最大值（不包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: created_at.lte in: query description: 用于过滤的最大值（包含，RFC3339格式的UTC时间，例如'2025-01-01T00:00:00Z') schema: type: string - name: customer_id in: query description: 仅返回此顾客 ID 指定的顾客的交易订单。 schema: type: string - $ref: '#/components/parameters/HeaderRequestID' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListTradesResponse' '400': description: ending_before and starting_after cannot be set at the same time content: application/json: schema: $ref: '#/components/schemas/BaseResponse' example: code: invalid_request_error message: >- ending_before and starting_after cannot be set at the same time. components: parameters: HeaderRequestID: name: Request-Id in: header description: 请求的唯一标识符 required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: ListTradesResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/ListTradesResponse_Data' description: 通过order_id查询交易单响应 BaseResponse: type: object properties: code: type: string description: 错误码 message: type: string description: 错误详细信息 ListTradesResponse_Data: type: object properties: has_more: type: boolean description: 是否还有更多数据 list: type: array items: $ref: '#/components/schemas/Trade' description: 交易单列表 description: 通过order_id查询交易单响应 Trade: type: object properties: trade_id: type: string description: 交易单ID access_no: type: string description: 接入方编号 merchant_id: type: string description: 商户ID amount: type: string description: 支付金额，截取两位小数 currency: type: string description: 币种 customer_id: type: string description: 平台顾客 ID callback_url: type: string description: webhook 通知回调地址 metadata: type: object additionalProperties: type: string description: 透传的元数据，key 长度不超过 40 字节，value 长度不超过 500 字节，JSON编码后 ≤ 1024字节 last_payment_error: allOf: - $ref: '#/components/schemas/LastPaymentError' description: 最后一次支付错误信息，如果该字段有值，则表示支付失败。 next_action: allOf: - $ref: '#/components/schemas/NextAction' description: 下一步操作 order_id: type: string description: 接入方订单号 last_trans_id: type: string description: 订单流水ID。 paid_at: type: string description: 支付成功时间 payment_mode: type: string description: >- 支付业务模式： - subscription：首次订阅支付，需要收集顾客支付信息，传入 payment_method_data 字段，支付成功时会返回 payment_token 用于后续订阅续费 - recurring_payment：订阅续订支付，需要传入 payment_token 完成支付，无需收集用户支付信息 payment_token: type: string description: 订阅支付时，返回的支付凭证，用于后续订阅续费 payment_method: type: string description: 支付方式 payment_channel: type: string description: 支付渠道 return_url: type: string description: 在类似 3DS 跳转支付场景时，支付渠道受理成功后重定向的页面 trade_status: type: string description: >- 交易单状态： - requires_payment_method：待支付。交易单初始状态，顾客尚未完成付款（可能尚未发起或正在支付中），或订阅续订扣费已发起但尚未返回结果。 - payment_failed：支付失败。支付请求被渠道拒绝，例如余额不足、卡验证失败或风控拦截。顾客可再次发起支付。 - processing：支付处理中。顾客已完成支付操作，支付渠道正在处理支付请求，但支付结果暂未确认，可能处于风控核验、银行处理中或延迟清算流程中。 - succeeded：支付成功。支付已被渠道确认成功，款项已入账。 - closed：已关闭。订阅续订失败（多次重试后仍失败）或超过7天无支付结果返回等状态基本不会再正向变化时，交易单轮转为已关闭。 txn_time: type: string description: 交易发起时间，客户端发起接口的时间 created_at: type: string description: 创建时间 refund_status: type: string description: |- 退款状态： - no_refund：无退款 - partially_refunded：部分退款。已成功退款部分金额，退款成功金额小于交易单总金额。 - refunded：全额退款。已成功退款全部交易单金额。 total_refunded_amount: type: string description: 退款金额，截取两位小数 session_id: type: string description: Session 唯一标识 session_url: type: string description: Session 的访问地址 refer_info: allOf: - $ref: '#/components/schemas/ReferInfo' description: 顾客的来源信息 order_type: type: string description: |- 在不同采购或计费场景下生成的订单类型： - onetime_payment: 一次性付款请求创建的交易订单 - subscription: 发起订阅付款请求创建的交易订单 - recurring_payment: Subotiz订阅续订服务创建的交易订单 - token_payment: 商家使用现有订阅合同令牌向客户扣款时创建的交易订单 line_items: type: array items: $ref: '#/components/schemas/LineItem' description: 顾客购买的商品明细 discounts: allOf: - $ref: '#/components/schemas/Discounts' description: 应用于交易的折扣，包括此交易的所有折扣信息 closed_at: type: string description: 交易关闭时间 closed_reason: type: string description: |- 关闭原因 - timeout: 交易支付超时 - renewal_failed: 订阅续订扣费失败（含重试） first_source_channel: type: string description: 交易关联的结账会话首次创建来源渠道 last_source_channel: type: string description: 交易关联的结账会话最后访问的来源渠道 billing_address: allOf: - $ref: '#/components/schemas/BillingAddress' description: 顾客的账单地址信息 tax_amount: type: string description: 税费总额 payment_info: allOf: - $ref: '#/components/schemas/PaymentInfo' description: 支付信息 description: Trade LastPaymentError: type: object properties: code: type: string description: 系统返回交易返回码 message: type: string description: 系统返回交易返回说明 NextAction: type: object properties: type: type: string description: |- 客户端下一步需要操作的类型： - redirect：重定向 redirect: allOf: - $ref: '#/components/schemas/NextActionRedirect' description: 重定向信息 client: allOf: - $ref: '#/components/schemas/NextActionClient' description: 客户端操作信息 description: NextAction ReferInfo: type: object properties: country_code: type: string description: 客户下单时的国家 (ISO 2格式) ip: type: string description: 客户下单时的 IP device: type: string description: |- 客户设备的类型 - pc：指个人电脑设备类型，包括台式机和笔记本电脑。 - mobile：指移动端设备类型，包括智能手机和平板电脑。 user_agent: type: string description: 客户端的 user agent description: ReferInfo LineItem: type: object properties: id: type: string title: type: string price: type: string price_id: type: string quantity: type: string sku: type: string vendor: type: string cycle_unit: type: string Discounts: type: object properties: current_period: type: array items: $ref: '#/components/schemas/CurrentPeriodDiscount' description: 当前时期的折扣详情 description: 交易订单折扣信息 BillingAddress: type: object properties: first_name: type: string last_name: type: string email: type: string phone: type: string country_code: type: string country: type: string province_code: type: string province: type: string area: type: string city: type: string address: type: string address1: type: string zip: type: string company: type: string phone_area_code: type: string PaymentInfo: type: object properties: verification: allOf: - $ref: '#/components/schemas/Verification' description: 卡支付安全验证结果（CVC / AVS / 3DS）；非卡支付或失败时为 null authcode: type: string description: 发卡行授权码；卡支付有值，非卡支付为空 network_transaction_id: type: string description: 网络交易号（卡组织侧交易标识）；卡支付有值，非卡支付为空 description: PaymentInfo - 支付明细，用于订单侧透传给商家 NextActionRedirect: type: object properties: url: type: string description: 重定向 URL NextActionClient: type: object properties: confirm_url: type: string description: 确认支付 URL apple_pay_session: type: string description: ApplePay 创建使用的数据 CurrentPeriodDiscount: type: object properties: discount_id: type: string description: 折扣的唯一标识符 discount_amount: type: string description: 折扣金额 discount_code: type: string description: 使用的折扣代码 description: 当前时期应用的折扣详情 Verification: type: object properties: cvc_check: type: string description: CVC 校验结果：pass / fail / unchecked / unavailable avs: allOf: - $ref: '#/components/schemas/Avs' description: 地址校验结果；未触发时为 null three_d_secure: allOf: - $ref: '#/components/schemas/ThreeDSecure' description: 3DS 校验结果；未走 3DS 时为 null description: Verification - 卡支付安全验证结果 Avs: type: object properties: line1_check: type: string description: 地址行校验：pass / fail / unchecked / unavailable postal_code_check: type: string description: 邮编校验：pass / fail / unchecked / unavailable description: Avs - 地址校验结果 ThreeDSecure: type: object properties: authentication_flow: type: string description: 认证流程：frictionless / challenge result: type: string description: >- 认证结果：authenticated / attempt_acknowledged / not_supported / failed / exempted / processing_error result_reason: type: string description: 失败 / 降级原因，成功时为空 version: type: string description: 3DS 协议版本，如 2.2.0 eci: type: string description: ECI 电子商务指示符；非 3DS 交易或发卡行未返回时为空 description: ThreeDSecure - 3DS 校验结果 securitySchemes: sec0: type: http description: 'Bearer API Key 鉴权。格式：Authorization: Bearer {your_api_key}' scheme: bearer ````