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

Build a Public Key signed URL manually

Use PolyPay::buildCheckoutUrl() only when you are already managing the Public Key hosted checkout parameters yourself.

$checkoutUrl = PolyPay::buildCheckoutUrl([
    'public_key'   => 'pub_your_public_key',
    'amount'       => 10.00,
    'order_id'     => 'ORDER_' . time(),
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
]);

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

The SDK includes HMAC-SHA256 verification with timestamp window checks and nonce-based replay protection. For the full security model, also review Webhook Security.

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

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

try {
    $data = $polypay->webhook()->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

Method	Returns	Description
`createCheckoutUrl(array $params)`	`string`	Request a signed hosted checkout URL with API Key mode. Without currency and network, the customer chooses the payment method on PolyPay.
`buildCheckoutUrl(array $params)`	`string`	Build a Public Key signed hosted checkout URL manually.
`generateCheckoutSignature(array $params, string $publicKey)`	`string`	Generate the HMAC-SHA256 signature for hosted checkout.
`getPaymentMethods()`	`PaymentMethod[]`	Get available currency and network combinations for the current merchant.
`createOrder(array $params)`	`Order`	Create a checkout order and return payment URL, address, and trade ID.
`getOrderByTradeId(string $tradeId)`	`Order`	Query an order by PolyPay trade ID.
`getOrderByMchOrderId(string $mchOrderId)`	`Order`	Query an order by your own merchant order ID.
`getMerchantDetail()`	`Merchant`	Get merchant profile details associated with the API key.
`webhook()`	`WebhookHandler`	Create a webhook verifier that reuses the same API key.

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.php.

Repository

GitHub: PolyPayAi/php-sdk