Add alternative payment methods support (like Google Pay)

Author: OlegGS

.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);
     }