会员是你的用户。我方给他一个身份与一套账本，其余的（定价、限额、风控）都是你的事。

会员建档与生命周期

会员是你的

我方在会员这件事上只做两件：给他一个在你这个商户下唯一的身份，以及一套按资产记账的账本。

不做的事，因为那是你的生意：

• 向他收多少钱（你的零售定价）
• 他单笔能做多大（你的会员限额）
• 他的风险怎么管（你的会员风控）

想先看整条链路（建会员 → 实名 → 放行）长什么样？

看创建会员与 KYC 全流程那张图。

建档

POST /v1/members
{ "external_member_id": "u_88123", "email": "…" }

external_member_id 是你系统里的用户 ID。我方用它做幂等：同一个值再建一次返回 200 与原来那个会员，不会新建，也不会发member.created 事件。

⚠ 幂等命中返回 200、首次创建返回 201。靠状态码分辨「是不是新用户」是

可靠的；靠 member.created 事件分辨也是可靠的。别靠两者的组合猜 ——

事件是异步的。

标识符：两个都能用，但别混

哪个地方收哪个：

⚠ 前缀不要剥。 把 mem_ 去掉存进你自己的库、再拿裸 UUID 来调，

会被当成 external_member_id 去查 —— 404 member_not_found，

一个看起来像「这个会员不存在」而实际是「你用错标识了」的错误。

⚠ 判据是前缀二选一，没有回落。 所以**别用 mem_ 开头的

external_member_id** —— 那个会员会在上面几处永久 404。

换绑邮箱：email-sessions

POST /v1/members/{id}/email-sessions   → { "hosted_url": "…" }

把链接交给终端用户。他在我方页面上填新地址，我方向新旧两个地址各发一个验证码，两个都填对才换。

为什么不是一个 PATCH 字段 —— 邮箱是这个会员在我方唯一的强认证因子：他没有我方的密码（建号时写的是随机占位串）、没有通行密钥、没有受信设备。一个能直接改邮箱的写口，意味着你可以把任意会员的因子改指到你自己的信箱，之后随时替他过强认证：拿走卡密、新增提现地址。那是一条完整的账号接管路径。

两道码各自证明一件事：

⚠ 换绑成功会吊销该会员在我方的全部会话、受信设备与通行密钥。对你没有直接影响（你的会员本来就不用我方的会话），但你那侧缓存过他的邮箱就要刷新。

uid 是会员号，建号那一刻就有

POST /v1/members 的响应里 uid 是九位数字 —— 站内转账的缺省 recipient_type 就是它。

⚠ 2026-08-14 之前这一位恒为空串（分配那一步只在会员端的注册里）。

表现不是报错而是钝刀：你按缺省值发起转账，稳定拿到「查无此人」；

运营按会员号也搜不到这个人。已修，新建的会员都有。

停用与恢复

POST /v1/members/{id}/suspend   { "suspended": true }

这一位只影响该会员在你这边的可用性。停用与恢复共用一条事件（member.suspended），方向靠 data.status 区分。

⚠ 这条事件会来第二次（停用 → 恢复 → 再停用），且 status_version 恒为 0。

别写「version 相等就跳过」—— 那会让恢复那条被丢掉，你这边的人永远解不开。

⚠⚠ status_version 恒为 0 的事件不止这一条。 会重复到达的还有

kyc.result.updated（驳回 → 补件 → 通过，一路都发）与理财派息一类。

对它们写「version 不大于当前值就跳过」的后果分别是：

实名结论永远停在第一条、第二天起所有派息全丢。

判据要按事件类型分：带对象状态的（订单、卡片）才用 status_version

向前合并；恒为 0 的一律按 created_at 顺序处理。

哪些恒为 0 见 Webhook 概览。

平台级封禁是另一套，你看不到。 会员触犯平台底线时我方会停掉他，那与你这一位无关，也不会因为你恢复而解除。

相关端点

• POST /v1/members
• GET /v1/members
• POST /v1/members/{id}/suspend
• POST /v1/members/{id}/sessions/revoke