迁移到 v3

• 第 1 部分：概念。 请先阅读本部分。v3 是重塑，而不是改名：如果您把旧端点一对一地映射过来，就会与 API 处处对抗。在这里花十分钟，可以为您日后节省数天时间。
• 第 2 部分：API。 逐个端点的映射、请求示例、状态机以及迁移检查清单。

​

第 1 部分：概念

​

1.1 为什么会有 v3

​

1.2 对象模型

1. Capability 决定一切。 account 只能在 ready 状态的 capability 下开立；quote 基于 capability 定价。入驻等同于让您需要的 capability 达到 ready。
2. Task 可以附着在任何地方。 capability、account 或进行中的 transfer 都可能携带 openTaskIds。无论出现在哪里，处理循环都相同：读取 task，提交答案，等待审核，再重新读取父资源。

​

1.3 就绪状态是按 capability 计算的，而不是按客户

• 「他们能在 X 上交易吗？」变为 capability X 的 status == "ready"。
• 「他们是否需要做什么？」变为存在任何状态为 action_required 的 task（此时 capability 通常显示为 restricted，statusReason.resolution: "complete_tasks"）。
• 「我们是否在等 Swipelux？」变为 task 处于 in_review、capability 处于 pending。

​

1.4 task 循环

• 一个 task 携带 requirements[]，即具体的问询项。每项都有 task 内唯一的 requirementId、一个用于命名问询的稳定 key（例如地址证明，UI 中据此去重），以及一个类型化的 request，精确描述所需输入的类型（text、date、select、document、attestation 等）。
• 提交是受审核约束的：提交本身绝不会直接改变 capability 或 account 的状态，只有被接受才会。有一个例外：profile 类答案在提交时会直接写入客户档案（见 2.3）。提交后，请轮询 task 或其父资源。
• taskRevision（对 task revision 的回显）是并发保护：如果自您读取以来 task 已发生变化，需重新读取并重建答案。
• absence 是一等公民的答案（「我没有这个，因为……」），请使用它，而不要让 requirement 悬空。

​

1.5 资金流动

​

1.6 每个资源一台状态机

​

1.7 约定

• 使用相同的 key 但不同的请求体，在该 key 的保留期内（至少 7 天）会返回 409 idempotency_conflict，因此绝不要计划复用 key。请为每个逻辑操作生成一个新的 UUID，并与您的任务一起持久化。
• 重放同样适用于错误：如果原请求以终态 4xx 结束，同样的 key 加请求体会再次返回相同的问题响应。
• 两个使用相同 key 的并发请求：一个胜出，另一个得到 409。请在胜者落定后重试失败的那个；重放会返回原始响应。

​

1.8 黄金路径

​

第 2 部分：API

​

2.1 Customers

// POST /v3/customers        Idempotency-Key: <fresh uuid>
{
  "type": "individual",
  "externalId": "user-1042",
  "individual": {
    "firstName": "Maria",
    "lastName": "Silva",
    "birthDate": "1990-04-12",
    "nationalities": ["BR"],
    "residenceCountry": "BR",
    "email": "maria@example.com",
    "residentialAddress": {
      "streetLine1": "Av. Paulista 1000",
      "city": "Sao Paulo",
      "postalCode": "01310-100",
      "country": "BR"
    }
  },
  "financialProfile": {
    "accountPurposes": ["cross_border_remittance"],
    "sourcesOfFunds": ["salary"]
  }
}

