# Zeffra 代付 pay_type_code 接入说明

渠道标识：`zeffra`，国家/币种：`US / USD`。

## 启用账户类型

| 平台 `payTypeCode` | 平台 `payeeType` | 上游产品码（平台内部） |
| --- | --- | --- |
| `card` | `BANK_CARD` | `110` |
| `debit_card` | `BANK_CARD` | `117` |
| `ach` | `ACH` | `115` |
| `paypal` | `PAYPAL` | `112` |
| `cashapp` | `CASHAPP` | `113` |

Apple Pay、Google Pay 代付因收款账户语义未确认而默认禁用。

## 公共外必填字段

除统一代付公共字段外，Zeffra 还要求：

- `payeeName`、`payeeFirstName`、`payeeLastName`
- `payeeEmail`、`payeeMobile`
- `payeeAccountExpireAt`
- `payeeProvince`、`payeeCity`、`payeeAddress`、`payeePostalCode`
- `countryCode=US`、`currency=USD`
- ACH 额外要求 `payeeBankCode` 为通过校验位验证的 9 位 ABA Routing Number
- `payeeBirthday` 可选，推荐 `YYYY-MM-DD`

平台字段会映射为 Zeffra 的 `first_name/last_name/email/phone/receive_account_expire_at/state/city/address/postal_code/birthday`。标准字段必须位于请求根节点，不得塞进 `ext`。

## 用户确认

提交或查单可能返回 `needUserConfirm=true` 和 `confirmUrl`。此时订单仍为处理中，商户应引导当前用户打开确认地址，并继续等待回调或查单终态。后续响应明确返回 `needUserConfirm=false` 时，平台会同步清除旧 `confirmUrl`，商户不得继续使用缓存的确认地址。

## 订单号

- `merchant_order_no`：我方代付 BatchId。
- `order_no`：Zeffra 上游订单号。
- `identifier`：上游交易凭证，仅作附加信息，不用于定位我方订单或作为幂等键。