Merge pull request #64 from AltaPay/add_misisng_customerinfo_param

Add support for new customer organization fields

Author: emicha

.github/workflows/sonarqube-analysis.yml

@@ -0,0 +1,31 @@
+name: SonarQube Analysis
+
+on:
+  pull_request:
+  push:
+    branches: ["**"]
+    
+jobs:
+  build:
+    name: Run SonarQube Analysis
+    runs-on: self-hosted
+    
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: SonarQube Scan
+        uses: sonarsource/sonarqube-scan-action@v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+
+      - name: SonarQube Quality Gate check
+        id: sonarqube-quality-gate-check
+        uses: sonarsource/sonarqube-quality-gate-action@v1.2.0
+        with:
+          pollingTimeoutSec: 600
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.6] - 2025-10-27
+### Added
+- Add support for new customer organization fields: `organisation_name`, `organisation_entity_type`, and `organisation_vat_id` with proper validation.
+- Deprecate legacy customer fields (`company_name`, `company_type`, `vat_id`, `type`) with runtime warnings and migration guidance.
+
 ## [3.5.5] - 2025-10-09
 ### Fixes
 - Fix deprecation warnings on PHP 8.4

docs/request/customerinfo.md

@@ -46,9 +46,17 @@ setBankPhone(string) | Customer bank phone | string
 setBirthdate(DateTime) | Customer birthdate | DateTime
 setCreatedDate(DateTime) | When was the customer created | DateTime
 setOrganisationNumber(string) | The country specific organisation number for the customer, if it is a corporate customer. | string
+setOrganisationName(string) | The organisation name. **Preferred over setCompanyName()** | string
+setOrganisationEntityType(string) | The organisation nature. **Validated values:** ltd (limited company), plc (public limited company), public_institution (public institution), other (all other types). **Preferred over setCompanyType()** | string
+setVatId(string) | **Deprecated:** The VAT identifier. Use setOrganisationVatId() instead | string
+setOrganisationVatId(string) | The organisation VAT identifier. **Preferred method for VAT ID** | string
 setPersonalIdentifyNumber(string) | The country specific personal identity number for the customer, for countries where it is applicable. eg. Norway, Sweden, Finland | string
 setGender(string) | What gender is the customer | String (f, female, m, male)
 setCardHolderName(string) | Set the cardholder name associated with the customer | string
