PolyPay logoPolyPay.ai
Beginner12 min read

PHP SDK

Use the official PolyPay PHP SDK to redirect customers to hosted checkout, create server-side orders when the payment method is known, query status, and verify webhook callbacks.

If you need raw HTTP endpoints instead of the SDK wrapper, see the API Key guide.

Installation

composer require polypay/php-sdk

Initialize the client

use PolyPay\PolyPay;

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

Redirect to hosted checkout with API Key mode

This is the recommended server-side merchant checkout flow. The API Key stays on your server, and PolyPay returns a signed hosted checkout URL. Without currency and network, PolyPay shows the payment method selection page first. Pass both currency and network only when your site already knows the payment method and should skip selection.

$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'       => 'en',
]);

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

Skip selection when the method is known

$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'       => 'en',
    'currency'     => 'USDT',
    'network'      => 'Tron',
]);

Create an order with API Key mode

Use this only for server-side integrations where your business already selected the currency and network.

$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;

Query an order

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

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

Verify webhook callbacks

Use API-key-independent Ed25519 v2 verification, including merchant ID, environment, timestamp, nonce, and raw-body checks. Also review Webhook Security.

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') {
        // update your business order here
    }

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

Available SDK methods

MethodReturnsDescription
createCheckoutUrl(array $params)stringRequest a signed hosted checkout URL with API Key mode. Without currency and network, the customer chooses the currency first and then confirms the transfer network on PolyPay.
getPaymentMethods()PaymentMethod[]Get available currency and network combinations for the current merchant.
createOrder(array $params)OrderCreate a checkout order and return payment URL, address, and trade ID.
getOrderByTradeId(string $tradeId)OrderQuery an order by PolyPay trade ID.
getOrderByMchOrderId(string $mchOrderId)OrderQuery an order by your own merchant order ID.
getMerchantDetail()MerchantGet merchant profile details associated with the API key.
webhookV2()WebhookV2HandlerRecommended. Verify Ed25519 v2 with PolyPay JWKS, independently of API keys.

Debug and local testing

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

The SDK repository also includes ready-to-run examples such as examples/hosted_checkout.php, examples/create_order.php, and examples/webhook_v2.php.

Repository

GitHub: PolyPayAi/php-sdk

Standalone storefront integrations

Dujiao-Next: apply the versioned host-source patch from the repository native/ directory and rebuild the backend and both frontends. Select PolyPay directly under Payment channels and configure the merchant ID, production API Key and USD conversion rate. The form follows the panel language. Disable Require HTTPS for LAN HTTP; private addresses use authenticated server-side payment queries because public webhooks cannot reach them.

Dujiao-Next · GitHub

ACG-Faka: install app/Pay/PolyPay/ and app/Plugin/PolyPayCallback/, enable PolyPay Callback, then configure the payment extension for purchases or recharge. For the app store, use the two separate store packages documented in the repository. Force HTTPS (force_https) is on by default; turn it off for HTTP testing. Public webhooks cannot reach a LAN IP. Configuration labels follow the panel language: Simplified Chinese, Traditional Chinese, English and Japanese.

ACG-Faka · GitHub

Preview integrations still require real-payment acceptance. Native Dujiao-Next synchronizes cancellation and reconciles payment races; follow the ACG-Faka repository for its cancellation procedure. Use production credentials. No real payment or public-webhook fulfillment has been verified.