Add alternative payment methods support (like Google Pay)

.github/workflows/php.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       matrix:
         operating-system: [ubuntu-latest]
-        php-versions: ['7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3']
+        php-versions: ['7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4']
     name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
 
     steps:

README.md

@@ -243,6 +243,34 @@ if (
 }
 ```
 
+### Using alternative payment methods
+
+To use an alternative payment method (like Google Pay), send a received token AS-IS or data from a decrypted token.
+
+```php
+<?php
+
+use TransactPro\Gateway\DataSets\Command;
+
+// set a corresponding flag that indicates a token provider
+$operation->command()->setPaymentMethodType(Command::PAYMENT_METHOD_TYPE_GOOGLE_PAY);
+
+// option 1: send received token AS-IS
+$operation->paymentMethod()->setToken('<token>');
+
+// option 2: send data from decrypted token
+$operation->paymentMethod()
+    ->setPAN('<card number>')
+    ->setExpire('<card expiry>')
+    ->setCardHolderName('<cardholder name>') // if available
+    ->setExternalTokenCryptogram('<cryptogram from token>') // if available
+    ->setExternalTokenECI('<ECI from token>') // if available
+    ->setExternalTokenTransStatus('<transStatus from token>') // available for Click to Pay
+    ->setExternalTokenDsTransId('<dsTransId from token>') // available for Click to Pay
+    ->setExternalTokenAcsTransId('<acsTransId from token>') // available for Click to Pay
+    ->setExternalTokenCardHolderAuthenticated($decryptedToken['paymentMethodDetails']['assuranceDetails']['cardHolderAuthenticated']); // for Google Pay
+```
+
 ### Callback validation
 
 ```php

src/Gateway/DataSets/Command.php

@@ -31,6 +31,11 @@ class Command extends DataSet implements DataSetInterface
     const DATA_SOURCE_USE_GATEWAY_SAVED_MERCHANT_INITIATED = 5;
     const DATA_SOURCE_USE_MERCHANT_SAVED_MERCHANT_INITIATED = 6;
 
+    const PAYMENT_METHOD_TYPE_CARD = 'cc';
+    const PAYMENT_METHOD_TYPE_GOOGLE_PAY = 'google_pay';
+    const PAYMENT_METHOD_TYPE_APPLE_PAY = 'apple_pay';
+    const PAYMENT_METHOD_TYPE_CLICK2PAY = 'click2pay';
+
     /**
      * @param  string  $gatewayTransactionID
      * @return Command
@@ -96,4 +101,15 @@ public function setPaymentMethodDataToken(string $paymentMethodDataToken): self
 
         return $this;
     }
+
+    /**
+     * @param  string  $paymentMethodType
+     * @return Command
+     */
+    public function setPaymentMethodType(string $paymentMethodType): self
+    {
+        $this->data[ self::COMMAND_DATA_PAYMENT_METHOD_TYPE ] = $paymentMethodType;
+
+        return $this;
+    }
 }

src/Gateway/DataSets/DataSet.php

@@ -28,6 +28,7 @@ abstract class DataSet
     const COMMAND_DATA_CARD_VERIFICATION = 'data.command-data.card-verification';
     const COMMAND_DATA_PAYMENT_METHOD_DATA_SOURCE = 'data.command-data.payment-method-data-source';
     const COMMAND_DATA_PAYMENT_METHOD_DATA_TOKEN = 'data.command-data.payment-method-data-token';
+    const COMMAND_DATA_PAYMENT_METHOD_TYPE = 'data.command-data.payment-method-type';
 
     // customer data
     const GENERAL_DATA_CUSTOMER_DATA_EMAIL = 'data.general-data.customer-data.email';
@@ -69,12 +70,20 @@ abstract class DataSet
     const PAYMENT_METHOD_DATA_EXPIRE = 'data.payment-method-data.exp-mm-yy';
     const PAYMENT_METHOD_DATA_CVV = 'data.payment-method-data.cvv';
     const PAYMENT_METHOD_DATA_CARDHOLDER_NAME = 'data.payment-method-data.cardholder-name';
