跳转到内容
Gateway API

Query API

查看 .md
服务地址
https://query-api.psp.example.com
Example host; obtain the actual Query host from PSP
认证
Ed25519 签名
版本
1.0.0

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

Section titled “Query Payments”

List invoice payment intents

Section titled “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.

请求示例

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

响应

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 必填 — 
{
  "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
}

Get a invoice payment intent

Section titled “Get a invoice payment intent”
GET/api/v1/payments/intents/{invoice_number}

路径参数

名称 类型 必填 说明
invoice_number string 必填 —

请求示例

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

响应

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 可选 — 
{
  "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": {}
}

List transfer intents

Section titled “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.

请求示例

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

响应

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 必填 — 
{
  "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
}

Get a transfer intent

Section titled “Get a transfer intent”
GET/api/v1/payments/transfers/{intent_id}

路径参数

名称 类型 必填 说明
intent_id string 必填 —

请求示例

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

响应

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 可选 — 
{
  "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": {}
}

List refunds

Section titled “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

请求示例

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

响应

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 必填 — 
{
  "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
}

Get a refund

Section titled “Get a refund”
GET/api/v1/payments/refunds/{refund_id}

路径参数

名称 类型 必填 说明
refund_id string 必填 —

请求示例

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

响应

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> 可选 — 
{
  "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"
}

List order events

Section titled “List order events”
GET/api/v1/orders/{order_id}/events

路径参数

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

请求示例

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

响应

Order event list

List order notifications

Section titled “List order notifications”
GET/api/v1/orders/{order_id}/notifications

路径参数

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

请求示例

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

响应

Order notification list

Query Accounts

Section titled “Query Accounts”

List merchant accounts

Section titled “List merchant accounts”
GET/api/v1/merchant-accounts

请求示例

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

响应

Merchant account page

Get a merchant account

Section titled “Get a merchant account”
GET/api/v1/merchant-accounts/{account_id}

路径参数

名称 类型 必填 说明
account_id string 必填 —

请求示例

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

响应

Merchant account detail

Get merchant account balance

Section titled “Get merchant account balance”
GET/api/v1/merchant-accounts/{account_id}/balance

路径参数

名称 类型 必填 说明
account_id string 必填 —

请求示例

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

响应

Balance detail

List account transactions

Section titled “List account transactions”
GET/api/v1/merchant-accounts/{account_id}/transactions

路径参数

名称 类型 必填 说明
account_id string 必填 —

查询参数

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

请求示例

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

响应

Account transaction page

Get aggregate merchant balance

Section titled “Get aggregate merchant balance”
GET/api/v1/merchants/balance

请求示例

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

响应

Merchant balance list

Query Cards

Section titled “Query Cards”

Get credit card authorization

Section titled “Get credit card authorization”
GET/api/v1/cards/authorizations/{authorization_id}

路径参数

名称 类型 必填 说明
authorization_id string 必填 —

请求示例

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

响应

Authorization detail

Get credit card capture

Section titled “Get credit card capture”
GET/api/v1/cards/captures/{invoice_id}

路径参数

名称 类型 必填 说明
invoice_id string 必填 —

请求示例

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

响应

Capture detail

List credit card refunds

Section titled “List credit card refunds”
GET/api/v1/cards/refunds

请求示例

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

响应

Card refund page

Get credit card refund

Section titled “Get credit card refund”
GET/api/v1/cards/refunds/{refund_id}

路径参数

名称 类型 必填 说明
refund_id string 必填 —

请求示例

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

响应

Card refund detail

Query Tokenization

Section titled “Query Tokenization”

Get token metadata

Section titled “Get token metadata”
GET/api/v1/tokenization/tokens/{token_id}

路径参数

名称 类型 必填 说明
token_id string 必填 —

请求示例

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

响应

Token detail

List customer tokens

Section titled “List customer tokens”
GET/api/v1/tokenization/customers/{customer_id}/tokens

路径参数

名称 类型 必填 说明
customer_id string 必填 —

请求示例

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

响应

Customer token page