PHPackages                             ponponpay/php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. ponponpay/php-sdk

ActiveLibrary[Payment Processing](/categories/payments)

ponponpay/php-sdk
=================

PolyPay Crypto Payment Gateway - Official PHP SDK

v1.0.0(1mo ago)00MITPHPPHP >=7.4

Since Apr 27Pushed 1w agoCompare

[ Source](https://github.com/useponponpay/php-sdk)[ Packagist](https://packagist.org/packages/ponponpay/php-sdk)[ Docs](https://ponponpay.com)[ RSS](/packages/ponponpay-php-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (2)Used By (0)

PolyPay PHP SDK
===============

[](#polypay-php-sdk)

Accept cryptocurrency payments (USDT, USDC, etc.) on any PHP website via [PolyPay](https://polypay.ai).

[English](#installation) | [中文](#%E5%AE%89%E8%A3%85)

Features
--------

[](#features)

- 🔑 **Simple Setup** — Just provide your API Key
- 🌐 **Framework Agnostic** — Works with any PHP project (Laravel, WordPress, custom, etc.)
- 📦 **Zero Dependencies** — Pure PHP with cURL, no external packages required
- 🔒 **Webhook Verification** — Built-in HMAC-SHA256 signature validation with replay protection
- 🤖 **Agent Payments** — x402 helper for API/resource payments by agents
- 💰 **Multi-Currency** — Support USDT, USDC on Tron, Ethereum, BSC, Polygon, Solana

Requirements
------------

[](#requirements)

- PHP >= 7.4
- ext-curl
- ext-json

Installation
------------

[](#installation)

### Via Composer (Recommended)

[](#via-composer-recommended)

```
composer require polypay/php-sdk
```

### Manual Installation

[](#manual-installation)

Download the SDK and include the autoloader:

```
require_once '/path/to/php-sdk/autoload.php';
```

Quick Start
-----------

[](#quick-start)

### 1. Initialize

[](#1-initialize)

```
use PolyPay\PolyPay;

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

### Sandbox Testing

[](#sandbox-testing)

Use a sandbox API key that starts with `sk_sandbox_` to create sandbox orders:

```
$polypay = new PolyPay('sk_sandbox_your_key');
```

The API base URL stays the same. PolyPay separates production and sandbox data by the API key environment. Sandbox orders use `SB...` trade IDs and virtual payment addresses, and you can simulate payment states from the merchant dashboard.

### 2. Redirect to Hosted Checkout with API Key Mode

[](#2-redirect-to-hosted-checkout-with-api-key-mode)

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

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

PolyPay returns a signed hosted checkout URL such as:

```
https://checkout.polypay.ai/en/checkout

```

PolyPay displays the payment method selection page. If your site already has a confirmed payment method, pass `currency` and `network` to skip selection and go directly to the payment page:

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

Use `PolyPay::buildCheckoutUrl()` only when you already manage Public Key hosted checkout parameters yourself:

```
$checkoutUrl = PolyPay::buildCheckoutUrl([
    'public_key'   => 'pub_your_public_key',
    'amount'       => 10.00,
    'order_id'     => 'ORDER_001',
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
    'currency'     => 'USDT',
    'network'      => 'Tron',
]);
```

### 3. Create an Order with API Key Mode

[](#3-create-an-order-with-api-key-mode)

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

echo $order->paymentUrl;  // Redirect user to this URL
echo $order->tradeId;     // PolyPay trade ID
echo $order->address;     // Payment address
```

For normal merchant checkout, prefer hosted checkout so PolyPay owns payment method selection.

### 4. Query Order

[](#4-query-order)

```
// By trade ID
$order = $polypay->getOrderByTradeId('T20240101120000123456');

// By merchant order ID
$order = $polypay->getOrderByMchOrderId('ORDER_001');

echo $order->status;   // paid, pending, expired, cancelled
echo $order->txHash;   // Blockchain transaction hash
```

### 5. Handle Webhook Callback

[](#5-handle-webhook-callback)

```
try {
    $data = $polypay->webhook()->handle();
    $status = WebhookHandler::resolveStatus($data);

    if ($status === 'paid') {
        // Payment successful!
        // Update your order status here
    }

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

### 6. Protect an API with x402 Agent Payments

[](#6-protect-an-api-with-x402-agent-payments)

```
$x402 = $polypay->x402([
    'resource' => [
        'payTo' => '0xYourMerchantSettlementWallet',
        'resource' => 'https://api.example.com/premium-data',
        'method' => 'GET',
        'price' => '$0.01',
        'maxAmountRequired' => '10000',
        'network' => 'eip155:8453',
        'asset' => 'USDC',
        'description' => 'Premium market data',
    ],
]);

$result = $x402->verifyAndSettle();

if (!$result['paid']) {
    $x402->sendRequirementAndExit();
}

header('Content-Type: application/json');
echo json_encode(['data' => 'premium payload']);
```

API Reference
-------------

[](#api-reference)

### `PolyPay` Class

[](#polypay-class)

MethodDescriptionReturns`createCheckoutUrl(array $params)`Request a signed hosted checkout URL with API Key Mode`string``buildCheckoutUrl(array $params, array $options = [])`Build a Public Key signed hosted checkout URL manually`string``generateCheckoutSignature(array $params, string $publicKey)`Generate hosted checkout signature`string``getPaymentMethods()`Get available payment methods`PaymentMethod[]``createOrder(array $params)`Create a payment order`Order``getOrderByTradeId(string $tradeId)`Query order by trade ID`Order``getOrderByMchOrderId(string $mchOrderId)`Query order by merchant order ID`Order``getMerchantDetail()`Get merchant info`Merchant``activatePlugin(string $type)`Activate plugin`bool``webhook(?NonceStorageInterface $nonce)`Create webhook handler (shares API Key)`WebhookHandler``x402(array $options)`Create x402 agent payment helper`X402`### `x402` Resource Options

[](#x402-resource-options)

ParameterRequiredDescription`payTo`✅Merchant EVM wallet address receiving USDC`resource`✅Canonical protected resource URL`price`✅\*Human-readable price, e.g. `$0.01``maxAmountRequired`✅\*USDC base-unit amount; required if `price` is omitted`method`❌Protected HTTP method`description`❌Description shown to agents`mimeType`❌Resource MIME type`scheme`❌Defaults to `exact``network`❌Defaults to `eip155:8453`; supported: `eip155:8453`, `eip155:1`, `eip155:137``asset`❌Defaults to `USDC``assetContract`❌Defaults to the network-specific Circle USDC contract`maxTimeoutSeconds`❌Defaults to `60`> x402 verification binds the payment to `resource` and `method`. If your application is behind a proxy, pass the canonical public URL to `verifyAndSettle($headers, $method, $url)` so it matches the URL advertised in the 402 requirement.

Supported standard x402 networks:

NetworkChainUSDC Contract`eip155:8453`Base`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913``eip155:1`Ethereum`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48``eip155:137`Polygon`0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`Only standard EVM `exact` payments with Circle USDC `transferWithAuthorization` are supported. BSC, Tron, Solana, TON, and BTC are not part of this standard exact flow.

### `createOrder` Parameters

[](#createorder-parameters)

ParameterRequiredDescription`mch_order_id`✅Your unique order ID`currency`✅Cryptocurrency: `USDT`, `USDC``network`✅Network: `tron`, `ethereum`, `bsc`, `polygon`, `solana``amount`✅Payment amount (in fiat currency)`notify_url`✅Webhook callback URL`redirect_url`❌URL to redirect after payment### `Order` Model Properties

[](#order-model-properties)

PropertyTypeDescription`tradeId``string`PolyPay trade ID`paymentUrl``string`Payment page URL`amount``float`Order amount`actualAmount``float`Actual crypto amount`address``string`Payment address`expiresAt``?int`Expiry timestamp (Unix)`currency``string`Cryptocurrency`network``string`Network`status``string`Order status`txHash``string`Transaction hash`mchOrderId``string`Merchant order ID### Webhook Callback Status Codes

[](#webhook-callback-status-codes)

Status CodeMeaningResolved Status1Pending payment`pending`2Payment successful`paid`3Expired`expired`4Cancelled`cancelled`5Manual recharge`paid`Configuration Options
---------------------

[](#configuration-options)

```
$polypay = new PolyPay('your-api-key', [
    'api_url'        => 'https://api.polypay.ai',  // API base URL
    'timeout'        => 30,                            // Request timeout (seconds)
    'debug'          => false,                         // Enable debug logging
    'debug_log_file' => '/tmp/polypay-debug.log',    // Debug log file path
]);
```

Custom Nonce Storage
--------------------

[](#custom-nonce-storage)

By default, the webhook handler uses file-based nonce storage. For high-traffic scenarios, implement `NonceStorageInterface` with Redis:

```
use PolyPay\Nonce\NonceStorageInterface;

class RedisNonceStorage implements NonceStorageInterface
{
    private $redis;

    public function __construct(\Redis $redis)
    {
        $this->redis = $redis;
    }

    public function consume(string $nonce, int $ttl = 600): bool
    {
        // SET NX returns true only if key doesn't exist
        return $this->redis->set('polypay_nonce:' . $nonce, '1', ['NX', 'EX' => $ttl]);
    }
}

// Usage
$handler = $polypay->webhook(new RedisNonceStorage($redis));
```

Error Handling
--------------

[](#error-handling)

```
use PolyPay\Exception\ConfigException;
use PolyPay\Exception\ApiException;
use PolyPay\Exception\SignatureException;

try {
    $order = $polypay->createOrder([...]);
} catch (ConfigException $e) {
    // API Key not configured
} catch (ApiException $e) {
    echo $e->getMessage();       // Error message
    echo $e->getHttpCode();      // HTTP status code
    echo $e->getApiCode();       // Business error code
    echo $e->getResponseBody();  // Raw response body
}
```

Examples
--------

[](#examples)

See the [`examples/`](./examples) directory for complete, runnable examples:

- [`create_order.php`](./examples/create_order.php) — Create a payment order
- [`query_order.php`](./examples/query_order.php) — Query order status
- [`webhook.php`](./examples/webhook.php) — Handle payment callback
- [`payment_methods.php`](./examples/payment_methods.php) — List available methods
- [`hosted_checkout.php`](./examples/hosted_checkout.php) — Redirect to hosted checkout
- [`payment_page.php`](./examples/payment_page.php) — Hosted checkout redirect example

License
-------

[](#license)

MIT License. See [LICENSE](./LICENSE) for details.

---

安装
==

[](#安装)

### 通过 Composer（推荐）

[](#通过-composer推荐)

```
composer require polypay/php-sdk
```

### 手动安装

[](#手动安装)

下载 SDK 并引入自动加载文件：

```
require_once '/path/to/php-sdk/autoload.php';
```

快速开始
----

[](#快速开始)

```
use PolyPay\PolyPay;
use PolyPay\WebhookHandler;

// 初始化
$polypay = new PolyPay('你的API Key');

// 使用 API Key 模式跳转到 PolyPay 托管收银台，由 PolyPay 统一选择支付方式
$checkoutUrl = $polypay->createCheckoutUrl([
    'mch_order_id' => 'ORDER_001',
    'amount'       => 10.00,
    'notify_url'   => 'https://your-site.com/webhook.php',
    'redirect_url' => 'https://your-site.com/success',
    'locale'       => 'zh',
]);

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

// 默认跳转页面：https://checkout.polypay.ai/en/checkout
// 中文收银台：locale = zh，对应页面：https://checkout.polypay.ai/zh/checkout

// 如果商户已经明确支付方式，也可以使用 API Key 模式直接创建订单
$order = $polypay->createOrder([
    'mch_order_id' => 'ORDER_001',
    'currency'     => 'USDT',
    'network'      => 'tron',
    'amount'       => 10.00,
    'notify_url'   => 'https://your-site.com/webhook.php',
]);

// 处理回调（自动共享 API Key）
$data = $polypay->webhook()->handle();
if (WebhookHandler::resolveStatus($data) === 'paid') {
    // 支付成功，更新订单状态
}

// x402 Agent 支付保护接口
$x402 = $polypay->x402([
    'resource' => [
        'payTo' => '0x你的EVM收款钱包',
        'resource' => 'https://api.example.com/premium-data',
        'method' => 'GET',
        'price' => '$0.01',
        'maxAmountRequired' => '10000',
        'network' => 'eip155:8453',
        'asset' => 'USDC',
        'description' => '高级数据接口',
    ],
]);

$result = $x402->verifyAndSettle();
if (!$result['paid']) {
    $x402->sendRequirementAndExit();
}
```

更多示例请参考 [`examples/`](./examples) 目录。

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance95

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

43d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a4f244c9d215ef64f2c988441a9f0f4cdad8a6f39dff200847a131eaf5faa0a6?d=identicon)[useponponpay](/maintainers/useponponpay)

---

Tags

cryptopaymentpayment gatewayblockchainUSDCUSDTponponpay

### Embed Badge

![Health badge](/badges/ponponpay-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/ponponpay-php-sdk/health.svg)](https://phpackages.com/packages/ponponpay-php-sdk)
```

###  Alternatives

[shetabit/payment

Laravel Payment Gateway Integration Package

943336.8k5](/packages/shetabit-payment)[shetabit/multipay

PHP Payment Gateway Integration Package

293355.3k4](/packages/shetabit-multipay)[cybersource/rest-client-php

Client SDK for CyberSource REST APIs

40930.1k6](/packages/cybersource-rest-client-php)[victorybiz/laravel-crypto-payment-gateway

GoUrl.io Crypto Payment Gateway for Laravel

642.6k](/packages/victorybiz-laravel-crypto-payment-gateway)[tzsk/payu

PayU India Payment Gateway Integration with Laravel

47111.0k6](/packages/tzsk-payu)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)