整體流程
- 商戶端組裝請求參數 → 表單 POST 至 99Bill 閘道。
- 用戶在 99Bill 頁面完成付款。
- 99Bill 異步通知 (背景通知
bgUrl) + 同步跳轉 (頁面跳轉 redirectUrl) 回商戶系統。
- 商戶驗證簽名、更新訂單狀態、回應 99Bill。
1. 請求模型 (BillRequest)
<?php
class BillRequest {
public $merchantAcctId = '1001011111101'; // 商戶號
public $bgUrl = 'https://myshop.com/pay/99bill/notify'; // 異步通知地址
public $orderId; // 訂單號 (商戶唯一)
public $orderAmount; // 金額 (分)
public $orderTime; // 訂單時間 YmdHis
public $payerName = '';
public $payerContactType = '';
public $payerContact = '';
public $productName = '';
public $productNum = 1;
public $productId = '';
public $productDesc = '';
public $pageUrl = 'https://myshop.com/pay/99bill/return'; // 同步跳轉
public $version = 'v2.0';
public $language = '1';
public $signType = '4'; // PKI
public $payType = '00';
public $bankId = '';
public $ext1 = '';
public $ext2 = '';
public $signMsg; // 簽名 (由私鑰產生)
public function __construct(array $order) {
$this->orderId = 'TOLPC' . sprintf('%09d', $order['orderId']);
$this->orderAmount = $order['orderAmount']; // 分
$this->orderTime = date('YmdHis', $order['orderTime']);
$this->productName = $order['productName'] ?? '商品';
// ... 其他欄位映射
// 產生簽名
$this->signMsg = $this->generateSignMsg();
}
private function generateSignMsg() {
// 依 99Bill 規範拼接字串 (參考文件順序)
$str = $this->merchantAcctId . $this->version . $this->language . $this->signType
. $this->payType . $this->bankId . $this->orderId . $this->orderTime
. $this->orderAmount . $this->productName . $this->productNum
. $this->productId . $this->productDesc . $this->pageUrl . $this->bgUrl
. $this->payerName . $this->payerContactType . $this->payerContact
. $this->ext1 . $this->ext2;
// 私鑰簽名 (SHA1withRSA)
$privKey = openssl_pkey_get_private(file_get_contents('private.pem'), 'passphrase');
openssl_sign($str, $signature, $privKey, OPENSSL_ALGO_SHA1);
openssl_free_key($privKey);
return base64_encode($signature);
}
}
?>
2. 前端提交表單 (View)
<form name="kqPay" action="https://www.99bill.com/gateway/recvMerchantInfoAction.htm" method="post">
<?php foreach ((array)$BillRequest as $k => $v): ?>
<input type="hidden" name="<?= $k ?>" value="<?= htmlspecialchars($v) ?>">
<?php endforeach; ?>
<input type="submit" value="前往付款">
</form>
<script>document.forms.kqPay.submit();</script>
3. 異步通知處理 (bgUrl)
<?php
// notify.php
require_once 'BillResponse.php';
$response = new BillResponse($_POST); // $_POST 含 99Bill 回傳所有欄位
// 1. 驗證簽名
if (!$response->checkSignMsg()) {
error_log('99Bill notify: 簽名驗證失敗');
exit('fail');
}
// 2. 判斷支付結果
if ($response->isSuccess()) {
// 更新訂單狀態:已付款
// 注意:需防重複處理 (檢查訂單當前狀態、幂等性)
updateOrderStatus($response->orderId, 'paid', $response->dealTime);
// 回應 99Bill (XML 格式)
exit("<result>1</result><redirecturl>https://myshop.com/pay/success</redirecturl>");
} else {
// 支付失敗
updateOrderStatus($response->orderId, 'failed', $response->dealTime);
exit("<result>1</result><redirecturl>https://myshop.com/pay/fail</redirecturl>");
}
?>
4. 回應模型 (BillResponse) - 核心驗簽邏輯
<?php
class BillResponse {
public $merchantAcctId, $version, $language, $signType, $payType, $bankId;
public $orderId, $orderTime, $orderAmount, $dealId, $bankDealId, $dealTime;
public $payAmount, $fee, $ext1, $ext2, $payResult, $errCode, $signMsg;
public $checkSignMsg = false;
public function __construct(array $data) {
foreach ($data as $k => $v) {
if (property_exists($this, $k)) $this->$k = $v;
}
$this->checkSignMsg = $this->verifySign();
}
private function verifySign() {
// 依文件順序拼接待驗證字串 (不含 signMsg)
$str = $this->merchantAcctId . $this->version . $this->language . $this->signType
. $this->payType . $this->bankId . $this->orderId . $this->orderTime
. $this->orderAmount . $this->dealId . $this->bankDealId . $this->dealTime
. $this->payAmount . $this->fee . $this->ext1 . $this->ext2 . $this->payResult . $this->errCode;
$pubKey = openssl_pkey_get_public(file_get_contents('99bill_public.pem'));
$ok = openssl_verify($str, base64_decode($this->signMsg), $pubKey, OPENSSL_ALGO_SHA1);
openssl_free_key($pubKey);
return $ok === 1;
}
public function isSuccess() {
return $this->payResult === '10'; // 10=成功, 11=失敗
}
}
?>
關鍵安全提醒
- 簽名驗證不可省略,防止偽造通知修改訂單狀態。
- 異步通知可能重複,資料庫更新需冪等 (判斷狀態、唯一索引)。
- 金額核對:以分為單位,確認
payAmount == orderAmount。
- 測試環境:使用 Sandbox 端點與測試商戶號、測試憑證。