+    const PAYMENT_METHOD_DATA_TOKEN = 'data.payment-method-data.token';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_DATA = 'data.payment-method-data.external-mpi-data';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_PROTOCOL = 'data.payment-method-data.external-mpi-data.protocolVersion';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_DS_TRANS_ID = 'data.payment-method-data.external-mpi-data.dsTransID';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_XID = 'data.payment-method-data.external-mpi-data.xid';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_CAVV = 'data.payment-method-data.external-mpi-data.cavv';
     const PAYMENT_METHOD_DATA_EXTERNAL_MPI_TRANS_STATUS = 'data.payment-method-data.external-mpi-data.transStatus';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_DATA = 'data.payment-method-data.external-token-data';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_CRYPTOGRAM = 'data.payment-method-data.external-token-data.cryptogram';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_ECI = 'data.payment-method-data.external-token-data.eci';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_TRANS_STATUS = 'data.payment-method-data.external-token-data.transStatus';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_DS_TRANS_ID = 'data.payment-method-data.external-token-data.dsTransID';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_ACS_TRANS_ID = 'data.payment-method-data.external-token-data.acsTransID';
+    const PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_AUTHENTICATED = 'data.payment-method-data.external-token-data.cardHolderAuthenticated';
 
     // money data
     const MONEY_DATA_AMOUNT = 'data.money-data.amount';

src/Gateway/DataSets/PaymentMethod.php

@@ -64,6 +64,17 @@ public function setCardHolderName(string $cardHolderName): self
         return $this;
     }
 
+    /**
+     * @param  string        $token
+     * @return PaymentMethod
+     */
+    public function setToken(string $token): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_TOKEN] = $token;
+
+        return $this;
+    }
+
     /**
      * @param  string        $protocolVersion
      * @return PaymentMethod
@@ -118,4 +129,70 @@ public function setExternalMpiTransStatus(string $transStatus): self
 
         return $this;
     }
+
+    /**
+     * @param  string        $cryptogram
+     * @return PaymentMethod
+     */
+    public function setExternalTokenCryptogram(string $cryptogram): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_CRYPTOGRAM] = $cryptogram;
+
+        return $this;
+    }
+
+    /**
+     * @param  string        $eci
+     * @return PaymentMethod
+     */
+    public function setExternalTokenECI(string $eci): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_ECI] = $eci;
+
+        return $this;
+    }
+
+    /**
+     * @param  string        $transStatus
+     * @return PaymentMethod
+     */
+    public function setExternalTokenTransStatus(string $transStatus): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_TRANS_STATUS] = $transStatus;
+
+        return $this;
+    }
+
+    /**
+     * @param  string        $dsTransId
+     * @return PaymentMethod
+     */
+    public function setExternalTokenDsTransId(string $dsTransId): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_DS_TRANS_ID] = $dsTransId;
+
+        return $this;
+    }
+
+    /**
+     * @param  string        $acsTransId
+     * @return PaymentMethod
+     */
+    public function setExternalTokenAcsTransId(string $acsTransId): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_ACS_TRANS_ID] = $acsTransId;
+
+        return $this;
+    }
+
+    /**
+     * @param  bool          $value
+     * @return PaymentMethod
+     */
+    public function setExternalTokenCardHolderAuthenticated(bool $value): self
+    {
+        $this->data[self::PAYMENT_METHOD_DATA_EXTERNAL_TOKEN_AUTHENTICATED] = $value;
+
+        return $this;
+    }
 }

src/Gateway/Exceptions/DigestMismatchException.php

