# 查询协议支付订单


查询协议支付订单接口，用于开发者根据代扣单号或商户代扣单号查询对应协议支付订单的支付状态及详细信息。适用于代扣发起后的支付结果确认、对账、订单详情展示等业务场景。

## 使用限制

- 调用频次限制：请遵守平台默认 QPS 限制，避免高频调用。
- 查询时需提供 pay_order_id 或 out_pay_order_no 中的至少一个，否则查询将失败。

## 接口说明

- 业务场景：适用于开发者在发起协议支付（代扣）后，主动查询代扣订单的支付状态、支付方式、支付金额等详细信息。常见场景包括：代扣结果页展示、定时对账任务、代扣订单异常排查等。
- 前提条件：调用方需已完成应用创建，并通过 get_client_token 接口获取到有效的应用级 AccessToken。
- 注意事项：
- pay_order_id 为平台侧代扣单号，out_pay_order_no 为商户侧代扣单号，两者均可用于查询，但建议优先使用 pay_order_id。
- 支付结果以 pay_status 字段为准，枚举值包括 PROCESS（支付处理中）和 SUCCESS（支付成功）。

## 基本信息

| 名称 | 描述 |
|-|-|
| HTTP Path | /api/trade_basic/v1/developer/query_sign_pay |
| HTTP Method | POST |
| Scope | trade.sign_pay.query |
| 权限要求 | - 需要申请权限 - 申请路径：豆包开放平台控制台 > 应用详情 > 能力 > 支付权限 - 需要应用级 AccessToken |

## 请求头

| 名称 | 类型 | 必填 | 描述 |
|-|-|-|-|
| content-type | string | 是 | 固定值 application/json |
| x-DB-AccessToken | string | 是 | 调用 get_client_token 接口生成的应用级访问凭证 |

## 请求参数

### Body

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| pay_order_id | string | 否（与 out_pay_order_no 二选一） | 平台代扣单的单号，pay_order_id 与 out_pay_order_no 二选一，长度不超过 64 byte | 90214322040407612\*\*\* |
| out_pay_order_no | string | 否（与 pay_order_id 二选一） | 外部代扣单号，pay_order_id 与 out_pay_order_no 二选一，长度不超过 64 byte | SIGNPAY2024010100\*\*\* |

## 请求示例

cURL

```shell
curl -X POST 'https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_pay' \
  -H 'content-type: application/json' \
  -H 'x-DB-AccessToken: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******' \
  -d '{
    "pay_order_id": "90214322040407612***",
    "out_pay_order_no": ""
  }'
```

Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_pay"
    reqBody := map[string]string{
        "pay_order_id":     "90214322040407612***",
        "out_pay_order_no": "",
    }
    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("content-type", "application/json")
    req.Header.Set("x-DB-AccessToken", "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class QuerySignPay {
    public static void main(String[] args) throws Exception {
        String url = "https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_pay";
        String requestBody = "{\"pay_order_id\":\"90214322040407612***\",\"out_pay_order_no\":\"\"}";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("content-type", "application/json")
                .header("x-DB-AccessToken", "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

Node.js

```javascript
const axios = require('axios');

async function querySignPay() {
    const url = 'https://api.doubao-dev.com/api/trade_basic/v1/developer/query_sign_pay';
    const headers = {
        'content-type': 'application/json',
        'x-DB-AccessToken': 'clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******'
    };
    const data = {
        pay_order_id: '90214322040407612***',
        out_pay_order_no: ''
    };

    try {
        const response = await axios.post(url, data, { headers });
        console.log(response.data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

querySignPay();
```

## 响应参数

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| code | int32 | 是 | 错误码，0 表示成功，非 0 表示失败 | 0 |
| msg | string | 是 | 错误提示 | success |
| log_id | string | 是 | 请求日志 ID，用于问题排查时提供给技术支持 | 2023010128382726 |
| data | object | 否 | 代扣订单详情对象，仅在查询成功时返回 | 见下方 data 字段说明 |

### data 字段说明

| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|-|-|-|-|-|
| app_id | string | 是 | 应用 ID | tt1234567890\*\*\*\*\*\* |
| auth_order_id | string | 是 | 平台侧签约单号，标识该代扣订单对应的签约关系 | 80214322040407612\*\*\* |
| pay_order_id | string | 是 | 平台代扣单号 | 90214322040407612\*\*\* |
| out_pay_order_no | string | 是 | 商户代扣单号，与 pay_order_id 一一对应 | SIGNPAY2024010100\*\*\* |
| merchant_uid | string | 是 | 商户用户标识 | MER_USER_001\*\*\* |
| total_amount | string | 是 | 订单总金额，单位：分 | 1000 |
| pay_status | string | 是 | 支付状态，枚举值：PROCESS - 支付处理中；SUCCESS - 支付成功 | PROCESS |
| trade_time | string | 是 | 交易下单时间，精度：毫秒 | 1692775192000 |
| pay_success_source | integer | 否 | 支付成功来源：1 - 用户主动支付成功；2 - 代扣协议扣款成功 |  |
| pay_time | string | 否 | 支付时间，精度：毫秒 | 1692776192000 |
| pay_type | string | 否 | 支付类型，枚举值：ALI_PAY - 支付宝；WECHAT_PAY - 微信；BYTE_PAY - 抖音支付 | BYTE_PAY |
| pay_order_no | string | 否 | 支付单号 | PAY20240101000\*\*\* |
| sign_pay_fail_code | string | 否 | 失败错误码。支付失败时返回 |  |
| sign_pay_fail_msg | string | 否 | 失败原因描述。支付失败时返回 |  |

## 响应示例

### 正常示例

```json
{
    "data": {
        "app_id": "tt1234567890******",
        "auth_order_id": "80214322040407612***",
        "pay_order_id": "90214322040407612***",
        "out_pay_order_no": "SIGNPAY2024010100***",
        "merchant_uid": "MER_USER_001***",
        "total_amount": "1000",
        "pay_status": "SUCCESS",
        "trade_time": "1692775192000",
        "pay_time": "1692776192000",
        "pay_type": "BYTE_PAY",
        "pay_order_no": "PAY20240101000***"
    },
    "code": 0,
    "msg": "success",
    "log_id": "2022092115392201020812109511046"
}
```

### 异常示例

```json
{
    "code": 500000001,
    "msg": "Parameter error",
    "log_id": "2022092115392201020812109511047",
    "data": null
}
```

## 错误码

### 通用错误码

| 错误码 | 错误名称 | 描述（msg） | 排查建议 |
|-|-|-|-|
| 0 | Success | success | 请求成功，无需处理 |
| 500000000 | OApiCommonInternalError | internal error | 系统内部错误，请稍后重试；若持续出现请携带 log_id 联系技术支持 |
| 500000001 | OApiCommonDeveloperParamError | Parameter error | 请求参数错误，请检查 pay_order_id 和 out_pay_order_no 是否至少传入一个，以及参数格式是否正确 |
| 500000002 | OApiCommonDeveloperRateLimitError | Rate limit error | 请求触发限流，请降低调用频率后重试 |
| 500000003 | OApiCommonVerifySignFailError | Verify sign fail | 签名验证失败，请检查 x-DB-AccessToken 是否有效、是否过期，必要时重新调用 get_client_token 获取新 token |