---
name: shortpay-data-reading
description: Use when reading approved RockPay account, charge, event, payment intent, or refund data without initiating a payment action.
---

> 生产主站和 API 使用 https://rockpay.ai，托管结账使用 https://checkout.rockpay.ai。既有 shortpay.ai、checkout.shortpay.ai 和已配置的旧域名仍可直接访问；新接入使用 RockPay 域名。

# RockPay 公共数据读取

生产服务地址：网站、公共文档与管理页面使用 `https://rockpay.ai`；服务端 API base 使用 `https://rockpay.ai`；托管结账、同源 `/checkout-api/*` 与 `/embed.js` 使用 `https://checkout.rockpay.ai`。管理浏览器请求保持与 `https://rockpay.ai` 同源。服务端 API 与网站、公共文档共用主域名。

公开文档不需要密钥，但读取业务数据仍需要单站点 Bearer 服务端密钥。当前协议和参数以 `https://rockpay.ai/v1/docs?format=markdown` 为准。

## 允许的读取

- `GET /v1/account`：当前站点稳定 account ID；能力 flags 为未知。
- `GET /v1/charges`：已确认付款的最新优先列表，支持 `limit`、`starting_after`、`ending_before` 与 `created` 时间过滤。
- `GET /v1/events`：不可变的 `charge.succeeded` 快照，支持与 charges 相同的游标/时间过滤及单一 `types[]=charge.succeeded`。
- `GET /v1/customers/{id}`、`/v1/checkout/sessions/{id}`、`/v1/checkout/sessions/{id}/line_items`、`/v1/payment_intents/{id}`、`/v1/refunds/{id}`：读取已知且属于本站点的对象。

## 约束

- 不要寻找、复制、揭示或自动轮换密钥；缺少经过批准的服务端密钥时停止。
- 不调用 POST 端点、托管 checkout capability 路径或管理 API 来完成一次“读取”任务。
- 金额一律以整数最小单位和货币一起报告，避免浮点计算。
- `processing`、`pending`、`unknown` 与未确认退款不应被表述为已完成。Charge 是支付确认，不是结算或银行对账证据。
- 游标、对象 ID 和返回数据按站点隔离。404/400 不是尝试其他站点或其他凭据的理由。
- 输出中最小化个人信息、买家 capability URL 和标识符；不要把原始业务数据公开传播。

## 主动查询支付结果

`GET /v1/checkout/sessions/{id}` / `GET /v1/payment_intents/{id}`

在业务站服务端调用以下任一接口，使用创建 Session 时返回的 `id`（`cs_...`）或 `payment_intent`（`pi_...`）。业务站自己的订单号不能代替这两个 ID。

两个接口均使用本站点服务端 Bearer 密钥。存在支付尝试时，每次读取都会主动核验原支付结果并同步已确认状态，包括此前已成功的付款；尚未发起支付时，返回未支付对象，不发起扣款。

判断付款成功：Session 的 `payment_status` 为 `paid`，或 PaymentIntent 的 `status` 为 `succeeded`。不要仅凭 Session 的 `status` 判断付款成功；其值为 `open`、`complete` 或 `expired`。

查询超时、查询服务不可用、结果无法验证或暂时无法确认最终性时，返回 `502` / `api_error`，不是未支付或付款失败。错误响应：

```json
{"error":{"type":"api_error","message":"Payment inquiry unavailable or unverified","param":null,"code":null}}
```

稍后使用同一 ID 重试；不要因查询失败重新创建支付或扣款。查询确认成功后，核对金额、币种及本地订单归属，并与 Webhook 共用按支付 ID 去重的履约逻辑，防止重复发放。