# Возвраты платежей

Метод инициирует **возврат** успешного платежа ЕРИП. Передайте `order_id` исходной оплаты и отдельный `user_data` для операции возврата. После принятия запроса API вернёт `refund_order_id` и статус `REFUND_PENDING`; финальный результат придёт на `notify_url` проекта.

Формат запросов и подписи — в разделе [Формат запросов к API](/pages/init-request).

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

1. **Исходный платёж** — возврат возможен по `order_id` платежа в статусе успеха (`SUCCESS`, код `3`). ID берётся из ответа [создания по форме](/pages/erip/init-form) или [GATE](/pages/erip/host2host).
2. **Инициация** — подписанный запрос на `init_refund` с уникальным `user_data` **возврата** (не совпадает с `user_data` платежа).
3. **Ответ** — `refund_order_id`, `status` `9` (`REFUND_PENDING`) и `status_description`.
4. **Финал** — колбек POST JSON на `notify_url`; при необходимости опросите статус по `refund_order_id` через [Статусы платежей](/pages/erip/status).


Расшифровка `status` и `status_description` для возвратов — в [Статусы транзакций](/pages/transaction-statuses) (`REFUND`, `REFUND_PENDING`).

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

|  |  |
|  --- | --- |
| **Эндпоинт** | `https://api.1payment.com/init_refund` |
| **Методы** | `GET`, `POST` |
| **Формат ответа** | JSON |
| **Тип в колбеке** | `payment_type` — см. [Типы платежей](/pages/payment-types) (`refund` в уведомлениях по возврату) |


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

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

| Параметр | Тип | Описание |
|  --- | --- | --- |
| `partner_id` | Integer | Ваш уникальный ID в системе 1Payment. |
| `project_id` | Integer | Идентификатор вашего проекта. |
| `order_id` | String | `order_id` **исходного успешного** платежа ЕРИП. |
| `user_data` | String | Уникальный ID **возврата** на вашей стороне (отличный от `user_data` платежа). До 255 символов; рекомендуется UUID. |
| `sign` | String | Контрольная подпись запроса (см. раздел «Подпись»). |


### Опциональные

| Параметр | Тип | Описание |
|  --- | --- | --- |
| `amount` | Number | Сумма **частичного** возврата. Доступность частичных возвратов уточняйте у менеджера 1Payment. |


## Формирование подписи (`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_refund + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)
```

**Пример строки до хеширования:**


```text
init_refundorder_id=8p3brmb19gfg0sg8gcwhws8kgc748s87&partner_id=1234&project_id=5678&user_data=abcd1234secret_key
```

При частичном возврате в подпись включается переданный `amount`.

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

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

Node.js

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

async function initEripRefund(apiKey, params) {
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  const baseString = `init_refund${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  const response = await axios.get('https://api.1payment.com/init_refund', { params });
  return response.data;
}

const apiKey = process.env.ONEPAYMENT_API_KEY;
const data = {
  partner_id: 1234,
  project_id: 5678,
  order_id: '8p3brmb19gfg0sg8gcwhws8kgc748s87',
  user_data: 'abcd1234',
};

initEripRefund(apiKey, data).then(console.log);
```

Python

```python
import hashlib
import os
import requests

def init_erip_refund(api_key: str, params: dict) -> dict:
    sorted_keys = sorted(params.keys())
    query_string = "&".join(f"{k}={params[k]}" for k in sorted_keys)

    base_string = f"init_refund{query_string}{api_key}"
    params["sign"] = hashlib.md5(base_string.encode("utf-8")).hexdigest()

    response = requests.get("https://api.1payment.com/init_refund", params=params)
    response.raise_for_status()
    return response.json()

api_key = os.environ["ONEPAYMENT_API_KEY"]
data = {
    "partner_id": 1234,
    "project_id": 5678,
    "order_id": "8p3brmb19gfg0sg8gcwhws8kgc748s87",
    "user_data": "abcd1234",
}

print(init_erip_refund(api_key, data))
```

cURL

```bash
# sign = md5("init_refund" + order_id=...&partner_id=1234&project_id=5678&user_data=abcd1234 + API_KEY)
curl -sS "https://api.1payment.com/init_refund?partner_id=1234&project_id=5678&order_id=8p3brmb19gfg0sg8gcwhws8kgc748s87&user_data=abcd1234&sign=PASTE_MD5_HEX"
```

## Ответ API

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


```json
{
  "refund_order_id": "crf_1p3brmb19gfg0sg8gcwhws8kgc748s87",
  "status": 9,
  "status_description": "REFUND_PENDING",
  "status_code": 0
}
```

| Поле | Описание |
|  --- | --- |
| `refund_order_id` | ID возврата в 1Payment; используйте для опроса статуса и в учёте. |
| `status` | Числовой код (`9` — возврат в обработке). |
| `status_description` | `REFUND_PENDING` и др. |
| `status_code` | Код отказа при ошибке возврата (см. [коды отказов](/pages/decline-error-codes)). |


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


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

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

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

| Параметр | Тип | Обяз. | Описание |
|  --- | --- | --- | --- |
| `payment_type` | String | Да | Тип операции (см. [Типы платежей](/pages/payment-types)). |
| `order_id` | String | Да | Идентификатор **возврата** в 1Payment. |
| `project_id` | Integer | Да | ID вашего проекта. |
| `status` | Integer | Да | Состояние возврата (`5` — `REFUND`, `9` — `REFUND_PENDING` и др.). |
| `status_description` | String | Да | `REFUND`, `REFUND_PENDING`, `FAILURE` и др. |
| `init_time` | String | Да | Время создания возврата. |
| `status_time` | String | Да | Время получения статуса. |
| `merchant_price` | Number | Да | Сумма исходного платежа для плательщика. |
| `init_price` | Number | Нет | Сумма при инициации. |
| `user_price` | Number | Да | Списание по возврату. |
| `user_data` | String | Да | ID возврата, переданный в `init_refund`. |
| `original_order_id` | String | Нет | `order_id` исходного платежа. |
| `status_code` | String | Нет | Код ошибки при отказе. |
| `sign` | String | Да | Контрольная подпись колбека. |


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

**Проверка подписи колбека:** MD5 от всех параметров в алфавитном порядке через `&` + `API_KEY` (**без** префикса `init_refund`). Подробнее — в разделе [Формат запроса к 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/erip/init-form)
- [Создание платежа по host2host (GATE)](/pages/erip/host2host)
- [Статусы платежей](/pages/erip/status)
- [Статусы транзакций](/pages/transaction-statuses)
- [Типы платежей](/pages/payment-types)
- [Коды ошибок (API)](/pages/error-codes-api)
- [Коды ошибок (отказы)](/pages/decline-error-codes)