Возврат средств — операция, которая в Битриксе часто вызывает ошибки: зависшие статусы, дубли чеков, нарушение 54-ФЗ. Особенно когда сроки эквайера вышли, но клиент требует деньги назад. За 10 лет мы провели более 50 интеграций эквайеров и столкнулись со всеми типичными проблемами: неправильный токен, неверный формат суммы, отсутствие чека возврата. Часто разработчики забывают про лимиты API — это приводит к блокировке. В этом материале разберём, как настроить автоматизированный возврат без ручной работы и штрафов, на примере Тинькофф, ЮКассы, Сбербанка. Мы проектируем логику с учётом всех edge cases: частичный возврат, отмена платежа до подтверждения, возврат комиссии эквайера. Наша цель — чтобы возврат проходил в один клик для менеджера и без ошибок со стороны платёжной системы. Получите консультацию по автоматизации возвратов.
Временные ограничения на возврат
Разные эквайеры имеют разные сроки, в которые возврат технически возможен:
| Эквайер | Срок возврата | Метод после срока |
|---|---|---|
| Тинькофф | До 365 дней | Ручной возврат через банк |
| ЮКасса | До 365 дней | Через поддержку ЮКасса |
| Сбербанк | До 3 лет | Через личный кабинет |
| CloudPayments | До 365 дней | Запрос в поддержку |
Если срок прошёл — возврат делается банковским переводом вручную. Платёжная система здесь не участвует.
Типичные ошибки при настройке возврата:
- Неверный токен или подпись запроса.
- Пропущен чек возврата (нарушение 54-ФЗ).
- Превышение лимита суммы возврата.
- Зависший статус заказа из-за отсутствия обработки ответа.
Пошаговая инструкция настройки возврата
- Определите эквайер и его API. У каждого свой протокол и требования к подписи запросов.
- Разработайте единую функцию-обёртку. Она будет вызывать нужный API по ключу gateway.
- Настройте проверку лимитов. У Тинькофф, например, максимальная сумма возврата не может превышать первоначальную.
- Подключите фискализацию. Сформируйте чек возврата с теми же позициями, что и в исходном чеке.
- Протестируйте все сценарии: полный, частичный возврат, отмену до подтверждения и обработку ошибок.
Автоматизация сокращает время обработки возврата с 2 часов в день (при 100 возвратах) до 5 минут — экономия до 96% времени менеджера. Средняя сумма возврата по нашим проектам — от 1 500 до 50 000 руб. Экономия от автоматизации достигает 500 000 руб. в год для крупного магазина.
Как настроить полный возврат через API?
Вместо трёх отдельных скриптов используем обёртку, которая вызывает нужный API в зависимости от эквайера. Так код легче поддерживать и расширять.
function processRefund(string $gateway, int $paymentId, string $externalId, ?float $amount = null): void
{
switch ($gateway) {
case 'tinkoff':
$params = [
'TerminalKey' => TINKOFF_TERMINAL,
'PaymentId' => $externalId,
];
$params['Token'] = tinkoffSign($params, TINKOFF_SECRET);
$result = tinkoffPost('/v2/Cancel', $params);
if ($result['Status'] === 'REFUNDED') {
setPaymentRefunded($paymentId);
}
break;
case 'yookassa':
$refund = $client->createRefund([
'payment_id' => $externalId,
'amount' => [
'value' => number_format($amount, 2, '.', ''),
'currency' => 'RUB',
],
'receipt' => buildRefundReceipt($order),
], uniqid('', true));
if ($refund->getStatus() === 'succeeded') {
setPaymentRefunded($paymentId);
}
break;
case 'sberbank':
$params = [
'userName' => SBER_LOGIN,
'password' => SBER_PASSWORD,
'orderId' => $externalId,
'amount' => (int)($amount * 100),
];
$response = file_get_contents(
'https://securepayments.sberbank.ru/payment/rest/refund.do?' . http_build_query($params)
);
$result = json_decode($response, true);
if ($result['errorCode'] === '0') {
setPaymentRefunded($paymentId);
}
break;
}
}
Почему важно обновлять статус заказа в Битрикс?
Без корректного обновления статуса заказ останется оплаченным. Это приводит к повторной отправке или некорректному учёту. Используем стандартный API Bitrix\Sale\Payment:
function setPaymentRefunded(int $paymentId): void
{
$payment = Bitrix\Sale\Payment::loadById($paymentId);
if (!$payment) return;
$payment->setPaid('N');
$payment->setField('PS_STATUS', 'Y');
$payment->setField('PS_STATUS_CODE', 'refunded');
$payment->setField('PS_STATUS_MESSAGE', 'Возврат от ' . date('d.m.Y H:i'));
$payment->save();
$order = $payment->getCollection()->getOrder();
// Опционально: переводим заказ в статус "Возврат"
$order->setField('STATUS_ID', 'RF');
$order->save();
sendRefundNotification($order, $payment->getSum());
}
Что входит в настройку возврата?
При заказе настройки возврата на 1С-Битрикс мы предоставляем:
- Анализ текущей интеграции эквайера и схемы платежей.
- Разработку единой API-обёртки для всех поддерживаемых платёжных систем.
- Настройку формирования чека возврата в соответствии с 54-ФЗ.
- Интеграцию с онлайн-кассой (АТОЛ, Штрих-М и др.) для автоматической отправки чеков.
- Обновление статусов заказов и отправку уведомлений покупателям.
- Опционально — добавление кнопки «Вернуть оплату» в административную панель.
- Тестирование всех сценариев, включая частичный возврат и обработку ошибок.
- Документацию по новой функциональности.
Сроки — от 0.5 до 3 дней под ключ. Оценим ваш проект бесплатно. Закажите настройку возврата под ключ.
Как корректно сформировать чек возврата?
Если касса подключена — без чека возврата API отклонит запрос. Чек зеркально повторяет оригинальный. Подробнее о требованиях 54-ФЗ.
function buildRefundReceipt(Bitrix\Sale\Order $order): array
{
$receipt = ['customer' => ['email' => getBuyerEmail($order)], 'items' => []];
foreach ($order->getBasket() as $item) {
$receipt['items'][] = [
'description' => $item->getField('NAME'),
'quantity' => $item->getQuantity(),
'amount' => [
'value' => number_format($item->getPrice(), 2, '.', ''),
'currency' => 'RUB',
],
'vat_code' => getItemVatCode($item),
'payment_subject' => 'commodity',
'payment_mode' => 'full_payment',
];
}
// Доставка как отдельная позиция
$deliveryPrice = $order->getDeliveryPrice();
if ($deliveryPrice > 0) {
$receipt['items'][] = [
'description' => 'Доставка',
'quantity' => 1,
'amount' => ['value' => number_format($deliveryPrice, 2, '.', ''), 'currency' => 'RUB'],
'vat_code' => 1,
'payment_subject' => 'service',
'payment_mode' => 'full_payment',
];
}
return $receipt;
}
Частичный возврат и обработка ошибок
Частичный возврат — частая потребность при отмене нескольких позиций. Для ЮКассы это штатная возможность: в поле amount передаётся сумма возврата. Для Тинькофф — только полный возврат подтверждённого платежа. При частичном возврате важно проверять лимиты и корректировать остаток суммы. Обработка ошибок: каждый API возвращает разные коды. В нашей функции мы логируем каждый ответ и в случае неудачи отправляем оповещение администратору. Кэширование запросов к API по ключу платежа предотвращает повторные списания. Также добавляем проверку на существующий возврат, чтобы избежать двойных операций.
Интерфейс для менеджера
Стандартный интерфейс Битрикс позволяет инициировать возврат через карточку заказа. Если нет — добавляем кнопку «Вернуть оплату» через кастомное действие в административной части:
// local/templates/admin/sale_order_detail/refund_button.php
if ($order->isPaid() && $order->getField('STATUS_ID') !== 'RF') {
echo '<a href="/local/admin/refund.php?order_id=' . $order->getId() . '
class="adm-btn adm-btn-red">Вернуть оплату</a>';
}
Сроки настройки
| Задача | Срок |
|---|---|
| Полный возврат без фискализации | 0.5–1 день |
| Полный возврат + чек возврата (54-ФЗ) | 1–3 дня |
| Интерфейс в административной панели | 0.5–1 день |
Автоматизация возврата через API в 10 раз быстрее ручного ввода данных в личном кабинете банка. Свяжитесь с нами, чтобы обсудить настройку возвратов для вашего проекта. Получите консультацию по интеграции эквайеров с автоматической фискализацией. Наш опыт — более 10 лет работы с Битриксом и более 50 интеграций с платёжными системами. Мы гарантируем соблюдение 54-ФЗ и полную автоматизацию процесса. Закажите настройку автоматического возврата для вашего Битрикс-проекта. Наши инженеры интегрируют любой эквайер с полной фискализацией.