Payments API Updates

lib/PayPal/Api/CreditCard.php

@@ -10,36 +10,31 @@ use PayPal\Validation\ArgumentValidator;
 /**
  * Class CreditCard
  *
- * A resource representing a credit card that can be used to fund a payment.
+ * @deprecated Represents a credit card to fund a payment. Use Payment Card instead.
  *
- * @package PayPal\Api
+ * @package    PayPal\Api
  *
- * @property string id
- * @property string number
- * @property string type
- * @property int expire_month
- * @property int expire_year
- * @property string cvv2
- * @property string first_name
- * @property string last_name
+ * @property string              number
+ * @property string              type
+ * @property int                 expire_month
+ * @property int                 expire_year
+ * @property string              cvv2
+ * @property string              first_name
+ * @property string              last_name
  * @property \PayPal\Api\Address billing_address
- * @property string external_customer_id
- * @property string merchant_id
- * @property string payer_id
- * @property string external_card_id
- * @property string state
- * @property string create_time
- * @property string update_time
- * @property string valid_until
+ * @property string              external_customer_id
+ * @property string              state
+ * @property string              valid_until
  * @property \PayPal\Api\Links[] links
  */
 class CreditCard extends PayPalResourceModel
 {
     /**
-     * ID of the credit card being saved for later use.
+     * ID of the credit card. This ID is provided in the response when storing credit cards. **Required if using a stored credit card.**
      *
+     * @deprecated Not publicly available
      * @param string $id
-     * 
+     *
      * @return $this
      */
     public function setId($id)
@@ -49,8 +44,9 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * ID of the credit card being saved for later use.
+     * ID of the credit card. This ID is provided in the response when storing credit cards. **Required if using a stored credit card.**
      *
+     * @deprecated Not publicly available
      * @return string
      */
     public function getId()
@@ -59,10 +55,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card number.
+     * Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. *Redacted in responses.*
      *
      * @param string $number
-     * 
+     *
      * @return $this
      */
     public function setNumber($number)
@@ -72,7 +68,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card number.
+     * Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. *Redacted in responses.*
      *
      * @return string
      */
@@ -82,11 +78,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Type of the Card. Currently supporting Visa, Mastercard, Amex, Discover and Maestro
-     * Valid Values: ["visa", "mastercard", "amex", "discover", "maestro"]
+     * Credit card type. Valid types are: `visa`, `mastercard`, `discover`, `amex`
      *
      * @param string $type
-     * 
+     *
      * @return $this
      */
     public function setType($type)
@@ -96,7 +91,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Type of the Card. Currently supporting Visa, Mastercard, Amex, Discover and Maestro
+     * Credit card type. Valid types are: `visa`, `mastercard`, `discover`, `amex`
      *
      * @return string
      */
@@ -106,10 +101,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * 2 digit card expiry month.
+     * Expiration month with no leading zero. Acceptable values are 1 through 12.
      *
      * @param int $expire_month
-     * 
+     *
      * @return $this
      */
     public function setExpireMonth($expire_month)
@@ -119,7 +114,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * 2 digit card expiry month.
+     * Expiration month with no leading zero. Acceptable values are 1 through 12.
      *
      * @return int
      */
@@ -129,10 +124,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * 4 digit card expiry year
+     * 4-digit expiration year.
      *
      * @param int $expire_year
-     * 
+     *
      * @return $this
      */
     public function setExpireYear($expire_year)
@@ -142,7 +137,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * 4 digit card expiry year
+     * 4-digit expiration year.
      *
      * @return int
      */
@@ -152,10 +147,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card validation code. Only supported when making a Payment but not when saving a credit card for future use.
+     * 3-4 digit card validation code.
      *
      * @param string $cvv2
-     * 
+     *
      * @return $this
      */
     public function setCvv2($cvv2)
@@ -165,7 +160,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card validation code. Only supported when making a Payment but not when saving a credit card for future use.
+     * 3-4 digit card validation code.
      *
      * @return string
      */
@@ -175,10 +170,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card holder's first name.
+     * Cardholder's first name.
      *
      * @param string $first_name
-     * 
+     *
      * @return $this
      */
     public function setFirstName($first_name)
@@ -188,7 +183,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card holder's first name.
+     * Cardholder's first name.
      *
      * @return string
      */
@@ -198,10 +193,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card holder's last name.
+     * Cardholder's last name.
      *
      * @param string $last_name
-     * 
+     *
      * @return $this
      */
     public function setLastName($last_name)
@@ -211,7 +206,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Card holder's last name.
+     * Cardholder's last name.
      *
      * @return string
      */
@@ -224,7 +219,7 @@ class CreditCard extends PayPalResourceModel
      * Billing Address associated with this card.
      *
      * @param \PayPal\Api\Address $billing_address
-     * 
+     *
      * @return $this
      */
     public function setBillingAddress($billing_address)
@@ -244,10 +239,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * A unique identifier of the customer to whom this bank account belongs to. Generated and provided by the facilitator. This is required when creating or using a stored funding instrument in vault.
+     * A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. **This is now used in favor of `payer_id` when creating or using a stored funding instrument in the vault.**
      *
      * @param string $external_customer_id
-     * 
+     *
      * @return $this
      */
     public function setExternalCustomerId($external_customer_id)
@@ -257,7 +252,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * A unique identifier of the customer to whom this bank account belongs to. Generated and provided by the facilitator. This is required when creating or using a stored funding instrument in vault.
+     * A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. **This is now used in favor of `payer_id` when creating or using a stored funding instrument in the vault.**
      *
      * @return string
      */
@@ -270,7 +265,7 @@ class CreditCard extends PayPalResourceModel
      * A user provided, optional convenvience field that functions as a unique identifier for the merchant on behalf of whom this credit card is being stored for. Note that this has no relation to PayPal merchant id
      *
      * @param string $merchant_id
-     * 
+     *
      * @return $this
      */
     public function setMerchantId($merchant_id)
@@ -291,9 +286,10 @@ class CreditCard extends PayPalResourceModel
 
     /**
      * A unique identifier that you can assign and track when storing a credit card or using a stored credit card. This ID can help to avoid unintentional use or misuse of credit cards. This ID can be any value you would like to associate with the saved card, such as a UUID, username, or email address. Required when using a stored credit card if a payer_id was originally provided when storing the credit card in vault.
+     *
      * @deprecated This is being deprecated in favor of the `external_customer_id` property.
      * @param string $payer_id
-     * 
+     *
      * @return $this
      */
     public function setPayerId($payer_id)
@@ -304,6 +300,7 @@ class CreditCard extends PayPalResourceModel
 
     /**
      * A unique identifier that you can assign and track when storing a credit card or using a stored credit card. This ID can help to avoid unintentional use or misuse of credit cards. This ID can be any value you would like to associate with the saved card, such as a UUID, username, or email address. Required when using a stored credit card if a payer_id was originally provided when storing the credit card in vault.
+     *
      * @deprecated This is being deprecated in favor of the `external_customer_id` property.
      * @return string
      */
@@ -316,7 +313,7 @@ class CreditCard extends PayPalResourceModel
      * A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
      *
      * @param string $external_card_id
-     * 
+     *
      * @return $this
      */
     public function setExternalCardId($external_card_id)
@@ -340,7 +337,7 @@ class CreditCard extends PayPalResourceModel
      * Valid Values: ["expired", "ok"]
      *
      * @param string $state
-     * 
+     *
      * @return $this
      */
     public function setState($state)
@@ -350,7 +347,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * State of the funding instrument.
+     * State of the credit card funding instrument.
      *
      * @return string
      */
@@ -360,10 +357,10 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Resource creation time  as ISO8601 date-time format (ex: 1994-11-05T13:15:30Z) that indicates creation time.
+     * Funding instrument expiration date.
      *
      * @param string $create_time
-     * 
+     *
      * @return $this
      */
     public function setCreateTime($create_time)
@@ -386,7 +383,7 @@ class CreditCard extends PayPalResourceModel
      * Resource creation time  as ISO8601 date-time format (ex: 1994-11-05T13:15:30Z) that indicates the updation time.
      *
      * @param string $update_time
-     * 
+     *
      * @return $this
      */
     public function setUpdateTime($update_time)
@@ -409,7 +406,7 @@ class CreditCard extends PayPalResourceModel
      * Date/Time until this resource can be used fund a payment.
      *
      * @param string $valid_until
-     * 
+     *
      * @return $this
      */
     public function setValidUntil($valid_until)
@@ -419,7 +416,7 @@ class CreditCard extends PayPalResourceModel
     }
 
     /**
-     * Date/Time until this resource can be used fund a payment.
+     * Funding instrument expiration date.
      *
      * @return string
      */
