向PayPal创建订单API传递付款人信息求助（Hosted Fields SDK）

一、传递付款人姓名、邮箱信息 #

原payer对象部分字段虽已弃用，但针对Hosted Fields（卡支付场景），可通过以下方式确保付款人信息被正确纳入付款详情：

1. 创建订单API请求体中声明核心字段 #

在/v2/checkout/orders的创建请求里，同时使用payer和payment_source.card.billing_address字段传递信息，双重保障信息被PayPal系统收录：

{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "10.00"
      }
    }
  ],
  "payer": {
    "email_address": "customer@example.com",
    "name": {
      "given_name": "John",
      "surname": "Doe"
    }
  },
  "payment_source": {
    "card": {
      "billing_address": {
        "name": {
          "full_name": "John Doe"
        },
        "email_address": "customer@example.com"
      }
    }
  }
}

2. 前端Hosted Fields提交时补充信息 #

在Hosted Fields的tokenize回调中，将收集到的用户信息附加到请求参数，再传递给后端发起订单创建：

paypal.HostedFields.render({
  // 省略client-id、fields等配置项
}).then(function (hostedFieldsInstance) {
  document.querySelector('#pay-btn').addEventListener('click', function () {
    hostedFieldsInstance.tokenize({
      billingAddress: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'customer@example.com'
      }
    }).then(function (payload) {
      // 将token化数据和用户信息一同传给后端
      fetch('/create-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          nonce: payload.nonce,
          payerName: 'John Doe',
          payerEmail: 'customer@example.com'
        })
      });
    });
  });
});

二、捕获付款人是否拥有PayPal账户 #

付款人账户状态无法在订单创建阶段获取，需在订单捕获完成后从响应数据中提取：

• 捕获订单的API响应里，payer.account_status字段会返回VERIFIED（已验证PayPal账户）或UNVERIFIED；若付款人无关联PayPal账户，该字段可能不返回
• 若payment_source.card.paypal_account_id存在，说明当前使用的银行卡已绑定PayPal账户

示例捕获响应片段：

{
  "payer": {
    "email_address": "customer@example.com",
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "account_status": "VERIFIED"
  },
  "payment_source": {
    "card": {
      "paypal_account_id": "XYZ12345"
    }
  }
}

三、常见问题排查 #

• 若付款信息未出现在PayPal后台详情中，检查是否同时传递了payer和payment_source.card.billing_address字段，单一字段可能导致信息不完整
• 确保全程使用PayPal v2 Orders API，v1 API已完全弃用相关字段逻辑

内容的提问来源于stack exchange，提问作者Andy Browning