«Твои Платежи»: Интеграция на PHP

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

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

Описание

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

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

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

$merchant = new Merchant('MERCHANT_CODE', 'SECRET_KEY'); // Коды подключения API
$merchantPaymentReference = 123; // Номер заказа в вашей системе
$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'  => 'test_artikul', // Артикул
    'unitPrice'  => 20.42, // Стоимость единицы
    'quantity'  => 1, // Количество
]));
$payment_method = $_GET['method'] ?? PaymentMethods::CCVISAMC; // Определим платёжный метод
$authorization = new Authorization($payment_method, true);
$payment->setAuthorization($authorization);
$payment->setMerchantPaymentReference($merchantPaymentReference);
$payment->setSuccessUrl('https://' . $_SERVER['HTTP_HOST'] . '/?status=success'); // Редирект после успешной оплаты
$payment->setFailUrl('https://' . $_SERVER['HTTP_HOST'] . '/?status=success'); // Редирект в случае неоплаты
$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. Подписки

Рекуррентные платежи 1. Создание подписки СБП 1. Оплата по подписке СБП 1. Создание подписки SberPay, T-Pay, Картой не РФ 1. Оплата по подписке SberPay, T-Pay, Картой не РФ

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

Запомнить данные клиента, чтобы не запрашивать и не вводить их повторно 1. Создание платёжного токена 2. Оплата токеном

5. Отчёты

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

7. Выплаты

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

Добавление сабмерчантов маркетплейсов по API 1. Подключение продавца-юридического лица (отправка анкеты) 2. Подключение продавца-ИП (отправка анкеты) 3. Получение статуса анкеты 4. Печать анкеты 5. Список анкет

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

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

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

Обновление

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

composer update yourpayments/php-api-client

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

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

«Твои Платежи»: Интеграция на PHP

Оглавление

Описание

Требования

Установка

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

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

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

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

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

3. Подписки

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

5. Отчёты

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

7. Выплаты

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

9. Обработка вебхуков

10. Страница после оплаты

11. Безопасные поля (Secure fields)

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

Обновление

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

Описание

Конвейеры

Разработчики