Повернення коштів — операція, яка в Бітріксі часто викликає помилки: завислі статуси, дублі чеків, порушення 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-ФЗ і повну автоматизацію процесу. Замовте налаштування автоматичного повернення для вашого Бітрікс-проєкту. Наші інженери інтегрують будь-який еквайр з повною фіскалізацією.