# Создание платежа по host2host (GATE)

Интеграция **GATE** позволяет создать платёж напрямую с вашего сервера и получить готовую ссылку на оплату у **партнёра**. Вы полностью контролируете внешний вид: можете отрисовать ссылку как QR-код на сайте или сделать кнопку «Оплатить», которая откроет приложение банка на телефоне клиента.

## Принцип работы

Процесс проведения платежа через API состоит из четырёх шагов:

1. **Инициализация** — ваш сервер формирует запрос с параметрами заказа и отправляет его на эндпоинт 1Payment.
2. **Получение ссылки** — в ответ система возвращает прямую ссылку на оплату у партнёра (`redirect_url`).
3. **Оплата** — вы отрисовываете ссылку в виде QR-кода на сайте или используете её для кнопки «Оплатить» в мобильной версии; клиент переходит в приложение банка и подтверждает платёж.
4. **Уведомление (колбек)** — после изменения статуса операции мы отправляем **POST**-уведомление на ваш `notify_url` с финальным результатом транзакции.


## Техническая информация

|  |  |
|  --- | --- |
| **Эндпоинт** | `https://api.1payment.com/init_payment` |
| **Методы** | `GET`, `POST` |
| **Формат ответа** | JSON |
| **Тип платежа** | В запросе обязательно `payment_type=link` |


## Параметры запроса

### Обязательные

Эти поля должны присутствовать в каждом запросе для корректного создания платежа.

| Параметр | Тип | Описание |
|  --- | --- | --- |
| `partner_id` | Integer | Ваш уникальный ID в системе 1Payment. |
| `project_id` | Integer | Идентификатор вашего проекта. |
| `amount` | Number | Сумма платежа (например, `100.00`). |
| `payment_type` | String | Для канала `link` всегда передаётся значение `link`. |
| `user_data` | String | Ваш внутренний ID заказа (вернётся в колбеке). |
| `shop_url` | String | URL сайта, на котором совершается покупка. |
| `sign` | String | Контрольная подпись запроса (см. раздел «Подпись»). |


### Дополнительные

Позволяют передать расширенную информацию о клиенте или активировать подписку.

| Параметр | Тип | Описание |
|  --- | --- | --- |
| `description` | String | Описание заказа, которое увидит клиент в банковском приложении. |
| `phone` | String | Номер телефона плательщика. |
| `email` | String | Электронная почта плательщика. |
| `user_id` | String | ID клиента в вашей базе данных. |
| `return_url` | String | URL, куда вернуть плательщика после оплаты в банке. |
| `subscribe` | Integer | Передайте `1`, чтобы создать токен для рекуррентных платежей. |


## Формирование подписи (`sign`)

Подпись: MD5, lowercase (hex). Общие правила — [Формат запроса к API](/pages/init-request#%D0%BF%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0-sign).

**Формула:**


```text
MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)
```

**Сценарий 1 — только обязательные параметры**

Параметры: `amount=50`, `partner_id=1`, `payment_type=link`, `project_id=5678`, `shop_url=test.com`, `user_data=order123`.


```text
init_paymentamount=50&partner_id=1&payment_type=link&project_id=5678&shop_url=test.com&user_data=order123secret_key
```

**Сценарий 2 — с полем `description`**

При добавлении `description=Payment1` поле включается в строку по алфавиту:


```text
init_paymentamount=50&description=Payment1&partner_id=1&payment_type=link&project_id=5678&shop_url=test.com&user_data=order123secret_key
```

### Проверка подписи в документации

## Примеры запроса

Node.js

```javascript
const crypto = require('crypto');
const axios = require('axios');

async function createLinkPayment(apiKey, params) {
  // 1. Сортируем параметры по алфавиту
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  // 2. Формируем подпись с префиксом init_payment
  const baseString = `init_payment${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  // 3. Отправляем POST-запрос
  try {
    const response = await axios.post('https://api.1payment.com/init_payment', params);
    return response.data; // order_id, status, redirect_url
  } catch (error) {
    console.error('Ошибка при создании платежа:', error.message);
  }
}

// Пример данных запроса
const apiKey = process.env.ONEPAYMENT_API_KEY;
const data = {
  partner_id: 1234,
  payment_type: 'link',
  project_id: 5678,
  amount: 50.0,
  user_data: 'inv_12345',
  shop_url: 'https://myshop.com',
};

createLinkPayment(apiKey, data).then((result) => console.log('Ответ системы:', result));
```

Python

```python
import hashlib
import os
import requests

def create_link_payment(api_key: str, params: dict) -> dict:
    # 1. Сортировка параметров по алфавиту
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    # 2. Формирование подписи (префикс init_payment)
    base_string = f"init_payment{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    # 3. Запрос к API
    response = requests.post("https://api.1payment.com/init_payment", data=params)
    response.raise_for_status()
    return response.json()

api_key = os.environ["ONEPAYMENT_API_KEY"]
data = {
    "partner_id": 1234,
    "payment_type": "link",
    "project_id": 5678,
    "amount": 50.00,
    "user_data": "inv_12345",
    "shop_url": "https://myshop.com",
}

print(create_link_payment(api_key, data))
```

PHP

```php
<?php

function createLinkPayment(string $apiKey, array $params): string
{
    // 1. Сортировка параметров по алфавиту
    ksort($params, SORT_LOCALE_STRING);
    $tail = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign') {
            continue;
        }
        $tail .= "{$k}={$v}&";
    }
    $tail = substr($tail, 0, -1);

    // 2. Формирование подписи (префикс init_payment)
    $params['sign'] = md5('init_payment' . $tail . $apiKey);

    // 3. Запрос к API
    $ch = curl_init('https://api.1payment.com/init_payment');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
}

