# Клиентский пакет ClickPay24

Пакет позволяет разместить **форму оплаты** и **обработку партнёрских ссылок** на собственном сервере. Браузер покупателя никогда не обращается к сервису напрямую — все запросы проксируются через PHP на вашем сервере.

---

## Скачивание

Актуальный ZIP-архив доступен в личном кабинете:

```
https://[service-domain]/ClientPackage/Download/
```

> Требуется авторизация с вашим API-токеном.

---

## Структура пакета

```
client-package/
├── config.php          # Конфигурация (SERVICE_URL, API_TOKEN)
├── redirect.php        # Обработчик партнёрской ссылки
├── includes/           # Служебные файлы (не редактировать)
├── payment/
│   ├── index.php       # Страница формы оплаты
│   ├── ajax.php        # AJAX-прокси
│   └── success.php     # Финальный редирект после оплаты
└── assets/
    ├── css/payment.css
    └── js/payment.js
```

---

## Требования к серверу

- PHP 7.4 или выше
- Расширения: `curl`, `json`, `session`
- Apache или Nginx (без дополнительной настройки)
- HTTPS (обязательно)

---

## Установка

### 1. Распаковать архив

Загрузите файлы пакета в любую директорию на вашем сервере, например:

```
/var/www/your-site.com/public_html/pay/
```

Структура URL после установки:

```
https://your-site.com/pay/redirect.php        ← партнёрские ссылки
https://your-site.com/pay/payment/index.php   ← форма оплаты
```

### 2. Заполнить config.php

```php
define('SERVICE_URL', 'https://your-service-domain.com');
define('SERVICE_API_TOKEN', 'ВАШ_API_ТОКЕН');
define('SERVICE_TIMEOUT', 15);
```

API-токен берётся из личного кабинета сервиса.

---

## Где брать ссылки

В личном кабинете, в разделе продукта, есть два типа ссылок:

### buy_code — ссылка на оплату (только для автора)

Выглядит как `bXXXXXXXXXXXXXXXX` (начинается с `b`).

Используется **автором** для подключения формы оплаты к странице товара. Одна на продукт — одинакова для всех партнёров.

Ссылка, которую автор ставит на кнопку «Купить» на своём сайте:

```
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX
```

Форма оплаты автоматически подтянет сессию партнёра из куки, поэтому отдельно передавать `fp` не нужно — он уже сохранён после перехода по партнёрской ссылке.

### Апселы и несколько цен

Если у продукта настроено несколько ценовых вариантов (основной оффер, апсел, даунсел и т.д.), каждый вариант имеет свой `price_id`. Автор создаёт отдельную кнопку для каждого варианта:

```
# Основной оффер
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX

# Апсел (другая цена того же продукта)
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX&price_id=42

# Даунсел
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX&price_id=43
```

`buy_code` во всех вариантах **одинаковый** — это код продукта автора. Меняется только `price_id`.  
Значения `price_id` берутся из личного кабинета сервиса, в разделе настроек цен продукта.

### public_code — партнёрская ссылка (для каждого партнёра своя)

Выглядит как `rXXXXXXXXXXXXXXXX` (начинается с `r`).

**У каждого партнёра на каждый продукт — свой уникальный `public_code`.**

Партнёр использует его в `redirect.php` на сервере автора:

```
https://your-site.com/pay/redirect.php?code=rXXXXXXXXXXXXXXXX
```

Именно эту ссылку партнёр использует в рекламе, Keitaro и других трекерах.

> Партнёр находит свой `public_code` в личном кабинете сервиса, в разделе «Мои офферы» → нужный продукт → «Ссылки».

---

## Как это работает вместе

