> For the complete documentation index, see [llms.txt](https://docs.merchant.alb.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.merchant.alb.ua/platizhni-vidzheti-dlya-cms/opencart/funkcional-ta-opis-platizhnogo-modulya.md).

# Функціонал та опис платіжного модуля

Приймання платежів, підписки та рекурентні списання, перевірка операцій, PREAUTH / COMPLETION і повернення коштів у модулях AlliancePay для OpenCart 3 і 4.

### Перевірка статусу замовлення

Перед початком роботи заповніть параметри за інструкцією [«Налаштування та авторизація»](https://docs.merchant.alb.ua/platizhni-vidzheti-dlya-cms/opencart/nalashtuvannya-ta-avtorizaciya).

1. В адміністративній панелі OpenCart відкрийте потрібне замовлення.
2. Натисніть кнопку перевірки статусу замовлення, показану на ілюстрації.
3. Перегляньте результат операції та статус замовлення.

Статус замовлення в OpenCart залежить від відповідності статусів, заданої в налаштуваннях модуля. Для перевірки платежу також переглядайте дані платіжних операцій.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2Fn30GwG2JZ2Wkld53rRFW%2Fimage.png?alt=media&amp;token=7db61778-448d-4e3b-8c1b-99fe738cfe6c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FEDPGJyCwU0THI9HAXD5W%2Fimage.png?alt=media&amp;token=7d208475-db76-42bf-a3d0-4794184d7e99" alt=""><figcaption></figcaption></figure>

### Перегляд платіжних операцій

У деталях замовлення перегляньте операції AlliancePay. Зіставте тип операції, її суму та результат із потрібним замовленням. Для PREAUTH перевіряйте окремо результат холдування та подальшого списання COMPLETION.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FOCw4vXFA21UfgQLF0Wrz%2Fimage.png?alt=media&amp;token=79637ddc-91ef-4cae-ad21-ea4fd6b3abbe" alt=""><figcaption></figcaption></figure>

### Історія замовлення

Історія замовлення відображає зміни статусів і коментарі до них. Використовуйте її разом із даними платіжних операцій, щоб простежити результат оплати, підтвердження або повернення коштів.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FhvvOdcx0K6qG2efaGYKe%2Fimage.png?alt=media&amp;token=f0443499-867b-4ef1-84eb-1ee1bcfa080a" alt=""><figcaption></figcaption></figure>

### Оформлення замовлення

Під час оформлення замовлення покупець обирає оплату через AlliancePay і підтверджує замовлення. Модуль створює платіж та перенаправляє покупця на платіжну сторінку банку (HPP).

Сценарій оплати визначається параметром **HPP Payment Type** у налаштуваннях модуля.

| Тип платежу | Призначення                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| PURCHASE    | Оплата замовлення на платіжній сторінці банку.                                              |
| A2A         | Переказ між рахунками. Цей тип платежів має бути підключений банком для термінала мерчанта. |
| PREAUTH     | Холдування коштів із подальшим списанням через операцію COMPLETION.                         |

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FeW354tcyVdz0guNW7KIY%2Fimage.png?alt=media&amp;token=07564406-a46e-418f-bdcc-bd490c3b4ab4" alt=""><figcaption></figcaption></figure>

### Сторінка оплати

Покупець завершує оплату на HPP-сторінці банку. Для повернення до магазину використовуються URL успішної та неуспішної оплати, задані в налаштуваннях модуля.

Результат платежу перевіряйте в деталях замовлення за даними операцій і сповіщенням банку (callback).

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FbMrt4hvmhIsZwx8vDO6t%2Fimage.png?alt=media&amp;token=be11c5a9-9b03-462e-9d1b-8655feb2b759" alt=""><figcaption></figcaption></figure>

### PREAUTH і COMPLETION

**PREAUTH** резервує кошти на рахунку покупця. Для їх списання потрібно виконати окрему операцію **COMPLETION**.

До приймання таких платежів налаштуйте період холдування **Pre-Auth Expiration Period** та статуси замовлення після преавторизації й списання коштів.

#### Підтвердження списання коштів

1. Відкрийте замовлення з успішною операцією PREAUTH та перевірте суму холдування.
2. Натисніть **Confirm Payment** / **«Підтвердити оплату»**, щоб виконати COMPLETION.
3. Перевірте результат операції COMPLETION та оновлений статус замовлення.

Успішна преавторизація підтверджує холдування коштів. Завершене списання підтверджується успішною операцією COMPLETION.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FZ9nWMWjlIeppGPKSXYw0%2Fimage.png?alt=media&amp;token=9859683e-1754-4791-b01b-16b476802998" alt=""><figcaption></figcaption></figure>

### Підписки (рекурентні платежі)

Підписка дає змогу приймати регулярні платежі за товар за наперед заданим розкладом. Мерчант створює план, покупець оформлює підписку на платіжній сторінці банку (HPP), а наступні списання виконує банк. Модуль отримує підписані сповіщення (callback) і зберігає результати платежів.

Для запитів підписок використовується **Авторизація 2.0 (JWS)**. Перед початком роботи заповніть параметри за інструкцією [«Налаштування та авторизація»](https://docs.merchant.alb.ua/platizhni-vidzheti-dlya-cms/opencart/nalashtuvannya-ta-avtorizaciya).

#### Увімкнення підписок

| OpenCart 3.0                                                                                                                                                                                                                                      | OpenCart 4.0                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Відкрийте **Extensions → Extensions → Payments → Alliance Підписки**, установіть модуль, відкрийте його налаштування та ввімкніть. Він використовує Merchant ID, JWS-ключі, способи оплати, URL і статуси замовлень основного модуля AlliancePay. | Підписки входять до платіжного модуля AlliancePay з підтримкою цієї функції (версія модуля 1.6.0 у наданій інструкції). Після оновлення відкрийте налаштування модуля, щоб виконалося оновлення його структури. |
| У бічному меню **AlliancePay** доступні шаблони планів, плани та підписки: **Subscription Templates**, **Subscription Plans**, **Subscriptions**.                                                                                                 | У бічному меню **Плани підписки** доступні розділи **Плани підписки** та **Підписки**.                                                                                                                          |

#### Створення плану в OpenCart 3.0

1. Відкрийте **AlliancePay → Subscription Plans** і натисніть **Додати**.
2. Виберіть товар, укажіть категорію (indicator), назву й опис плану. Якщо назву або опис залишити порожніми, модуль використовує назву товару або плану.
3. За потреби виберіть **Шаблон плану**. Він заповнює структуру розкладу; суму та валюту кожного етапу потрібно вказати окремо.
4. Додайте щонайменше одне правило: діапазон номерів платежів, значення й одиницю інтервалу, суму в копійках та валюту.
5. Збережіть план і перевірте його статус синхронізації. План має бути активним для нових клієнтів.

**Шаблони планів.** У **Subscription Templates** можна створити шаблон з унікальним кодом, назвою, індикатором категорії та правилами розкладу без сум. Шаблон, який уже використовується планом, можна архівувати, але не редагувати.

#### Створення плану в OpenCart 4.0

1. Відкрийте **Плани підписки → Плани підписки** і натисніть **Додати план підписки**.
2. Укажіть назву плану, виберіть товар, заповніть опис і категорію (індикатор).
3. У блоці **Правила розкладу оплат** натисніть **Додати правило** та заповніть діапазон платежів, інтервал і суму. Валюта цієї форми — **UAH**.
4. Натисніть **Зберегти** та перевірте повідомлення про результат. Модуль створює план у банку й зберігає його ідентифікатор та версію.

Якщо план із такими параметрами вже існує, модуль використовує наявний запис. Якщо створення або синхронізація завершилися помилкою, перевірте її опис і журнал `alliance.log` перед повторною спробою.

#### Правила розкладу та суми

| Параметр                     | Що вказати                                                                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Від платежу № / До платежу № | Діапазон номерів платежів, до яких застосовується правило. Кінцевий номер має бути не меншим за початковий; діапазони різних правил не повинні перетинатися. |
| Інтервал                     | Числове значення та одиницю: `DAY`, `WEEK` або `MONTH`. Наприклад, `1 MONTH` — щомісяця.                                                                     |
| Сума в OpenCart 3.0          | У копійках: для платежу 100 грн укажіть `10000`.                                                                                                             |
| Сума в OpenCart 4.0          | У гривнях: для платежу 100 грн укажіть `100`. Модуль сам перетворює суму на копійки для запиту до банку.                                                     |
| Пробний період               | Задається окремим початковим правилом із сумою `0`. Наступні правила визначають платні списання.                                                             |

#### Оформлення підписки покупцем

| OpenCart 3.0                                                                                                                                                                                                        | OpenCart 4.0                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| На сторінці товару з активним планом покупець вибирає **Регулярний платіж** замість **Купити один раз**. Для підписки кількість товару дорівнює **1**.                                                              | На сторінці товару покупець вибирає активний план у списку **Варіант придбання** замість **Одноразова покупка**. Для оформлення потрібно ввійти в обліковий запис.                  |
| Підписку потрібно оформлювати окремим замовленням: один товар у кількості 1. На оформленні покупець натискає **Підтвердити підписку** та переходить на HPP.                                                         | Товар із підпискою не можна поєднувати з іншими товарами або іншою підпискою в одному замовленні. Підтвердження замовлення перенаправляє покупця на HPP.                            |
| Після створення замовлення підписка має статус `PENDING`. У кабінеті покупця доступний розділ **Мої підписки** з планом, товаром, статусом, датою початку та скасуванням підписок у статусі `ACTIVE` або `PENDING`. | Після створення замовлення та отримання посилання HPP підписка має статус `AWAITING_PAYMENT`. Перегляд і скасування мерчантом виконуються в адміністративному розділі **Підписки**. |

Результат оформлення визначайте за callback і статусом операції. Саме повернення покупця на сторінку успішної оплати ще не є підтвердженням завершеного платежу.

#### Повторні списання та статуси

Банк виконує списання за правилами плану та надсилає callback. Для кожного запланованого платежу модуль зберігає результат і ідентифікатор операції. Статус підписки та статус окремого платежу — різні значення.

| Статус підписки                | Значення                                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| `PENDING` / `AWAITING_PAYMENT` | Очікується завершення початкового оформлення або платежу; назва залежить від версії модуля. |
| `ACTIVE`                       | Підписка активна. Результат кожного наступного списання перевіряйте окремо.                 |
| `CANCELED`                     | Підписку скасовано.                                                                         |
| `ERROR`                        | Помилка створення або початкового платежу; перевірте дані операції та повідомлення модуля.  |

Для платежів використовуються, зокрема, `WAITING`, `PROCESSING`, `SUCCESS` і `FAIL`. Наявність `PROCESSING` означає обробку запиту, а не успішне списання. Власний автоматичний білінг і розклад повторних спроб модуль не запускає — регулярні списання виконує банк.

#### Перегляд і діагностика

1. Відкрийте **AlliancePay → Subscriptions** в OpenCart 3 або **Плани підписки → Підписки** в OpenCart 4.
2. Знайдіть підписку за замовленням, планом або ідентифікатором замовлення в банку. В OpenCart 3 також доступні фільтри за клієнтом/email і статусом та кнопка **Переглянути підписку** в пов’язаному замовленні.
3. Відкрийте діагностику або натисніть **Перегляд**. Перевірте статус підписки, умови оплати на момент оформлення та таблицю **Заплановані платежі**.
4. Для потрібного платежу зіставте дату, статус та ідентифікатор операції.

Якщо сторінка повідомляє, що актуальний статус із банку отримати не вдалося, вона показує локально збережені дані. У перевіреній реалізації OpenCart 4 діагностика використовує саме локальні дані та показує відповідне попередження.

#### Ручний запуск і скасування

**Запустити зараз.** У діагностиці виберіть потрібний запланований платіж і натисніть цю кнопку. Вона надсилає запит на рекурентний платіж. Перед запуском перевірте поточний результат операції, а після — повідомлення модуля та остаточний статус платежу.

**Скасувати підписку.** Відкрийте діагностику потрібної підписки, перевірте замовлення й план та натисніть **Скасувати підписку**. Після успішної відповіді банку перевірте статус `CANCELED`. В OpenCart 3 покупець також може скасувати доступну для скасування підписку в розділі **Мої підписки**.

Скасування підписки не виконує повернення вже сплачених коштів. Повернення оформлюється окремою операцією.

#### Приховування плану та зміна ціни

**Деактивувати для нових клієнтів** в OpenCart 3 або **Не пропонувати новим клієнтам** в OpenCart 4 прибирає план із нових оформлень. Чинні підписки продовжують діяти. В OpenCart 3 дія **Архівувати у провайдера** доступна лише для деактивованого плану без активних підписок.

1. У списку планів відкрийте **Масова зміна ціни** в OpenCart 3 або **Зміна ціни** в OpenCart 4.
2. Перевірте кількість активних підписок, яких стосується зміна, та задайте нові суми в правилах. Дотримуйтеся одиниць суми для своєї версії OpenCart.
3. Укажіть дату набуття чинності **не раніше ніж через 30 днів** і причину зміни.
4. Підтвердьте у формі, що клієнтів повідомлено або буде повідомлено, та застосуйте зміни.
5. Перевірте результат синхронізації з банком і запис в історії версій плану.

Зміна ціни стосується всіх активних підписників вибраного плану. Для цієї дії потрібне право `modify` на відповідний розділ; в OpenCart 3 право на масову зміну ціни надається адміністратором окремо.

Структуру збережених даних описано в розділі [«Структура бази даних»](https://docs.merchant.alb.ua/platizhni-vidzheti-dlya-cms/opencart/struktura-bazi-danikh).

### Повернення коштів

Нижче наведено інструкції повного та часткового повернення коштів (REFUND) для OpenCart 3.0 та OpenCart 4.0.

Перед підтвердженням перевірте замовлення, операцію оплати та склад повернення. Після виконання звірте результат платіжної операції й запис в історії замовлення.

{% tabs %}
{% tab title="OpenCart 3.0" %}
Відкрийте деталі замовлення, за яким потрібно повернути кошти.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FyLXLRB8gCFMxQZod9GaH%2Fimage.png?alt=media&amp;token=fbd6a239-a30f-4152-ad1d-2dbf1f58e408" alt=""><figcaption></figcaption></figure>

У блоці платіжного модуля доступні кнопки **«Повне повернення коштів»** та **«Часткове повернення»**.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2Fw79Mg90itEyCkXCpIN8I%2Fimage.png?alt=media&amp;token=58465bac-367e-404b-8fff-f5653e868af9" alt=""><figcaption></figcaption></figure>

### Повне повернення коштів&#x20;

Натисніть «Повне повернення коштів». Після успішного виконання операції модуль відобразить повідомлення про повернення.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FEBT8Im8o77lAhtvE1Gws%2Fimage.png?alt=media&amp;token=c26f8f28-3e33-45ec-a2e2-89c9aeddc347" alt=""><figcaption></figcaption></figure>

Перевірте, що товари позначено як повернуті, а в історії замовлення з’явився запис про повне повернення коштів.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FOQFIS1B4jexQOoOyMYh2%2Fimage.png?alt=media&amp;token=4ea5ab3b-07d6-4784-88cd-48a89b34dd6e" alt=""><figcaption></figcaption></figure>

Часткове повернення

У деталях замовлення виберіть товари, за які потрібно повернути кошти.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2F8O1hJJSuXJHiY86nmEyW%2Fimage.png?alt=media&amp;token=7993e1e0-e694-437c-9644-f1c07a421f41" alt=""><figcaption></figcaption></figure>

Натисніть «Часткове повернення» та підтвердьте дію у вікні, що відкриється.

<div align="center"><figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FXPY8Uo7xHomldmNgChHm%2Fimage.png?alt=media&amp;token=5765d609-10da-4869-a58f-e72894cd8c3d" alt=""><figcaption></figcaption></figure></div>

Перегляньте повідомлення з результатом операції.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FvvFKtBrQzCCBsA62UjJp%2Fimage.png?alt=media&amp;token=45a486a0-32a8-4d95-b44c-fd7ad90b1799" alt=""><figcaption></figcaption></figure>

Після успішного повернення перевірте позначки біля вибраних товарів у деталях замовлення.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FHbkj9MvlLy2lVvC8jBQx%2Fimage.png?alt=media&amp;token=81c0cdc5-8424-40d1-ace6-2a7de78c574b" alt=""><figcaption></figcaption></figure>

### Перегляд деталей повернень&#x20;

Відкрийте розділ Returns, щоб переглянути записи про повернення товарів.

Кожен рядок відповідає окремому товару, для якого оформлено повернення.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FDkBcWpA5Mz8dJguHO4Hb%2Fimage.png?alt=media&amp;token=507d6169-aec3-49ec-9661-93135896584e" alt=""><figcaption></figcaption></figure>

Натисніть кнопку редагування запису, показану нижче.![](https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FoiH6wrzAVboyNv49ADfL%2Fimage.png?alt=media\&token=ca7e3006-6f61-4af3-9935-cda98017ad10)У деталях повернення можна переглянути інформацію про покупця, указати причину, змінити статус запису та дані товару.

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2FQdq2qFgCoeq1jFrEJkv2%2Fimage.png?alt=media&amp;token=098f9b24-0e8f-4ed4-8108-a73dcf3271fc" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1348498792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdjW26z83WQoOq0ZjunWw%2Fuploads%2Frz32UXClp5Hvlf7RWqEm%2Fimage.png?alt=media&amp;token=80d93c3c-37ad-4f1a-8cea-8dbc17e7254f" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="OpenCart 4.0" %}

В адміністративній панелі OpenCart відкрийте деталі замовлення, оплаченого через AlliancePay. У верхній частині сторінки доступні кнопки **«Повернення коштів» (Refund)** та **«Часткове повернення коштів» (Partial refund)**.

Перед поверненням перевірте результат оплати. Для платежу PREAUTH кошти мають бути списані операцією COMPLETION.

### Повне повернення коштів

1. Перевірте номер замовлення та суму оплати.
2. Натисніть **«Повернення коштів» (Refund)**. Кнопка одразу надсилає запит на повне повернення, без окремого вікна підтвердження.
3. Перегляньте повідомлення з результатом запиту.
4. Оновіть сторінку замовлення та перевірте результат повернення за даними платіжних операцій і записом в історії замовлення.

### Часткове повернення коштів

1. У переліку товарів позначте позиції, за які потрібно повернути кошти. Потрібно вибрати щонайменше одну позицію.
2. Якщо потрібно також повернути вартість доставки, установіть позначку **«Повернути вартість доставки?» (Refund shipping cost?)**.
3. Натисніть **«Часткове повернення коштів» (Partial refund)**.
4. Підтвердьте дію у вікні **«Ви підтверджуєте повернення?»**.
5. Перегляньте результат запиту. Після повідомлення про успішне виконання сторінка оновлюється; перевірте дані операції повернення.

Суму часткового повернення модуль розраховує за вибраними товарними позиціями та, якщо встановлено відповідну позначку, вартістю доставки.

### Перегляд результату повернення

Перевірте статус і суму платіжної операції. Статус замовлення після повного повернення визначається параметром **«Статус "оплату повернено"»** у налаштуваннях модуля.

Записи щодо повернених товарів можна переглянути у стандартному розділі повернень OpenCart (Returns). Кожен запис містить дані окремого товару. Для підтвердження руху коштів звіряйте ці записи з результатом банківської операції REFUND.
{% endtab %}
{% endtabs %}
