Документация для разработчиков

Оплаты

Внимание! Оплаты всегда связаны с заказом. Использовать метод \Bitrix\Sale\Payment::save() для сохранения категорически запрещается. При изменении оплаты может произойти изменение связанных сущностей, которые не будут сохранены. Необходимо выполнять сохранение через заказ: \Bitrix\Sale\Order::save(). Помимо всего этого в одной из ближайших версий вызов \Bitrix\Sale\Payment::save() будет генерировать ошибку уровня E_WARNING.

  • Получение оплат:
  • Получение конкретной оплаты
  • Добавление оплаты
  • Редактирование оплаты
  • Удаление оплаты
  • Получение суммы оплаты
  • Получение текущего состояния оплаты: оплачено или нет
  • Возврат средств
  • Получение оплаченной суммы по заказу
  • Получение объекта платежной системы
  • Получение списка доступных платежных систем с учетом настроенных ограничений
  • Получение оплат

    • Работа с коллекцией
      $collection = $order->getPaymentCollection();
      foreach ($collection as $payment)
      {
      	// ...
      }
      
    • Работа с массивом

      Помимо объектов есть возможность напрямую обращаться к базе через метод \Bitrix\Sale\PaymentCollection::getList($parameters), либо \Bitrix\Sale\Payment::getList($parameters). Оба этих метода работают аналогично.

      Методы всегда возвращают объект Bitrix\Main\DB\Result, из которого можно получить данные с помощью метода fetch().

      Параметр Описание С версии
      $parameters Массив, структура которого полностью соответствует структуре ORM'ного getList.
      // получение списка оплат для заказа 1234
      $dbRes = \Bitrix\Sale\PaymentCollection::getList([
      	'select' => ['*'],
      	'filter' => [
      		'=ORDER_ID' => 1234, 
      	]
      ]);
      
      while ($item = $dbRes->fetch())
      {
      	var_dump($item);
      }
      

    Получение конкретной оплаты

    $collection = $order->getPaymentCollection();
    
    • по ID:
      $payment = $collection->getItemById($id);
      
    • по внутреннему индексу:
      $payment = $collection->getItemByIndex($index);
      

    Добавление оплаты

    • Вариант 1:
      /*
       * $collection - объект класса \Bitrix\Sale\PaymentCollection
       */
      
      $payment = $collection->createItem();
      $payment->setFields([
      	'PAY_SYSTEM_ID' => 10,
      	'SUM' => 100,
      ]);
      
      
    • Вариант 2:
      /*
       * метод \Bitrix\Sale\PaymentCollection::createItem принимает один необязательный параметр: $paySystemService - объект платежной системы
       */
      $service = \Bitrix\Sale\PaySystem\Manager::getObjectById(10);
      $payment = $collection->createItem($service);
      		
      $payment->setField('SUM', 100);
      
    • Вариант 3:
      /*
       * в метод \Bitrix\Sale\Payment::create тоже можно передать объект платежной системы
       */
      $service = \Bitrix\Sale\PaySystem\Manager::getObjectById(10);
      $payment = \Bitrix\Sale\Payment::create($collection, $service);
      
      $payment->setField('SUM', 100);
      
      $collection->addItem($payment);
      

    Редактирование оплаты

    Изменить данные в оплате можно через методы:

    • $r = $payment->setField($fieldName, $value);
      
    • $r = $payment->setFields([
      	$fieldName1 => $value1,
      	$fieldName2 => $value2,
      	...
      ]);
      

    В обоих случаях результатом работы метода является объект класса \Bitrix\Sale\Result.

    Список доступных для редактирования полей:

    'PAID', // Флаг оплаченности: Y или N
    'DATE_PAID', // Дата оплаты
    'EMP_PAID_ID', // Кто оплатил
    'PAY_SYSTEM_ID', // ID платежной системы
    'PS_INVOICE_ID', // идентификатор оплаты в платежной системе
    'PS_STATUS', // данные, пришедшие от платежной системы: статус транзакции
    'PS_STATUS_CODE', // данные, пришедшие от платежной системы: код транзакции
    'PS_STATUS_DESCRIPTION', // данные, пришедшие от платежной системы: описание транзакции
    'PS_STATUS_MESSAGE', // данные, пришедшие от платежной системы: сообщение
    'PS_SUM', // данные, пришедшие от платежной системы: сумма транзакции
    'PS_CURRENCY', // данные, пришедшие от платежной системы: валюта
    'PS_RESPONSE_DATE', // данные, пришедшие от платежной системы: дата ответа от платежной системы
    'PAY_VOUCHER_NUM', // номер платежного документа 
    'PAY_VOUCHER_DATE', // дата платежного документа
    'DATE_PAY_BEFORE', // дата, до которой необходимо оплатить счет (в магазине не используется)
    'DATE_BILL', // дата выставления счета
    'XML_ID', // XML_ID
    'SUM', // сумма оплаты
    'CURRENCY', // валюта
    'PAY_SYSTEM_NAME', // название платежной системы
    'COMPANY_ID', // ID компании, которая будет принимать оплату
    'PAY_RETURN_NUM', // номер документа возврата
    'PAY_RETURN_DATE',  // дата документа возврата
    'PAY_RETURN_COMMENT', // комментарий к возврату
    'PRICE_COD', // стоимость оплаты при доставке (используется, например, для наложенного платежа)
    'EMP_RETURN_ID', // ID пользователя, который выполнял возврат
    'RESPONSIBLE_ID', // ID пользователя, ответственного за оплату
    'EMP_RESPONSIBLE_ID', // ID пользователя, который назначил ответственного
    'DATE_RESPONSIBLE_ID', // дата назначения ответственного
    'IS_RETURN', // выполнялся ли возврат. (см. блок возврат оплаты ниже в данной главе)
    'COMMENTS', // комментарий к оплате
    'ACCOUNT_NUMBER', // номер оплаты
    'UPDATED_1C', // обновлена ли через 1С
    'ID_1C', // ID в 1С
    'VERSION_1C', // версия документа оплаты от 1с
    'EXTERNAL_PAYMENT', // флаг Y/N: внешняя оплата или нет
    'MARKED', // промаркирована ли оплата
    'REASON_MARKED', // причина маркировки
    'DATE_MARKED', // дата маркировки
    'EMP_MARKED_ID', // кем промаркирована оплата
    

    Удаление оплаты

    Возвращает объект типа \Bitrix\Sale\Result.

    $r = $payment->delete();
    if (!$r->isSuccess())
    {
    	var_dump($r->getErrorMessages());
    }
    

    Получение суммы оплаты

    $sum = $payment->getSum();
    

    Получение текущего состояния оплаты: оплачено или нет

    Возвращает true или false.

    $isPaid = $payment->isPaid();
    

    Возврат средств

    Метод принимает единственный параметр, значения которого могут быть следующие:

    • 'Y' - при возврате на внутренний счет;
      $r = $payment->setReturn('Y');
      if (!$r->isSuccess())
      {
      	var_dump($r->getErrorMessages());
      }
      
    • 'P' - при возврате через платежную систему(если она поддерживает данный функционал);
      $r = $payment->setReturn('P');
      if (!$r->isSuccess())
      {
      	var_dump($r->getErrorMessages());
      }
      
    • 'N' - при отмене возврата.
      $r = $payment->setReturn('N');
      if (!$r->isSuccess())
      {
      	var_dump($r->getErrorMessages());
      }
      

    Возвращает объект типа \Bitrix\Sale\Result. При выполнении возврата Вам не требуется делать каких-то дополнительных операций вроде вызова методов API платежной системы для выполнения возврата. Система все сделает сама. При попытке выполнить возврат через платежную систему, которая его не поддерживает, будет возвращена ошибка.

    Получение оплаченной суммы по заказу

    $paymentCollection = $order->getPaymentCollection();
    $paymentCollection->getPaidSum();
    

    Получение объекта платежной системы

    Результатом работы метода является объект класса \Bitrix\Sale\PaySystem\Service.

    $service = $payment->getPaySystem();
    

    Получение списка доступных платежных систем с учетом настроенных ограничений

    $paySystemList = \Bitrix\Sale\PaySystem\Manager::getListWithRestrictions($payment, $mode);
    
    Параметры Описание С версии
    $payment Объект оплаты.
    $mode Одно из двух значений:
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_MANAGER

    По умолчанию: \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT. В режиме клиента возвращается список только тех платежных систем, которые попадают под ограничения.

    В режиме менеджера возвращается полный список платежных систем (системы, которые не подают под ограничения, имеют ключ RESTRICTED).


    Пользовательские комментарии

    Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

    Для этого нужно всего лишь авторизоваться на сайте

    Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

    Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
    © «Битрикс», 2001-2019, «1С-Битрикс», 2019
    Наверх