Zen Cart 整合 PayPal IPN 取得聯絡電話完整修改教學

需求背景

PayPal IPN 回傳參數包含 `contact_phone` (買家預留電話)，但 Zen Cart 內建 PayPal 模組未接收此欄位。需修改資料表、IPN 處理函式、後台顯示三處才能完整保存並顯示電話。

修改步驟

1. 資料表新增欄位

ALTER TABLE `paypal` 
ADD `contact_phone` VARCHAR(50) NULL COMMENT '買家聯絡電話';

2. 修改 IPN 處理函式

檔案：`includes/modules/payment/paypal/paypal_functions.php`

尋找 `ipn_create_order_array()` 函式，在回傳陣列中新增：

// 原有程式碼中新增此行
'contact_phone' => $_POST['contact_phone'],

完整函式範例：

function ipn_create_order_array($new_order_id, $txn_type) {
    $sql_data_array = array(
        'order_id' => $new_order_id,
        'txn_type' => $txn_type,
        'module_name' => 'paypal (ipn-handler)',
        'module_mode' => 'IPN',
        'reason_code' => $_POST['reason_code'],
        'payment_type' => $_POST['payment_type'],
        'payment_status' => $_POST['payment_status'],
        'pending_reason' => $_POST['pending_reason'],
        'invoice' => $_POST['invoice'],
        'mc_currency' => $_POST['mc_currency'],
        'first_name' => $_POST['first_name'],
        'last_name' => $_POST['last_name'],
        'payer_business_name' => $_POST['payer_business_name'],
        'contact_phone' => $_POST['contact_phone'],  // 新增
        'address_name' => $_POST['address_name'],
        'address_street' => $_POST['address_street'],
        'address_city' => $_POST['address_city'],
        'address_state' => $_POST['address_state'],
        'address_zip' => $_POST['address_zip'],
        'address_country' => $_POST['address_country'],
        'address_status' => $_POST['address_status'],
        'payer_email' => $_POST['payer_email'],
        'payer_id' => $_POST['payer_id'],
        'payer_status' => $_POST['payer_status'],
        'payment_date' => datetime_to_sql_format($_POST['payment_date']),
        'business' => $_POST['business'],
        'receiver_email' => $_POST['receiver_email'],
        'receiver_id' => $_POST['receiver_id'],
        'txn_id' => $_POST['txn_id'],
        'parent_txn_id' => $_POST['parent_txn_id'],
        'num_cart_items' => $_POST['num_cart_items'],
        'mc_gross' => $_POST['mc_gross'],
        'mc_fee' => $_POST['mc_fee'],
        'settle_amount' => $_POST['settle_amount'],
        'settle_currency' => $_POST['settle_currency'],
        'exchange_rate' => $_POST['exchange_rate'],
        'notify_version' => $_POST['notify_version'],
        'verify_sign' => $_POST['verify_sign'],
        'date_added' => 'now()',
        'memo' => $_POST['memo']
    );
    return $sql_data_array;
}

3. 後台訂單頁面顯示電話

檔案：`includes/modules/payment/paypal/paypal_admin_notification.php`

在適當位置 (如地址資訊後) 新增：

$output .= '<tr><td class="main">Contact Phone:</td>';
$output .= '<td class="main">' . $ipn->fields['contact_phone'] . '</td></tr>';

重要前提條件

PayPal 帳戶必須啟用「要求買家提供電話號碼」設定，否則 IPN 不會回傳 `contact_phone` 參數 (預設為空)。

設定路徑：PayPal 商家後台 → 設定 → 付款偏好設定 → 聯絡電話 → 「必填」或「選填」

測試驗證流程

1. 沙箱環境建立測試帳號，啟用電話要求
2. 模擬付款流程，確認 IPN 回傳包含 `contact_phone`
3. 查看 `paypal` 資料表該筆記錄 `contact_phone` 欄位已寫入
4. 後台訂單詳情頁面確認電話正確顯示

擴充建議

• 同步儲存至 `orders` 主表 `customers_telephone` 欄位，統一客戶資料
• 加入電話格式驗證/正規化 (國碼、區碼分離)
• 後台訂單列表頁面加入電話欄位可搜尋/排序
• 匯出訂單報表 (CSV/Excel) 包含聯絡電話