快速开始

完成第一笔请求需要一个商户账户、一组账户级 API 凭证和 Ed25519 私钥。PSP 只保存你上传的公钥；私钥必须留在你的安全环境中。

1. 选择服务

业务动作	服务	凭证类型
创建或取消代收、代收退款	Invoice	Invoice account secret
创建或取消代付、同步代付订单	Transfer	Transfer account secret
查询订单、退款、账户或余额	Query	Invoice 或 Transfer account secret

2. 准备请求

以下是创建 PIX 代收意图的最小示例。金额使用最小货币单位；10000 BRL 表示 R$ 100.00。

{
  "payment_method": "pix",
  "rail_variant": "pix_qr",
  "amount": 10000,
  "currency": "BRL",
  "merchant_order_id": "ORDER_20260827_001"
}

3. 生成签名

请求签名前先计算 body 的 SHA-256，并严格按换行顺序拼接 payload：

v1
{api_id}
{merchant_account_id}
{METHOD}
{escaped_path}
{canonical_query}
{timestamp}
{idempotency_key}
{sha256(body)}

使用 Ed25519 私钥签名 UTF-8 payload，再将签名编码为标准 Base64。完整规则见认证与签名。

4. 发送请求

curl --request POST "${PSP_INVOICE_BASE_URL}/api/v1/payments/intents" \
  --header "Content-Type: application/json" \
  --header "X-API-ID: ${PSP_API_ID}" \
  --header "X-API-Key: ${PSP_API_KEY}" \
  --header "X-Timestamp: ${PSP_TIMESTAMP}" \
  --header "X-Signature: ${PSP_SIGNATURE}" \
  --header "X-Idempotency-Key: invoice:create:ORDER_20260827_001" \
  --data-binary @request.json

不要直接复制 Host

生产与测试 Host 由接入团队提供。OpenAPI 中的 *.example.com 只用于描述服务边界，不是可调用地址。

5. 保存关键标识

成功后至少保存 PSP 返回的 id、invoice_number、商户订单号、请求幂等键和创建时间。查询、取消及退款使用 invoice_number；状态确认应调用 Query API，不应只依赖同步响应或 Webhook 到达顺序。

下一步

1. 对照服务与 Host拆分客户端。
2. 按幂等与重试实现超时恢复。
3. 接入Webhook并完成验签和去重。
4. 在申请生产权限前完成上线检查清单。