```
Покупатель
  │
  ▼
Переходит по партнёрской ссылке
  https://your-site.com/pay/redirect.php?code=rHASH
  │
  ├─ redirect.php регистрирует клик (server-to-server)
  ├─ Сохраняет сессию партнёра в куку buyer_fp
  │
  ▼
Попадает на страницу товара автора
(с параметрами партнёра: partner_id, hash и т.д.)
  │
  ▼
Нажимает кнопку «Купить»
  https://your-site.com/pay/payment/index.php?buy_code=bHASH
  │
  ├─ index.php создаёт заказ (server-to-server, InitOrder)
  │   — привязывает к партнёру через куку buyer_fp
  │   — рассчитывает суммы автора, партнёра, реферала
  ├─ Редиректит на ?id=ORDER_ID&hash=ORDER_HASH
  │
  ▼
Форма оплаты отображается покупателю
  — выбор метода, реквизиты, таймер, статус
```

---

## Безопасность файлов пакета

`config.php` и папка `includes/` защищены на уровне PHP: при прямом обращении браузера они возвращают `403` без каких-либо данных. Никакой дополнительной настройки веб-сервера для этого не требуется — работает на Apache и Nginx без изменений конфигурации.

Пакет также содержит `.htaccess` для Apache — он добавляет защиту на уровне сервера как дополнительный слой, но не является обязательным условием работы.

---

## Партнёрские ссылки (redirect.php)

Партнёр размещает в рекламе ссылку на `redirect.php` с **своим** `public_code`:

```
https://your-site.com/pay/redirect.php?code=rXXXXXXXXXXXXXXXX
```

### Дополнительные параметры

| Параметр | Описание |
|----------|----------|
| `code`   | public_code партнёра (обязательный) |
| `sub`    | Суб-аккаунт партнёра |
| `data1`..`data5` | Кастомные параметры постбэка |
| Любые другие | Сохраняются и пробрасываются в постбэк (utm_*, fbclid, gclid, roistat и т.д.) |

### Пример для Keitaro

```
https://your-site.com/pay/redirect.php?code=rXXXXXXXXXXXXXXXX&data1={click_id}&data2={campaign_id}&utm_source={source}
```

### Что происходит при переходе

1. `redirect.php` регистрирует клик на сервисе (server-to-server)
2. Получает токен сессии (`fp`)
3. Сохраняет `fp` в куку `buyer_fp` на вашем домене
4. Перенаправляет покупателя на страницу товара

---

## Форма оплаты (payment/index.php)

### Ссылка на кнопке «Купить»

Автор ставит на своей странице товара ссылку с **своим** `buy_code`:

```
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX
```

При необходимости можно указать конкретную цену (для продуктов с несколькими ценами):

```
https://your-site.com/pay/payment/index.php?buy_code=bXXXXXXXXXXXXXXXX&price_id=42
```

### Как работает

1. Покупатель переходит по ссылке с `buy_code`

2. `index.php` создаёт заказ на сервисе (server-to-server):
   - Определяет партнёра через куку `buyer_fp`, установленную `redirect.php`
   - Рассчитывает суммы для автора, партнёра и реферальной цепочки
   - Получает `order_id` и `order_hash`

3. Браузер редиректится на чистый URL `?id=ORDER_ID&hash=ORDER_HASH` — при обновлении страницы заказ не пересоздаётся

4. Покупатель видит форму с выбором метода оплаты

5. Все AJAX-запросы идут на `ajax.php` — **ваш домен, без внешних URL**

6. После успешной оплаты — редирект через `success.php` на страницу подтверждения

### Дополнительные параметры

Utm-метки и прочие параметры, переданные в URL формы оплаты (`utm_source`, `roistat_visit` и т.д.), автоматически сохраняются в сессии и пробрасываются на сервис.

---

## Безопасность

- `config.php` защищён от прямого доступа из браузера
- Папка `includes/` закрыта от прямого доступа
- API-токен никогда не попадает в браузер или HTML
- Весь обмен с сервисом — сервер-сервер по HTTPS
- Форма не раскрывает URL сервиса, адреса провайдеров и логику обработки платежей

---

## Поддержка

При возникновении проблем:

1. Проверьте PHP-логи на вашем сервере (`error_log` в php.ini или журнал вашего хостинга)
2. Убедитесь, что `config.php` заполнен корректно и API-токен действителен
3. Убедитесь, что сервер работает по HTTPS — без него сессии и куки не сохраняются
4. Обратитесь в поддержку сервиса, указав URL вашей формы оплаты и время возникновения проблемы