概览
本文档仅供已签约商户使用，请勿公开转载。
交易类型
ST Pay 提供两种交易，均由您的服务器调用 API 创建：
| 交易 | 资金流向 | 流程 |
|---|---|---|
| 代收 | 付款人 → ST Pay 收款账户 → 您的 ST Pay 余额 | 您创建代收单，获取收款账号与订单金额，并请付款人转账。ST Pay 确认入账后，将扣除手续费后的结算金额计入您的余额，并通过 Callback 通知您。 |
| 代付 | 您的 ST Pay 余额 → 收款人 | 您创建代付单并指定收款账号。ST Pay 出款后，从您的余额中扣除代付金额与手续费，并通过 Callback 通知您。 |
支持两种通道：fps（转数快）与 bank_transfer（银行转账）。
API 列表
| API | 用途 | 方法与路径 |
|---|---|---|
| 代收建单 | 创建代收单，获取付款信息 | POST /api/v1/collect/orders |
| 代付建单 | 创建代付单 | POST /api/v1/payout/orders |
| 代收查单 | 查询代收单当前的状态与金额 | POST /api/v1/collect/orders/query |
| 代付查单 | 查询代付单当前的状态与金额 | POST /api/v1/payout/orders/query |
| Callback | 订单有结果时，ST Pay 主动通知您 | ST Pay POST 到您建单时传入的 callback_url |
对接流程
- 向 ST Pay 提供以下资料
- 服务器出口 IP：调用 API 的所有来源 IP，每个都必须是单个 IPv4 或 IPv6 地址，不支持网段。
- 后台登录 IP：登录商户后台的来源 IP，格式同上。与 API 的 IP 白名单分开设置。
- 获取 API 凭证与后台账号：ST Pay 会提供
api_identity（API 身份）与 API 验证密钥。密钥仅在创建时显示一次，之后 ST Pay 不再显示，请立即妥善保存。ST Pay 也会创建商户主管的后台账号并提供初始密码，首次登录时必须修改。 - 在测试环境完成对接：按照本文档完成四个 API 与 Callback 的对接，并对照上线前检查清单逐项确认。
- 上线生产环境：生产环境的域名、凭证、IP 白名单与测试环境完全独立，需另行申请。
API 与后台登录的 IP 白名单、凭证均由 ST Pay 配置。如需变更，请联系您的 ST Pay 对接联系人；IP 白名单变更后约 1 分钟生效。
Callback 地址无需提供给 ST Pay：请在每次建单时通过 callback_url 传入，规则见 Callback 地址。
环境
| 环境 | API 域名 | 商户后台 | 说明 |
|---|---|---|---|
| 测试环境 | 由 ST Pay 对接窗口提供 | 由 ST Pay 对接窗口提供 | 不产生真实资金流转；使用测试环境专用的凭证 |
| 生产环境 | 测试环境完成对接后另行提供 | 测试环境完成对接后另行提供 | 真实资金流转；使用生产环境专用的凭证 |
完整地址为“域名 + 路径”，例如 https://merchant.vincoterra.com/api/v1/collect/orders。商户后台与 API 使用同一个域名（只是路径不同），付款页则在 pay.vincoterra.com。本文档示例一律使用生产环境的实际域名：merchant.vincoterra.com（API 与商户后台）、pay.vincoterra.com（付款页）；测试环境的域名由 ST Pay 对接窗口另行提供。