接入流程

概览

本文介绍 Pyvio 平台的完整接入流程，覆盖从创建子商户、开户、收款、付款、转账到文件上传的核心链路。阅读对象：准备对接 Pyvio Open API (opens new window) 的开发者。完整的 API 文档请访问：https://developer-doc.pyvio.com (opens new window)

# 通用请求头

所有接口调用均需要在请求头中携带以下字段：

请求头	必填	说明
`X-Unit-Id`	机构模式必填	指定当前要操作的账户。机构模式下必须传子商户的 `UnitId`；大商户模式可省略。
`Request-Id`	是	唯一请求 ID，长度 ≤ 32 字符，用于幂等与链路追踪。
`X-Timestamp`	POST 必填	毫秒级时间戳，参与签名计算。
`Sign`	POST 必填	RSA 签名，具体规则请参考签名方式。

注意

调用接口之前，请先完成授权并了解签名方式。
确认已配置好开发者信息，包括 AppID、密钥、IP 白名单等。

# 1. 创建子商户 — Create User

创建子商户

查看创建子商户详细说明

- name: 创建子商户
  desc: 查看创建子商户详细说明
  link: /pages/guid/user/
  bgColor: '#f7f8fa'
  textColor: '#525866'

当采用机构模式接入时，需要调用 Create User (opens new window) 接口，将子商户资料报送给 Pyvio。

提交后，Pyvio 会对子商户资料进行审核，审核结果通过 User Notification (opens new window) 异步回调。status 取值如下：

状态	说明
`Pending`	提交成功，待审核。
`Active`	审核通过。
`Suspend`	合规原因不可用，也无法再次创建。
`Deact`	合规原因不可用，也无法再次创建。
`Returned`	需要补充材料，通过 Update User (opens new window) 接口更新。
`PreOverdue`	材料即将过期。在被 `Returned` 之前，用户状态正常，不影响使用。可通过 Update User (opens new window) 进行更新。

关键说明：

子商户审核通过后，会生成对应的 UnitId，后续操作均需要携带此 UnitId。
开户审核细节详见开户流程。

# 2. 创建 VA（全球收款账户） — Open Global Account

创建收款账户

查看创建收款账户详细说明

- name: 创建收款账户
  desc: 查看创建收款账户详细说明
  link: /pages/va/create
  bgColor: '#f7f8fa'
  textColor: '#525866'

子商户开户需要调用 Open Global Account (opens new window) 接口，申请虚拟收款账户（VA）。

关键说明：

开户申请结果通过 Global Account Notification (opens new window) 异步回调。
B2C 场景需先调用 Create Shop (opens new window) 创建店铺，再创建 Global Account。详见创建店铺。
Shop 的 site / currency 必须与 Global Account 的 country / currency 保持一致。
不同业务类型（Collection、Direct Payment、B2B Collection）的申请限制和参数要求，请参考创建收款账户。

# 3. 入账 — Collection

入账流程

查看入账流程详细说明

- name: 入账流程
  desc: 查看入账流程详细说明
  link: /pages/collection/inbound
  bgColor: '#f7f8fa'
  textColor: '#525866'

资金入账到 VA 后，默认状态为 Pending。详细流程请参考入账流程。

# 材料补充流程

当入账需要补充材料时，会触发以下流程：

收到 Attachment Notification (opens new window)（需提交材料通知）
调用 Submit Attachment (opens new window) 提交材料
等待审核结果回调 Attachment Audit Notification (opens new window)
若审核结果为 Declined，根据失败原因修正后重新提交材料
审核通过后，Collection Notification (opens new window) 状态变为 Success，即成功入账

# 退回流程

当入账资金被退回时，会触发以下流程：

Collection Notification (opens new window) 状态变为 Refunding，表示入账被退回
收到 Refund Notification (opens new window)（状态 Pending）
当退回订单状态变为 Success 后，Collection Notification 状态变为 Failure

注意

入账状态为终态（Success 或 Failure）后，后续的状态通知不应再做状态变更。
入账材料的首次提交会被视为有效，重复提交将被忽略。

# 4. 付款 — Create Payment

发起一笔付款

查看发起付款详细说明

- name: 发起一笔付款
  desc: 查看发起付款详细说明
  link: /pages/payment/create
  bgColor: '#f7f8fa'
  textColor: '#525866'

调用 Create Payment (opens new window) 接口发起付款。

# order_type 订单类型

类型	说明
`Withdraw`	提现，仅限收款人为当前企业对公户、法人/董事/股东，对应 `payee.payee_type` 为 `BeneficiaryBankAccount`
`Payout`	付款给供应商/个人/企业，对应 `payee.payee_type` 为 `SupplierBankAccount`

# cal_origin 出款资金方向

方向	说明
`ORIGIN2TARGET`	固定钱包出款金额，实际到账金额 = 出款 amount − 手续费
`TARGET2ORIGIN`	固定到账金额，实际钱包出款金额 = 到账金额 + 手续费

关键参数：

rate_id：汇率 ID，同币种付款可为空
payee_id / payee：收款人 ID 或收款人信息（二选一）
charge_indicator：手续费承担方（OUR / SHA）
purpose：交易用途，参见交易用途枚举

更多参数细节请参考发起一笔付款。

# 5. 内部账户转账 — Create Transfer

发起一笔转账

查看发起转账详细说明

- name: 发起一笔转账
  desc: 查看发起转账详细说明
  link: /pages/transfer/create
  bgColor: '#f7f8fa'
  textColor: '#525866'

转账是指 Pyvio 系统内部账户之间的资金划转，调用 Create Transfer (opens new window) 接口。

注意

转账接口需要通过 BD 申请开通。
转账暂无手续费，默认返回的手续费金额为 0。

异步通知：

转出通知：Transfer Notification (opens new window)
到账通知：TransferIn Notification (opens new window)

# 6. 获取文件 ID — File Upload

获取文件 ID

查看文件上传与 file_id 获取说明

- name: 获取文件 ID
  desc: 查看文件上传与 file_id 获取说明
  link: /pages/file/
  bgColor: '#f7f8fa'
  textColor: '#525866'

部分业务接口（如创建收款人、补充入账材料等）需要上传文件。Pyvio 统一文件处理流程如下：

开发者先将文件上传到 Pyvio SFTP 服务器
调用 File Upload (opens new window) 接口获取 file_id
将 file_id 作为其他业务接口的参数使用

支持的文件类型： xls、xlsx、doc、docx、pdf、jpg、jpeg、png、bmp、zip、rar

SFTP 目录规则

SFTP 服务器仅允许在 IP 白名单内访问
目录格式：/{appId}/INPUT/{bizType}/{yyyyMMdd}/{unitId}
bizType 枚举：Settlement、Inbound、Payee、Outbound、User

# 相关参考

← 对接模式账号注册→