• 创建是渐进式的：仅 { "type": "individual" } 也是有效的创建请求。缺失的信息永远不会使客户无效，它们会在稍后作为需要它的 capability 上的 intake task 呈现出来。
• 企业客户携带 business 及注册数据。v1 的股东 CRUD 被映射到 related parties，并扩展为涵盖董事、高管和所有人：可以在创建客户时以内联方式创建（每个都会获得一个稳定的 rp_ id），也可以通过专用的 related-parties 端点进行管理。
• 没有客户 status 字段，参见 1.3。
• 已存在的客户可延续使用：在 v1 或 v2 上创建的客户，可通过相同的 id 在 v3 端点上访问。v3 读取的是一个_已净化的视图_，无法通过 v3 校验的历史值会以缺失形式返回。在您的第一次 v3 写入之后，该视图将永久固化：缺失的值不会自行回来。因此请尽早补全数据，规划一次一次性的操作，用您自己的记录 PATCH 完整档案，然后再依赖 v3 读取。v1 的 metadata 属于独立的命名空间，不会被延续，请在 v3 上重新设置。
• externalId 是一等字段，在 v3 上在您的客户之间保持唯一，按环境隔离（409 duplicate_external_id）。归档客户并不会释放其 externalId，若您打算复用，请在 DELETE 之前用 PATCH 将其清空。
• DELETE 是归档级联操作（不可恢复；id 永不复用）。当存在任何未归档的 account 或进行中的 transfer 时会被阻止，返回 409 customer_has_active_resources 并附带 blockingResources[]。
• PATCH 合并规则：显式 null 会清空可空字段；数组整体替换（inline related parties 例外，按 id upsert）；metadata 的键会合并。完整 schema 与列表过滤条件详见 OpenAPI 规范。

​

2.2 /rails、/banks、application 演变为 Capabilities

• 一个 capability 由 method（ach、wire、rtp、pix、sepa、swift、spei、pse、transfers_3_0、faster_payments、sepa_instant、uaefts、card、stablecoin_transfers 等）加 accountType（pooled 或 named，非银行方式为 null）加 directions（payin 或 payout）构成。公开的 capabilityId 是限定组合（sepa_pooled、ach_named），或对 card 与 stablecoin_transfers 而言就是方式本身。
• 每次请求 capability 都会派生出一个 application，即 .../capabilities/{capabilityId}/applications 之下的按次尝试记录（还有 /{applicationId}/history），它有自己的状态（见 1.6）和 statusReason。它是一次请求的审计轨迹；日常轮询请针对 capability 本身。
• capabilities/supported 返回可用性（available、beta 或 disabled）、资格以及可选的机构。银行选择在请求时通过可选的 institutions 数组进行，不再有单独的 /banks 资源。省略该字段（或发送 []）即选中所有默认机构；isDefault: true 是针对特定客户与特定 capability 的标志，并非全局标志。非空列表将覆盖默认值；如果某个基于银行的 capability 没有适用的默认值，将返回 422 capability_institutions_required。机构 id 是不透明的，请对新的 id 保持容忍。
• stablecoin_transfers 在创建客户时被自动授予，出生即为 ready（因此永远不需要请求，也不可取消）。card 仅限个人客户。
• capability 上的 openTaskIds 是您的「下一步做什么」指针。开放即 action_required 或 in_review，且该汇总包含通过活跃依赖关系涉及到的客户级共享 task。
• cancel 仅可在 pending 或 restricted 状态下且没有阻塞资源时使用，否则返回 409 capability_not_cancelable，其问题响应体列出 blockingResources。取消后如需再次请求，需带一个新的幂等性 key 全新创建。
• 轮询 GET。 capability 状态在您读取时刷新；请轮询 GET .../capabilities/{capabilityId} 或订阅 capability.status_changed，不要缓存。
• 请求某一种方式可能会一次性使多种相关方式变为可用，请将 capability 视为一个需要整体重新读取的集合，而不是单独跟踪的一行。
• 使用 tasks-preview 可以在承诺一次请求之前先展示入驻问询。
• 验证不是一次性的：即便一个 capability 已处于 ready 状态，仍可能出现新的 task（周期性或事件驱动的再验证）。请让 task 循环在客户的整个生命周期内保持运转，而不仅仅是入驻期间。

​

2.3 文档与 KYC 演变为 Tasks 和 Submissions

