查询支付与列表

查询单笔支付（含退款记录），或按状态分页列出商户的全部支付。用于订单详情、对账和补偿 Webhook 丢失的场景。

查询单笔支付

GET/api/v1/payments/:id需要 API Key

:id 接受 pay_1 或纯数字 1。只能查询本商户的支付单，其他商户的编号返回 404 PAYMENT_NOT_FOUND。

请求示例

curl "https://your-domain/api/v1/payments/pay_1" \
  -H "Authorization: Bearer $SPACEPAY_KEY"

import os
import requests

resp = requests.get(
    "https://your-domain/api/v1/payments/pay_1",
    headers={"Authorization": f"Bearer {os.environ['SPACEPAY_KEY']}"},
    timeout=15,
)
print(resp.json())

const resp = await fetch('https://your-domain/api/v1/payments/pay_1', {
  headers: { Authorization: `Bearer ${process.env.SPACEPAY_KEY}` },
});
const data = await resp.json();

响应示例

{
  "ok": true,
  "payment": {
    "id": "pay_1",
    "numeric_id": 1,
    "reference": "order-2026-0001",
    "amount_cents": 1234,
    "amount": "12.34",
    "currency": "USD",
    "status": "PARTIALLY_REFUNDED",
    "refunded_cents": 234,
    "refundable_cents": 1000,
    "description": "拿铁两杯",
    "customer_email": "[email protected]",
    "metadata": { "sku": "latte" },
    "checkout_url": "https://your-domain/pay.html?token=…",
    "created_at": 1762800000000,
    "paid_at": 1762800030000,
    "expires_at": 1762801800000
  },
  "refunds": [
    {
      "id": "ref_1",
      "payment_id": 1,
      "amount_cents": 234,
      "amount": "2.34",
      "reason": "部分退单",
      "status": "SUCCEEDED",
      "created_at": 1762800200000
    }
  ]
}

支付列表

GET/api/v1/payments需要 API Key

参数	类型	说明
`limit`可选	integer	每页条数，1–100，默认 20
`starting_after`可选	string	游标：上一页最后一个 `id`（如 `pay_100`），返回比它更早的记录
`status`可选	string	按状态筛选：`CREATED` / `SUCCEEDED` / `PARTIALLY_REFUNDED` / `REFUNDED` / `CANCELED` / `EXPIRED`

结果按创建时间倒序（最新的在前）。响应中的 has_more 与 next_starting_after 用于翻页：

{
  "ok": true,
  "items": [ { "id": "pay_100", "status": "SUCCEEDED", "amount_cents": 1234 } ],
  "has_more": true,
  "next_starting_after": "pay_100"
}

翻页示例

import os
import requests

key = os.environ["SPACEPAY_KEY"]
cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["starting_after"] = cursor
    data = requests.get(
        "https://your-domain/api/v1/payments",
        headers={"Authorization": f"Bearer {key}"},
        params=params,
        timeout=15,
    ).json()
    for p in data["items"]:
        print(p["id"], p["status"], p["amount"])
    if not data["has_more"]:
        break
    cursor = data["next_starting_after"]

let cursor = null;
for (;;) {
  const qs = new URLSearchParams({ limit: '100' });
  if (cursor) qs.set('starting_after', cursor);
  const data = await (await fetch(`https://your-domain/api/v1/payments?${qs}`, {
    headers: { Authorization: `Bearer ${process.env.SPACEPAY_KEY}` },
  })).json();
  for (const p of data.items) console.log(p.id, p.status, p.amount);
  if (!data.has_more) break;
  cursor = data.next_starting_after;
}

常见用法

对账：按天拉取 SUCCEEDED 的支付，与自己的订单表比对。
补偿：Webhook 丢失时，用 reference 找到对应支付并主动查询状态。
客服：根据订单号或支付编号查看退款记录与可退金额。

i列表接口只返回当前商户的数据。分页使用游标而不是页码，数据量大时也能稳定遍历。