pscbonline-php/README.md

# PSCB PHP SDK (beta)

- [Общая информация](#общая-информация)
    - [Требования](#требования)
    - [Описание](#описание)
        - [Структура компонента SDK](#структура-компонента-sdk)
- [Методы работы с платежами](#методы-работы-с-платежами)
    - [Вызов платежной формы](#вызов-платежной-формы)
        - [Пример вызова платежной формы:](#пример-вызова-платежной-формы)
    - [Создание платежа СБП](#создание-платежа-сбп)
        - [Пример использования:](#пример-использования-1)
    - [Подтверждение предавторизации](#подтверждение-предавторизации)
        - [Пример использования:](#пример-использования-2)
    - [Отмена предавторизации](#отмена-предиавторизации)
        - [Пример использования:](#пример-использования-3)
    - [Возврат платежа](#возврат-платежа)
        - [Пример использования:](#пример-использования-4)
- [Обработка нотификаций](#обработка-нотификаций)
    - [Подключение](#подключение)
    - [Примеры использования](#примеры-использования)
- [Вопросы и ответы](#вопросы-и-ответы)

## Общая информация

Библиотека является дополнением к API интернет-эквайринга ПСКБ и позволяет интегрировать прием платежей картами и СБП в PHP-проекты с минимальными усилиями.

### Требования

PHP 8.0+

### Описание

SDK включает 2 базовых компонента, которые предназначены для следующих целей:

- `SDK_PayModul` – методы работы с платежами
- `SDK_Callback` – обработка нотификаций

Для работы с SDK вам понадобятся:

- `marketPlace` – идентификатор Магазина
- `secretKey` – секретный ключ, используемый для аутентификации

Параметры `marketPlace` и `secretKey` доступны в [Кабинете мерчанта](https://oos.pscb.ru/auth) в разделе "Профиль". Параметр `secretKey` отличается для тестового и боевого окружения Системы.

### Структура компонента SDK

| Файл/каталог | Описание |
|--------------| --- |
| `README.md`  | Cодержит информацию про доступные для передачи параметры в методы класса | 
| `events`     | Отображает ответы и результаты выполнения от API (путь хранения выбирается самостоятельно) |
| `logs`       | Отображает ответы и результаты выполнения от SDK (путь хранения выбирается самостоятельно) |
| `src`        | Каталог с исходными кодами SDK |


## Методы работы с платежами

### Вызов платежной формы

#### Пример вызова платежной формы:

```php
<?php

//Подключение библиотеки
include 'payment.class.php';
//Основные параметры платежа
$data = array(
    "marketPlace" => 47607,
    "secretKey" => '111111',
    "orderId" => 2000,
    "request_url"=>" https://oosdemo.pscb.ru ", 
    "hold" => true // Активируем создание двухстадийного платежа картой
);
//Параметры для чека
$products = array(
    array(
        "object" => 'Товар1',
        "quantity" => 1,
        "price" => 2,
        "amount" => 2
    ),
);
//Указание путей для сохранения логов и событий
//Вместо logs и events установите свой путь для сохранения, например /var/log 
$M = new SetWay();
$M->SetLogsAndEvensWay('logs','events'); 
//Создание экземпляра платежной формы и ее запуск
$PayForm = new ClassPay($data);
$PayForm->CreatePayment($products);
?>
```

### Создание платежа СБП

Для создания платежа через СБП используйте класс `ClassInvoicing`. 

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

```php
<?php
// ... подключение библиотеки и настройка путей для логов ...

$data = array(
    "marketPlace" => 47607,
    "orderId" => 6026,
    "request_url"=>"https://oosdemo.pscb.ru", 
    "secretKey" => '111111',
    "sbpRedirectUrl"=>"https://your-site.com/sbp-callback" //URL - для сайтов, schema - для мобильных приложений
);

$products = array(
    array(
        "object" => 'Товар1',
        "quantity" => 1,
        "price" => 2,
        "amount" => 2
    ),
);

$InvoicingPay = new ClassInvoicing($data);
$result = $InvoicingPay->CreatePayment($products);
?>
```

### Подтверждение предавторизации

Для подтверждения двухстадийного платежа картой используйте класс `ClassConfirm`. 

#### Пример использования:
```php
<?php
// ... подключение библиотеки и настройка путей для логов ...

$data = array(
    "marketPlace" => 47607,
    "orderId" => 6026,
    "request_url"=>"https://oosdemo.pscb.ru",
    "secretKey" => '111111'
);

$products = array(
    array(
        "object" => 'Товар1',
        "quantity" => 1,
        "price" => 2,
        "amount" => 2
    ),
);

$ConfirmPay = new ClassConfirm($data);
$result = $ConfirmPay->CreatePayment($products);
?>
```

### Отмена предавторизации

Для отмены двухстадийного платежа картой используйте класс `ClassReject`. 

#### Пример использования:
```php
<?php
// ... подключение библиотеки и настройка путей для логов ...

$data = array(
    "marketPlace" => 47607,
    "orderId" => 6026,
    "request_url"=>"https://oosdemo.pscb.ru",
    "secretKey" => '111111'
);

$RejectPay = new ClassReject($data);
$result = $RejectPay->CancelPayment();
?>
```

### Возврат платежа

Для возврата платежа используйте класс `ClassRefund`. 

#### Пример использования:
```php
<?php
// ... подключение библиотеки и настройка путей для логов ...

$data = array(
    "marketPlace" => 47607,
    "orderId" => 6026,
    "request_url"=>"https://oosdemo.pscb.ru",
    "secretKey" => '111111',
    "partialRefund"=> true // Укажите false для полного возврата
);

$products = array(
    array(
        "object" => 'Товар1',
        "quantity" => 1,
        "price" => 2,
        "amount" => 2
    ),
);

$RefundPay = new ClassRefund($data);
$result = $RefundPay->CreatePayment($products);
?>
```

## Обработка нотификаций

Сценарий работы с нотификациями позволяет получать уведомления об изменении статусов платежей. Для обработки нотификаций используйте класс `CallbackClass`.

### Подключение 
```php
<?php
include 'Src/CallbackClass/CallbackClass.php';

$callback = new CallbackClass();
$result = $callback->processNotification($_POST);
?>
```

### Примеры использования
```php
<?php
// ... подключение библиотеки ...
$callback = new CallbackClass();
$notificationData = $callback->processNotification($_POST);

if ($notificationData['status'] == 'success') {
// Обработка успешного платежа
} else {
// Обработка ошибки
}
?>
```

## Вопросы и ответы

**Q: Как изменить пути для сохранения логов?**  
A: Используйте метод `SetLogsAndEvensWay` класса `SetWay`:
```php
$M = new SetWay();
$M->SetLogsAndEvensWay('/custom/logs/path', '/custom/events/path');
```

**Q: Как проверить корректность URL для запросов?**  
A: SDK автоматически проверяет URL на соответствие допустимым доменам: oos.pscb.ru или oosdemo.pscb.ru.

**Q: Как обрабатывать ошибки?**  
A: Все ошибки записываются в соответствующие log-файлы в указанной директории. Также можно анализировать возвращаемые значения методов.

**Q: Как настроить обратный редирект после успешной оплаты через СБП?**  
A: Используйте параметр `sbpRedirectUrl` при создании платежа:

```php
$data = array(
// ... другие параметры ...
"sbpRedirectUrl" ="https://your-site.com/success"
);
```

**Q: Как настроить язык платежной формы?**  
A: Используйте параметр `displayLanguage`:
```php
$data = array(
// ... другие параметры ...
"displayLanguage" ="en" // Доступные значения: "ru", "en"
);
```

**Q: Как включить режим отладки?**  
A: Добавьте параметр `debug` со значением `true`:
```php
$data = array(
    // ... другие параметры ...
    "debug" =true
);
```

**Q: Какой формат данных требуется для позиций чека?**  
A: Каждая позиция чека должна содержать следующие поля:
```php
array(
   "object" ='Название товара',
   "quantity" =1, // Количество
   "price" =100.50, // Цена за единицу
   "amount" =100.50 // Общая сумма
)
```

**Q: Как обрабатывать повторные платежи с одинаковым `orderId`?**  
A: SDK автоматически проверяет уникальность `orderId`. При попытке создать платеж с уже существующим `orderId` будет возвращена ошибка.

**Q: Как создавать установочные платежи для сохранения реквизитов карты?**  
A: Для сохранения реквизитов карты/создания установочных рекуррентных платежей используйте параметр `recurrentable`:
```php
$data = array(
// ... другие параметры ...
"recurrentable" = true
);
```

**Q: Как получить QR-код для оплаты?**  
A: Для получения QR-кода установите параметры `requestQrCodeImage` и `requestQrCodeImageUrl` в `true`:
```php
$data = array(
// ... другие параметры ...
"requestQrCodeImage" =true,
"requestQrCodeImageUrl" =true
);
```