创建支付

创建一笔支付单并拿到结账链接。支付单在 30 分钟内有效；付款人完成支付后，你会收到 payment.succeeded Webhook。

POST/api/v1/payments需要 API Key

请求参数

参数	类型	说明
`amount`必填	string	金额，如 `"12.34"`。最多 2 位小数，必须大于 0，上限 `$10,000,000.00`
`currency`可选	string	币种，当前仅支持 `USD`（默认）
`reference`可选	string	你的订单号，同一商户内唯一。相同订单号且金额一致时返回同一笔支付；金额不同返回 `REFERENCE_CONFLICT`
`description`可选	string	商品或服务描述，付款人可见，最长 200 字
`customer_email`可选	string	限定付款人。设置后其他账户不能支付该单，返回 `CUSTOMER_MISMATCH`
`metadata`可选	object	自定义键值，序列化后不超过 2KB，会原样出现在查询结果和 Webhook 中
`success_url`可选	string	付款成功后付款人浏览器跳转的地址（http/https）
`cancel_url`可选	string	付款人取消后跳转的地址

请求示例

curl "https://your-domain/api/v1/payments" \
  -X POST \
  -H "Authorization: Bearer $SPACEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4c55-9a10-2f8e7d6c5b4a" \
  -d '{
    "amount": "12.34",
    "reference": "order-2026-0001",
    "description": "拿铁两杯",
    "metadata": { "sku": "latte" },
    "success_url": "https://shop.example/paid"
  }'

import os
import requests

resp = requests.post(
    "https://your-domain/api/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEPAY_KEY']}",
        "Idempotency-Key": "6f1c2a9e-3b7d-4c55-9a10-2f8e7d6c5b4a",
    },
    json={
        "amount": "12.34",
        "reference": "order-2026-0001",
        "description": "拿铁两杯",
        "metadata": {"sku": "latte"},
        "success_url": "https://shop.example/paid",
    },
    timeout=15,
)
payment = resp.json()["payment"]
print(payment["checkout_url"])

const resp = await fetch('https://your-domain/api/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPACEPAY_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2a9e-3b7d-4c55-9a10-2f8e7d6c5b4a',
  },
  body: JSON.stringify({
    amount: '12.34',
    reference: 'order-2026-0001',
    description: '拿铁两杯',
    metadata: { sku: 'latte' },
    success_url: 'https://shop.example/paid',
  }),
});
const { payment } = await resp.json();

响应字段

字段	说明
`payment.id`	支付单编号，形如 `pay_1`
`payment.numeric_id`	纯数字编号，便于数据库存储
`payment.reference`	你的订单号；未传时自动生成
`payment.amount_cents`	金额（整数分），如 `1234`
`payment.amount`	金额（十进制字符串）
`payment.currency`	`USD`
`payment.status`	见下方状态表
`payment.refunded_cents`	已退款金额（分）
`payment.refundable_cents`	剩余可退金额（分）
`payment.metadata`	创建时传入的自定义数据
`payment.checkout_url`	付款人结账地址，交给浏览器打开
`payment.created_at`	创建时间（毫秒时间戳）
`payment.paid_at`	付款时间；未支付时为 `null`
`payment.expires_at`	过期时间（创建后 30 分钟）

支付状态

CREATEDSUCCEEDEDPARTIALLY_REFUNDEDREFUNDEDEXPIREDCANCELED

状态	含义
`CREATED`	待支付，等待付款人完成结账
`SUCCEEDED`	付款成功
`PARTIALLY_REFUNDED`	已部分退款
`REFUNDED`	已全额退款
`CANCELED`	付款人取消
`EXPIRED`	超过 30 分钟未支付

幂等与去重

Idempotency-Key：网络超时后用同一个键重试，24 小时内会重放原响应，并返回 Idempotent-Replayed: true；同键不同参数返回 422。
reference：适合作为业务侧去重键。相同订单号且金额一致时返回同一笔支付，不会重复创建。

两者可以同时使用：Idempotency-Key 保证单次请求的传输安全，reference 保证业务订单唯一。

注意事项

支付单 30 分钟后过期，过期后不能再付款，需要重新创建。
设置 customer_email 后，只有该邮箱的账户能付款；不确定付款人时不要设置。
metadata 只用于你的业务数据，不要放密钥、密码等敏感信息。
金额是虚拟资金；本环境不产生真实扣款。

!不要用前端传来的金额直接创建支付：金额应由你的服务端根据订单计算，否则用户可以篡改价格。