> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询付款批次

> 按批次 ID 查询当前商户的付款批次。

批次不存在时返回 `404 batch_not_found`；当前商户无权访问时返回 `403 forbidden`。

商户身份由 stablepay-auth 的认证结果确定，请求参数不得传入 merchant\_id。批次状态和业务规则以 StablePay Payout 服务为准。

## 认证与请求头

使用 Bearer API Key 和以下三个签名请求头。使用 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，并转换为小写 hex。签名使用实际发送的原始请求体；不发送请求体时使用空字符串。详见[认证与签名](/zh/api/getting-started#认证与签名)。

<ParamField header="Authorization" type="string" required>
  Bearer API Key: `Bearer sk_live_xxx`.
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix 时间戳（秒），与服务器时间相差不超过 5 分钟。
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  防重放随机字符串，每次请求使用新的 nonce。 最短字符数：16。 最长字符数：64。
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  请求签名，使用小写十六进制编码。
</ParamField>

## 路径参数

<ParamField path="batch_id" type="string" required>
  最短字符数：1。 最长字符数：64。
</ParamField>

## 成功响应

HTTP `200`, `application/json`. 查询成功。

对象仅允许包含下列已定义字段。

<ResponseField name="batch_id" type="string" required />

<ResponseField name="status" type="string" required>
  可选值：`draft`、`needs_fix`、`pending`、`pending_approval`、`processing`、`partially_completed`、`completed`、`failed`、`canceled`、`rejected`。
</ResponseField>

<ResponseField name="currency" type="string" required>
  可选值：`USDT`、`USDC`。
</ResponseField>

<ResponseField name="network" type="string" required>
  可选值：`erc20`、`trc20`、`spl`。
</ResponseField>

<ResponseField name="total_count" type="integer" required>
  最小值：0。
</ResponseField>

<ResponseField name="valid_count" type="integer" required>
  最小值：0。
</ResponseField>

<ResponseField name="invalid_count" type="integer" required>
  最小值：0。
</ResponseField>

<ResponseField name="success_count" type="integer" required>
  最小值：0。
</ResponseField>

<ResponseField name="failed_count" type="integer" required>
  最小值：0。
</ResponseField>

<ResponseField name="total_amount" type="string" required>
  非负十进制金额字符串，最多两位小数。 匹配规则：`^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`。
</ResponseField>

<ResponseField name="service_fee_amount" type="string" required>
  非负十进制金额字符串，最多两位小数。 匹配规则：`^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`。
</ResponseField>

<ResponseField name="debit_amount" type="string" required>
  非负十进制金额字符串，最多两位小数。 匹配规则：`^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`。
</ResponseField>

<ResponseField name="frozen_amount" type="string" required>
  非负十进制金额字符串，最多两位小数。 匹配规则：`^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`。
</ResponseField>

<ResponseField name="charged_service_fee_amount" type="string" required>
  非负十进制金额字符串，最多两位小数。 匹配规则：`^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$`。
</ResponseField>

<ResponseField name="can_submit" type="boolean">
  批次当前是否可以提交；status 为 canceled 时不返回。
</ResponseField>

<ResponseField name="validation_errors" type="object[]" required>
  <Expandable title="字段">
    对象仅允许包含下列已定义字段。

    <ResponseField name="field" type="string" required />

    <ResponseField name="code" type="string" required />

    <ResponseField name="message" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string | null" />

<ResponseField name="created_at" type="integer" required>
  格式：`int64`。
</ResponseField>

<ResponseField name="submitted_at" type="integer | null">
  格式：`int64`。
</ResponseField>

<ResponseField name="completed_at" type="integer | null">
  格式：`int64`。
</ResponseField>

### 响应头

| 响应头 | 说明 |
| - | - |
| `X-Request-ID` | 请求追踪 ID。 |
| `Cache-Control` | 响应不得缓存。 可选值：`no-store`。 |

## 错误响应

| HTTP | 说明 |
| - | - |
| 400 | HTTP 请求格式、参数无效，或付款请求不满足业务校验。可能的业务错误码包括 address\_risk\_rejected、batch\_amount\_limit\_exceeded、batch\_amount\_too\_low、batch\_cannot\_submit、batch\_empty\_items、custody\_balance\_insufficient、insufficient\_balance 和 quota\_blocked。 |
| 401 | 鉴权失败或缺少可信商户身份。 |
| 403 | 当前商户无权访问或操作该资源。 |
| 404 | 指定的付款批次或明细不存在。 |
| 500 | 当前未细分的付款业务错误。 |
| 503 | 付款服务超时或暂时不可用。写请求发生此错误时应先查询资源状态。 |

对象仅允许包含下列已定义字段。

<ResponseField name="code" type="integer" required />

<ResponseField name="message" type="string" required />

<ResponseField name="errorCode" type="string" required />

<ResponseField name="data" type="null" required />

## 相关接口

* [创建付款批次](/zh/api/payouts/create-batch)
* [提交付款批次](/zh/api/payouts/submit-batch)
* [取消付款批次](/zh/api/payouts/cancel-batch)
* [查询付款批次列表](/zh/api/payouts/list-batches)
* [查询批次明细](/zh/api/payouts/list-batch-items)
* [查询付款明细](/zh/api/payouts/get-item)

<RequestExample>
  运行示例前设置 `API_KEY` 和 `SECRET_KEY`，并按接口路径设置 `BATCH_ID` 或 `ITEM_ID`。

  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  BODY=''
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}.${BODY}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --request GET --get "https://api.stablepay.co/api/v1/payout-batches/${BATCH_ID}" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 401 theme={"system"}
  {
    "code": 401,
    "message": "authenticated merchant is required",
    "errorCode": "authentication_required",
    "data": null
  }
  ```

  ```json 403 theme={"system"}
  {
    "code": 403,
    "message": "access denied",
    "errorCode": "forbidden",
    "data": null
  }
  ```

  ```json 404 theme={"system"}
  {
    "code": 404,
    "message": "batch not found",
    "errorCode": "batch_not_found",
    "data": null
  }
  ```

  ```json 500 theme={"system"}
  {
    "code": 500,
    "message": "payout request failed",
    "errorCode": "payout_error",
    "data": null
  }
  ```

  ```json 503 theme={"system"}
  {
    "code": 503,
    "message": "payout service is temporarily unavailable",
    "errorCode": "service_unavailable",
    "data": null
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.