Feature/248 add sale payment

CHANGELOG.md

@@ -1,5 +1,18 @@
 # b24-php-sdk change log
 
+## Upcoming 1.7.0 - 2025.10.01
+
+### Added
+
+- Added service `Services\Sale\Payment\Service\Payment` with support methods,
+  see [sale.payment.* methods](https://github.com/bitrix24/b24phpsdk/issues/248):
+    - `add` adds a payment
+    - `update` updates the fields of a payment
+    - `get` returns a payment by its identifier
+    - `list` returns a list of payments
+    - `delete` deletes a payment
+    - `getFields` returns the fields and settings for payments
+
 ## 1.6.0 – 2025.09.01
 
 ### Added

Makefile

@@ -290,6 +290,10 @@ integration_tests_task:
 .PHONY: integration_tests_sale
 integration_tests_sale:
 	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sale
+
+.PHONY: integration_tests_sale_payment
+integration_tests_sale_payment:
+	docker-compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sale_payment
 
 # work dev environment
 .PHONY: php-dev-server-up

phpunit.xml.dist

@@ -124,6 +124,9 @@
         <testsuite name="integration_tests_sale">
             <directory>./tests/Integration/Services/Sale/</directory>
         </testsuite>
+        <testsuite name="integration_tests_sale_payment">
+            <directory>./tests/Integration/Services/Sale/Payment/</directory>
+        </testsuite>
         <testsuite name="integration_tests_sale_order">
             <directory>./tests/Integration/Services/Sale/Order/</directory>
         </testsuite>

src/Services/Sale/Payment/Result/PaymentAddedResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AddedItemResult;
+
+/**
+ * Class PaymentAddedResult
+ * Represents the result of an add payment operation.
+ */
+class PaymentAddedResult extends AddedItemResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getId(): int
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        return isset($result['payment']['id']) ? (int)$result['payment']['id'] : 0;
+    }
+}

src/Services/Sale/Payment/Result/PaymentFieldsResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Class PaymentFieldsResult
+ * Represents the result of a get payment fields operation.
+ */
+class PaymentFieldsResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getFieldsDescription(): array
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        return $result['payment'] ?? [];
+    }
+}

src/Services/Sale/Payment/Result/PaymentItemResult.php

@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
+use Money\Money;
+
+/**
+ * Class PaymentItemResult
+ * Represents a single payment item (payment) returned by Bitrix24 REST API.
+ *
+ * Fields and their types are taken from Bitrix24 API (sale.payment.getfields).
+ *
+ * @property-read string|null $accountNumber Payment account number
+ * @property-read string|null $comments Payment comments
+ * @property-read int|null    $companyId Company identifier
+ * @property-read string|null $currency Payment currency code
+ * @property-read CarbonImmutable|null $dateBill Invoice date
+ * @property-read CarbonImmutable|null $dateMarked Date when payment was marked
+ * @property-read CarbonImmutable|null $datePaid Payment date
+ * @property-read CarbonImmutable|null $datePayBefore Date by which the invoice must be paid
+ * @property-read CarbonImmutable|null $dateResponsibleId Date when responsible was assigned
+ * @property-read int|null    $empMarkedId User who marked the payment
+ * @property-read int|null    $empPaidId User who made the payment
+ * @property-read int|null    $empResponsibleId User who assigned the responsible
+ * @property-read int|null    $empReturnId User who processed the return
+ * @property-read bool|null $externalPayment External payment flag
+ * @property-read int|null    $id Payment ID
+ * @property-read string|null $id1c Identifier in QuickBooks
+ * @property-read bool|null $isReturn Return processed flag
+ * @property-read bool|null $marked Problem marking flag
+ * @property-read int|null    $orderId Order ID
+ * @property-read bool|null $paid Payment status
+ * @property-read string|null $payReturnComment Return comment
+ * @property-read CarbonImmutable|null $payReturnDate Return document date
+ * @property-read string|null $payReturnNum Return document number
+ * @property-read int|null    $paySystemId Payment system ID
+ * @property-read bool|null $paySystemIsCash Is cash payment system
+ * @property-read string|null $paySystemName Payment system name
+ * @property-read string|null $paySystemXmlId Payment system XML ID
+ * @property-read CarbonImmutable|null $payVoucherDate Payment document date
+ * @property-read string|null $payVoucherNum Payment document number
+ * @property-read Money|null $priceCod Cost of payment upon delivery
+ * @property-read string|null $psCurrency Payment system currency
+ * @property-read string|null $psInvoiceId Payment ID in payment system
+ * @property-read CarbonImmutable|null $psResponseDate Payment system response date
+ * @property-read bool|null $psStatus Payment system status
+ * @property-read string|null $psStatusCode Payment system status code
+ * @property-read string|null $psStatusDescription Description of payment system result
+ * @property-read string|null $psStatusMessage Message from payment system
+ * @property-read Money|null  $psSum Payment system amount
+ * @property-read string|null $reasonMarked Reason for marking
+ * @property-read int|null    $responsibleId User responsible for payment
+ * @property-read Money|null  $sum Payment amount
+ * @property-read bool|null $updated1c Updated via QuickBooks flag
+ * @property-read string|null $version1c Payment document version
+ * @property-read string|null $xmlId External identifier
+ */
+class PaymentItemResult extends AbstractItem
+{
+}

src/Services/Sale/Payment/Result/PaymentResult.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Class PaymentResult
+ * Represents the result of a single payment operation.
+ */
+class PaymentResult extends AbstractResult
+{
+    /**
+     * Returns the payment as PaymentItemResult
+     */
+    public function payment(): PaymentItemResult
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        return new PaymentItemResult($result['payment'] ?? []);
+    }
+}

src/Services/Sale/Payment/Result/PaymentUpdatedResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\UpdatedItemResult;
+
+/**
+ * Class PaymentUpdatedResult
+ * Represents the result of an update payment operation.
+ */
+class PaymentUpdatedResult extends UpdatedItemResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function isSuccess(): bool
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        return isset($result['payment']) && !empty($result['payment']);
+    }
+}

src/Services/Sale/Payment/Result/PaymentsResult.php

@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Sally Fancen <[email protected]>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Sale\Payment\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+/**
+ * Class PaymentsResult
+ * Represents the result of a list payments operation.
+ */
+class PaymentsResult extends AbstractResult
+{
+    /**
+     * Returns an array of payment items
+     *
+     * @return PaymentItemResult[] array of payment item results
+     */
+    public function getPayments(): array
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+        $payments = $result['payments'] ?? [];
+        return array_map(fn ($payment): PaymentItemResult => new PaymentItemResult($payment), $payments);
+    }
+}