Skip to main content
当收款人通过 sepa 方法接收 EUR 时使用本指南。目录保持 provider-agnostic:它公开国家、EUR 和 sepa,账户扣款则沿用普通 payout 定价和幂等合约。

路由走廊

V1 只注册一个路由走廊:country=EU、currency=EUR、 method=sepa。EU 是欧洲的目录路由代码,不是受益人的实际国家。 实际国家取自规范化 IBAN 的前两个字母;IBAN 必须属于支持 SEPA Instant 的国家集合。 GB 不在 SEPA Instant V1:英国 IBAN 会因为 sepaInstReachable=false 在派发前快速返回 HTTP 400。英国的 SEPA Credit Transfer 属于未来的独立范围。走廊启用时, GET /v1/payouts/methods 返回唯一的 EU/EUR/sepa 行。

Beneficiary 合约

beneficiary 必须包含: 整笔操作使用一个幂等键。description 在 API 边界可选;如果发送, adapter 会先为 SEPA wire 规则规范化:折叠变音符号,应用下方的欧洲字符 映射,结果必须符合 provider 的 corporate charset,并限制为 140 个 Unicode code points。折叠后仍含有不允许字符时,创建返回 400 invalid_payload。省略时,adapter 会生成有效的内部 SEPA 描述。 姓名在 charset 校验前使用相同的确定性折叠: 个人必须解析出名字和姓氏。V1 不支持以单名作为 individual 付款; 请发送 given_name 与 first_surname,或发送包含多个词的 name。

创建 payout

响应沿用普通 payout 资源:
Provider create 与显式 approve 是内部步骤。该 payout 为 processing 时不要创建替代操作;客户端重试必须使用同一个幂等键。

EUR 资金来源与付款人身份

对于客户账户,每笔 sepa payout 都必须解析到一个已分配且 active、 purpose 为 funding_usdt 的虚拟 IBAN。这是客户 payout 的入金用途;EUR Banking 提现使用独立的 banking_eur 用途。 需要选择某个具体的 active funding_usdt 虚拟 IBAN 时,在顶层发送 source_virtual_iban_id:
  • 只有一个 active 的 funding_usdt 虚拟 IBAN 时,省略该字段会确定性地 选择它。
  • 没有 active 来源时返回 422 funding_account_required。
  • 有多个 active 来源时,在发送所选 UUID 前返回 422 ambiguous_source_viban。
  • 明确指定的 UUID 不属于该账户或不是 active 时,返回 404 not_found 或 422 funding_account_required。
入金用途、如何申请和读取虚拟 IBAN,以及付款人身份如何写入与修复,全部 集中在一处:见欧元:入金地址与欧元银行,集中在一处。本页仅保留 payout 合约。 此流程没有按 vIBAN 设置的金额上限。Payout 从账户正常的结算余额扣款 (settlement asset:USD 为主资产);BANK_EUR 仅用于 EUR Banking 操作,不用于客户 payout。
这道来源门控上线前创建的 payout hold 属于 grandfathered 记录:继续使用 原有 dispatch 与 reconciliation 流程,不会被追溯拒绝。
来源检查在任何扣款或调用 provider 前执行。若来源查询暂时不可用,请使用 相同的幂等键重试。

幂等与来源选择边界情况

来源 vIBAN 属于 payout 意图的一部分。如果两次顺序请求之间 active vIBAN 集合发生变化,使用同一幂等键重试仍返回原 payout。如果并发请求观察到 不同的来源集合,则返回 409 idempotency_conflict;两种结果都安全, 不会创建第二笔扣款。不要使用新键猜测结果。 同一幂等键不能同时表示默认来源和明确的 source_virtual_iban_id: 这种 replay 返回 409 idempotency_conflict。严格比较可以避免静默更换 付款账户。

状态与 return

订阅 payout_status_changed。SEPA 不新增 webhook;provider callback 经过校验后进入同一个 payout 状态 pipeline。

错误

不是。IBAN 必填,BIC 可选。
不可以。sepa 仅支持 EUR,并在派发前拒绝其他币种。
不会。payout_status_changed 携带 status_code: reversed 和正常退款结果。
最后修改于 2026年10月4日