README

Офіційний PHP SDK для інтеграції з платіжним шлюзом VarxPay.

📋 Вимоги

PHP 8.1 або вище
Composer
Guzzle HTTP Client ^7.0

📦 Встановлення

Через Composer

composer require varxpay/sdk

⚙️ Конфігурація

Основне використання (без фреймворку)

<?php

require_once 'vendor/autoload.php';

use VarxPay\VarxPayClient;

$client = new VarxPayClient(
    publicKey: 'your_public_key',
    privateKey: 'your_private_key',
    baseUrl: 'https://varxpay.com'
);

Laravel

Опублікуйте конфігурацію:

php artisan vendor:publish --tag=varxpay-config

Додайте змінні оточення в .env:

VARXPAY_PUBLIC_KEY=your_public_key
VARXPAY_PRIVATE_KEY=your_private_key
VARXPAY_BASE_URL=https://varxpay.com

Використання через Facade або Dependency Injection:

<?php

use VarxPay\Laravel\Facades\VarxPay;
use VarxPay\VarxPayClient;

// Через Facade
$response = VarxPay::createInvoice('100.00', 'ORDER-123', 'Оплата замовлення');

// Через DI
class PaymentController extends Controller
{
    public function create(VarxPayClient $client)
    {
        $response = $client->createInvoice('100.00', 'ORDER-123');
        return redirect($response->getPaymentUrl());
    }
}

Symfony

Зареєструйте bundle в config/bundles.php:

<?php

return [
    // ...
    VarxPay\Symfony\VarxPayBundle::class => ['all' => true],
];

Створіть конфігурацію config/packages/varxpay.yaml:

varxpay:
    public_key: '%env(VARXPAY_PUBLIC_KEY)%'
    private_key: '%env(VARXPAY_PRIVATE_KEY)%'
    base_url: '%env(VARXPAY_BASE_URL)%'
    http_options:
        timeout: 30
        connect_timeout: 10

Додайте змінні оточення в .env:

VARXPAY_PUBLIC_KEY=your_public_key
VARXPAY_PRIVATE_KEY=your_private_key
VARXPAY_BASE_URL=https://varxpay.com

Використання через Dependency Injection:

<?php

use VarxPay\VarxPayClient;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class PaymentController extends AbstractController
{
    public function create(VarxPayClient $client): Response
    {
        $response = $client->createInvoice('100.00', 'ORDER-123');
        return $this->redirect($response->getPaymentUrl());
    }
}

🚀 Використання

Створення інвойсу

<?php

use VarxPay\VarxPayClient;
use VarxPay\Exception\ApiException;

$client = new VarxPayClient(
    publicKey: 'your_public_key',
    privateKey: 'your_private_key',
    baseUrl: 'https://varxpay.com'
);

try {
    // Простий спосіб
    $response = $client->createInvoice(
        amount: '100.50',
        orderId: 'ORDER-' . time(),
        description: 'Оплата замовлення #12345'
    );

    if ($response->isSuccess()) {
        // Редірект клієнта на сторінку оплати
        header('Location: ' . $response->getPaymentUrl());
        exit;
    } else {
        echo 'Помилка: ' . $response->getError();
    }
} catch (ApiException $e) {
    echo 'API помилка: ' . $e->getMessage();
    echo 'HTTP код: ' . $e->getHttpStatusCode();
}

Створення інвойсу з розширеними параметрами

<?php

use VarxPay\VarxPayClient;
use VarxPay\DTO\CreateInvoiceRequest;

$client = new VarxPayClient(
    publicKey: 'your_public_key',
    privateKey: 'your_private_key',
    baseUrl: 'https://varxpay.com'
);

// Створення запиту з повним контролем
$request = new CreateInvoiceRequest(
    publicKey: 'your_public_key',
    amount: '250.00',
    orderId: 'ORDER-12345',
    description: 'Підписка на місяць',
    currency: 'USDT',
    action: 'pay',
    version: 1
);

$response = $client->createInvoiceFromRequest($request);

Обробка Callback (Webhook)

VarxPay надсилає callback на вашу callback URL при зміні статусу платежу.

<?php

use VarxPay\CallbackHandler;
use VarxPay\DTO\Callback;
use VarxPay\Exception\SignatureException;

// Створення обробника з приватним ключем
$handler = new CallbackHandler('your_private_key');

// Або через клієнт
// $handler = $client->createCallbackHandler();

try {
    // Обробка POST запиту від VarxPay
    $callback = $handler->handleFromRequest();
    
    // Перевірка статусу
    if ($callback->isApproved()) {
        // Платіж успішний!
        $orderId = $callback->getOrderReference(); // ваш order_id
        $invoiceId = $callback->getOrderId();      // VarxPay invoice UID
        $amount = $callback->getAmount();
        
        // Оновіть статус замовлення в вашій БД
        updateOrderStatus($orderId, 'paid');
        
    } elseif ($callback->isDeclined()) {
        // Платіж відхилено
        updateOrderStatus($callback->getOrderReference(), 'failed');
        
    } elseif ($callback->isPending()) {
        // Платіж в очікуванні
        updateOrderStatus($callback->getOrderReference(), 'pending');
    }
    
    // Відповідь для VarxPay (HTTP 200)
    http_response_code(200);
    echo json_encode(['status' => 'ok']);
    
} catch (SignatureException $e) {
    // Невалідний підпис - можлива атака!
    http_response_code(403);
    echo json_encode(['error' => 'Invalid signature']);
    
} catch (\Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => 'Internal error']);
}

