Z Zise Developers
/
全球账户 › 指南

跨境汇款：先建收款人，再报价，再下单。三步之间各有一个会卡住的地方。

全球账户概述

会员把钱从他在你这里的余额汇到境外的一个收款人。我方负责走廊、报价、合规与出款，你负责界面与你自己的定价。

一张图：收款人 · VP 账户 · 汇款 · 订单状态

① 前置 —— 四样缺一不可 会员POST /v1/members KYC 等级 极速要 level 1 · 个人要 level 2 会员可用余额 ≥ 冻结额（含滑点预留） 你的预付余额 不足 → 订单排队，会员的钱不动 ② 收款人 —— 上游无关的实体，两条线共用 GET /remit/corridors 走廊是动态的，别硬编码 GET /payee-form-schema 五个参数（含 entity_type）→ 字段表 POST /remit/payees 只做格式校验，不外呼上游 upstream_status not_submitted 是正常的 ⚠ 别看 status（恒为 active，与上游认不认无关）—— 看 upstream_status ③ 两条产品线 —— 唯一的区别是「付款主体」 极速线 express 付款主体 = 平台账户 · 无需额外开通 个人线 pobo 付款主体 = 会员自己的上游子账户 POST /remit/vp/applications 前置：L1 + L2 都通过 我方审核 + 上游开户 stage = ready 才可以下 pobo 的单 ⚠ 照 stage 判断，别自己拼「我方审核」与「上游开户」两个状态 ④ 试算与下单 POST /v1/remit/quotes 纯计算：不建单、不冻结、没有 quote_id POST /v1/remittances 钱开始动：冻结会员余额 + 你的预付 幂等键：下单沿用同一把 换新键 = 第二笔真实付款；试算则每次换新 ⑤ 订单状态 —— 15 档，终局只有 5 个 pending 你的预付不足 · 钱未动 platform_reviewing 商户单必过总后台审核 dispatching → submitting → processing completed 结算之后才置 failed / refunded 钱已退回可用 supplementing · pending_docs · needs_reconfirm 停下来等人 —— 不会自动超时退款，钱一直锁着 ⚠ dispatch_failed 不是失败终局 —— 钱还锁着，等我方人工处置 ⚠ 认不出的状态告警挂起，绝不 default 成「处理中」 ⑥ 跟踪 —— 事件只说「变了」，结论一律回查 remittance.order.* completed / failed / action_required GET /v1/remittances/{id} 按 status_version 只许向前合并 GET /v1/remittances/{id}/pending-action 停在哪一步、要补什么 ⚠ 取消只在未分发前可用（POST /v1/remittances/{id}/cancel）；分发之后上游没有撤销接口。

一笔汇款的三步


① 建收款人 ──► ② 试算 ──► ③ 下单
   payees        quotes      remittances

每一步都可能卡住，而卡住的理由不同：

步卡住的典型原因
①该走廊的字段要求没满足（字段表是动态的，见下）；五个查询参数漏了一个
②走廊当前不可用、汇率暂时取不到（那是 200 + rate_available:false，不是错误）
③你的预付不足（订单排队）、需要补件、价格变动需要重新确认

⚠ 试算不是「报价」：它不建单、不冻结、没有 quote_id，

也没有有效期。价格在下单那一刻重新算，由你设的滑点上限罩着。

两条产品线，付款主体不同

线谁在付款
极速汇款平台账户
个人汇款（POBO）该会员自己的上游子账户

其余全部共用 —— 下单、定价、冻结、分发、结算、收款人一个字都不分线。

个人汇款要先为会员开通上游子账户：POST /v1/remit/vp/applications 提交申请，我方审核并开户之后 stage 变成 ready 才能下 line: "pobo" 的单。

⚠ 申请 ≠ 开户。 开户会在上游创建一个不可撤销的实体

（上游既没有删除也没有 update/resubmit 接口），那一步在我方运营手里。

先读这几篇

一条最容易写错的

下单沿用同一把幂等键，试算每次换新。 两者方向相反：

详见幂等。