如何使用PayPal Checkout PHP SDK获取付款人账单地址与收货地址

默认情况下PayPal不会返回付款人账单地址等敏感信息，你需要按以下步骤调整配置即可获取两类地址：

步骤1：创建订单时配置地址获取权限 #

创建订单的请求中新增对应参数，告知PayPal需要返回地址字段，参考代码如下：

use PayPalCheckoutSdk\Orders\OrdersCreateRequest;

$request = new OrdersCreateRequest();
$request->prefer('return=representation');
$request->body = [
    "intent" => "CAPTURE",
    "purchase_units" => [[
        "amount" => [
            "currency_code" => "你的币种",
            "value" => "订单金额"
        ]
    ]],
    "application_context" => [
        "return_url" => "你的支付成功回调地址",
        "cancel_url" => "你的支付取消跳转地址",
        // 收货地址规则配置：
        // GET_FROM_FILE = 取用用户PayPal账户内已保存的收货地址
        // SET_PROVIDED_ADDRESS = 要求用户手动填写收货地址
        // NO_SHIPPING = 不需要收货地址（虚拟商品场景）
        "shipping_preference" => "GET_FROM_FILE"
    ],
    // 新增：要求返回付款人账单地址
    "payment_source" => [
        "paypal" => [
            "experience_context" => [
                "payment_method_preference" => "IMMEDIATE_PAYMENT_REQUIRED",
            ]
        ]
    ],
    // 新增：指定响应返回字段，确保地址相关字段被包含
    "fields" => "payer,payment_source,purchase_units"
];

// 后续执行创建订单请求逻辑和原有流程一致
$response = $client->execute($request);

步骤2：支付完成后解析地址信息 #

订单捕获完成后，直接从返回的订单结果中提取对应地址字段即可，参考代码如下：

use PayPalCheckoutSdk\Orders\OrdersCaptureRequest;

$orderId = "已创建的订单ID";
$captureRequest = new OrdersCaptureRequest($orderId);
$captureRequest->prefer('return=representation');
$response = $client->execute($captureRequest);
$orderResult = $response->result;

// 提取收货地址
$shippingAddress = $orderResult->purchase_units[0]->shipping->address ?? null;
if ($shippingAddress) {
    $recipientName = $orderResult->purchase_units[0]->shipping->name->full_name ?? '';
    $shippingStreet = $shippingAddress->address_line_1;
    $shippingStreet2 = $shippingAddress->address_line_2 ?? '';
    $shippingCity = $shippingAddress->admin_area_2; // 城市
    $shippingState = $shippingAddress->admin_area_1; // 省份/州
    $shippingPostalCode = $shippingAddress->postal_code; // 邮编
    $shippingCountryCode = $shippingAddress->country_code; // 国家编码
}

// 提取账单地址
$billingAddress = $orderResult->payment_source->paypal->billing_address ?? $orderResult->payer->address ?? null;
if ($billingAddress) {
    $payerFullName = ($orderResult->payer->name->given_name ?? '') . ' ' . ($orderResult->payer->name->surname ?? '');
    $billingStreet = $billingAddress->address_line_1;
    $billingStreet2 = $billingAddress->address_line_2 ?? '';
    $billingCity = $billingAddress->admin_area_2;
    $billingState = $billingAddress->admin_area_1;
    $billingPostalCode = $billingAddress->postal_code;
    $billingCountryCode = $billingAddress->country_code;
}

常见问题排查 #

• 沙箱环境测试时需要先给测试PayPal账户手动完善账单、收货地址，否则对应字段会返回空
• 部分地区的个人PayPal账户如果没有主动填写账单地址，会出现账单地址字段为空的情况，业务侧需要做好兼容
• 建议升级到Checkout PHP SDK最新版本，旧版本可能存在字段映射不全的问题

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