+**Deprecated Methods** | |
+setType(string) | **Deprecated:** Customer type indicator. Any organisation_* field automatically triggers business customer | string
+setCompanyName(string) | **Deprecated:** Use setOrganisationName() instead | string
+setCompanyType(string) | **Deprecated:** Use setOrganisationEntityType() instead | string
 ```php
 $customer->setEmail('email@email.com');
 $customer->setBirthdate(new \DateTime('1982-07-23'));

sonar-project.properties

@@ -0,0 +1,3 @@
+sonar.projectKey=AltaPay_api-php_90804e1e-91c4-43f6-a024-51f03ac0e4e8
+sonar.projectBaseDir=src
+sonar.coverage.exclusions=**

src/AbstractApi.php

@@ -55,7 +55,7 @@ abstract class AbstractApi
     /**
      * PHP API version
      */
-    const PHP_API_VERSION = '3.5.5';
+    const PHP_API_VERSION = '3.5.6';
 
     /**
      * Event dispatcher

src/Request/Customer.php

@@ -24,6 +24,7 @@
 namespace Altapay\Request;
 
 use Altapay\Exceptions\Exception;
+use Altapay\Types\OrganisationEntityTypes;
 
 class Customer extends AbstractSerializer
 {
@@ -47,27 +48,31 @@ class Customer extends AbstractSerializer
     /**
      * Indicator of whether the customer is an individual or a business.
      *
+     * @deprecated Any customer_info[organisation_*] field set will trigger the business customer indicator.
      * @var string
      */
     private $type;
 
     /**
      * Name of the customer,if the customer type is Business.
      *
+     * @deprecated Use customer_info[organisation_name] field instead.
      * @var string
      */
     private $companyName;
 
     /**
      * The nature of the company.
      *
+     * @deprecated Use customer_info[organisation_entity_type] field instead.
      * @var string
      */
     private $companyType;
 
     /**
      * The company's VAT registration number.
      *
+     * @deprecated Use customer_info[organisation_vat_id] field instead.
      * @var string
      */
     private $vatId;
@@ -114,6 +119,27 @@ class Customer extends AbstractSerializer
      */
     private $organisationNumber;
 
+    /**
+     * The organisation name.
+     *
+     * @var string
+     */
+    private $organisationName;
+
+    /**
+     * The organisation nature (ltd, plc, public_institution, other).
+     *
+     * @var string
+     */
+    private $organisationEntityType;
+
+    /**
+     * The organisation VAT identifier.
+     *
+     * @var string
+     */
+    private $organisationVatId;
+
     /**
      * The country specific personal identity number for the customer,
      * for countries where it is applicable. eg. Norway, Sweden, Finland
@@ -315,6 +341,7 @@ public function setUsername($username)
     /**
      * Set Customer Type
      *
+     * @deprecated Any customer_info[organisation_*] field set will trigger the business customer indicator.
      * @param string $type
      *
      * @return $this
@@ -329,6 +356,7 @@ public function setType($type)
     /**
      * Set Company Name
      *
+     * @deprecated Use setOrganisationName() method instead.
      * @param string $companyName
      *
      * @return $this
@@ -343,6 +371,7 @@ public function setCompanyName($companyName)
     /**
      * Set Company Type
      *
+     * @deprecated Use setOrganisationEntityType() method instead.
      * @param string $companyType
      *
      * @return $this
@@ -357,6 +386,7 @@ public function setCompanyType($companyType)
     /**
      * Set VAT Id
      *
+     * @deprecated Use setOrganisationVatId() method instead. The vat_id field is deprecated.
      * @param string $vatId
      *
      * @return $this
@@ -500,6 +530,54 @@ public function setOrganisationNumber($organisationNumber)
         return $this;
     }
 
+    /**
+     * Set Organisation Name
+     *
+     * @param string $organisationName
+     *
+     * @return $this
+     */
+    public function setOrganisationName($organisationName)
+    {
+        $this->organisationName = $organisationName;
+
+        return $this;
+    }
+
+    /**
+     * Set Organisation Entity Type
+     *
+     * @param string $organisationEntityType
+     *
+     * @return $this
+     *
+     * @throws Exception
+     */
+    public function setOrganisationEntityType($organisationEntityType)
+    {
+        if (!OrganisationEntityTypes::isAllowed($organisationEntityType)) {
+            throw new Exception('setOrganisationEntityType() only allows the values: ' . implode(', ', OrganisationEntityTypes::getAllowed()));
+        }
+
+        $this->organisationEntityType = $organisationEntityType;
+
+        return $this;
+    }
+
+    /**
+     * Set Organisation VAT ID
+     *
+     * @param string $organisationVatId
+     *
+     * @return $this
+     */
+    public function setOrganisationVatId($organisationVatId)
+    {
+        $this->organisationVatId = $organisationVatId;
+
+        return $this;
+    }
+
     /**
      * @param string $personalIdentifyNumber
      *
@@ -793,9 +871,20 @@ public function serialize()
         }
 
         if ($this->organisationNumber) {
-            $output['organisationNumber'] = $this->organisationNumber;
+            $output['organisation_number'] = $this->organisationNumber;
+        }
+
+        if ($this->organisationName) {
+            $output['organisation_name'] = $this->organisationName;
         }
 
+        if ($this->organisationEntityType) {
+            $output['organisation_entity_type'] = $this->organisationEntityType;
+        }
+
+        if ($this->organisationVatId) {
+            $output['organisation_vat_id'] = $this->organisationVatId;
+        }
         if ($this->personalIdentifyNumber) {
             $output['personalIdentifyNumber'] = $this->personalIdentifyNumber;
         }

src/Types/OrganisationEntityTypes.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * Copyright (c) 2025 AltaPay
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is furnished
+ * to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+namespace Altapay\Types;
+
+/**
+ * Allowed organisation entity types
+ */
+class OrganisationEntityTypes implements TypeInterface
+{
+    /**
+     * Allowed organisation entity types
+     *
+     * @var list<string>
+     */
+    private static $types = [
+        'ltd',
+        'plc',
+        'public_institution',
+        'other',
+    ];
+
+    /**
+     * Get allowed values
+     *
+     * @return list<string>
+     */
+    public static function getAllowed()
+    {
+        return self::$types;
+    }
+
+    /**
+     * Is the requested value allowed
+     *
+     * @param string $value
+     *
+     * @return bool
+     */
+    public static function isAllowed($value)
+    {
+        return in_array($value, self::$types);
+    }
+}

tests/Request/CustomerTest.php

@@ -21,11 +21,11 @@ public function test_customer(): void
         $customer->setGender('f');
         $serialized = $customer->serialize();
 
-        $this->assertArrayHasKey('organisationNumber', $serialized);
+        $this->assertArrayHasKey('organisation_number', $serialized);
         $this->assertArrayHasKey('personalIdentifyNumber', $serialized);
         $this->assertArrayHasKey('gender', $serialized);
 
-        $this->assertSame('123', $serialized['organisationNumber']);
+        $this->assertSame('123', $serialized['organisation_number']);
         $this->assertSame('20304050', $serialized['personalIdentifyNumber']);
         $this->assertSame('F', $serialized['gender']);