moneta-sdk-php v2.0.0

This commit is contained in:
2025-02-24 22:31:15 +03:00
commit 7a455450ce
16 changed files with 1443 additions and 0 deletions
+36
View File
@@ -0,0 +1,36 @@
## Базовые методы Moneta SDK PHP
[Документация Монеты](https://docs.moneta.ru/)
* [Генерация ссылки на оплату с помощью MONETA.Assistant](#Генерация-платежа-assistant)
* [Документация SDK](#Документация)
---
### Генерация ссылки на оплату с помощью MONETA.Assistant<a name="Генерация-платежа-assistant"></a>
[Создание платежа в документации](https://docs.moneta.ru/protocols/#get-/-ASSTNT--payment)
Чтобы сгенерировать ссылку на оплату, нужно создать объект `MonetaSdk`. Он принимает следующие параметры:
1. ID заказа*;
2. Сумма заказа*;
3. Описание заказа.
`*` --- обязательный параметр. Должен быть передан.
Затем вам требуется вызвать метод `getAssistantPaymentLink`. В ответе вам вернется ссылка на оплату, на которую вы должны переадресовать плательщика.
```php
include_once('vendor/autoload.php');
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 123.45);
$paymentLink = $mSdk->getAssistantPaymentLink();
if(!empty($paymentLink)){
header('Location: ' . $paymentLink);
}
```
---
## Документация SDK <a name="Документация"></a>
- #### [Описание config-файлов](config.md);
- #### [Обработка http-уведомлений от Монеты](notifications.md);
- #### [Методы MerchantAPI](merchantAPI.md).
+41
View File
@@ -0,0 +1,41 @@
## Настройки Moneta SDK PHP
Все файлы с настройками лежат по пути `moneta-sdk-new/config/`. Все настройки возвращают ассоциативный массив (ключ - значение).
[Документация Монеты](https://docs.moneta.ru/)
* [Описание account.php](#Описание-account)
* [Описание api.php](#Описание-api)
* [Описание url.php](#Описание-url)
* [Документация SDK](#Документация)
---
1. `account.php` <a name="Описание-account"></a> --- данные от учетной записи:
`id`* --- номер бизнес-счета в системе Монета;
`secret`* --- код проверки целостности данных, указанный в настройках счета в [Монета | PayAnyWay](https://www.payanyway.ru/backoffice/accounts/business);
`demo_mode` --- ставится значение `true`, если тестируете интеграцию на демо-стенде (demo.moneta.ru);
`username`** --- логин от личного кабинета [Монета | PayAnyWay](https://www.payanyway.ru/backoffice/auth/signin);
`password`** --- пароль от личного кабинета [Монета | PayAnyWay](https://www.payanyway.ru/backoffice/auth/signin);
`payment_password`** --- платежный пароль, указанный в настройках счета в [Монета | PayAnyWay](https://www.payanyway.ru/backoffice/accounts/business);
`locale` --- локализация. `ru` -- русская локализация, `en` -- английская. Используется при вызове платежной формы;
`currency` --- валюта. Пока доступно только одно значение -- `RUB`;
`unit_id` --- платежная система по умолчанию. При отображении платежной формы, позволяет выводить первым указанную платежную систему, например, СБП. Доступные значения платежных систем можно найти в разделе "Счета" → "Настройки способа оплаты" → "Разработчику" → "paymentSystem.unitId";
`limit_ids` → ограниченный список платежных систем на платежной форме. Позволяет оставить на платежной форме только указанные платежные системы. Например, только СБП и SberPay.
Параметры, отмеченные `*`, являются обязательными.
Параметры, отмеченные `**`, являются обязательными, если вы планируете использовать методы MerchantAPI.
2. `api.php` <a name="Описание-api"></a> --- системные параметры для MerchantAPI, **изменять их не нужно**:
`payment_url` --- url-ы, на которые шлются запросы;
`urn` --- urn, который используется для запросов при указании в заголовке запроса `username` и `password`;
3. `url.php` <a name="Описание-url"></a> --- адреса на страницы интернет-магазина, куда осуществляется перевод пользователя после обработки формы оплаты заказа:
`success` --- страница магазина, на которой информируется успешный приеме платежа;
`fail` --- страница магазина, где отображается информация о неудачной оплате;
`inprogress` --- страница магазина, где отображается информация о том, что платёж находится в процессе обработки;
`return` --- страница магазина, куда пользователь попадает после завершения оплаты заказа;
`iframe_target` --- одно из значений — `_parent`, `_blank`, `_self_`, , `_top_`, которое используется для настройки окна возврата при интеграции страницы оплаты в iframe. Речь идёт об использовании виджета оплаты заказа вместо полноценной страницы оплаты.
## Документация SDK <a name="Документация"></a>
- #### [Базовые методы](baseMethods.md);
- #### [Обработка http-уведомлений от Монеты](notifications.md);
- #### [Методы MerchantAPI](merchantAPI.md).
+144
View File
@@ -0,0 +1,144 @@
## Методы MerchantAPI
[Документация Монеты](https://docs.moneta.ru/)
* [Однофазный платеж](#однофазный-платеж)
* [Двухфазный платеж (операция с холдированием)](#двухфазный-платеж)
* [Подтверждение операции](#подтверждение-операции)
* [Отмена операции](#отмена-операции)
* [Привязка карты (получение токена для рекуррентных платежей)](#привязка-карты)
* [Оплата по рекуррентному токену](#рекуррентный-платеж)
* [Возврат по операции](#возврат)
* [Получить детали операции по ID](#детали-операции-по-id)
* [Документация SDK](#Документация)
---
> **Эти методы доступны только для юридических лиц и ИП. Чтобы узнать, поддерживает ли ваш бизнес-счёт рекуррентные платежи и операции с холдированием, обратитесь в коммерческий отдел: com@payanyway.ru.**
### Однофазный платеж <a name="однофазный-платеж"></a>
[Однофазный платеж в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--invoice-request--simple)
Создайте объект `MonetaSdk`, передав номер заказа и сумму, а также по желанию описание. Затем вызовите метод `createInvoice`, будет возвращен номер операции в системе Монета. Данный номер операции требуется передать в метод `getPaymentLink`, тем самым можно получить ссылку на оплату, по которой надо будет перевести плательщика.
```php
include_once('vendor/autoload.php');
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 123.45);
$operationId = $mSdk->createInvoice();
$paymentLink = $mSdk->getPaymentLink($operationId);
if (!empty($paymentLink)) {
header('Location: ' . $paymentLink);
}
```
---
### Двухфазный платеж (операция с холдированием) <a name="двухфазный-платеж"></a>
[Двухфазный платеж в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--invoice-request--hold)
Создайте объект `MonetaSdk`, передав номер заказа и сумму, а также по желанию описание. Затем вызовите метод `createInvoice` и передайте в качестве аргумента true, будет возвращен номер операции с холдированием в системе Монета. Данный номер операции требуется передать в метод `getPaymentLink`, тем самым можно получить ссылку на оплату, по которой надо будет перевести плательщика.
```php
include_once('vendor/autoload.php');
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 123.45);
$operationId = $mSdk->createInvoice(true);
$paymentLink = $mSdk->getPaymentLink($operationId);
if (!empty($paymentLink)) {
header('Location: ' . $paymentLink);
}
```
> **При проведении двухфазного платежа(холдирование), нужно подтвердить или отменить операцию.**
---
### Подтверждение операции<a name="подтверждение-операции"></a>
[Подтверждение операции в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--confirm-transaction-request)
Чтобы подтвердить операцию нужно создать объект `MonetaSdk`, передать номер заказа и вызвать метод `confirmInvoice`, передав номер операции. В ответе будет возвращен массив с информацией об операции.
```php
include_once('vendor/autoload.php');
$orderId = $_POST['MNT_TRANSACTION_ID'];
$operationId = $_POST['MNT_OPERATION_ID'];
$mSdk = new Moneta\MonetaSdk($transactionId);
$mSdk->confirmInvoice($operationId);
```
---
### Отмена операции<a name="отмена-операции"></a>
[Отмена операции в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--cancel-transaction-request)
Чтобы отменить операцию нужно создать объект `MonetaSdk`, передать номер заказа и вызвать метод `confirmInvoice`, передав номер операции. В ответе будет возвращен массив с информацией об операции.
```php
include_once('vendor/autoload.php');
$orderId = $_POST['MNT_TRANSACTION_ID'];
$operationId = $_POST['MNT_OPERATION_ID'];
$mSdk = new Moneta\MonetaSdk($transactionId);
$mSdk->cancelInvoice($operationId);
```
---
### Привязка карты (получение токена для рекуррентных платежей)<a name="привязка-карты"></a>
[Привязка карты в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--payment-request--get-token-only)
Для привязки карты создайте объект `MonetaSdk`, передав номер, сумму заказа, и, при необходимости, описание. Затем вызовите метод `createRecurrentInvoice` — он вернёт номер операции в системе Монета.в. Этот номер нужно передать в метод `getPaymentLink`, чтобы получить ссылку для оплаты, по которой надо будет перевести плательщика.
```php
include_once('vendor/autoload.php');
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 456.78);
$operationId = $mSdk->createRecurrentInvoice();
$paymentLink = $mSdk->getPaymentLink($operationId);
if (!empty($paymentLink)) {
header('Location: ' . $paymentLink);
}
```
На платежной форме плательщику потребуется ввести свои карточный данные, а также поставить галочку в чекбоксе "Запомнить карту". После успешной оплаты, на указанный PayURL, указанный в настройках бизнес-счета будет отправлено http-уведомление, в котором будет передан токен для рекуррентных платежей (название параметра в уведомлении: `paymenttoken`). Чтобы проводить рекуррентный платеж без дальнейшего участия плательщика: требуется записать токен в базу данны.___
### Оплата по рекуррентному токену<a name="рекуррентный-платеж"></a>
[Оплата по рекуррентному токену в документации](https://docs.moneta.ru/protocols/#post-/-MRCHNT--payment-request--by-token)
Чтобы привязать карту, создайте объект `MonetaSdk`, передав номер заказа, сумму и, при необходимости, описание. Затем вызовите метод recurringPayment, передав токен плательщика, который получили и сохранили в сценарии "[Привязка карты (получение токена для рекуррентных платежей)](#привязка-карты)". В ответе вы получите массив с информацией об операции.
```php
include_once("moneta-sdk-lib/autoload.php");
$paymentToken = '123456';
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 123.45, 'Оплата за подписку, январь 2025');
$mSdk->recurringPayment($paymentToken);
```
> Обратите внимание: при вызове `recurringPayment` в системе Монеты к переданному номеру заказа добавится "_MONETA" с временной меткой. Например, "6787bc9f456b29.67450389_MONETA1736948895". Это нужно для уникальности номера заказа, иначе операция не создастся. Чтобы получить исходный номер заказа из уведомления, разделите MNT_TRANSACTION_ID с помощью функции `explode`: `explode('_MONETA', $transactionId)[0]`.
---
### Возврат по операции<a name="возврат"></a>
[Возврат по операции в документации (стр. 218)](https://www.moneta.ru/doc/MONETA.MerchantAPI.v2.ru.pdf)
Чтобы выполнить возврат, создайте объект `MonetaSdk`, передав номер, сумму возврата и, при необходимости, описание. Затем вызовите метод refund, передав номер операции из системы Монета. В ответе вы получите массив с информацией о возврате.
```php
include_once("moneta-sdk-lib/autoload.php");
$mSdk = new Moneta\MonetaSdk(uniqid('', true), 123.45, 'Возврат по заказу ' . uniqid('', true));
$operationId = 1234567890;
$mSdk->refund($operationId);
```
---
### Получить детали операции по ID<a name="детали-операции-по-id"></a>
[Возврат по операции в документации (стр. 240)](https://www.moneta.ru/doc/MONETA.MerchantAPI.v2.ru.pdf)
Создайте объект `MonetaSdk`, передав пустой номер заказа. Затем вызовите метод `getOperationDetailsById`, передав номер операции, по которой нужно получить информацию. В ответе вам вернется массив с информацией об операции в системе Монета.
```php
include_once("moneta-sdk-lib/autoload.php");
$mSdk = new Moneta\MonetaSdk('');
$operationId = 1234567890;
$mSdk->getOperationDetailsById($operationId);
```
---
## Документация SDK <a name="Документация"></a>
- #### [Базовые методы](baseMethods.md);
- #### [Описание config-файлов](config.md);
- #### [Обработка http-уведомлений от Монеты](notifications.md);
+180
View File
@@ -0,0 +1,180 @@
## Обработка http-уведомлений от Монеты
[Документация Монеты](https://docs.moneta.ru/)
* [Минимальный ответ на платежное уведомление (PayURL)](#Минимальный-ответ-pay-url)
* [Ответ с передачей номенклатуры (PayURL)](#Ответ-с-номенклатурой-pay-url)
* [Ответ на проверочный запрос с передачей номенклатуры (CheckURL)](#Ответ-с-номенклатурой-pay-url)
* [Документация SDK](#Документация)
---
### Минимальный ответ на платежное уведомление (PayURL)<a name="Минимальный-ответ-pay-url"></a>
[Минимальный ответ в документации](https://docs.moneta.ru/payments/payment-notification/)
Чтобы сгенерировать минимальный ответ для платежного уведомления от Монеты, требуется создать объект `MonetaSDK` и передать номер заказа. В результате для Монеты будет предоставлен минимальный ответ `SUCCESS` и на стороне платежной системы статус операции будет изменен на "Выполнена"
```php
include_once('vendor/autoload.php');
$orderId = $_POST['MNT_TRANSACTION_ID'];
$mSdk = new Moneta\MonetaSdk($orderId);
$mSdk->responseToPaymentNotification();
```
---
### Ответ с передачей номенклатуры (PayURL)<a name="Ответ-с-номенклатурой-pay-url"></a>
[Ответ с передачей номенклатуры в документации (раздел "Передача номенклатуры через ответ скрипта Pay URL")](https://docs.moneta.ru/54-fz/module/_index.files/Assistant54FZ.pdf)
Чтобы передать номенклатуру в ответе на платежное уведомление, нужно создать объект `MonetaSdkReceipt` и заполнить переменные объекта:
1. `items`* --- переменная товаров, тип `array`.
В примере ниже показан максимальный и минимальный набор передаваемых параметров товара. Подробное о параметрах и их значениях можно прочитать в [документации раздел "Передача номенклатуры через ответ скрипта Pay URL"](https://docs.moneta.ru/54-fz/module/_index.files/Assistant54FZ.pdf).
> Обратите внимание, что значения `vat` отличаются от того, что написано в документации:
> `none` - без НДС
> `vat0` - НДС по ставке 0%
> `vat10` - НДС чека по ставке 10%
> `vat110` - НДС чека по расчетной ставке 10/110
> `vat20` - НДС чека по ставке 20%
> `vat120` - НДС чека по расчетной ставке 20/120
> `vat5` - 5%
> `vat15` - по расчётной ставке 5%
> `vat7` - 7%
> `vat17` - по расчётной ставке 7
2. `customer`* --- переменная плательщика, тип `array`.
Используется для отправки чека. Параметр `email` --- обязательный
3. `delivery` --- переменная доставки, тип `float`.
Если есть доставка, то указать ее стоимость.
Параметры, отмеченные *, являются обязательными. Их нужно передать при создании объекта MonetaSDKReceipt.
После этого создайте объект `MonetaSDK`, передав номер заказа и сумму. Затем вызовите метод `responseToPaymentNotification`, передайте в него ранее созданный объект `MonetaSdkReceipt`. В результате система Монета получит ответ в формате XML, статус операции изменится на "Выполнена", а в кассовый сервис [kassa.payanyway](https://kassa.payanyway.ru/) будет передана номенклатура для печати чеков.
```php
include_once('vendor/autoload.php');
$mSdkReceipt = new Moneta\MonetaSdkReceipt();
// "Тестовый товар №1" ——— максимальный набор параметров товара
// "Тестовый товар №2" ——— минимальный набор параметров товара
$mSdkReceipt->items = [
[
'name' => 'Тестовый товар №1',
'price' => 123.45,
'quantity' => 1,
'measure' => 'шт',
"paymentMethod" => "full_payment",
"paymentObject" => "commodity",
'vat' => 'none',
'agentInfo' => [
'type' => 'payment_agent',
],
'supplierInfo' => [
'name' => 'Поставщик 1',
'inn' => '1234567890',
'phones' => [
'79995558844',
'79998855221'
]
]
],
[
'name' => 'Тестовый товар №2',
'price' => 999,
'quantity' => 2,
]
];
$mSdkReceipt->customer = [
'email' => 'com@moneta.ru',
'phone' => '74956465848'
];
$mSdkReceipt->delivery = 456.78;
$orderId = $_POST['MNT_TRANSACTION_ID'];
$mSdk = new Moneta\MonetaSdk($orderId);
$mSdk->responseToPaymentNotification($mSdkReceipt);
```
---
### Ответ на проверочный запрос с передачей номенклатуры (CheckURL)<a name="Ответ-с-номенклатурой-check-url"></a>
[Ответ на проверочный запрос с передачей номенклатуры (раздел "Ответ на проверочный запрос (check url - уведомление)")](https://www.payanyway.ru/info/p/ru/public/merchants/cmsspecification.pdf)
Если вы используете кассу БПА ПА (Payanyway) и в настройках счёта указан CheckURL, вам нужно ответить на проверочный запрос, передав номенклатуру. Ответ нужно предоставить до оплаты. Если система магазина не ответит на запрос, пользователь не сможет перейти к оплате.
Чтобы передать номенклатуру в ответе, создайте объект `MonetaSdkReceipt` и заполните его переменные:
1. `items`* --- переменная товаров, тип `array`.
В примере ниже показан максимальный и минимальный набор передаваемых параметров товара. Подробное о параметрах и их значениях можно прочитать в документации в разделе "Ответ на проверочный запрос (check url - уведомление)".
2. `customer`* --- переменная плательщика, тип `array`.
Используется для отправки чека. Параметр `email` --- обязательный
3. `delivery` --- переменная доставки, тип `float`.
Если есть доставка, то указать ее стоимость.
`*` --- обязательная переменная, её нужно заполнить.
После заполнения переменных создайте объект `MonetaSDK`, передав номер заказа и сумму. Затем вызовите метод `responseToCheckRequest`, передав в него ранее созданный объект `MonetaSdkReceipt`. В результате система Монета получит ответ в формате JSON, и пользователь сможет перейти на страницу оплаты.
```php
include_once('vendor/autoload.php');
$mSdkReceipt = new Moneta\MonetaSdkReceipt();
$mSdkReceipt->items = [
[
'name' => 'Тестовый товар №1',
'price' => 123.45,
'quantity' => 1,
'measure' => 'шт',
"paymentMethod" => "full_payment",
"paymentObject" => "commodity",
'vat' => 'none',
'agentInfo' => [
'payingAgent' => [
'operation' => 'Наименование операции банковского платежного агента',
'phones' => [
'79995558844',
'79998855221'
]
],
'supplierInfo' => [
'name' => 'Поставщик 1',
'inn' => '1346',
'phones' => [
'79995558844',
'79998855221'
]
]
]
],
[
'name' => 'Тестовый товар2',
'price' => 999,
'quantity' => 2,
]
];
$mSdkReceipt->customer = [
'name' => 'Иванов Иван Иванович',
'inn' => '1234567890',
'email' => 'com@moneta.ru',
'phone' => '75556664477'
];
$mSdkReceipt->additionalCheckProp = 'Дополнительный реквизит чека';
$mSdkReceipt->additionalUserProps = [
'name' => 'Доп. реквизиты пользователя',
'value' => 'Значение',
];
$mSdkReceipt->delivery = 456.78;
$orderId = $_POST['MNT_TRANSACTION_ID'];
$amount = $_POST['MNT_AMOUNT'];
$mSdk = new Moneta\MonetaSdk($orderId, $amount);
$mSdk->responseToCheckRequest($mSdkReceipt);
```
> **Если вы передаете номенклатуру в ответе на проверочный запрос, то на платежное уведомление можно отдать минимальный ответ в виде SUCCESS ([Пример](#Минимальный-ответ-pay-url))**.
---
## Документация SDK <a name="Документация"></a>
- #### [Описание config-файлов](config.md);
- #### [Базовые методы](baseMethods.md);
- #### [Методы MerchantAPI](merchantAPI.md).