README

Готовая библиотека PHP API Client для YourPayments + примеры с комментариями

Описание
Требования
Установка
- Запуск встроенного сервера
- Запуск в контейнере docker
Примеры использования
- Начало работы: настройка интеграции
- Приём платежей
- Подписки (рекуррентные платежи)
- Токенизация (запомнить данные плательщика, чтобы не запрашивать и не вводить их повторно)
- Отчёты и статусы платежей
- Возврат средств плательщику (refunds, рефанды)
- Выплаты (отправка денег по номеру карты или телефона)
- Подключение продавцов
- Обработка вебхуков
- Страница после оплаты
- Безопасные поля (отдельный вид интеграции карточной формы)
- Обработка ошибок
Обновление библиотеки
Поддержка и контакты

Описание

yourpayments/php-api-client — это PHP библиотека для быстрой и удобной интеграции с платежным шлюзом YourPayments. С её помощью можно принимать оплаты и создавать выплаты, получать отчёты, делать возвраты и работать с подпискам.

Библиотека ориентирована на простое и надёжное использование, подходит как для опытных, так и для начинающих разработчиков.

Пример быстрого старта для приёма платежей:

$merchant = new Merchant('MERCHANT_CODE', 'SECRET_KEY');
$billing = (new Billing)
  ->setCountryCode('RU')
  ->setFirstName('Иван')
  ->setLastName('Петров')
  ->setEmail('test1@ypmn.ru')
  ->setPhone('+74996492009')
  ->setCity('Москва');
  
$client = (new Client)
  ->setBilling($billing);

$payment = (new Payment)
  ->addProduct(new Product([
    'name'  => 'Заказ №' . $merchantPaymentReference,
    'sku'  => $merchantPaymentReference,
    'unitPrice'  => 20.42,
    'quantity'  => 1,
]));
$payment_method = $_GET['method'] ?? PaymentMethods::CCVISAMC; // Определим платёжный метод
$authorization = new Authorization($payment_method, true);
$payment->setAuthorization($authorization);
$payment->setMerchantPaymentReference($merchantPaymentReference);
$payment->setReturnUrl('https://' . @$_SERVER['HTTP_HOST'] . '/php-api-client/?function=returnPage');
$payment->setClient($client);
$apiRequest = new ApiRequest($merchant);
$responseData = $apiRequest->sendAuthRequest($payment, $merchant);
$responseData = json_decode((string) $responseData["response"], true);

if (isset($responseData["paymentResult"])) {
    if (!empty($responseData['paymentResult']['bankResponseDetails']['customBankNode']['qr'])) {
        $qr = $responseData['paymentResult']['bankResponseDetails']['customBankNode']['qr'];
    }

    // Выведем кнопку оплаты, рекомендуется
    echo Std::drawYpmnButton([
        'qr' => ($qr ?? null),
        'url' => $responseData['paymentResult']['url'] ?? '',
        'sum' => $payment->sumProductsAmount() ?? 0,
        'payment_method' => $payment_method ?? null,
        'newpage' => true,
    ]);

    // .. или сделаем редирект на форму оплаты (опционально)
    // Std::redirect($responseData["paymentResult"]['url']);
}

Особенностями системы являются:

мульти-эквайринг (работа сразу со многими банками, переключение в случае недоступности)
поддержка сплитования (разделение одного платежа на несколько получателей платежа, в рамках одного чеке)
безопасность и точность расчётов

Библиотека содержит:

Клиент API
Простой встроенный сервер с примерами
Описание контейнера для запуска в Docker

Требования

PHP 7.4 и выше (рекомендуется PHP 8.1+)
Расширения PHP: curl, json, mbstring
Рекомендуется: Composer для управления зависимостями

Установка

Установка с пакета composer -- самый простой и рекомендуемый способ:

composer require yourpayments/php-api-client

Если на вашем проекте нет Composer, склонируйте или скачайте, а затем подключите файлы этого репозитория, (пример)

Запуск встроенного сервера

php -S localhost:8080 index.php

После запуска по адресу http://localhost:8080 будут доступны интерактивные примеры в следующем виде:

Запуск в контейнере docker

Создайте и запустите docker контейнер следующей командой:

docker compose up

Либо в фоновом режиме командой:

docker compose up --detach

После выполнения сервис с документацией и примерами будет доступен по адресу http://localhost:8080/

Примеры использования:

1. Начало работы: настройка интеграции

2. Приём платежей

3. Подписки

Рекуррентные платежи

4. Токенизация

Запомнить данные клиента, чтобы не запрашивать и не вводить их повторно

5. Отчёты

6. Возврат средств плательщику (Refund)

7. Выплаты

8. Подключение продавцов

Добавление сабмерчантов маркетплейсов по API

12. Обработка ошибок

Библиотека выбрасывает один вид исключений: Ypmn\PaymentException.

Пример перехвата исключения можно посмотреть в примере: Cамый простой платёж

Обновление

Обновления библиотеки позволяют быстро исправлять ошибки и получать доступ к новым функциям

composer update yourpayments/php-api-client

Ссылки, поддержка и контакты

🟢 «Твои Платежи» -- финтех для сайтов, платформ и приложений

yourpayments / php-api-client

Maintainers

Details