@@ -431,8 +428,8 @@ class CreditCard extends PayPalResourceModel
     /**
      * Creates a new Credit Card Resource (aka Tokenize).
      *
-     * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
-     * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
+     * @param ApiContext     $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
+     * @param PayPalRestCall $restCall   is the Rest Call Service that is used to make rest calls
      * @return CreditCard
      */
     public function create($apiContext = null, $restCall = null)
@@ -453,9 +450,9 @@ class CreditCard extends PayPalResourceModel
     /**
      * Obtain the Credit Card resource for the given identifier.
      *
-     * @param string $creditCardId
-     * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
-     * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
+     * @param string         $creditCardId
+     * @param ApiContext     $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
+     * @param PayPalRestCall $restCall   is the Rest Call Service that is used to make rest calls
      * @return CreditCard
      */
     public static function get($creditCardId, $apiContext = null, $restCall = null)
@@ -478,8 +475,8 @@ class CreditCard extends PayPalResourceModel
     /**
      * Delete the Credit Card resource for the given identifier.
      *
-     * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
-     * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
+     * @param ApiContext     $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
+     * @param PayPalRestCall $restCall   is the Rest Call Service that is used to make rest calls
      * @return bool
      */
     public function delete($apiContext = null, $restCall = null)
@@ -500,9 +497,9 @@ class CreditCard extends PayPalResourceModel
     /**
      * Update information in a previously saved card. Only the modified fields need to be passed in the request.
      *
-     * @param PatchRequest $patchRequest
-     * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
-     * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
+     * @param PatchRequest   $patchRequest
+     * @param ApiContext     $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
+     * @param PayPalRestCall $restCall   is the Rest Call Service that is used to make rest calls
      * @return CreditCard
      */
     public function update($patchRequest, $apiContext = null, $restCall = null)