Обробка Callback в Laravel

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use VarxPay\CallbackHandler;
use VarxPay\Exception\SignatureException;

class VarxPayCallbackController extends Controller
{
    public function __construct(
        private CallbackHandler $callbackHandler
    ) {}
    
    public function handle(Request $request)
    {
        try {
            $callback = $this->callbackHandler->handle(
                $request->all()
            );
            
            if ($callback->isApproved()) {
                // Оновити замовлення
                Order::where('order_id', $callback->getOrderReference())
                    ->update(['status' => 'paid']);
            }
            
            return response()->json(['status' => 'ok']);
            
        } catch (SignatureException $e) {
            return response()->json(['error' => 'Invalid signature'], 403);
        }
    }
}

Обробка Callback в Symfony

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
use VarxPay\CallbackHandler;
use VarxPay\Exception\SignatureException;

class VarxPayCallbackController extends AbstractController
{
    #[Route('/webhook/varxpay', name: 'varxpay_callback', methods: ['POST'])]
    public function callback(Request $request, CallbackHandler $handler): JsonResponse
    {
        try {
            $payload = json_decode($request->getContent(), true);
            $callback = $handler->handle($payload);
            
            if ($callback->isApproved()) {
                // Обробка успішного платежу
            }
            
            return new JsonResponse(['status' => 'ok']);
            
        } catch (SignatureException $e) {
            return new JsonResponse(['error' => 'Invalid signature'], 403);
        }
    }
}

📊 Структура Callback

Callback від VarxPay містить наступні дані:

Поле	Тип	Опис
`orderId`	string	Унікальний ID інвойсу VarxPay
`merchantAccount`	string	Слаг компанії
`orderReference`	string	Ваш order_id
`amount`	string	Сума платежу
`currency`	string	Валюта (USDT)
`email`	string	Email клієнта (якщо є)
`processingDate`	string	Дата обробки (Y-m-d H:i:s)
`transactionStatus`	string	Статус: Approved, Declined, Pending
`last4`	string	Останні 4 символи адреси відправника
`signature`	string	Підпис для верифікації

🔐 Генерація підпису

Підпис генерується за формулою:

base64_encode(sha1($privateKey . $dataJson . $privateKey, true))

Де $dataJson - це JSON рядок без пробілів (використовуйте json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).

SDK автоматично генерує та перевіряє підписи.

⚠️ Обробка помилок

SDK використовує виключення для повідомлення про помилки:

<?php

use VarxPay\Exception\VarxPayException;
use VarxPay\Exception\ApiException;
use VarxPay\Exception\SignatureException;
use VarxPay\Exception\ConfigurationException;

try {
    $response = $client->createInvoice('100.00', 'ORDER-123');
} catch (ApiException $e) {
    // Помилка API запиту
    echo $e->getMessage();
    echo $e->getHttpStatusCode();
    echo $e->getApiErrorMessage();
} catch (ConfigurationException $e) {
    // Помилка конфігурації
} catch (SignatureException $e) {
    // Помилка підпису
} catch (VarxPayException $e) {
    // Загальна помилка SDK
}

Коди помилок API

Помилка	Опис
`Invalid Action`	Невірний тип дії (має бути "pay")
`Order ID already exist`	order_id вже існує для цієї компанії
`Invalid signature`	Невалідний підпис запиту
`Company not found`	public_key не знайдено
`Company is inactive`	Компанія деактивована

📁 Структура SDK

sdk/
├── src/
│   ├── VarxPayClient.php         # Головний клієнт
│   ├── CallbackHandler.php       # Обробник callback
│   ├── DTO/
│   │   ├── CreateInvoiceRequest.php
│   │   ├── CreateInvoiceResponse.php
│   │   └── Callback.php
│   ├── Exception/
│   │   ├── VarxPayException.php
│   │   ├── ApiException.php
│   │   ├── SignatureException.php
│   │   └── ConfigurationException.php
│   ├── Signature/
│   │   ├── SignatureGenerator.php
│   │   └── SignatureValidator.php
│   ├── Laravel/
│   │   ├── VarxPayServiceProvider.php
│   │   └── Facades/
│   │       └── VarxPay.php
│   └── Symfony/
│       ├── VarxPayBundle.php
│       ├── VarxPayExtension.php
│       └── Configuration.php
├── config/
│   └── varxpay.php              # Laravel конфігурація
├── composer.json
└── README.md

🧪 Тестування

# Встановлення залежностей для розробки
composer install --dev

# Запуск тестів
./vendor/bin/phpunit

📝 Ліцензія

MIT License. Дивіться LICENSE для деталей.

🤝 Підтримка

Email: support@varxpay.com
Документація API: https://varxpay.com/api-docs

📌 Версії

v1.0.0

Перша стабільна версія
Створення інвойсів
Обробка callback
Інтеграція з Laravel та Symfony

varxpay / sdk

Maintainers

Package info

Statistics

Security