# Query API

- 服务地址（示例，真实 Host 由接入团队提供）：`https://query-api.psp.example.com`
- 认证：Ed25519 签名
- 版本：1.0.0
- OpenAPI 规范：https://docs.potabank.com/openapi/query.openapi.yaml

Query service surface for merchant read operations. Query accepts invoice or
transfer account secrets for reads, but it does not expose write routes.
A missing X-API-ID header returns 400 INVALID_REQUEST. A missing X-API-Key
header or invalid credentials return 401 UNAUTHORIZED. A credential store
failure returns 500 INTERNAL_ERROR before the request handler runs.

## Query Payments

### List invoice payment intents

**GET** `/api/v1/payments/intents`

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_method` | `string` | 可选 | — |
| `merchant_order_id` | `string` | 可选 | — |
| `status` | `string` | 可选 | — |
| `state` | `string` | 可选 | — |
| `created_after` | `string<date-time>` | 可选 | — |
| `created_before` | `string<date-time>` | 可选 | — |
| `limit` | `integer` | 可选 | ≥ 1 · ≤ 100 |
| `offset` | `integer` | 可选 | ≥ 0 |
| `cursor` | `string` | 可选 | Presence selects cursor pagination, including an empty value for the first page. Response contains items, next_cursor, has_more and page_size instead of total. |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/intents' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Payment intent page

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `（InvoiceOffsetPage）` | `object` | 可选 | — |
| `items` | `object[]` | 必填 | — |
| `items[].id` | `string<uuid>` | 必填 | — |
| `items[].invoice_number` | `string` | 必填 | — |
| `items[].payment_method` | `string` | 必填 | — |
| `items[].amount` | `integer<int64>` | 必填 | — |
| `items[].currency` | `string` | 必填 | — |
| `items[].status` | `string` | 必填 | — |
| `items[].state` | `string` | 可选 | — |
| `items[].merchant_order_id` | `string` | 可选 | — |
| `items[].paid_amount` | `integer<int64>` | 可选 | — |
| `items[].refunded_amount` | `integer<int64>` | 可选 | — |
| `items[].payment_url` | `string` | 可选 | — |
| `items[].psp_checkout_url` | `string` | 可选 | — |
| `items[].provider_checkout_url` | `string` | 可选 | — |
| `items[].instruction` | `object` | 可选 | — |
| `items[].expected_payer_info` | `object` | 可选 | — |
| `items[].payer_info` | `object` | 可选 | — |
| `items[].created_at` | `string<date-time>` | 可选 | — |
| `items[].updated_at` | `string<date-time>` | 可选 | — |
| `items[].metadata` | `object` | 可选 | — |
| `total` | `integer<int64>` | 必填 | — |
| `limit` | `integer` | 必填 | — |
| `offset` | `integer` | 必填 | — |
| `（InvoiceCursorPage）` | `object` | 可选 | — |
| `next_cursor` | `string` | 必填 | — |
| `has_more` | `boolean` | 必填 | — |
| `page_size` | `integer` | 必填 | — |


```json
{
  "items": [
    {
      "id": "00000000-0000-7000-8000-000000000000",
      "invoice_number": "string",
      "payment_method": "string",
      "amount": 0,
      "currency": "string",
      "status": "string",
      "state": "string",
      "merchant_order_id": "string",
      "paid_amount": 0,
      "refunded_amount": 0,
      "payment_url": "string",
      "psp_checkout_url": "string",
      "provider_checkout_url": "string",
      "instruction": {},
      "expected_payer_info": {},
      "payer_info": {},
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "metadata": {}
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get a invoice payment intent

**GET** `/api/v1/payments/intents/{invoice_number}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `invoice_number` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/intents/{invoice_number}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Payment intent detail

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `string<uuid>` | 必填 | — |
| `invoice_number` | `string` | 必填 | — |
| `payment_method` | `string` | 必填 | — |
| `amount` | `integer<int64>` | 必填 | — |
| `currency` | `string` | 必填 | — |
| `status` | `string` | 必填 | — |
| `state` | `string` | 可选 | — |
| `merchant_order_id` | `string` | 可选 | — |
| `paid_amount` | `integer<int64>` | 可选 | — |
| `refunded_amount` | `integer<int64>` | 可选 | — |
| `payment_url` | `string` | 可选 | — |
| `psp_checkout_url` | `string` | 可选 | — |
| `provider_checkout_url` | `string` | 可选 | — |
| `instruction` | `object` | 可选 | — |
| `expected_payer_info` | `object` | 可选 | — |
| `payer_info` | `object` | 可选 | — |
| `created_at` | `string<date-time>` | 可选 | — |
| `updated_at` | `string<date-time>` | 可选 | — |
| `metadata` | `object` | 可选 | — |


```json
{
  "id": "00000000-0000-7000-8000-000000000000",
  "invoice_number": "string",
  "payment_method": "string",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "state": "string",
  "merchant_order_id": "string",
  "paid_amount": 0,
  "refunded_amount": 0,
  "payment_url": "string",
  "psp_checkout_url": "string",
  "provider_checkout_url": "string",
  "instruction": {},
  "expected_payer_info": {},
  "payer_info": {},
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "metadata": {}
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List transfer intents

**GET** `/api/v1/payments/transfers`

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `payment_method` | `string` | 可选 | — |
| `merchant_order_id` | `string` | 可选 | — |
| `status` | `string` | 可选 | — |
| `state` | `string` | 可选 | — |
| `created_after` | `string<date-time>` | 可选 | — |
| `created_before` | `string<date-time>` | 可选 | — |
| `limit` | `integer` | 可选 | ≥ 1 · ≤ 100 |
| `offset` | `integer` | 可选 | ≥ 0 |
| `cursor` | `string` | 可选 | Presence selects cursor pagination, including an empty value for the first page. Response contains items, next_cursor, has_more and page_size instead of total. |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/transfers' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Transfer intent page

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `（TransferOffsetPage）` | `object` | 可选 | — |
| `items` | `object[]` | 必填 | — |
| `items[].id` | `string<uuid>` | 必填 | — |
| `items[].transfer_number` | `string` | 必填 | — |
| `items[].payment_method` | `string` | 必填 | — |
| `items[].amount` | `integer<int64>` | 必填 | — |
| `items[].currency` | `string` | 必填 | — |
| `items[].status` | `string` | 必填 | — |
| `items[].state` | `string` | 可选 | — |
| `items[].merchant_order_id` | `string` | 可选 | — |
| `items[].beneficiary` | `object` | 可选 | — |
| `items[].actual_beneficiary` | `object` | 可选 | — |
| `items[].transferred_amount` | `integer<int64>` | 可选 | — |
| `items[].returned_amount` | `integer<int64>` | 可选 | — |
| `items[].created_at` | `string<date-time>` | 可选 | — |
| `items[].updated_at` | `string<date-time>` | 可选 | — |
| `items[].metadata` | `object` | 可选 | — |
| `total` | `integer<int64>` | 必填 | — |
| `limit` | `integer` | 必填 | — |
| `offset` | `integer` | 必填 | — |
| `（TransferCursorPage）` | `object` | 可选 | — |
| `next_cursor` | `string` | 必填 | — |
| `has_more` | `boolean` | 必填 | — |
| `page_size` | `integer` | 必填 | — |


```json
{
  "items": [
    {
      "id": "00000000-0000-7000-8000-000000000000",
      "transfer_number": "string",
      "payment_method": "string",
      "amount": 0,
      "currency": "string",
      "status": "string",
      "state": "string",
      "merchant_order_id": "string",
      "beneficiary": {},
      "actual_beneficiary": {},
      "transferred_amount": 0,
      "returned_amount": 0,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "metadata": {}
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get a transfer intent

**GET** `/api/v1/payments/transfers/{intent_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `intent_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/transfers/{intent_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Transfer intent detail

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `string<uuid>` | 必填 | — |
| `transfer_number` | `string` | 必填 | — |
| `payment_method` | `string` | 必填 | — |
| `amount` | `integer<int64>` | 必填 | — |
| `currency` | `string` | 必填 | — |
| `status` | `string` | 必填 | — |
| `state` | `string` | 可选 | — |
| `merchant_order_id` | `string` | 可选 | — |
| `beneficiary` | `object` | 可选 | — |
| `actual_beneficiary` | `object` | 可选 | — |
| `transferred_amount` | `integer<int64>` | 可选 | — |
| `returned_amount` | `integer<int64>` | 可选 | — |
| `created_at` | `string<date-time>` | 可选 | — |
| `updated_at` | `string<date-time>` | 可选 | — |
| `metadata` | `object` | 可选 | — |


```json
{
  "id": "00000000-0000-7000-8000-000000000000",
  "transfer_number": "string",
  "payment_method": "string",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "state": "string",
  "merchant_order_id": "string",
  "beneficiary": {},
  "actual_beneficiary": {},
  "transferred_amount": 0,
  "returned_amount": 0,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "metadata": {}
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List refunds

**GET** `/api/v1/payments/refunds`

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `original_intent_id` | `string<uuid>` | 可选 | — |
| `payment_method` | `string` | 可选 | — |
| `status` | `string` | 可选 | — |
| `state` | `string` | 可选 | — |
| `created_after` | `string<date-time>` | 可选 | — |
| `created_before` | `string<date-time>` | 可选 | — |
| `limit` | `integer` | 可选 | ≥ 1 · ≤ 100 |
| `offset` | `integer` | 可选 | ≥ 0 |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/refunds' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Refund page

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `items` | `object[]` | 必填 | — |
| `items[].id` | `string<uuid>` | 必填 | — |
| `items[].refund_number` | `string` | 必填 | — |
| `items[].original_intent_id` | `string<uuid>` | 必填 | — |
| `items[].invoice_number` | `string` | 可选 | — |
| `items[].amount` | `integer<int64>` | 必填 | — |
| `items[].currency` | `string` | 必填 | — |
| `items[].status` | `string` | 必填 | — |
| `items[].state` | `string` | 可选 | — |
| `items[].reason` | `string` | 可选 | — |
| `items[].created_at` | `string<date-time>` | 可选 | — |
| `items[].updated_at` | `string<date-time>` | 可选 | — |
| `total` | `integer<int64>` | 必填 | — |
| `limit` | `integer` | 必填 | — |
| `offset` | `integer` | 必填 | — |


```json
{
  "items": [
    {
      "id": "00000000-0000-7000-8000-000000000000",
      "refund_number": "string",
      "original_intent_id": "00000000-0000-7000-8000-000000000000",
      "invoice_number": "string",
      "amount": 0,
      "currency": "string",
      "status": "string",
      "state": "string",
      "reason": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get a refund

**GET** `/api/v1/payments/refunds/{refund_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `refund_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/payments/refunds/{refund_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Refund detail

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | `string<uuid>` | 必填 | — |
| `refund_number` | `string` | 必填 | — |
| `original_intent_id` | `string<uuid>` | 必填 | — |
| `invoice_number` | `string` | 可选 | — |
| `amount` | `integer<int64>` | 必填 | — |
| `currency` | `string` | 必填 | — |
| `status` | `string` | 必填 | — |
| `state` | `string` | 可选 | — |
| `reason` | `string` | 可选 | — |
| `created_at` | `string<date-time>` | 可选 | — |
| `updated_at` | `string<date-time>` | 可选 | — |


```json
{
  "id": "00000000-0000-7000-8000-000000000000",
  "refund_number": "string",
  "original_intent_id": "00000000-0000-7000-8000-000000000000",
  "invoice_number": "string",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "state": "string",
  "reason": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List order events

**GET** `/api/v1/orders/{order_id}/events`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `order_id` | `string<uuid>` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/orders/{order_id}/events' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Order event list

### List order notifications

**GET** `/api/v1/orders/{order_id}/notifications`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `order_id` | `string<uuid>` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/orders/{order_id}/notifications' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Order notification list

## Query Accounts

### List merchant accounts

**GET** `/api/v1/merchant-accounts`

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/merchant-accounts' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Merchant account page

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get a merchant account

**GET** `/api/v1/merchant-accounts/{account_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `account_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/merchant-accounts/{account_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Merchant account detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get merchant account balance

**GET** `/api/v1/merchant-accounts/{account_id}/balance`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `account_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/merchant-accounts/{account_id}/balance' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Balance detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List account transactions

**GET** `/api/v1/merchant-accounts/{account_id}/transactions`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `account_id` | `string` | 必填 | — |

**查询参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `limit` | `integer` | 可选 | ≥ 1 · ≤ 100 |
| `offset` | `integer` | 可选 | ≥ 0 |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/merchant-accounts/{account_id}/transactions' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Account transaction page

### Get aggregate merchant balance

**GET** `/api/v1/merchants/balance`

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/merchants/balance' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Merchant balance list

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

## Query Cards

### Get credit card authorization

**GET** `/api/v1/cards/authorizations/{authorization_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `authorization_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/cards/authorizations/{authorization_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Authorization detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get credit card capture

**GET** `/api/v1/cards/captures/{invoice_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `invoice_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/cards/captures/{invoice_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Capture detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List credit card refunds

**GET** `/api/v1/cards/refunds`

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/cards/refunds' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Card refund page

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### Get credit card refund

**GET** `/api/v1/cards/refunds/{refund_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `refund_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/cards/refunds/{refund_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Card refund detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

## Query Tokenization

### Get token metadata

**GET** `/api/v1/tokenization/tokens/{token_id}`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `token_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/tokenization/tokens/{token_id}' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Token detail

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.

### List customer tokens

**GET** `/api/v1/tokenization/customers/{customer_id}/tokens`

**路径参数**

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `customer_id` | `string` | 必填 | — |

**请求示例**

```bash
curl -X GET 'https://query-api.psp.example.com/api/v1/tokenization/customers/{customer_id}/tokens' \
  -H 'X-API-ID: <api-id>'
```

**响应**

#### 响应 200 OK

Customer token page

#### 响应 500 Server Error

Credential lookup failed (INTERNAL_ERROR). The request handler was not executed.