初級12 分鐘閱讀

PHP SDK

使用官方 PolyPay PHP SDK，在 Laravel、WordPress、WHMCS 或自定義 PHP 專案中跳轉託管收銀臺、在已知支付方式時服務端建立訂單、查詢訂單和 Webhook 驗籤。

如果你希望直接呼叫 HTTP 介面而不是使用 SDK 封裝，可以先看 API Key 指南。

安裝

composer require polypay/php-sdk

初始化客戶端

use PolyPay\PolyPay;

$polypay = new PolyPay('your-api-key', [
    'api_url' => 'https://api.polypay.ai',
    'timeout' => 30,
]);

使用 API Key 模式跳轉託管 Checkout

這是推薦的服務端商戶收銀臺流程。API Key 保留在你的服務端，由 PolyPay 返回已簽名的託管 checkout URL。未傳 currency 和 network 時，PolyPay 會先展示支付方式選擇頁；只有在商戶已經明確支付方式時，才同時傳入這兩個引數跳過選擇頁。

$checkoutUrl = $polypay->createCheckoutUrl([
    'mch_order_id' => 'ORDER_' . time(),
    'amount'       => 10.00,
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
    'locale'       => 'zh-TW',
]);

header('Location: ' . $checkoutUrl);
exit;

已知支付方式時跳過選擇頁

$checkoutUrl = $polypay->createCheckoutUrl([
    'mch_order_id' => 'ORDER_' . time(),
    'amount'       => 10.00,
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
    'locale'       => 'zh-TW',
    'currency'     => 'USDT',
    'network'      => 'Tron',
]);

使用 API Key 模式建立訂單

僅在服務端已經明確幣種和鏈時使用這種方式。

$order = $polypay->createOrder([
    'mch_order_id' => 'ORDER_' . time(),
    'currency'     => 'USDT',
    'network'      => 'tron',
    'amount'       => 10.00,
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
]);

echo $order->tradeId;
echo $order->paymentUrl;
echo $order->address;

查詢訂單

$order = $polypay->getOrderByTradeId('T20240101120000123456');

echo $order->status;
echo $order->txHash;

驗證 Webhook 回撥

使用獨立於 API Key 的 Ed25519 v2 驗籤，並校驗商戶 ID、環境、時間視窗、 nonce 和原始請求體。完整說明請檢視 Webhook 安全文件。

use PolyPay\PolyPay;
use PolyPay\WebhookHandler;
use PolyPay\Exception\SignatureException;

$polypay = new PolyPay('your-api-key');

try {
    $data = $polypay->webhookV2('MCH_YOUR_ID', 'production')->handle();
    $status = WebhookHandler::resolveStatus($data);

    if ($status === 'paid') {
        // 在這裡更新你的業務訂單狀態
    }

    http_response_code(200);
    echo 'OK';
} catch (SignatureException $e) {
    http_response_code($e->getHttpStatus());
    echo $e->getMessage();
}

SDK 方法一覽

方法	返回值	說明
`createCheckoutUrl(array $params)`	`string`	使用 API Key 模式請求已簽名的託管 checkout URL。未傳 currency 和 network 時，由使用者在 PolyPay 先選擇幣種，再確認轉帳網路。
`getPaymentMethods()`	`PaymentMethod[]`	獲取當前商戶可用的幣種和鏈路組合。
`createOrder(array $params)`	`Order`	建立支付訂單，返回支付連結、收款地址和交易號。
`getOrderByTradeId(string $tradeId)`	`Order`	透過 PolyPay 交易號查詢訂單。
`getOrderByMchOrderId(string $mchOrderId)`	`Order`	透過商戶自己的訂單號查詢訂單。
`getMerchantDetail()`	`Merchant`	獲取當前 API Key 對應的商戶資訊。
`webhookV2()`	`WebhookV2Handler`	推薦。使用 PolyPay JWKS 驗證 Ed25519 v2 簽名，不依賴 API Key。

除錯與本地測試

$polypay = new PolyPay('your-api-key', [
    'debug' => true,
    'debug_log_file' => '/tmp/polypay-debug.log',
]);

SDK 倉庫中也包含可直接執行的示例，例如 examples/hosted_checkout.php、examples/create_order.php 和 examples/webhook_v2.php。

倉庫地址

GitHub：PolyPayAi/php-sdk