@@ -21,7 +21,7 @@
  */
 class DigestMismatchException extends ResponseException
 {
-    public function __construct($message = "Digest mismatch", $code = 0, Throwable $previous = null)
+    public function __construct($message = "Digest mismatch", $code = 0, ?Throwable $previous = null)
     {
         parent::__construct($message, $code, $previous);
     }

src/Gateway/Exceptions/DigestMissingException.php

@@ -20,7 +20,7 @@
  */
 class DigestMissingException extends ResponseException
 {
-    public function __construct($message = "Digest is missing", $code = 0, Throwable $previous = null)
+    public function __construct($message = "Digest is missing", $code = 0, ?Throwable $previous = null)
     {
         parent::__construct($message, $code, $previous);
     }

src/Gateway/Http/Crypto/ResponseDigest.php

@@ -28,7 +28,7 @@ class ResponseDigest extends Digest
      * @throws DigestMissingException
      * @throws DigestMismatchException
      */
-    public function __construct(string $authorizationHeader = null)
+    public function __construct(?string $authorizationHeader = null)
     {
         if (empty($authorizationHeader)) {
             throw new DigestMissingException();

src/Gateway/Http/Response.php

@@ -169,7 +169,7 @@ public function getDigest()
     /**
      * @param ResponseDigest|null $digest
      */
-    public function setDigest(ResponseDigest $digest = null)
+    public function setDigest(?ResponseDigest $digest = null)
     {
         $this->digest = $digest;
     }

src/Gateway/Responses/CallbackResult.php

@@ -13,7 +13,7 @@
 
 class CallbackResult extends PaymentResponse
 {
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         parent::__construct($rawDecoded['result-data'] ?? null);
     }

src/Gateway/Responses/CsvResponse.php

@@ -39,7 +39,7 @@ public function __construct(string $data)
             throw new ResponseException('Cannot parse CSV data: no headers line');
         }
 
-        $this->headers = str_getcsv($rawHeaders);
+        $this->headers = str_getcsv($rawHeaders, ",", "\"", "\\");
         $this->next();
     }
 
@@ -83,7 +83,7 @@ public function next()
             return;
         }
 
-        $data = str_getcsv(trim($rawLine, "\n"));
+        $data = str_getcsv(trim($rawLine, "\n"), ",", "\"", "\\");
         $this->current = array_combine($this->headers, $data);
         $this->status = true;
     }

src/Gateway/Responses/EnrollmentResponse.php

