PHP(Laravel)站点集成QuickBooks支付方式并生成可用支付链接咨询

1 发票支付链接访问错误核心原因 #

你遇到的链接跳转错误90%是以下原因导致：

• 未开通QuickBooks Payments服务：该服务是在线支付功能的前提，未开通的账户即使通过API创建发票，生成的支付链接也会直接报错
• 错误使用API返回的InvoiceLink字段：该字段是商户后台的发票编辑链接，并非面向客户的支付链接，直接访问自然触发权限错误
• API创建发票时漏加参数：必须在发票创建请求中把AllowOnlinePayment设置为true，否则生成的发票默认不支持在线支付
• 环境不匹配：沙箱环境生成的支付链接只能用沙箱测试账户访问，生产环境的链接只能在生产环境使用，环境混用会直接报错

2 完整实现流程 #

2.1 前置准备 #

• 开通QuickBooks账户并激活QuickBooks Payments功能
• 在QuickBooks开发者后台创建应用，获取Client ID、Client Secret，申请com.intuit.quickbooks.accounting权限
• 安装官方PHP SDK，命令如下：
  composer require quickbooks/v3-php-sdk

2.2 创建带支付链接的发票代码示例 #

// 初始化QuickBooks客户端
$service = new QuickBooksAPI\Service\InvoiceService();
$service->setAuthSettings($access_token, $realm_id, $environment); // environment可选值为sandbox/production

// 构造发票对象
$invoice = new QuickBooksAPI\Entity\Invoice();
$invoice->setCustomerRef($customer_id); // 对应QuickBooks后台创建的客户ID
$invoice->setTxnDate(date('Y-m-d'));
$invoice->setTotalAmt($order_amount);
$invoice->setAllowOnlinePayment(true); // 必须开启，否则不支持在线支付

// 添加商品明细
$line = new QuickBooksAPI\Entity\Line();
$line->setAmount($order_amount);
$line->setDetailType('SalesItemLineDetail');
$line->setSalesItemLineDetail([
    'ItemRef' => ['value' => $item_id], // 对应QuickBooks后台创建的商品ID
    'Qty' => 1,
    'UnitPrice' => $order_amount
]);
$invoice->setLine([$line]);

// 调用接口创建发票
$created_invoice = $service->create($invoice);
// 按规则拼接客户可访问的支付链接
$payment_link = $environment == 'production' 
    ? "https://pay.intuit.com/app/payments/invoice/{$created_invoice->getId()}"
    : "https://sandbox.pay.intuit.com/app/payments/invoice/{$created_invoice->getId()}";

2.3 Webhook接收支付状态配置 #

• 在QuickBooks开发者后台Webhook配置页，添加你站点的接收地址，勾选Payment、Invoice事件
• Laravel端处理Webhook的代码示例：

Route::post('/webhook/quickbooks', function (Request $request) {
    // 验证请求签名，防止伪造通知
    $signature = $request->header('intuit-signature');
    $webhook_verifier = new QuickBooksAPI\Util\WebhookVerifier($client_secret);
    if (!$webhook_verifier->verify($request->getContent(), $signature)) {
        return response()->json(['status' => 'invalid signature'], 403);
    }

    $payload = json_decode($request->getContent(), true);
    foreach ($payload['eventNotifications'] as $event) {
        if ($event['dataChangeEvent']['entities'][0]['name'] == 'Payment') {
            $payment_data = $event['dataChangeEvent']['entities'][0];
            // 此处处理你的业务逻辑：更新订单状态、发送支付成功通知等
        }
    }

    return response()->json(['status' => 'success']);
});

3 注意事项 #

• 测试阶段必须使用QuickBooks官方提供的沙箱测试信用卡号，不可使用真实银行卡测试
• 发票创建后默认30天有效，过期后支付链接自动失效
• 支付成功后Webhook通知可能存在最长5分钟的延迟，建议新增定时任务主动拉取发票状态做二次校验，避免漏单

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