初级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',
]);

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',
    '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