@@ -525,9 +522,9 @@ class CreditCard extends PayPalResourceModel
     /**
      * Retrieves a list of Credit Card resources.
      *
-     * @param array $params
-     * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
-     * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
+     * @param array          $params
+     * @param ApiContext     $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
+     * @param PayPalRestCall $restCall   is the Rest Call Service that is used to make rest calls
      * @return CreditCardList
      */
     public static function all($params, $apiContext = null, $restCall = null)
@@ -538,16 +535,16 @@ class CreditCard extends PayPalResourceModel
         ArgumentValidator::validate($params, 'params');
         $payLoad = "";
         $allowedParams = array(
-          'page_size' => 1,
-          'page' => 1,
-          'start_time' => 1,
-          'end_time' => 1,
-          'sort_order' => 1,
-          'sort_by' => 1,
-          'merchant_id' => 1,
-          'external_card_id' => 1,
-          'external_customer_id' => 1,
-      );
+            'page_size' => 1,
+            'page' => 1,
+            'start_time' => 1,
+            'end_time' => 1,
+            'sort_order' => 1,
+            'sort_by' => 1,
+            'merchant_id' => 1,
+            'external_card_id' => 1,
+            'external_customer_id' => 1,
+        );
         $json = self::executeCall(
             "/v1/vault/credit-cards" . "?" . http_build_query(array_intersect_key($params, $allowedParams)),
             "GET",