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
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。
BANK_EUR 仅用于
EUR Banking 操作,不用于客户 payout。
这道来源门控上线前创建的 payout hold 属于 grandfathered 记录:继续使用
原有 dispatch 与 reconciliation 流程,不会被追溯拒绝。
幂等与来源选择边界情况
来源 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。
错误
BIC 是必填的吗?
BIC 是必填的吗?
不是。IBAN 必填,BIC 可选。
可以通过该方法发送 USD 吗?
可以通过该方法发送 USD 吗?
不可以。
sepa 仅支持 EUR,并在派发前拒绝其他币种。Return 会创建新的 webhook 吗?
Return 会创建新的 webhook 吗?
不会。
payout_status_changed 携带 status_code: reversed 和正常退款结果。