Налаштування часткового повернення коштів на 1С-Бітрікс

Налаштування часткового повернення коштів на 1С-Бітрікс

Часткове повернення потрібне, коли покупець відмовився від однієї позиції із замовлення, або частина товарів виявилась недоступною для відвантаження, або послуга надана не в повному обсязі. На відміну від повного повернення, часткове вимагає точного розрахунку суми і — при підключеному онлайн-касі — відправки чека корекції. Стандартний модуль sale 1С-Бітрікс підтримує повернення, але потребує додаткового налаштування для коректної роботи з еквайрингом.

Архітектура повернень у 1С-Бітрікс

Повернення в 1С-Бітрікс — це об'єкт \Bitrix\Sale\PaymentCollection::createRefund() або прямий виклик API еквайрингу. Два підходи:

Через модуль sale — створюємо повернення коштів через платіжний обробник. Плюс: автоматичне оновлення статусу замовлення, журналювання. Мінус: обробник повинен підтримувати метод refund.

Безпосередньо через API еквайрингу — викликаємо API повернення незалежно від 1С-Бітрікс, потім вручну оновлюємо статус. Плюс: більше контролю. Мінус: потрібно синхронізувати стан.

Реалізація методу повернення в обробнику

class MyGatewayHandler extends \Bitrix\Sale\PaySystem\ServiceHandler
    implements \Bitrix\Sale\PaySystem\IRefund
{
    public function refund(
        \Bitrix\Sale\Payment $payment,
        $refundableSum
    ): \Bitrix\Sale\PaySystem\ServiceResult {

        $result = new \Bitrix\Sale\PaySystem\ServiceResult();

        $externalId = $payment->getField('PS_INVOICE_ID');
        if (!$externalId) {
            $result->addError(new \Bitrix\Main\Error('Не знайдено зовнішній ID платежу'));
            return $result;
        }

        try {
            $refundResult = $this->gateway->createRefund([
                'payment_id'  => $externalId,
                'amount'      => [
                    'value'    => number_format($refundableSum, 2, '.', ''),
                    'currency' => $payment->getField('CURRENCY'),
                ],
                'description' => 'Часткове повернення за замовленням ' . $payment->getOrderId(),
            ]);

            $result->setOperationType(
                \Bitrix\Sale\PaySystem\ServiceResult::MONEY_LEAVING
            );
            $result->setData(['refund_id' => $refundResult['id']]);
        } catch (\Exception $e) {
            $result->addError(new \Bitrix\Main\Error($e->getMessage()));
        }

        return $result;
    }
}

Часткове повернення через ЮКасу

// Повернення конкретної суми з оплаченого платежу
$refund = $yookassaClient->createRefund([
    'payment_id'  => $psInvoiceId,
    'amount'      => [
        'value'    => number_format($refundAmount, 2, '.', ''),
        'currency' => 'RUB',
    ],
    'description' => 'Повернення товару: ' . $itemName,
    'receipt'     => $refundReceipt,  // обов'язково при підключеній касі
], uniqid('', true));

Чек повернення (фіскальне законодавство)

При підключеному онлайн-касі часткове повернення вимагає чека з типом refund. Позиції чека — лише ті товари/послуги, за якими здійснюється повернення:

$refundReceipt = [
    'customer' => ['email' => $buyer->getEmail()],
    'items'    => [],
];

foreach ($returnedItems as $item) {
    $refundReceipt['items'][] = [
        'description'     => $item['name'],
        'quantity'        => $item['quantity'],
        'amount'          => [
            'value'    => number_format($item['price'], 2, '.', ''),
            'currency' => 'RUB',
        ],
        'vat_code'        => $item['vat_code'],
        'payment_subject' => 'commodity',
        'payment_mode'    => 'full_refund',  // для чека повернення
    ];
}

Сума позицій у чеку повернення повинна точно збігатися з сумою amount у запиті повернення — це перевіряється платіжною системою.

Ініціація повернення з адміністративної частини

В адмінці 1С-Бітрікс кнопка «Повернення» на сторінці замовлення (/bitrix/admin/sale_order_detail.php) створює форму введення суми. При відправці викликається метод \Bitrix\Sale\PaymentCollection::createRefund():

$order = \Bitrix\Sale\Order::load($orderId);
$paymentCollection = $order->getPaymentCollection();

foreach ($paymentCollection as $payment) {
    if ($payment->isPaid() && $payment->getField('PS_INVOICE_ID') === $externalId) {
        $paymentService = \Bitrix\Sale\PaySystem\Manager::getObjectById(
            $payment->getPaymentSystemId()
        );
        $result = $paymentService->refund($payment, $refundAmount);
        break;
    }
}

Терміни