Stripe集成：创建外部账户后用Token发起Payout提示无效的原因与解决

一、错误原因分析 #

• Token类型不匹配：你生成的可能是用于付款的普通token（如银行卡付款token），而非专门用于接收转账的外部账户token。Stripe提现只认关联到账户的外部账户ID，或创建时返回的专属外部账户token，普通付款token无法用于提现。
• Token已过期：Stripe的所有token都有有效期，外部账户token创建后如果短时间内没使用，会自动失效，得重新生成。
• API环境不匹配：测试环境（用sk_test_密钥）生成的token，拿到生产环境（用sk_live_密钥）用肯定无效，反之亦然。
• 外部账户未验证：部分地区的银行账户需要完成微存款验证，没通过验证的账户对应的token根本没法用来提现。

二、确保外部账户可用于提现的步骤 #

1. 生成正确的外部账户token
   创建外部账户时，调用POST /v1/tokens接口，必须指定bank_account或card参数（对应账户类型），确保返回的token类型是bank_account或card。示例请求：

   curl https://api.stripe.com/v1/tokens \
     -u sk_test_你的密钥: \
     -d "bank_account[country]"="US" \
     -d "bank_account[currency]"="usd" \
     -d "bank_account[routing_number]"="110000000" \
     -d "bank_account[account_number]"="000123456789"
   

2. 立即关联账户并使用账户ID
   拿到token后马上调用POST /v1/accounts/{账户ID}/external_accounts，把token关联到你的Stripe账户。关联成功后会返回一个external_account对象，后续提现直接用这个对象的id（比如ba_xxxxxx），别再用原始token了。
3. 完成账户验证流程
   • 美国银行账户：Stripe会打两笔小额存款（0.01-0.99美元）到该账户，收到后调用POST /v1/accounts/{账户ID}/external_accounts/{外部账户ID}/verify提交金额完成验证。
   • 其他地区账户：按Stripe要求上传身份、地址等验证材料，确保账户状态为valid。
4. 核对API环境
   测试用测试密钥，生产用生产密钥，全程保持一致，别混着用。

三、管理Stripe外部账户的最佳实践 #

• 存外部账户ID，别存token：token是一次性的，关联后就没用了，直接存返回的external_account的id，后续所有操作都用这个ID，彻底避免token过期问题。
• 定期检查账户状态：调用GET /v1/accounts/{账户ID}/external_accounts查询账户状态，要是看到status是inactive或者verification_required，赶紧处理验证或更新信息。
• 先测再批量操作：批量提现前，先用一个账户走一遍完整流程，确认没问题再批量执行，避免大规模失败。
• 加元数据备注：关联外部账户时，用metadata字段存用户ID、账户备注等信息，后面排查问题时能快速定位。
• 监控Webhook事件：订阅external_account.updated、payout.failed这些事件，实时接收账户状态变化和提现失败通知，第一时间处理异常。

内容的提问来源于stack exchange，提问作者Theja Krishna