visualpay / sdk

1.0.0 2026-09-05 09:16 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• VisualPay

• api
• payments
• crypto
• merchant
• USDT
• visualpay

Published on Packagist.org on 2026-09-05 09:18 UTC

README

Official PHP client for the VisualPay Merchant API.

Repository: visualpay-php

Requirements

• PHP 8.1+
• Extensions: curl, json

Install

composer require visualpay/sdk

From a local path (development):

composer require visualpay/sdk:@dev --prefer-source

Security notes

• API base URL is hardcoded to https://visualpay.net (not configurable) to prevent host spoofing / MITM via custom endpoints.
• All requests use HTTPS with TLS peer verification (CURLOPT_SSL_VERIFYPEER / VERIFYHOST).
• Redirects are disabled; only the HTTPS protocol is allowed.
• Webhook tokens are compared with hash_equals (timing-safe).
• Optional callback_url values are rejected unless they use https://.
• Keep your merchant API key and webhook secret on the server only — never expose them in browsers, mobile apps, or public repos.
• This SDK is for server-side use. It does not use cookies/sessions, so classic session hijacking / CSRF against the SDK itself do not apply; still protect your own app routes with your framework’s CSRF and auth controls.

Quick start

<?php

use VisualPay\Client;
use VisualPay\Webhook;
use VisualPay\Exceptions\ApiException;

$client = new Client(getenv('VISUALPAY_API_KEY'));

// 1) List currencies / networks
$currencies = $client->listCurrencies();

// 2) Create a payment
$created = $client->createTransaction([
    'currency_symbol' => 'USDT',
    'network_code' => 'trc20',
    'amount_usd' => 25.50,
    'ttl' => 15,
    'order_id' => 100001,
    'email' => '[e-mail]',
    'comment' => 'Invoice #1001',
    'callback_url' => 'https://example.com/order', // optional HTTPS redirect for the payer
]);

$trackingCode = $created['data']['tracking_code'];
$paymentUrl = $created['data']['payment_url'];

// 3) Check status
$status = $client->getTransactionStatus($trackingCode);

// 4) Cancel (pending only) / recheck (expired|cancelled)
// $client->cancelTransaction($trackingCode);
// $client->recheckTransaction($trackingCode);

// 5) History
$txs = $client->listTransactions(['limit' => 20, 'page' => 1]);
$withdrawals = $client->listWithdrawals(['limit' => 20]);

Webhooks

VisualPay POSTs JSON to your webhook_url with header token: {your webhook_api_key}.

<?php

use VisualPay\Webhook;
use VisualPay\Exceptions\ValidationException;

$headerToken = $_SERVER['HTTP_TOKEN'] ?? '';
$rawBody = file_get_contents('php://input') ?: '';

try {
    $event = Webhook::verifyAndParse(
        $headerToken,
        getenv('VISUALPAY_WEBHOOK_SECRET') ?: '',
        $rawBody
    );
    // $event is a TransactionItem (or settlement payload)
} catch (ValidationException $e) {
    http_response_code(401);
    exit;
}

Always confirm payment server-side via webhook or getTransactionStatus before fulfilling orders. Do not trust browser redirects alone.

Error handling

try {
    $client->createTransaction([...]);
} catch (\VisualPay\Exceptions\AuthenticationException $e) {
    // 401
} catch (\VisualPay\Exceptions\ValidationException $e) {
    // 422 — $e->getErrors()
} catch (\VisualPay\Exceptions\RateLimitException $e) {
    // 429
} catch (\VisualPay\Exceptions\ApiException $e) {
    // other API errors — $e->getStatusCode(), $e->getMessage()
} catch (\VisualPay\Exceptions\NetworkException $e) {
    // transport / TLS failure
}

API surface

Method	Endpoint
listCurrencies()	GET /api/v1/merchant/currencies/list
createTransaction()	POST /api/v1/merchant/transaction/create
getTransactionStatus()	GET /api/v1/merchant/transaction/status
cancelTransaction()	POST /api/v1/merchant/transaction/cancel
recheckTransaction()	GET /api/v1/merchant/transaction/recheck
listTransactions()	GET /api/v1/merchant/transaction/list
listWithdrawals()	GET /api/v1/merchant/withdrawals/list

Full HTTP reference: https://visualpay.net/api-docs

Publish checklist (Packagist)

1. Push this repo to GitHub as visualpay/visualpay-php.
2. Tag a release: git tag v1.0.0 && git push --tags.
3. Submit the GitHub URL on packagist.org (package name visualpay/sdk).
4. Enable Packagist GitHub Service / webhook for auto-updates.
5. Verify: composer require visualpay/sdk:^1.0.

Development

composer install
composer test

License

MIT — see LICENSE.