# 快速开始

完成第一笔请求需要一个商户账户、一组账户级 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。完整规则见[认证与签名](https://docs.potabank.com/guide/authentication.md)。

## 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 到达顺序。

## 下一步

1. 对照[服务与 Host](https://docs.potabank.com/guide/service-routing.md)拆分客户端。
2. 按[幂等与重试](https://docs.potabank.com/guide/idempotency.md)实现超时恢复。
3. 接入[Webhook](https://docs.potabank.com/guide/webhooks.md)并完成验签和去重。
4. 在申请生产权限前完成[上线检查清单](https://docs.potabank.com/guide/go-live.md)。