@@ -15,7 +15,7 @@ class EnrollmentResponse extends GenericResponse
 {
     public $enrollment;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         parent::__construct($rawDecoded);
         $this->enrollment = ($rawDecoded['enrollment'] ?? 'n') === 'y';

src/Gateway/Responses/GenericResponse.php

@@ -17,7 +17,7 @@ class GenericResponse
 {
     public $error;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->error = !empty($rawDecoded['error']) ? new Error($rawDecoded['error']) : null;
     }

src/Gateway/Responses/HistoryResponse.php

@@ -17,7 +17,7 @@ class HistoryResponse extends GenericResponse
 {
     public $transactions = [];
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         parent::__construct($rawDecoded);
         if (!empty($rawDecoded['transactions']) && is_array($rawDecoded['transactions'])) {

src/Gateway/Responses/LimitsResponse.php

@@ -17,7 +17,7 @@ class LimitsResponse extends GenericResponse
 {
     public $limits;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         parent::__construct($rawDecoded);
         $this->limits = new ObjectLimits($rawDecoded);

src/Gateway/Responses/Parts/Info/HistoryEvent.php

@@ -22,7 +22,7 @@ class HistoryEvent
     public $statusTextNew;
     public $statusTextOld;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->dateUpdated = !empty($rawDecoded['date-updated']) ? DateTime::createFromFormat('Y-m-d H:i:s', $rawDecoded['date-updated'], new DateTimeZone('UTC')) : null;
         $this->statusCodeNew = intval($rawDecoded['status-code-new'] ?? null);

src/Gateway/Responses/Parts/Info/InitialRecurringTransaction.php

@@ -19,7 +19,7 @@ class InitialRecurringTransaction
     public $error;
     public $subsequent = [];
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->gatewayTransactionId = strval($rawDecoded['gateway-transaction-id'] ?? null);
         $this->error = !empty($rawDecoded['error']) ? new Error($rawDecoded['error']) : null;

src/Gateway/Responses/Parts/Info/Limit.php

@@ -20,7 +20,7 @@ class Limit
     public $paymentMethodType;
     public $value;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->counterType = strval($rawDecoded['counter-type'] ?? null);
         $this->currency = strval($rawDecoded['currency'] ?? null);

src/Gateway/Responses/Parts/Info/ObjectLimits.php

@@ -19,7 +19,7 @@ class ObjectLimits
     public $limits = [];
     public $children = [];
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->type = strval($rawDecoded['type'] ?? null);
         $this->title = strval($rawDecoded['title'] ?? null);

src/Gateway/Responses/Parts/Info/RefundedTransaction.php

@@ -19,7 +19,7 @@ class RefundedTransaction
     public $error;
     public $refunds = [];
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->gatewayTransactionId = strval($rawDecoded['gateway-transaction-id'] ?? null);
         $this->error = !empty($rawDecoded['error']) ? new Error($rawDecoded['error']) : null;

src/Gateway/Responses/Parts/Info/TransactionHistory.php

@@ -19,7 +19,7 @@ class TransactionHistory
     public $error;
     public $history = [];
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->gatewayTransactionId = strval($rawDecoded['gateway-transaction-id'] ?? null);
         $this->error = !empty($rawDecoded['error']) ? new Error($rawDecoded['error']) : null;

src/Gateway/Responses/Parts/Info/TransactionInfo.php

@@ -32,7 +32,7 @@ class TransactionInfo
     public $statusText;
     public $statusTextGeneral;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->accountGuid = strval($rawDecoded['account-guid'] ?? null);
         $this->acqTerminalId = strval($rawDecoded['acq-terminal-id'] ?? null);

src/Gateway/Responses/Parts/Info/TransactionResult.php

@@ -24,7 +24,7 @@ class TransactionResult
     public $error;
     public $resultData;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->dateCreated = !empty($rawDecoded['date-created']) ? DateTime::createFromFormat('Y-m-d H:i:s', $rawDecoded['date-created'], new DateTimeZone('UTC')) : null;
         $this->dateFinished = !empty($rawDecoded['date-finished']) ? DateTime::createFromFormat('Y-m-d H:i:s', $rawDecoded['date-finished'], new DateTimeZone('UTC')) : null;

src/Gateway/Responses/Parts/Info/TransactionStatus.php

@@ -26,7 +26,7 @@ class TransactionStatus
     public $cardFamily;
     public $cardMask;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->error = !empty($rawDecoded['error']) ? new Error($rawDecoded['error']) : null;
         $this->gatewayTransactionId = strval($rawDecoded['gateway-transaction-id'] ?? null);

src/Gateway/Responses/Parts/Payment/AcquirerDetails.php

@@ -21,7 +21,7 @@ class AcquirerDetails
     public $terminalMid;
     public $transactionId;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->dynamicDescriptor = strval($rawDecoded['dynamic-descriptor'] ?? null);
         $this->eciSli = strval($rawDecoded['eci-sli'] ?? null);

src/Gateway/Responses/Parts/Payment/Error.php

@@ -16,7 +16,7 @@ class Error
     public $code;
     public $message;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->code = intval($rawDecoded['code'] ?? null);
         $this->message = strval($rawDecoded['message'] ?? null);

src/Gateway/Responses/Parts/Payment/GW.php

@@ -21,7 +21,7 @@ class GW
     public $statusCode;
     public $statusText;
 
-    public function __construct(array $rawDecoded = null)
+    public function __construct(?array $rawDecoded = null)
     {
         $this->gatewayTransactionId = strval($rawDecoded['gateway-transaction-id'] ?? null);
         $this->merchantTransactionId = strval($rawDecoded['merchant-transaction-id'] ?? null);