# SeavaPay 巴西 PIX 接入说明

来源：[SeavaPay Brazil API](https://sprinkle-tower-c8c.notion.site/SeavaPay-Brazil-API-2a430b99257c81dfbc82cb8fcf6cdbc0)。最后收集：2026-09-08 23:05（北京时间）。

渠道 `channelCode=seavapay`，国家 `countryCode=BR`，币种 `currency=BRL`。代收、代付均使用平台标准 `payTypeCode=pix`。金额为分，必须为 100 的正整数倍，例如 10000 表示 100.00 BRL。

## 代收

调用 `/api/PayRequest/UnifiedPay`，使用现有商户 API 的 HMAC-SHA256 签名规则。
支付返回信息可能同时包含二维码和跳转地址，应保留两者。创建订单成功表示等待付款，不代表交易成功。

```json
{
  "appId": "YOUR_APP_ID",
  "merchantOrderNo": "DEMO_SEAVA_PAY_001",
  "amount": 10000,
  "currency": "BRL",
  "countryCode": "BR",
  "channelCode": "seavapay",
  "payTypeCode": "pix",
  "subject": "Demo order",
  "notifyUrl": "https://merchant.example/notify/pay",
  "timestamp": "GENERATE_CURRENT_UNIX_SECONDS",
  "nonce": "GENERATE_UNIQUE_NONCE",
  "sign": "COMPUTE_WITH_MERCHANT_API_SECRET"
}
```

## 代付

调用 `/api/PayRequest/UnifiedPayout`。业务必填字段为 `payeeType`、`payeeAccount`，加公共请求字段和 `applyAmount`。`payeeName`、独立证件字段和银行字段不属于该渠道的必填项。

| 平台 payeeType | payeeAccount | 上游映射（供核对） |
|---|---|---|
| PIX_CPF | CPF 类型的 PIX Key | shape=PIX_CPF |
| PIX_CNPJ | CNPJ 类型的 PIX Key | shape=PIX_CNPJ |
| PIX_EMAIL | 邮箱类型的 PIX Key | shape=PIX_EMAIL |
| PIX_PHONE | 带 +55 的手机号 Key | shape=PIX_PHONE |
| PIX_RANDOM | 随机 UUID/EVP Key | shape=PIX_EVP |

商户不能传 `PIX_EVP`、`EVP`、`RANDOM` 作为 `payeeType`。`BANK`、`PIX_BANK` 不受支持。
CPF/CNPJ 类型的 Key 直接填 `payeeAccount`；无需重复填写独立 `payeeIdCard`。对其它渠道应遵循各自字段矩阵。

```json
{
  "appId": "YOUR_APP_ID",
  "merchantOrderNo": "DEMO_SEAVA_OUT_001",
  "applyAmount": 10000,
  "currency": "BRL",
  "countryCode": "BR",
  "channelCode": "seavapay",
  "payTypeCode": "pix",
  "payeeType": "PIX_EMAIL",
  "payeeAccount": "recipient@example.test",
  "notifyUrl": "https://merchant.example/notify/payout",
  "timestamp": "GENERATE_CURRENT_UNIX_SECONDS",
  "nonce": "GENERATE_UNIQUE_NONCE",
  "sign": "COMPUTE_WITH_MERCHANT_API_SECRET"
}
```

示例占位时间、随机值、签名必须实时生成；示例账户不用于真实交易。商户 API 密钥与 SeavaPay 渠道密钥不同。

## 订单号与状态

平台向 SeavaPay 提交的 `mchOrderNo` 是平台提交单号；代收重试时可能是独立尝试单号。SeavaPay 的 `payOrderId` 是代收上游单号，`agentpayOrderId` 是代付上游单号，`channelPayNo` 是 E2E 流水，三者不可替换。

商户始终按平台订单号或自己的 `merchantOrderNo` 使用平台查询接口。代付“受理成功”需要等待最终结果；处理中和二次审核保持待处理，失败与审核拒绝按失败处理，冲正进入人工对账。

## 银行范围

该渠道为 PIX Key 代付，不需要 `payeeBankCode`、分支号或 ISPB。官方未提供银行账号产品和银行表，因此没有本渠道可用的银行编码映射；不得将银行码作为 PIX Key。
详见[SeavaPay 银行标准适用范围](./seavapay-bank-codes.html)。