收款人建档

收款人字段表是动态的 —— 按走廊问一次再渲染表单，别照文档写死。

先问字段表，再渲染表单


GET /v1/remit/payee-form-schema
    ?country_code=GB&currency=GBP&payment_method=LOCAL
    &clearing_system=FASTER%20PAYMENTS&entity_type=INDIVIDUAL

五个参数都必填 —— 包括 entity_type，本页此前漏写了它。前三个与 entity_type 我方会转大写；clearing_system 大小写原样传。

entity_type 取值 INDIVIDUAL / COMPANY。

⚠ 漏掉任一个参数拿到的是 400 invalid_fields，出参的 fields 里会

点名缺了哪个键，照它补上即可。

（2026-08-13 之前漏参数拿到的是 corridor_not_supported ——

「这条走廊不可用，请换一条走廊或支付方式」。而走廊是好的，

换遍所有走廊也不会成功。现在「参数不全」与「走廊不可用」是两个码。）

返回的是按这条走廊求值出来的字段清单，不是一张固定表：

走廊	要什么
GB / GBP / FASTER PAYMENTS	IBAN + 6 位 sort code
US / USD / ACH	账号 + ABA
SG / SGD / PAYNOW	连姓名和地址都免填（上游明写不需要）

拿这份契约渲染表单、拿它的 pattern / max_length / required 做前端校验、提交时把用户填的原样放进 POST /v1/remit/payees 的 fields。我方加一个国家、加一条清算网络、收紧一条格式，你一行不用改。

三个不能望文生义的字段属性

required: false 不等于「可有可无」。 我方只下发「必填、或参与指纹、或文档措辞模糊」的字段 —— 表单上多一个永远用不到的框，用户只会以为自己漏填了。所以选填字段多半带 in_fingerprint: true：填与不填决定这次是新建一个收款人，还是关联到一个已有的。

bind：这个字段被填写时要一起提交的固定值。 例如 GBP + FASTER PAYMENTS的 6 位 sort code 是 bank_details.routing_code_value1，同时必须带bank_details.routing_code_type1: sort_code。

⚠ 路由码类型由走廊唯一决定，不要让用户选。给他一个下拉就是给了一个

改路由类型的口子 —— 而上游对这一维根本不校验，错的类型会让钱走错清算轨道。

pending_confirm 有值 = 上游文档措辞模糊，我方按更宽松处理。可以提示「选填」，但仍要允许提交。照文档补校验会当天挡住合法用户。

⚠ 入参是 snake_case（country_code），出参的 corridor 对象是 camelCase

（countryCode）。别把出参直接回灌进入参。

⚠ 不要照着示例写死一张表单。 写死的表现是：某条走廊多要了一个字段之后，

你的用户填完提交，拿到一个他看不懂的校验错误 —— 而那发生在他投入最多之后。

建档


POST /v1/remit/payees

我方在这一步只做格式校验。真正的上游建档发生在分发那一步 ——也就是钱已经从会员账上冻走之后。

⚠ 这是这条线上最贵的一个失败：本地漏校一条格式，代价不是一次 400，

而是钱已经冻进锁定桶之后才发现这个收款人建不出来 —— 那时订单卡在

分发中、收款人被上游钉成失败终态，只能人工处置。

所以字段表要按走廊问，别猜、别缓存过夜、别照示例写死。

校验


POST /v1/remit/payees/{id}/verify

对支持的走廊做一次账户名核对（收款账号与户名对不对得上）。结果有三种：一致、不一致、该走廊不支持核对。

第三种不是失败。把它当失败拦住用户的表现是：不支持核对的走廊上一个人都汇不出去。

「编辑收款人」= 重命名


PATCH /v1/remit/payees/{id}   { "nickname": "房东", "favorite": true }

收款人主体（银行、账号、户名）是平台级共享实体，主键是这几项算出来的指纹 —— 改账号就是另一个收款人，原地改会让所有关联到它的会员、以及已完成订单里的收款方快照跟着变。

所以银行信息不提供编辑：要改就新建一条。能改的只有落在关联表上的私有昵称与收藏位。请把「编辑」呈现成「重命名」，别在界面上摆一个改不了的表单。

两项都可选；一个都不传是 400（那多半是键名拼错了，静默 200 会让你以为改成功了）。

两个 status，别看错那一个

出参里有两个状态字段，它们回答的是完全不同的问题：

字段	回答的问题	取值
`status`	我方本地这条收款人启没启用	`active` / `blocked`
`upstream_status`	上游认不认这条收款人	见下表

⚠⚠ status 恒为 active，它不代表这条收款人能用。

新建的收款人一律 active —— 因为我方本地的枚举只有启用/停用两个值。

照着它判「可以下单」的表现是：钱冻进锁定桶之后才失败。

要判能不能用，看 upstream_status。

`upstream_status` 的取值

值	含义	你该做什么
`not_submitted`	还没往上游送过。这是新建收款人的正常状态	照常下单；想提前送就调 `verify`
`pending`	已送，上游还没答复	等
`active`	上游确认可用	照常下单
`failed`	上游拒了	别下单 —— 换一条收款人或改资料
`deleted`	上游那一侧已删除	重新建档
`unknown`	我方此刻答不出	不是收款人的问题 —— 见下

⚠ not_submitted 不是异常。 我方在建档那一刻一个上游接口都不调

（收款人是上游无关的实体）。别把它显示成「验证失败」。

想提前送一次：POST /v1/remit/payees/{id}/verify。

⚠ unknown 与 not_submitted 不是一回事，别合并。

unknown 的意思是「这条线现在没有可用的上游」（该线没有启用的供应商，

或这个会员还没有个人汇款子账户）。处置是先把那条线开通，

而不是让用户去改收款人资料。

`name_mismatch`

同一个银行账户此前登记过不同的户名时是 true。

它不阻止下单 —— 但你的风控应该看它。这是我方能提供的、最接近「这个账户可能不是他本人的」的信号。