tokenpay-platform/sdk-php

Official PHP SDK for the TokenPay payment gateway.

v0.1.0 2026-04-21 15:46 UTC

Requires

• php: ^8.1
• ext-hash: *
• ext-json: *
• guzzlehttp/guzzle: ^7.5

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5

MIT

• payments
• sdk
• crypto
• p2p
• tokenpay

README

Official PHP SDK for the TokenPay payment gateway — P2P crypto trading platform with fiat on/off ramps and webhook-driven merchant integrations.

Source of truth. The canonical source lives in the private gpgo/tokenpay monorepo under sdks/php/. A public mirror is auto-published to gpgo/tokenpay-sdk-php on every v*-php release tag; that mirror is what Packagist installs from. See ADR-097 in docs/DECISIONS.md (monorepo only) for the rationale.

Requirements

• PHP 8.1 or newer (tested on 8.1, 8.2, 8.3, 8.4).
• Composer 2.x.
• The ext-json and ext-hash extensions (present in every standard PHP build).

Install

composer require tokenpay-platform/sdk-php

The Packagist vendor prefix is tokenpay-platform/ rather than the shorter tokenpay/ because the latter is held by a defensive dependency-confusion registrar (m-vendors, unrelated to this project). The GitHub repository is still gpgo/tokenpay-sdk-php; only the Packagist vendor differs.

Quick start

<?php
require 'vendor/autoload.php';

use TokenPay\SDK\TokenPay;

$tokenpay = new TokenPay(getenv('TOKENPAY_API_KEY'));

// Create a payment (currency, amount in the smallest unit, optional metadata).
$payment = $tokenpay->payments->create([
    'currency' => 'AUD',
    'amount'   => 12500,          // A$125.00
    'metadata' => ['order_id' => 'WC-1234'],
]);

echo $payment['id'];              // pay_...
echo $payment['checkout_url'];    // https://merchant.tokenpayment.io/pay/...

Retrieve, list, cancel

$tokenpay->payments->get($payment['id']);

$tokenpay->payments->list([
    'status'    => 'matched',
    'from_date' => '2026-04-01T00:00:00Z',
    'limit'     => 50,
    'offset'    => 0,
]);

// Cancel a payment that is still in `created` or `matching` state.
$tokenpay->payments->cancel($payment['id']);

The OpenAPI spec exposes cancelPayment, not a refund endpoint. The SDK tracks the spec; a dedicated refund method will land when the server-side endpoint does.

Verify a webhook

The TokenPay server signs every webhook with HMAC-SHA256 over a canonical string method + "\n" + path + "\n" + timestamp + "\n" + payload. The SDK verifies the signature with constant-time comparison.

use TokenPay\SDK\TokenPay;

$tokenpay = new TokenPay(getenv('TOKENPAY_API_KEY'));

$isValid = $tokenpay->webhooks->verify(
    secret:    getenv('TOKENPAY_WEBHOOK_SECRET'),
    method:    $_SERVER['REQUEST_METHOD'],         // "POST"
    path:      $_SERVER['REQUEST_URI'],            // "/webhooks/merchant"
    timestamp: $_SERVER['HTTP_X_TOKENPAY_TIMESTAMP'],
    payload:   file_get_contents('php://input'),
    signature: $_SERVER['HTTP_X_TOKENPAY_SIGNATURE'],
);

if (!$isValid) {
    http_response_code(401);
    exit;
}

Client options

$tokenpay = new TokenPay('tk_test_...', [
    'baseUrl'    => 'https://api.tokenpayment.io',   // default
    'timeout'    => 30,                              // seconds, Guzzle compat
    'maxRetries' => 3,                               // 5xx + network errors only
    'userAgent'  => 'tokenpay-sdk-php/0.1.0',        // default
]);

Errors

Class	When
TokenPay\SDK\Exceptions\ApiException	HTTP 4xx / 5xx from the TokenPay API. getStatusCode() + getBody() available.
TokenPay\SDK\Exceptions\NetworkException	Transport failures (DNS, connection, TLS, timeout).
TokenPay\SDK\Exceptions\TokenPayException	Base class for both of the above. Catch this for "any SDK error".

The client retries transient failures (5xx + network) with exponential backoff up to maxRetries times (default 3). 4xx responses are never retried.

WooCommerce integration

A minimal WooCommerce integration lives under examples/woocommerce/. It demonstrates:

• Creating a payment on checkout (WC_Payment_Gateway::process_payment).
• Verifying an incoming webhook and updating the order status.

The example is runnable against a local WooCommerce instance for development; live-site production testing is part of the TokenPay Integration Partners review (S091).

Versioning and stability

The TokenPay API follows the deprecation policy in docs/api/VERSIONING.md: v1 stable with a 6-month deprecation window. This SDK's minor versions track the API's minor bumps; patch versions are bug fixes only. See CHANGELOG.md.

Publishing (maintainer-only)

Packagist auto-publishes via the GitHub webhook on every tag push. Maintainer workflow:

git tag -a v0.1.0-php -m "sdks/php v0.1.0 — initial Packagist release"
git push origin v0.1.0-php
# Packagist webhook fires within ~60s.
# Verify: https://packagist.org/packages/tokenpay-platform/sdk-php

Packagist webhook configuration, the one-time namespace reservation, and the public-mirror sync workflow are documented in docs/ops/packagist-setup.md (monorepo only). The sync itself runs from .github/workflows/sync-php-sdk.yml.

Security

Please report security issues privately to [e-mail] rather than via a public GitHub issue. See the repo's root SECURITY.md.

License

MIT — see LICENSE.