// Пример данных запроса (обязательные поля)
$apiKey = getenv('ONEPAYMENT_API_KEY');
$data = [
    'partner_id' => 1234,
    'payment_type' => 'link',
    'project_id' => 5678,
    'amount' => 50.00,
    'user_data' => 'inv_12345',
    'shop_url' => 'https://myshop.com',
];

echo createLinkPayment($apiKey, $data);
```

cURL

```bash
# 1–2. Подпись: md5("init_payment" + amount=50&partner_id=1&payment_type=link&project_id=5678&shop_url=test.com&user_data=order123 + API_KEY)

# 3. POST-запрос (можно также GET с теми же query-параметрами)
curl -sS -X POST "https://api.1payment.com/init_payment" \
  -d "partner_id=1234&project_id=5678&amount=50&payment_type=link&user_data=inv_12345&shop_url=https%3A%2F%2Fmyshop.com&sign=PASTE_MD5_HEX"
```

## Ответ API

Успешный ответ (`200`):


```json
{
  "order_id": "8p3brmb19gfg0sg8gcwhws8kgc748s87",
  "status": 2,
  "status_description": "PENDING",
  "redirect_url": "https://qr.nspk.ru/XXX"
}
```

| Поле | Описание |
|  --- | --- |
| `order_id` | Уникальный ID транзакции в системе 1Payment. |
| `status` | Числовой код состояния (`2` — ожидание оплаты). |
| `status_description` | Текстовое описание статуса (`PENDING` и др.). |
| `redirect_url` | Прямая ссылка на оплату у партнёра: отрисуйте QR-код или используйте её в качестве ссылки для кнопки «Оплатить». |


Ошибка запроса (`400`):


```json
{
  "error_code": 2
}
```

## Уведомления о статусе (колбеки)

После изменения статуса операции наш сервер отправляет **POST**-запрос в формате JSON на ваш `notify_url`.

| Параметр | Тип | Обяз. | Описание |
|  --- | --- | --- | --- |
| `payment_type` | String | Да | Тип платежа (`link`). |
| `order_id` | String | Да | Идентификатор платежа в системе 1Payment. |
| `project_id` | Integer | Да | ID вашего проекта. |
| `status` | Integer | Да | Состояние: `2` (ожидание), `3` (успех), `4` (отказ). |
| `status_description` | String | Да | `PENDING`, `SUCCESS` или `FAILURE`. |
| `init_time` | String | Да | Время создания платежа. |
| `status_time` | String | Да | Время получения финального статуса. |
| `merchant_price` | Number | Да | Сумма платежа. |
| `user_price` | Number | Да | Отчисления партнёра. |
| `currency` | String | Да | Валюта платежа (ISO 4217). |
| `account` | String | Да | Идентификатор канала (значение `link`). |
| `user_data` | String | Да | ID транзакции, переданный при инициации. |
| `sign` | String | Да | Контрольная подпись колбека. |
| `redirect_url` | String | Нет | URL для QR-кода, если не был передан ранее. |
| `status_code` | String | Нет | Код ошибки при отказе. |
| `token` | String | Нет | Идентификатор подписки для рекуррентных платежей. |
| `test` | Integer | Нет | `1` при тестовых операциях. |


**Важно:** ваш сервер должен вернуть **HTTP 200 OK**. Иначе система повторяет отправку колбека **раз в минуту в течение 10 минут**.

**Проверка подписи колбека:** MD5 от всех параметров в алфавитном порядке через `&` + `API_KEY` (**без** префикса `init_payment`). Подробнее — в разделе [Формат запроса к API](/pages/init-request#%D0%BA%D0%BE%D0%BB%D0%B1%D0%B5%D0%BA%D0%B8-%D1%83%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F).

## Связанные разделы

- [Создание платежа по форме](/pages/link/init-form)
- [Статусы платежей](/pages/link/status)
- [Возвраты платежей](/pages/link/refund)
- [Создание платежа по подписке (рекурренты)](/pages/link/recurring)
- [Статусы транзакций](/pages/transaction-statuses)
- [Коды ошибок (API)](/pages/error-codes-api)
- [Коды ошибок (отказы)](/pages/decline-error-codes)