Cash register methods

Attention! Before initializing cash register for printing receipts via payment system, we recommend to read about writing a custom online cash register handler.

Class \Bitrix\Sale\Cashbox\CashboxPaySystem

Your cash register must inherit the class CashboxPaySystem. This is an abstract class, containing abstract methods to be implemented in the descendant class.

abstract class CashboxPaySystem extends Cashbox implements IPrintImmediately, ICheckable
{
    abstract protected function getPrintUrl(): string;

    abstract protected function getCheckUrl(): string;

    abstract protected function send(string $url, Sale\Payment $payment, array $fields): Sale\Result;

    abstract protected function processPrintResult(Sale\Result $result): Sale\Result;

    abstract protected function getDataForCheck(Sale\Payment $payment): array;

    abstract protected function processCheckResult(Sale\Result $result): Sale\Result;

    abstract protected function onAfterProcessCheck(Sale\Result $result, Sale\Payment $payment): Sale\Result;

    abstract public static function getPaySystemCodeForKkm(): string;
}

Class CashboxPaySystem implements the interfaces IPrintImmediately and ICheckable. This allows printing receipts immediately when receiving payment and checking their status.

In addition to methods of class CashboxPaySystem, there is a following method:

abstract public function buildCheckQuery(Check $check);

This method is located in the class Cashbox and it must be implemented as well.

Let's overview the following methods in more detail:

• getPrintUrl

  abstract protected function getPrintUrl(): string;
  

  Method must return string with destination URL address to send data for printing closing receipt.

  This method is used in the method \Bitrix\Sale\Cashbox\CashboxPaySystem::printImmediately.



• getCheckUrl

  abstract protected function getCheckUrl(): string;
  

  The method must return a string with URL address that you can query to get the receipt status.

  This method is used in the method \Bitrix\Sale\Cashbox\CashboxPaySystem::check.



• send

  abstract protected function send(string $url, Sale\Payment $payment, array $fields): Sale\Result;
  

  Method gets URL address to send a query, payment object and array with data.

  This method is used in the methods \Bitrix\Sale\Cashbox\CashboxPaySystem::printImmediately and \Bitrix\Sale\Cashbox\CashboxPaySystem::check.

  Method must send data to specified URL only and return a result or error in case something is wrong.

  Let's overview an example, when method is called when printing a receipt. In such a case, method gets URL for receipt printing and receipt data, previously prepared by the method buildCheckQuery. If required, the method must prepare data for sending, i. e., sign the data before sending. Then, data is passed to payment gate and the retrieved result is returned. Next, this result will be processed in the method processPrintResult.



• processPrintResult

  abstract protected function processPrintResult(Sale\Result $result): Sale\Result;
  

  This method processes the receipt printing result, retrieved previously by the method send. Usually, during the processing, you need to return UUID - receipt external identifier, or an error, if something went wrong.



• getDataForCheck

  abstract protected function getDataForCheck(Sale\Payment $payment): array;
  

  Method must return data, needed for checking the receipt. For example, receipt ID, previously got when sending receipt for printing.

  Data will be sent to URL, fetched by the method getCheckUrl.

  This method is used in the method \Bitrix\Sale\Cashbox\CashboxPaySystem::check.



• processCheckResult

  abstract protected function processCheckResult(Sale\Result $result): Sale\Result;
  

  This method processes the result of receipt status verification. As a standard, processing verifies a receipt status, for example, in terms of printing (printed or an error). Method gets a result as an argument, previously returned by the method send.

  The method must return the result, subsequently used in the method onAfterProcessCheck or an error, if something went wrong.



• onAfterProcessCheck

  abstract protected function onAfterProcessCheck(Sale\Result $result, Sale\Payment $payment): Sale\Result;
  

  As the first argument, method get the result, returned previously by the method processCheckResult.

  On successful status verification, you need to call \Bitrix\Sale\Cashbox\Cashbox::applyCheckResult in the method to save the result of such verification. Or you need to return an error, if, for example, receipt isn't printed yet and you need to execute the query later.

  Attention! When calling the method \Bitrix\Sale\Cashbox\Cashbox::applyCheckResult you need to ensure that your cash register has an implemented method \Bitrix\Sale\Cashbox\Cashbox::extractCheckData, otherwise throws an exception \Bitrix\Main\NotImplementedException.



• getPaySystemCodeForKkm

  abstract public static function getPaySystemCodeForKkm(): string;
  

  Method must return payment system code, to subsequently create a cash register. Usually, this is a login field code.

  Cash register is added automatically when enabling receipt printing via payment system. Cash register is "associated" not to a specific payment system, but to an account, handled by the payment system.

  For example, in case of 2 available payment systems using 1 handler and configured with the same login - creates 1 cash register to be used for printing receipts for both payment systems. When there are 2 payment systems that are using 1 handler, but configured with different logins, 2 cash register are added (if receipt printing is enabled for both payment systems).