快速开始
完成第一笔请求需要一个商户账户、一组账户级 API 凭证和 Ed25519 私钥。PSP 只保存你上传的公钥；私钥必须留在你的安全环境中。
1. 选择服务
| 业务动作 | 服务 | 凭证类型 |
|---|---|---|
| 创建或取消代收、代收退款 | Invoice | Invoice account secret |
| 创建或取消代付、同步代付订单 | Transfer | Transfer account secret |
| 查询订单、退款、账户或余额 | Query | Invoice 或 Transfer account secret |
2. 准备请求
以下是创建 PIX 代收意图的最小示例。金额使用最小货币单位；10000 BRL 表示 R$ 100.00。
json
{
"payment_method": "pix",
"rail_variant": "pix_qr",
"amount": 10000,
"currency": "BRL",
"merchant_order_id": "ORDER_20260827_001"
}3. 生成签名
请求签名前先计算 body 的 SHA-256，并严格按换行顺序拼接 payload：
text
v1
{api_id}
{merchant_account_id}
{METHOD}
{escaped_path}
{canonical_query}
{timestamp}
{idempotency_key}
{sha256(body)}使用 Ed25519 私钥签名 UTF-8 payload，再将签名编码为标准 Base64。完整规则见认证与签名。
4. 发送请求
bash
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 到达顺序。