• 原始文件存储：POST/GET/DELETE /v3/customers/{customerId}/documents（以及 /{documentId}），使用您的 API key 一次性上传，然后在 submission 答案中引用 document id。它取代了所有的 upload-token 和 direct-upload 上传入口。
• 全新的读取：GET /v3/tasks（商户级收件箱）、GET /v3/transfers/{transferId}/tasks、GET .../tasks/{taskId}/history、GET .../tasks/{taskId}/submissions（以及 /{submissionId}）。

// POST /v3/customers/{cus}/tasks/{task}/submissions   Idempotency-Key: <fresh uuid>
{
  "taskRevision": 3,
  "answers": [
    { "requirementId": "req_a1", "answer": { "type": "document", "documentIds": ["doc_passport1"] } },
    { "requirementId": "req_b2", "answer": { "type": "text", "value": "Import/export business" } },
    { "requirementId": "req_c3", "answer": { "type": "absence", "reason": "not_applicable" } }
  ]
}

• 答案类型：profile、text、date、single_select、multi_select、boolean、attestation、document、resource_reference、absence。每个 requirement 的 request 对象会告诉您它期望的类型。
• 一次 submission 必须回答当前轮次中每一个可作答的 requirement，且携带您所读取的准确 taskRevision。部分回答将被拒绝。
• profile 类答案直写生效：它们通过常规校验路径更新客户档案，并立即重新评估引用相同 intake 工作的每个 capability。所有 requirement 都已满足的同级 intake task 会自动关闭。
• Requirement 可能构成互斥分组（alternativeKey）：请仅在该组中提交其中之一。
• changes_requested 会递增 remediationRound 并携带 reviewFeedback。请重新读取 task，并用一个新的幂等性 key再次提交。
• 托管验证 URL 仅出现在客户维度的 task 详情（GET /v3/customers/{customerId}/tasks/{taskId}）上，且仅在会话可作答时出现；列表和 GET /v3/tasks/{taskId} 有意不含 URL。
• 服务条款也是一个 task：openTaskIds 可能包含 category: "terms_of_service" 的 task，其托管接受页以同样方式提供（仅客户维度详情）。普通 submission 不能用来接受条款，KYC 通过也永远不代表接受条款。
• Task 是按 capability 划分的，因此「相同」的问询（例如地址证明）可能每个 capability 都会出现一次。请在 UI 中按 requirement key 去重。
• 没有翻译层：向 /v1/documents 发送内容不会解锁 v3 capability。一旦客户处于 v3 上，请通过 task 驱动所有问询。

​

2.4 Accounts 与 wallets

// issued bank account (capability must be ready)
{ "origin": "issued", "type": "bank", "method": "sepa",
  "currency": "EUR", "settlement": { "accountId": "acc_wallet1" } }

// external wallet the customer already owns (replaces /import)
{ "origin": "external", "type": "wallet", "currency": "USDC",
  "network": "polygon", "details": { "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" } }

• issued 银行 account 上的 country 是可选的（按 method 有默认值）；external 银行 account 需明确提供。钱包类 account 完全不携带国家/地区。
• 在 issued 银行 account 上 settlement.accountId 是必需的：它指定接收该银行 account 存款结算资金的 issued 钱包 account。
• issued account 暴露 details（IBAN 或 routing 加 account 或 address）、带版本的 routing（存款坐标可能会更新，请始终展示最新一次读取）、fees、balances。
• 网络：polygon、ethereum、base、arbitrum、optimism、bsc、avalanche。
• capability 门槛仅适用于 issued account：在非 ready 状态的 capability 下创建将失败并返回一个 capability 类错误码，请先请求该 capability（见 2.2）。external account 不需要 capability（也不需要客户批准）；它只会经过请求 schema 与银行详情校验。
• issued 银行 account 出生时状态为 provisioning，details: null。请轮询该 account 或监听 account.status_changed 直至 ready。
• DELETE 归档，绝不硬删除。被进行中的 transfer 引用的 account 会返回 409 account_has_active_transfers。在这些 transfer 达到终态后再重试。
• v3 新增：Rules，即 issued 钱包 account 上的常设指令（POST/GET /v3/customers/{customerId}/rules、GET/PATCH/DELETE .../rules/{ruleId}），可自动将到账资金归集到另一个 account 或钱包 destination。v1 或 v2 无等效功能。

