# Приветствие
Добро пожаловать в документацию платежной системы Aaio.\
Тут мы поможем Вам интегрировать наш сервис в Ваш сайт либо бота и поможем в работе с API.
# Нашли проблему?
Нашли ошибку либо проблему?\
\
Напишите нам о ней!\
E-Mail: \
Telegram: [@aaioio\_Bot](https://t.me/aaioio_Bot)
# Готовые CMS модули и SDK
CMS модули:
*  \
[Opencart 2.3.x](/gotovye-cms-moduli-i-sdk/opencart-2.3.x) | [Opencart 3.x](/gotovye-cms-moduli-i-sdk/opencart-3.x)
* [DLE Billing](/gotovye-cms-moduli-i-sdk/dle-billing)
* .svg?alt=media\&token=bc9864d1-d3a8-4243-8b63-c14d11857526)\
[Billmanager 6](/gotovye-cms-moduli-i-sdk/billmanager-6)
* \
[WHMCS 5.x-8.x](/gotovye-cms-moduli-i-sdk/whmcs)
* [WooCommerce — Плагин для WordPress](/gotovye-cms-moduli-i-sdk/woocommerce-plagin-dlya-wordpress)
* [Xenforo 2.1.0+](/gotovye-cms-moduli-i-sdk/xenforo-2.1.0+)
SDK:
* .svg?alt=media\&token=433b32e2-1718-41bc-80e5-78bb5b4318ed)\
[Python 3](/gotovye-cms-moduli-i-sdk/python-3-sdk)
* .svg?alt=media\&token=e529b9ef-3d92-4f92-ada8-d570660a7549)\
[Typescript SDK](/gotovye-cms-moduli-i-sdk/typescript-sdk)
* \
[Java SDK](/gotovye-cms-moduli-i-sdk/java-sdk)
# WHMCS 5.x-8.x
Готовые CMS модули и SDK
Загрузите архив [aaio\_whmcs-5.x-8.x.zip](https://aaio.so/upload/cms/aaio_whmcs-5.x-8.x.zip)\
Разархивируйте архив\
\
**1.** С помощью FTP-клиента скопируйте папку **modules** в корень вашего сайта.\
Если требуется замена файлов, то нужно согласиться.\
\
**2.** Зайдите в панель администратора вашего сайта. \
Перейдите в меню **Настройки → Платежи → Платежные шлюзы** *(/admin/configgateways.php)*\
Активируйте модуль Aaio и укажите необходимые данные в настройках.
Нажмите на All Payment Gateways. Активируйте платежную систему нажав на кнопку Aaio
Сохраните изменения
**3.** Укажите URL Оповещения, Успехи и Ошибки в настройках магазина. \
Пример:\
\- URL Оповещения: *whmcs.example/modules/gateways/callback/aaio.php*\
\- URL Успеха (как пример - страница счетов): *whmcs.example/clientarea.php?action=invoices*\
\- URL Ошибки (как пример - страница счетов): *whmcs.example/clientarea.php?action=invoices*\
\ **\*** Где *whmcs.example* - укажите свой домен\
\
**4.** К приему платежей через **Aaio** готовы!\
\
*Модуль проверялся на WHMCS v8.1.1*
# Opencart 2.3.x
Готовые CMS модули и SDK
Загрузите архив [aaio\_opencart\_2.3.x.zip](https://aaio.so/upload/cms/aaio_opencart_2.3.x.zip)\
Разархивируйте архив\
\
**1.** С помощью FTP-клиента скопируйте папки **admin** и **catalog** в корень вашего сайта.\
Если требуется замена файлов, то нужно согласиться.\
\
**2.** Зайдите в панель администратора вашего сайта. \
Перейдите в меню **Модули/Расширения -> Модули/Расширения**.\
\
\
**3.** Из списка выберите тип расширения **Оплата**.\
\
\
**4.** Найдите модуль Aaio в списке платежных систем, затем активируйте его.\
\
\
**5.** После установки, нажмите **Редактировать**.\
**6.** Заполните все настройки и начните принимать платежи через **Aaio**!\
> Не забудьте указать URL Оповещения в настройках магазина
# Opencart 3.x
Готовые CMS модули и SDK
Загрузите архив [aaio\_opencart\_3.x.zip](https://aaio.so/upload/cms/aaio_opencart_3.x.zip)\
Разархивируйте архив\
\
**1.** С помощью FTP-клиента скопируйте папки **admin** и **catalog** в корень вашего сайта.\
Если требуется замена файлов, то нужно согласиться.\
\
**2.** Зайдите в панель администратора вашего сайта. \
Перейдите в меню **Модули/Расширения -> Модули/Расширения**.\
\
\
**3.** Из списка выберите тип расширения **Оплата**.\
\
\
**4.** Найдите модуль Aaio в списке платежных систем, затем активируйте его.\
\
\
**5.** После установки, нажмите **Редактировать**.\
**6.** Заполните все настройки и начните принимать платежи через **Aaio**!\
> Не забудьте указать URL Оповещения в настройках магазина
# DLE Billing
Готовые CMS модули и SDK
Загрузите архив [aaio\_dle\_billing\_0.7.x.zip](https://aaio.so/upload/cms/aaio_dle_billing_0.7.x.zip) (для Dle Billing 0.7.x) либо [aaio\_dle\_billing\_0.9.5+.zip](https://aaio.so/upload/cms/aaio_dle_billing_0.9.5+.zip) (для Dle Billing 0.9.5+)\
Разархивируйте архив\
\
**1.** С помощью FTP-клиента скопируйте папку **engine** в корень вашего сайта.\
Если требуется замена файлов, то нужно согласиться.\
\
**2.** Зайдите в панель администратора вашего сайта. \
Перейдите в раздел **Сторонние модули -> DLE Billing -> Платежные системы**\
\
\
**3.** Заполните все настройки и начните принимать платежи через **Aaio**!
> Не забудьте указать URL Оповещения в настройках магазина
# Billmanager 6
Готовые CMS модули и SDK
Загрузите архив [aaio\_billmgr6.zip](https://aaio.so/upload/cms/aaio_billmgr6.zip)\
Разархивируйте архив\
\
**1.** С помощью SFTP-клиента скопируйте папки в директорию `/usr/local/mgr5` на сервере.\
Если требуется замена файлов, то нужно согласиться.
> Для работы модуля требуются пакеты: **php-cli**, **php-common**, **php-xml**
\
**2.** Выдайте права **755** PHP файлам модуля и перезагрузите биллинг командами:
```bash
chmod 755 /usr/local/mgr5/cgi/aaio_payment.php
chmod 755 /usr/local/mgr5/cgi/aaio_result.php
chmod 755 /usr/local/mgr5/include/php/bill_func_aaio.php
chmod 755 /usr/local/mgr5/paymethods/pmaaio.php
/usr/local/mgr5/sbin/mgrctl exit -m billmgr
```
\
**3.** Перейдите в Billmanager под аккаунтом администратора в раздел **Провайдер -> Методы оплаты -> Создать**\
**4.** Найдите модуль **Aaio** и нажмите **Добавить**\
**5.** Заполните все настройки\
**6.** Начните принимать платежи через **Aaio**!
> Не забудьте указать URL Оповещения в настройках магазина.\
> Пример: **billmgr\_url.example/mancgi/aaio\_result.php**
> Debug журнал метода оплаты находится по адресу **/usr/local/mgr5/var/pmaaio.log**
# WooCommerce — Плагин для WordPress
Готовые CMS модули и SDK
{% hint style="info" %}
Ожидается
{% endhint %}
# Xenforo 2.1.0+
Готовые CMS модули и SDK
**Требования:**\
Версия PHP >= 7.4\
Версия Xenforo >= 2.1.0
**Инструкция по установке:**\
**1.** В корень с сайтом загрузить содержимое архива [TC-PaygateAaio-1.0.1.zip](https://aaio.so/upload/cms/TC-PaygateAaio-1.0.1.zip)\
**2.** Установить плагин стандартными средствами **Xenforo**\
**3.** На форуме создать платежный шлюз на странице **/admin.php?payment-profiles** и указать требуемые данные (ID магазина, секретный ключ 1 и 2)\
**4.** В настройках магазина **Aaio** указать:\
\- **URL Оповещения** в формате:\
`https://{forum_domain}/payment_callback.php?_xfProvider=tcAaio`\
\- **URL Успешной и Неудачной оплаты** в формате:\
`https://{forum_domain}/tc-pg-aaio`\
**5.** Начните принимать платежи через **Aaio**!
# Python 3 SDK
Готовые CMS модули и SDK
Благодаря поддержке пользователей, уже имеем целых 3 версии SDK от разных разработчиков.
1\. SDK от [**kewldan**](https://t.me/kewldan) **и** [**lolkof**](https://t.me/lolkof) **(Рекомендуем)**\
Подробнее на сайте [**PyPI**](https://pypi.org/project/aaio)\
**Для установки используйте команду:**\
`pip install aaio`
2\. SDK от [**Belyashik2K**](mailto:lovelybelyashik@gmail.com)\
Подробнее на сайте [**PyPI**](https://pypi.org/project/AaioAsync)\
**Для установки используйте команду:**\
`pip install AaioAsync`
3\. SDK от [**Fre4ka**](mailto:yusufbek0303@gmail.com)\
Подробнее на сайте [**PyPI**](https://pypi.org/project/AaioAPI)\
**Для установки используйте команду:**\
`pip install AaioAPI`
# Typescript SDK
Готовые CMS модули и SDK
Благодаря поддержке пользователя, уже имеем 1 версию SDK от разработчика.\
\
1\. SDK от [**kewldan**](https://t.me/kewldan)\
Подробнее на сайте [**npm**](https://www.npmjs.com/package/aaio.js)\
**Для установки используйте команду:**\
`npm i aaio.js`
# Java SDK
Готовые CMS модули и SDK
Благодаря поддержке пользователя, уже имеем 1 версию SDK от разработчика.\
\
1\. SDK от [itskekoff](https://github.com/itskekoff)\
Подробнее на сайте [**Github**](https://github.com/itskekoff/AaioPaymentsSDK)\
**Для установки следуйте инструкции в репозитории Github**
# Создание заказа запросом (Рекомендуем)
{% hint style="info" %}
**Почему рекомендуем создавать заказ именно отправляя запрос на сервер?** \
*В связи с зачастившими блокировками домена мы выделяем новый домен под форму оплаты. Чтобы не менять его каждый раз в продакшене, мы решили сделать данный метод который будет возвращать Вам всегда актуальный URL для оплаты!*
{% endhint %}
> **Данные для запроса такие-же как и в переходе на форму.** \
> Все сделали для удобства перехода и меньшей мороки в коде.
## Запрос
`POST` `https://aaio.so/merchant/get_pay_url`
### Заголовки
`Accept: application/json` **\***\
`Content-Type: application/x-www-form-urlencoded` **\***
#### Определения **\***** - обязательные заголовки. Без них Вы не сможете получить корректный ответ.**
### Параметры (url-encoded)
name
type
description
merchant_id *
uuid
ID Вашего магазина
amount *
double
Сумма к оплате в валюте магазина (Если в сумме есть копейки, то отправляйте их с разделителем "." Пример: 100.18)
order_id *
string min: 1 max: 64
Идентификатор заказа в Вашей системе. Значение параметра может содержать только буквы, цифры и символы : , -, _, [, ] ,|.
Валюта заказа. Доступные значения: RUB, UAH, EUR, USD
method
string
Кодовое название платежной системы (см. способы оплаты). Предлагаемый способ оплаты. Клиент сможет изменить его в процессе оплаты
desc
string min: 1 max: 512
Описание заказа (показывается клиенту при оплате)
email
string
E-Mail клиента
lang
string
Язык интерфейса. Доступные значения: ru, en. По умолчанию: ru
referral
string
Внимание! Код реферала недоступен для данного метода, так-как пользователь будет отправлен не на основной домен aaio.so.
us_key
string min: 1 max: 2056
Так же Вы можете передавать свои параметры, которые наш сервер вернет на Ваш URL оповещения. Ключи параметров должны начинаться с us_ и содержать только латинские символы и цифры. Максимальная длина - 15. Значения параметров могут содержать только буквы, цифры и символы -, _, [, ], + ,=,|. Например:
us_name=ivanov&us_login=ivanov1971
Обратите внимание! Параметры передаются в формате `application/x-www-form-urlencoded`
## Примеры ответа
**Формат ответа** `application/json`
{% tabs %}
{% tab title="Успех - 200" %}
```json
{
"type": "success",
"url": "https://......" // URL для оплаты
}
```
{% endtab %}
{% tab title="Ошибка: 400, 401, 429, 500, 503 " %}
**Пользовательские коды ошибок** - `400`, `401`, `429`\
**Серверные коды ошибок** - `500`, `503`
```json
{
"type": "fail",
"code": "400",
"message": "message"
}
```
{% endtab %}
{% tab title="Другой код ответа" %}
Если код ответа другой, то возможна проблема на стороне сервера API. \
**Рекомендуем учитывать такие ситуации в коде.**
{% endtab %}
{% endtabs %}
## Готовые примеры запроса
{% tabs %}
{% tab title="PHP" %}
```php
$merchant_id,
'amount' => $amount,
'currency' => $currency,
'order_id' => $order_id,
'sign' => $sign,
'desc' => $desc,
'lang' => $lang
]));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 15); // Таймаут подключения к нашему серверу
curl_setopt($ch, CURLOPT_TIMEOUT, 60); // Таймаут обработки запроса
$result = curl_exec($ch); // Ответ
$http_code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // Код ответа
if (curl_errno($ch)) {
die('Connect error:' . curl_error($ch)); // Вывод ошибки соединения
}
curl_close($ch);
if(!in_array($http_code, [200, 400, 401])) {
die('Response code: ' . $http_code); // Вывод неизвестного кода ответа
}
$decoded = json_decode($result, true); // Парсинг результа. На выходе получаем массив данных
if(json_last_error() !== JSON_ERROR_NONE) {
die('Не удалось пропарсить ответ');
}
if($decoded['type'] == 'success') {
print_r($decoded); // Вывод результата
} else {
die('Ошибка: ' . $decoded['message']); // Вывод ошибки
}
```
{% endtab %}
{% endtabs %}
# Методика формирования подписи
Создание заказа запросом (Рекомендуем)
Подпись для создания заказа формируется путем нахождения `SHA256` Хеша от строки:\
"`ID Вашего магазина`**:**`Сумма к оплате`**:**`Валюта`**:**`Секретный ключ №1 из настроек магазина`**:**`Идентификатор заказа в Вашей системе`"
# Создание заказа переходом на форму (Устаревшее)
{% hint style="info" %}
**Почему не рекомендуем создавать заказ отправляя пользователя на форму?** \
*В связи с зачастившими блокировками домена мы выделяем новый домен под форму оплаты. Чтобы не менять его каждый раз в продакшене, Вам лучше использовать* [***Создание заказа запросом***](/priem-platezhei/sozdanie-zakaza-zaprosom-rekomenduem)\
\
***Если же домен aaio.so не заблокирован в Вашей стране где ведете бизнес - то смело используйте данный метод.*** \
***Данный метод не будет удален, он все еще поддерживается.***
{% endhint %}
Для создания заказа в магазине Вам необходимо отправить Покупателя на подготовленный URL `GET` либо `POST` запросом с параметрами (в формате **form-data**).
URL `https://aaio.so/merchant/pay`
Параметры (\* обязательные):
Параметр
Тип
Описание
merchant_id *
UUID
ID Вашего магазина
amount *
float
Сумма к оплате в валюте магазина (Если в сумме есть копейки, то отправляйте их с разделителем "." Пример: 100.18)
order_id *
string min: 1 max: 64
Идентификатор заказа в Вашей системе.
Значение параметра может содержать только буквы, цифры и символы : , -, _, [, ] ,|.
Валюта заказа. Доступные значения: RUB, UAH, EUR, USD
method
string
Кодовое название платежной системы (см. способы оплаты). Предлагаемый способ оплаты. Клиент сможет изменить его в процессе оплаты
desc
string min: 1 max: 512
Описание заказа (показывается клиенту при оплате)
email
string
E-Mail клиента
lang
string
Язык интерфейса. Доступные значения: ru, en. По умолчанию: ru
referral
string
Код реферала. Добавим данный код в Cookie покупателя. Если в течении 30 дней покупатель зарегистрируется в сервисе с данным кодом - он будет считаться Вашим рефералом
us_key
string min: 1 max: 2056
Так же Вы можете передавать свои параметры, которые наш сервер вернет на Ваш URL оповещения.
Ключи параметров должны начинаться с us_ и содержать только латинские символы и цифры. Максимальная длина - 15.
Значения параметров могут содержать только буквы, цифры и символы -, _, [, ], + ,=,|.
# Методика формирования подписи
Создание заказа переходом на форму (Устаревшее)
Подпись для создания заказа формируется путем нахождения `SHA256` Хеша от строки:\
"`ID Вашего магазина`**:**`Сумма к оплате`**:**`Валюта`**:**`Секретный ключ №1 из настроек магазина`**:**`Идентификатор заказа в Вашей системе`"
# Пример формы на PHP
Создание заказа переходом на форму (Устаревшее)
<?php
$merchant_id = ''; // ID Вашего магазина
$amount = 10.54; // Сумма к оплате
$currency = 'RUB'; // Валюта заказа
$secret = ''; // Секретный ключ №1 из настроек магазина
$order_id = 'php_form_order_1'; // Идентификатор заказа в Вашей системе
$sign = hash('sha256', implode(':', [$merchant_id, $amount, $currency, $secret, $order_id]));
$desc = 'Order Payment'; // Описание заказа
$lang = 'ru'; // Язык формы
?>
```html
```
# Пример получения ссылки на PHP
Создание заказа переходом на форму (Устаревшее)
# Пример получения ссылки на Python
Создание заказа переходом на форму (Устаревшее)
```python
import hashlib
from urllib.parse import urlencode
merchant_id = '' # ID Вашего магазина
amount = 10.54 # Сумма к оплате
currency = 'RUB' # Валюта заказа
secret = '' # Секретный ключ №1 из настроек магазина
order_id = 'python_order_1' # Идентификатор заказа в Вашей системе
desc = 'Order Payment' # Описание заказа
lang = 'ru' # Язык формы
sign = f':'.join([
str(merchant_id),
str(amount),
str(currency),
str(secret),
str(order_id)
])
params = {
'merchant_id': merchant_id,
'amount': amount,
'currency': currency,
'order_id': order_id,
'sign': hashlib.sha256(sign.encode('utf-8')).hexdigest(),
'desc': desc,
'lang': lang
}
# Выводим ссылку
print("https://aaio.so/merchant/pay?" + urlencode(params))
```
# Редирект клиента с формы оплаты
Редирект с формы оплаты на Ваши URL Успеха и Неудачи выполняется `GET` запросом с параметрами (в формате **form-data**):
Параметр
Тип
Описание
order_id
string
Идентификатор заказа в Вашей системе
amount
float
Сумма заказа
currency
string
Валюта заказа. Доступные значения: RUB, UAH, EUR, USD
# Оповещение об оплате заказа
## Как это работает?
После оплаты заказа мы один раз отправляем **HTTP уведомление** на Ваш **URL Оповещения**.\
**Важно!** Мы не отправляем повторно **HTTP уведомление** в случае неуспешного ответа. Если до Вас уведомление не дошло, в списке заказов будет отображатся ошибка возле статуса заказа **"HTTP 4xx"**. **Вы всегда можете самостоятельно отправить уведомление.**\
\
Отправляем уведомление только **POST** запросом с параметрами в формате **form-data (var1=val1\&var2=val2...)**. Отправка уведомления будет выполнена, если у Вашего магазина указан **URL Оповещения**.
> Прежде чем принимать запросы от нашего сервера, убедитесь что наши IP Адреса могут зайти на Ваш сайт.
**Параметры которые мы отправляем:**
Параметр
Тип
Описание
status
string
Статус заказа. Проверять необязательно!
Может иметь значения: success - Оплачен hold - Оплачен, но средства в холде Оба статуса означают что заказ успешно оплачен!
Не у всех методов может сообщать о холде. Это исправляем.
merchant_id
UUID
ID Вашего магазина
invoice_id
UUID
ID заказа в нашей системе
order_id
string min: 1 max: 64
Идентификатор заказа в Вашей системе
amount
float
Сумма заказа
currency
string
Валюта заказа. Доступные значения: RUB, UAH, EUR, USD
profit
float
Сумма зачисленная Вам на баланс в RUB
commission
float
Сумма комиссии магазина в RUB
commission_client
float
Сумма комиссии клиента в RUB
commission_type
text
Формат соотношения: Комиссия магазина:Комиссия покупателя Пример: 100:0
Кодовое название платежной системы (см. способы оплаты)
desc
string min: 1 max: 512
Описание заказа
email
string
E-Mail покупателя
us_key
string min: 1 max: 2056
Дополнительные параметры с префиксом us_ переданные в форму оплаты
\
# Методика формирования подписи
Оповещение об оплате заказа
Подпись для скрипта оповещения формируется путем нахождения `SHA256` Хеша от строки:\
"`ID Вашего магазина`**:**`Сумма к оплате`**:**`Валюта`**:**`Секретный ключ №2 из настроек магазина`**:**`Идентификатор заказа в Вашей системе`"
# Пример обработчика на PHP
Оповещение об оплате заказа
```php
1) {
$ip = $explode[0];
}
return trim($ip);
}
// Проверка на IP адрес сервиса (по желанию)
$ctx = stream_context_create([
'http' => [
'timeout' => 10
]
]);
$ips = json_decode(file_get_contents('https://aaio.io/api/public/ips', false, $ctx));
if (isset($ips->list) && !in_array(getIP(), $ips->list)) {
die("hacking attempt");
}
// Конец проверки на IP адрес сервиса
$sign = hash('sha256', implode(':', [$_POST['merchant_id'], $_POST['amount'], $_POST['currency'], $secret, $_POST['order_id']]));
if (!hash_equals($_POST['sign'], $sign)) {
die("wrong sign");
}
//Так же, рекомендуется проверять не был ли этот заказ уже оплачен или отменен
//Оплата прошла успешно, можно проводить операцию.
die('OK');
```
# Оповещение о выполнении либо отмене вывода
Добавлено 08.09.2023
## Как это работает?
После **отмены** либо **выполнения** вывода мы один раз отправляем **HTTP уведомление** на Ваш **URL Оповещения**.\
**Важно!** Мы не отправляем повторно **HTTP уведомление** в случае неуспешного ответа. Если до Вас уведомление не дошло, в списке выводов будет отображатся ошибка возле статуса вывода **"HTTP 4xx"**. **Вы всегда можете самостоятельно отправить уведомление.**\
\
Отправляем уведомление только **POST** запросом с параметрами в формате **form-data (var1=val1\&var2=val2...)**. Отправка уведомления будет выполнена, если у Вас в [настройках аккаунта](https://aaio.so/business/api/payoff-webhook) указан **URL Оповещения**, либо Вы указали его при создании вывода в параметре **webhook\_url.**
**Важно!** Отправляем **HTTP уведомление** только по тем заявкам, которые созданы через **API**.
> Прежде чем принимать запросы от нашего сервера, убедитесь что наши IP Адреса могут зайти на Ваш сайт.
**Параметры которые мы отправляем:**
