如何用Stripe API和PHP为客户支付源正确添加账单地址信息

报错根因 #

当前代码触发parameter_unknown - billing_address报错，核心是参数结构不符合Stripe接口规范：Stripe的老式Card类支付源更新接口，从设计上就没有提供顶层billing_address参数来接收嵌套的地址对象，属于无效参数，自然会被接口拒绝。

对应参数映射规则 #

针对老式Card类支付源，账单地址的字段是和卡片其他参数平级直接传递的，和你表单收集的内容对应关系为：

• 表单收集的详细地址 对应接口参数 address_line1
• 表单收集的城市 对应接口参数 address_city
• 表单收集的省/州 对应接口参数 address_state
• 表单收集的邮编 对应接口参数 address_zip
• 若有收集国家信息，可对应参数 address_country 同步传递

修正后的可运行代码 #

if ($_SERVER["REQUEST_METHOD"] == "POST") {
  // 获取表单提交的账单地址数据
  $address = stripslashes($_REQUEST['address']);
  $city    = stripslashes($_REQUEST['city']);
  $state   = stripslashes($_REQUEST['state']);
  $zip     = stripslashes($_REQUEST['zip_code']);

  \Stripe\Stripe::setApiKey("MY-API-KEY");
      
  // 更新客户名下指定支付源的账单信息
  $customer = \Stripe\Customer::updateSource(
    $ss_customer_id,
    $ss_card_id,
    [
      'address_line1' => $address,
      'address_city'  => $city,
      'address_state'  => $state,
      'address_zip'    => $zip
    ]
  );
}

常见适配场景说明 #

• 如果当前对接的是Stripe老式Card类型的支付源（通过Customer::createSource创建、可直接通过Customer::updateSource更新的源），用上面代码里的平级address_*参数即可正常生效。
• 如果对接的是Stripe新版PaymentMethod类型的支付源，不能继续使用Customer::updateSource方法，需要改用\Stripe\PaymentMethod::update接口，传入对应的PaymentMethod ID，此时的地址参数结构为嵌套形式，具体写法为：

  [
    'billing_details' => [
      'address' => [
        'line1' => $address,
        'city' => $city,
        'state' => $state,
        'postal_code' => $zip
      ]
    ]
  ]
  

  这类源的参数结构和平级的老式Card源有区别，不要混用。
• 地址字段非强制全传，可根据实际收集的内容传递，但字段不完整可能会触发Stripe的地址匹配校验提示。

内容的提问来源于stack exchange，提问作者Nicks Tech Corporation