Documentation

Payments

Attention! Shipments are always associated with orders. It's categorically prohibited to use the method \Bitrix\Sale\Shipment::save() for saving shipments. When updating a shipment changes, associated entities may be updated, which will not be saved. Saving action must be performed via the order method: \Bitrix\Sale\Order::save(). Additionally, calling \Bitrix\Sale\Shipment::save() will generate error E_WARNING.

  • Receiving payments:
  • Getting specific payment
  • Adding a payment
  • Editing payment
  • Deleting payment
  • Getting payment amount
  • Getting current payment status: paid or not
  • Refund
  • Getting paid amount for an order
  • Getting payment system object
  • Getting list of available payment systems with account to configured restrictions
    •

    Receiving payments

    • Handling a collection 
      $collection = $order->getPaymentCollection();
foreach ($collection as $payment)
{
	// ...
}
    • Handling an array

      In addition to objects, there is an option to directly query the database via the method \Bitrix\Sale\PaymentCollection::getList($parameters), or \Bitrix\Sale\Payment::getList($parameters). Both these methods operates similarly.

      Method always return the object Bitrix\Main\DB\Result, to retrieve data using the method fetch().

      Parameter Description Available from version
      $parameters Array with structure fully matching ORM's getList. 
      // getting list of payments for order 1234
$dbRes = \Bitrix\Sale\PaymentCollection::getList([
	'select' => ['*'],
	'filter' => [
		'=ORDER_ID' => 1234, 
	]
]);

while ($item = $dbRes->fetch())
{
	var_dump($item);
}

    Getting a specific payment

    $collection = $order->getPaymentCollection();
    • by ID: 
      $payment = $collection->getItemById($id);
    • by internal index: 
      $payment = $collection->getItemByIndex($index);

    Adding a payment

    • Variant 1: 
      /*
 * $collection - object of class \Bitrix\Sale\PaymentCollection
 */

$payment = $collection->createItem();
$payment->setFields([
	'PAY_SYSTEM_ID' => 10,
	'SUM' => 100,
]);
    • Variant 2: 
      /*
 * method \Bitrix\Sale\PaymentCollection::createItem receives one optional parameter: $paySystemService - payment system object
 */
$service = \Bitrix\Sale\PaySystem\Manager::getObjectById(10);
$payment = $collection->createItem($service);
		
$payment->setField('SUM', 100);
    • Variant 3: 
      /*
 * You also pass a payment object to the method \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);

    Editing a payment

    Payment data can be updated via the methods:

    • $r = $payment->setField($fieldName, $value);

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

    In both cases, method result is an object of class \Bitrix\Sale\Result.

    List of fields available for editing:

    'PAID', // Paid flag: Y or N
'DATE_PAID', // Payment date
'EMP_PAID_ID', // Who paid
'PAY_SYSTEM_ID', // payment system ID
'PS_INVOICE_ID', // payment ID in payment system
'PS_STATUS', // data, received from payment system: transaction status
'PS_STATUS_CODE', // data, received from payment system: transaction code
'PS_STATUS_DESCRIPTION', // data, received from payment system: transaction description
'PS_STATUS_MESSAGE', // data, received from payment system: message
'PS_SUM', // data, received from payment system: transaction amount
'PS_CURRENCY', // data, received from payment system: currency
'PS_RESPONSE_DATE', // data, received from payment system: payment system response date
'PAY_VOUCHER_NUM', // payment document number 
'PAY_VOUCHER_DATE', // payment document date
'DATE_PAY_BEFORE', // invoice due date (not used in online store)
'DATE_BILL', // date of invoice
'XML_ID', // XML_ID
'SUM', // payment total
'CURRENCY', // currency
'PAY_SYSTEM_NAME', // payment system name 
'COMPANY_ID', // company ID that will receive payment
'PAY_RETURN_NUM', // refund document number
'PAY_RETURN_DATE',  // refund document date
'PAY_RETURN_COMMENT', // comment to refund
'PRICE_COD', // Cost on delivery (used, for example for payment on delivery conditions)
'EMP_RETURN_ID', // user ID, who performed refund
'RESPONSIBLE_ID', // user ID, responsible for refund
'EMP_RESPONSIBLE_ID', // ID пользователя, который назначил ответственного
'DATE_RESPONSIBLE_ID', // date of assigned responsible user
'IS_RETURN', // performed refund. (see payment refund block below in this section)
'COMMENTS', // comment to payment
'ACCOUNT_NUMBER', // payment number
'UPDATED_1C', // updated using 1С accounting system
'ID_1C', // ID in 1С accounting system
'VERSION_1C', // payment document version in 1C
'EXTERNAL_PAYMENT', // flag Y/N: external payment or not
'MARKED', // marked payment
'REASON_MARKED', // reason for marking
'DATE_MARKED', // date of marking
'EMP_MARKED_ID', // who marked the payment

    Deleting payment

    Returns object type \Bitrix\Sale\Result.

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

    Getting payment amount

    $sum = $payment->getSum();

    Getting current payment status: paid or not

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

    $isPaid = $payment->isPaid();

    Refund

    Method receives single parameter, with the following values:

    • 'Y' - when refunding to internal account; 
      $r = $payment->setReturn('Y');
if (!$r->isSuccess())
{
	var_dump($r->getErrorMessages());
}
    • 'P' - when returning via payment system (when it supports this feature); 
      $r = $payment->setReturn('P');
if (!$r->isSuccess())
{
	var_dump($r->getErrorMessages());
}
    • 'N' - when refund cancelled. 
      $r = $payment->setReturn('N');
if (!$r->isSuccess())
{
	var_dump($r->getErrorMessages());
}

    Returns object type \Bitrix\Sale\Result. When performing refund, you don't have to perform additional operations such as calling payment system API methods for a refund. The system performs such operations automatically. When attempting to perform refund via payment system that doesn't support it, returns an error.

    Getting paid amount for an order 

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

    Getting payment system object

    Method result is object of class \Bitrix\Sale\PaySystem\Service. 

    $service = $payment->getPaySystem();

    list of available payment systems with account to configured restrictions 

    $paySystemList = \Bitrix\Sale\PaySystem\Manager::getListWithRestrictions($payment, $mode);
    Parameters Description Available from version
    $payment Payment object.
    $mode One of two values:
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT
    • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_MANAGER

    Default: \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT. Client mode returns list of only payment systems that fall under restrictions.

    Manager mode returns full list of payment systems (systems that do not fall under restrictions have the key RESTRICTED).


    © «Bitrix24», 2001-2024