REST: sale.payment и статусы оплаты

Оплата в модели онлайн-магазина Битрикс24 — это отдельная сущность внутри заказа. Один заказ может иметь несколько оплат разными платёжными системами, и у каждой свой статус. За управление ими отвечает группа методов sale.payment, а признак оплаты хранится в поле paid.

Место оплаты в модели заказа

Заказ Битрикс24 (sale.order) декомпозируется на составляющие: корзина (sale.basketitem), отгрузки (sale.shipment) и оплаты (sale.payment). Оплата описывает, чем и на какую сумму покупатель гасит заказ.

• Один заказ может содержать несколько оплат — например, часть бонусами, часть картой.
• Каждая оплата привязана к платёжной системе через paySystemId.
• Статус оплаты выражается булевым флагом paid (Y/N), а не набором произвольных статусов.

Методы группы sale.payment

Группа реализует привычный CRUD:

• sale.payment.add — создать оплату для заказа;
• sale.payment.get — получить по id;
• sale.payment.list — выборка с filter, select, order;
• sale.payment.update — изменить оплату, в том числе отметить как оплаченную;
• sale.payment.delete — удалить оплату;
• sale.payment.getfields — получить список полей с их атрибутами (обязательность, доступность на запись).

Список доступных платёжных систем портала получают через sale.paysystem.list, а типы плательщиков — через sale.persontype.list.

Ключевые поля оплаты

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

Создание оплаты картой на 3500 рублей для заказа 145:

POST https://portal.bitrix24.ru/rest/1/xxxxx/sale.payment.add.json

Отметка оплаты как оплаченной:

Выборка неоплаченных оплат за период:

Оформление возврата:

Логика статусов и оплаты

В отличие от статуса заказа (который может иметь много значений из справочника sale.status), состояние оплаты бинарно: оплачено или нет. Развёрнутую картину дают связанные поля:

• paid=Y и заполненный datePaid — оплата подтверждена;
• payReturned=Y — деньги возвращены покупателю;
• paySystemId — какой канал использовался.

Статус заказа в целом хранится отдельно в sale.order (поле statusId). Часто интеграции автоматически меняют статус заказа при поступлении оплаты — эту связку можно реализовать по событию или в обработчике вебхука.

События и вебхуки об оплате

Чтобы реагировать на оплату из внешней системы, подписывайтесь на онлайн-события через sale.* или используйте события заказа. Полезные подходы:

1. Исходящие вебхуки. При изменении оплаты Битрикс24 может отправить уведомление на ваш URL — вы забираете id и запрашиваете детали через sale.payment.get.
2. Периодический опрос. Резервный вариант — регулярный sale.payment.list с фильтром paid=N и последующей сверкой.
3. Идемпотентность. Обрабатывайте одно и то же событие оплаты один раз: сохраняйте признак обработки по id оплаты.

Частые ошибки и права

Что чаще всего ломает интеграцию оплат:

• Нет права sale. Методы группы требуют разрешения sale для вебхука или приложения.
• Неверный paySystemId. Идентификатор должен существовать на портале — проверяйте через sale.paysystem.list.
• Рассинхрон сумм. Сумма оплат не сверяется с итогом заказа автоматически, контролируйте это на своей стороне.
• Ручной paid при активной ПС. Если оплату подтверждает платёжный шлюз, ручная отметка может конфликтовать с колбэком.

Итог

Оплата в Битрикс24 — самостоятельная сущность заказа с ключевыми полями orderId, paySystemId, sum и бинарным статусом paid. Управляется группой sale.payment, а связь с платёжными системами идёт через sale.paysystem.list. Отдельно живёт статус самого заказа — их синхронизацию строит интегратор.

Чтобы оплаты из внешнего сайта, эквайринга и 1С надёжно доходили до CRM без задвоений и рассинхрона сумм, нужна аккуратная обработка событий и идемпотентность. Мы разрабатываем такие интеграции с Битрикс24 и сопровождаем их под SLA.