​

2.5 Recipients 与 destinations

• Recipient 即「谁」：individual（姓与名）或 business（公司名），并需要 relationship（employee、contractor、vendor、subsidiary、merchant、customer、landlord、family、other）。recipient 与 destination 只用于第三方。一笔第一方付款完全不使用 recipient：请将 quote 的 destinationId 指向该客户自己的某个 acc_ account（见 2.6）。
• Destination 即「在哪里」：按 method 分类型，sepa（iban，bic 可选）、ach 或 wire（routing 加 account）、swift（完整坐标加可选中间行）、spei（clabe）、pse、transfers_3_0（cbu）等，以及钱包 destination。每个 destination 都有自己的状态。请监听 destination.status_changed。
• 法币 destination 在创建之前需要 recipient 完整的 address（街道、城市、邮编、国家/地区）。缺失部分会以 422 recipient_address_required 失败。钱包 destination 不需要地址，但需要顶层 ownership（self_custodied，或 custodial 并附上托管机构名称）。
• 收款人姓名的准确性至关重要：接收银行按 account 的法定姓名进行匹配。请发送准确的法定姓与名或公司名，而非展示昵称。
• 各 method 的 destination 字段 schema 详见 OpenAPI 规范。

​

2.6 Quotes 与 transfers

// 1. Quote: amount on exactly one side picks mode (exact_in / exact_out).
// POST /v3/quotes            Idempotency-Key: <fresh uuid>
{
  "customerId": "cus_123",
  "capabilityId": "sepa_named",
  "in":  { "currency": "EUR", "amount": "150.00" },
  "out": { "currency": "USDC" },
  "destinationId": "acc_wallet1",   // fiat-funded: must be a customer-owned acc_ account
  "fees": { "breakdown": { "developer": { "fixed": "1.00", "bips": 50 } } }
}
// -> { mode: "exact_in", direction: "fiat_to_stablecoin", rate, fees[], expiresAt, ... }

// 2. Execute before expiresAt.
// POST /v3/transfers         Idempotency-Key: <fresh uuid>
{ "quoteId": "quo_789", "externalId": "order-991", "memo": "invoice 44" }

• destinationId 接受 acc_（客户自有 account）或 dst_（recipient destination）id。法币出资的 quote（payin）必须指向 acc_ account，指向 dst_ 总是表示 payout（否则返回 422 quote_direction_invalid）。
• quote 与 transfer 上的 externalId 是非唯一的关联引用（在读取时回显，可在列表中过滤）。按环境唯一性的规则（见 2.1）仅适用于客户的 externalId。
• 每个 quote 必须在 expiresAt 之前恰好执行一次。已过期的 quote 会以 409 quote_expired 失败；二次执行会以 409 quote_already_executed 失败（其问题响应携带已有的 transferId）。
• 尚未支持 transfer 取消：POST .../cancel 在任何状态下都会返回 409 transfer_not_cancelable。目前的 canceled 状态 transfer 来自 payin 未在出资窗口内到账，而非此端点。
• payin 从 awaiting_funds 开始：请向付款人展示 GET .../instructions，包括银行坐标加参考号或备注码（法币）或存款地址（加密货币）。参考号是匹配存款的方式。请始终展示它。
• state 加 stateDetail 提供机器可读的子状态；action_required 表示附加了一个合规 task（openTaskIds、GET .../tasks），请通过 submission 作答。
• 在 issued account 上检测到的入金存款会作为 origin: "inbound_deposit" 的 transfer 出现（而非 "quoted"）。
• 支付网络引用统一在 references 下：transactionHash、traceNumber、imad、uetr、explorerUrl、returnedTransferId。

