Merge branch 'examples_interface_fix' into 'main'

card details full bank name fix

See merge request ypmn-public/php-api-client!39

Author: payuru

README.md

@@ -33,41 +33,41 @@
 
 Пример быстрого старта для приёма платежей:
 ```php
-$merchant = new Merchant('MERCHANT_CODE', 'SECRET_KEY');
+$merchant = new Merchant('MERCHANT_CODE', 'SECRET_KEY'); // Коды подключения API
+$merchantPaymentReference = 123; // Номер заказа в вашей системе
 $billing = (new Billing)
-  ->setCountryCode('RU')
-  ->setFirstName('Иван')
-  ->setLastName('Петров')
-  ->setEmail('test1@ypmn.ru')
-  ->setPhone('+74996492009')
-  ->setCity('Москва');
+  ->setCountryCode('RU') // Страна Плательщика
+  ->setFirstName('Иван') // Имя Плательщика
+  ->setLastName('Петров') // Фамилия Плательщика
+  ->setEmail('test1@ypmn.ru') // Почта Плательщика
+  ->setPhone('+74996492009') // Телефон Плательщика
+  ->setCity('Москва');  // Город Плательщика
 
-$client = (new Client)
-  ->setBilling($billing);
-
+$client = (new Client)->setBilling($billing);
 $payment = (new Payment)
   ->addProduct(new Product([
-    'name'  => 'Заказ №' . $merchantPaymentReference,
-    'sku'  => $merchantPaymentReference,
-    'unitPrice'  => 20.42,
-    'quantity'  => 1,
+    'name'  => 'Заказ №' . $merchantPaymentReference, // Наименование товарной позиции
+    'sku'  => 'test_artikul', // Артикул
+    'unitPrice'  => 20.42, // Стоимость единицы
+    'quantity'  => 1, // Количество
 ]));
 $payment_method = $_GET['method'] ?? PaymentMethods::CCVISAMC; // Определим платёжный метод
 $authorization = new Authorization($payment_method, true);
 $payment->setAuthorization($authorization);
 $payment->setMerchantPaymentReference($merchantPaymentReference);
-$payment->setReturnUrl('https://' . @$_SERVER['HTTP_HOST'] . '/php-api-client/?function=returnPage');
+$payment->setSuccessUrl('https://' . $_SERVER['HTTP_HOST'] . '/?status=success'); // Редирект после успешной оплаты
+$payment->setFailUrl('https://' . $_SERVER['HTTP_HOST'] . '/?status=success'); // Редирект в случае неоплаты
 $payment->setClient($client);
+
 $apiRequest = new ApiRequest($merchant);
 $responseData = $apiRequest->sendAuthRequest($payment, $merchant);
-$responseData = json_decode((string) $responseData["response"], true);
-
+$responseData = json_decode((string) $responseData["response"], true); // Отправка запроса и обработка ответа
 if (isset($responseData["paymentResult"])) {
     if (!empty($responseData['paymentResult']['bankResponseDetails']['customBankNode']['qr'])) {
         $qr = $responseData['paymentResult']['bankResponseDetails']['customBankNode']['qr'];
     }
 
-    // Выведем кнопку оплаты, рекомендуется
+    // Выведем кнопку оплаты (рекомендуется)
     echo Std::drawYpmnButton([
         'qr' => ($qr ?? null),
         'url' => $responseData['paymentResult']['url'] ?? '',
@@ -87,7 +87,7 @@ if (isset($responseData["paymentResult"])) {
 - безопасность и точность расчётов
 
 Библиотека содержит:
-- Клиент API
+- Клиент для работы с API платежей, выплат, отчётов
 - Простой встроенный сервер с примерами
 - Описание контейнера для запуска в Docker
 

src/ApiRequest.php

@@ -368,7 +368,7 @@ private function sendPostPutRequest(
         $curl = curl_init();
         $date = (new DateTime())->format(DateTimeInterface::ATOM);
 
-        $useragent = "SDK_" . @PHP_VERSION;
+        $useragent = "SDK_PHP_" . @PHP_VERSION;
         $referer =  @$_SERVER['HTTP_HOST'] ?? @$_SERVER['SERVER_NAME'] ?? "" . @$_SERVER['REQUEST_URI'] ?? "";
 
         $setOptArray = [

src/CardDetails.php

@@ -41,6 +41,9 @@ class CardDetails implements CardDetailsInterface
     /** @var string Банк, выпустивший карту */
     private string $cardIssuerBank;
 
+    /** @var string Банк, выпустивший карту (полное наименование) */
+    private string $cardIssuerBankFullName;
+
     /** Protobuf generation Trait */
     use ProtobufSerializable;
 
@@ -69,6 +72,7 @@ public function getExpiryMonth(): ?int
     public function setExpiryMonth(int $expiryMonth): self
     {
         $this->expiryMonth = $expiryMonth;
+
         return $this;
     }
 
@@ -84,8 +88,8 @@ public function setYear(int $year): self
         if ( $year< 1900) {
             throw new PaymentException('Проверьте год выпуска карты');
         }
-
         $this->year = $year;
+
         return $this;
     }
 
@@ -99,6 +103,7 @@ public function getExpiryYear(): ?int
     public function setExpiryYear(int $expiryYear): self
     {
         $this->expiryYear = $expiryYear;
+
         return $this;
     }
 
@@ -112,6 +117,7 @@ public function getCvv(): ?string
     public function setCvv(string $cvv): self
     {
         $this->cvv = $cvv;
+
         return $this;
     }
 
@@ -125,6 +131,7 @@ public function getOwner(): ?string
     public function setOwner(string $owner): self
     {
         $this->owner = $owner;
+
         return $this;
     }
 
@@ -138,6 +145,7 @@ public function getTimeSpentTypingNumber(): ?int
     public function setTimeSpentTypingNumber(int $timeSpentTypingNumber): self
     {
         $this->timeSpentTypingNumber = $timeSpentTypingNumber;
+
         return $this;
     }
 
@@ -151,6 +159,7 @@ public function getTimeSpentTypingOwner(): ?int
     public function setTimeSpentTypingOwner(int $timeSpentTypingOwner): self
     {
         $this->timeSpentTypingOwner = $timeSpentTypingOwner;
+
         return $this;
     }
 
@@ -164,6 +173,7 @@ public function getBin(): ?int
     public function setBin(int $bin): self
     {
         $this->bin = $bin;
+
         return $this;
     }
 
@@ -177,6 +187,7 @@ public function getPan(): ?string
     public function setPan(string $pan): self
     {
         $this->pan = $pan;
+
         return $this;
     }
 
@@ -190,6 +201,7 @@ public function getType(): ?string
     public function setType(string $type): self
     {
         $this->type = $type;
+
         return $this;
     }
 
@@ -203,6 +215,21 @@ public function getCardIssuerBank(): ?string
     public function setCardIssuerBank(string $cardIssuerBank): self
     {
         $this->cardIssuerBank = $cardIssuerBank;
+
+        return $this;
+    }
+
+    /** @inheritDoc */
+    public function getCardIssuerBankFullName(): ?string
+    {
+        return $this->cardIssuerBankFullName ?? null;
+    }
+
+    /** @inheritDoc */
+    public function setCardIssuerBankFullName(string $cardIssuerBankFullName): CardDetails
+    {
+        $this->cardIssuerBankFullName = $cardIssuerBankFullName;
+
         return $this;
     }
 

src/CardDetailsInterface.php

@@ -138,6 +138,19 @@ public function setCardIssuerBank(string $cardIssuerBank) : self;
      */
     public function getCardIssuerBank() : ?string;
 
+    /**
+     * Установить Полное наименование Банка, выпустившего карту
+     * @param string $cardIssuerBankFullName
+     * @return CardDetails
+     */
+    public function setCardIssuerBankFullName(string $cardIssuerBankFullName): CardDetails;
+
+    /**
+     * Получить Полное наименование Банка, выпустившего карту
+     * @return string|null Полное наименование Банка, выпустившего карту
+     */
+    public function getCardIssuerBankFullName(): ?string;
+
     /**
      * Получить Год Карты
      * @return int|null Год Карты

src/Examples/returnPage.php

@@ -1,7 +1,12 @@
 <?php
 /**
- * Страница после оплаты.
- * Параметры передаются в $_GET или $_POST, в зависимости от настройки мерчанта в YPMN:
+ * @deprecated Используйте новые параметры
+ * `successUrl` после успешной оплаты
+ * и `failUrl` после неудачной оплаты
+ * https://ypmn.ru/doc/#tag/payment-api-return-url
+ *
+ * Ниже старая (единая) страница после оплаты.
+ * В ней параметры передаются в $_GET или $_POST, в зависимости от настройки мерчанта в YPMN
  */
 $statusResponseFromServer = (json_decode($_POST['body'] ?? '{}', true))['status'] ?? null;
 

src/Examples/start.php

@@ -16,4 +16,3 @@
  * Убедитесь, что эти адреса разрешены в Firewall вашего приложения
  */
 $merchant = new Merchant('gitttest', 'vk0!K4(~9)1d69@0p4&N');
-//$merchant = new Merchant('CLD_FUL', 'SECRET_KEY');

src/Webhook.php

@@ -90,6 +90,10 @@ public function catchJsonRequest(): self
                 $cardDetails->setCardIssuerBank($request['paymentResult']['cardDetails']['cardIssuerBank']);
             }
 
+            if (!empty($request['paymentResult']['cardDetails']['cardIssuerBankFullName'])) {
+                $cardDetails->setCardIssuerBankFullName($request['paymentResult']['cardDetails']['cardIssuerBankFullName']);
+            }
+
             $this->paymentResult = new PaymentResult;
             $this->paymentResult->setCardDetails($cardDetails);