• Transfer 不跨版本。 在 v1 或 v2 上创建的 transfer 无法通过 v3 读取。列表会略过它们，GET /v3/transfers/{transferId} 返回 404。请先切换_创建_路径，并保留 v1 的读取路径，直到那些 transfer 到达终态后再移除。
• 不支持币种兑换。 stablecoin_move 要求进出币种相同：USDC 到 USDT 会以 422 recipient_destination_invalid 失败，并附带 currency_mismatch 字段错误。两侧必须同网络，不做跨链，且钱包到钱包目前仅支持零费递送：任何平台费或开发者费不为零的 quote 会以 422 amount_not_deliverable 失败。

​

2.7 Webhooks

• GET /v3/webhooks/portal 返回一个托管管理门户的 URL，可用于投递日志、重试和手动重放。
• transfer.created 当前仍以旧的 v1 载荷形态投递（v3 信封将在 v1 webhook 下线时启用）。请将其单纯视为提示并 GET 该 transfer；不要依赖其载荷来构建业务。
• 事件是提示：收到后请 GET 该资源，并基于读取结果行动。绝不要基于事件载荷或投递顺序构建状态。投递至少一次，可能延迟或乱序。请按事件 id 去重，并使用每个列表的包含式 updatedAfter 过滤器补齐遗漏的事件。
• 请订阅 api.deprecation，这是版本下线的机器通道。
• 目前没有 task.* 事件：提交之后请轮询 task 或其父资源。

​

2.8 沙箱

​

2.9 没有 v3 替代品的遗留端点

​

2.10 建议的迁移顺序

​

2.11 常见陷阱清单

• 每个逻辑操作使用新的 UUID，与您的任务一起持久化并在重试时复用；绝不要用相同的 key 搭配已变更的请求体（409 idempotency_conflict）。沙箱端点无需该请求头。
• 在进行任何其他 v3 写入之前先补全已存在的客户档案（PATCH 完整档案，重新设置 metadata，它不会被延续），第一次 v3 写入会使净化视图永久固化。
• externalId 按环境唯一，归档并不释放它，若您计划复用，请在 DELETE 前用 PATCH 清空。
• 没有客户 status 字段，请按 capability 推导就绪状态。
• action_required 与 in_review 都表示存在一个开放的 task。
• submission 受审核约束（提交并不等于解锁），且必须以准确的 taskRevision 回答每一个可作答的 requirement。不匹配时请重新读取并重建。
• 没有 task.* webhook，每次提交后请轮询 task（或其父资源）。
• changes_requested 的重试意味着重新读取 task、给出新答案，并使用新的幂等性 key。
• 向 /v1/documents 发送内容永远不会解锁 v3 capability，一旦客户切到 task 上，请通过 task 驱动每一个问询。
• 即便一个 capability 已是 ready，仍可能出现新的 task，请在入驻之后依然保持 task 循环运转，而不仅仅是在入驻期间。
• capability 的 cancel 仅可在 pending 或 restricted 且无阻塞资源时使用（409 capability_not_cancelable）；取消后如需再次请求，需用新的幂等性 key 全新创建。
• 在其下开立 account 或对其报价之前，capability 必须处于 ready。
• quote 只能在一侧提供金额；没有方向字段；必须在 expiresAt 之前恰好执行一次（409 quote_expired 或 409 quote_already_executed）。
• 稳定币划转仅支持同币种、同网络（USDC 到 USDT 会 422 失败）；钱包到钱包目前仅支持零费递送。
• DELETE 归档，绝不硬删除。account 删除会被进行中的 transfer 阻止（409 account_has_active_transfers）；客户删除还会被任何未归档的 account 阻止（409 customer_has_active_resources，blockingResources[] 会列出这些资源）。
• v1 或 v2 的 transfer 对 v3 读取不可见（列表略过、GET 返回 404），请双读至清空，然后再移除旧路径。
• 存款 routing 与 instructions 可能会变化，请始终展示最新一次 GET，并始终展示参考号。
• webhook 是提示；GET 才是事实，请按事件 id 去重，并用 updatedAfter 找回遗漏事件。

​

下一步