Split up cards and card params.

CHANGELOG

@@ -1,4 +1,5 @@
 == X.Y.Z 2017-XX-YY
+* Many methods on `STPCard` and `STPCardParams` have been deprecated or made readonly to bring card objects more in line with the rest of the API. See MIGRATING for further details.
 * Adds nullability annotations to `STPPaymentMethod` protocol
 * Improves the `[STPAPIResponseDecodable allResponseFields]` by removing all instances of `[NSNull null]` including ones that are nested. See MIGRATING.md.
 

MIGRATING.md

@@ -1,6 +1,12 @@
 ## Migration Guides
 
 ### Migration from versions < X.Y.Z
+* Changes to `STPCard` and `STPCardParams`
+  * `STPCard` no longer subclasses from `STPCardParams`. You must now specifically create `STPCardParams` objects to create new tokens.
+  * You can no longer directly create `STPCard` objects, you should only use ones that have been decoded from Stripe API responses via `STPAPIClient`.
+  * All `STPCard` properties have been made readonly.
+  * Broken out individual address properties on `STPCard` and `STPCardParams` have been deprecated in favor of the grouped `address` property.
+
 * The value of `[STPAPIResponseDecodable allResponseFields]` is now completely (deeply) filtered to not contain any instances of `[NSNull null]`. Previously, only `[NSNull null]` one level deep (shallow) were removed.
 
 ### Migrating from versions < 11.2.0

Stripe/PublicHeaders/STPCard.h

@@ -31,123 +31,151 @@ typedef NS_ENUM(NSInteger, STPCardFundingType) {
 
  @see https://stripe.com/docs/api#cards
  */
-@interface STPCard : STPCardParams<STPAPIResponseDecodable, STPPaymentMethod, STPSourceProtocol>
+@interface STPCard : NSObject<STPAPIResponseDecodable, STPPaymentMethod, STPSourceProtocol>
 
 /**
- Create an STPCard from a Stripe API response.
-
- @param cardID   The Stripe ID of the card, e.g. `card_185iQx4JYtv6MPZKfcuXwkOx`
- @param brand    The brand of the card (e.g. "Visa". To obtain this enum value from a string, use `[STPCardBrand brandFromString:string]`;
- @param last4    The last 4 digits of the card, e.g. 4242
- @param expMonth The card's expiration month, 1-indexed (i.e. 1 = January)
- @param expYear  The card's expiration year
- @param funding  The card's funding type (credit, debit, or prepaid). To obtain this enum value from a string, use `[STPCardBrand fundingFromString:string]`.
-
- @return an STPCard instance populated with the provided values.
+ You cannot directly instantiate an `STPCard`. You should only use one that has been returned from an `STPAPIClient` callback.
  */
-- (instancetype)initWithID:(NSString *)cardID
-                     brand:(STPCardBrand)brand
-                     last4:(NSString *)last4
-                  expMonth:(NSUInteger)expMonth
-                   expYear:(NSUInteger)expYear
-                   funding:(STPCardFundingType)funding;
+- (nonnull instancetype) init __attribute__((unavailable("You cannot directly instantiate an STPCard. You should only use one that has been returned from an STPAPIClient callback.")));
 
 /**
- This parses a string representing a card's brand into the appropriate STPCardBrand enum value, i.e. `[STPCard brandFromString:@"American Express"] == STPCardBrandAmex`
+ The last 4 digits of the card.
+ */
+@property (nonatomic, readonly) NSString *last4;
 
- @param string a string representing the card's brand as returned from the Stripe API
+/**
+ For cards made with Apple Pay, this refers to the last 4 digits of the "Device Account Number" for the tokenized card. For regular cards, it will be nil.
+ */
+@property (nonatomic, readonly, nullable) NSString *dynamicLast4;
 
- @return an enum value mapped to that string. If the string is unrecognized, returns STPCardBrandUnknown.
+/**
+ Whether or not the card originated from Apple Pay.
  */
-+ (STPCardBrand)brandFromString:(NSString *)string;
+@property (nonatomic, readonly) BOOL isApplePayCard;
 
 /**
- Returns a string representation for the provided card brand; i.e. `[NSString stringFromBrand:STPCardBrandVisa] ==  @"Visa"`.
+ The card's expiration month. 1-indexed (i.e. 1 == January)
+ */
+@property (nonatomic, readonly) NSUInteger expMonth;
 
- @param brand the brand you want to convert to a string
+/**
+ The card's expiration year.
+ */
+@property (nonatomic, readonly) NSUInteger expYear;
 
- @return A string representing the brand, suitable for displaying to a user.
+/**
+ The cardholder's name.
  */
-+ (NSString *)stringFromBrand:(STPCardBrand)brand;
+@property (nonatomic, copy, nullable, readonly) NSString *name;
 
 /**
- This parses a string representing a card's funding type into the appropriate `STPCardFundingType` enum value, i.e. `[STPCard fundingFromString:@"prepaid"] == STPCardFundingTypePrepaid`.
+ The cardholder's address.
+ */
+@property (nonatomic, nonnull, readonly) STPAddress *address;
 
- @param string a string representing the card's funding type as returned from the Stripe API
+/**
+ The issuer of the card.
+ */
+@property (nonatomic, readonly) STPCardBrand brand;
 
- @return an enum value mapped to that string. If the string is unrecognized, returns `STPCardFundingTypeOther`.
+/**
+ The funding source for the card (credit, debit, prepaid, or other)
  */
-+ (STPCardFundingType)fundingFromString:(NSString *)string;
+@property (nonatomic, readonly) STPCardFundingType funding;
 
 /**
- The last 4 digits of the card.
+ Two-letter ISO code representing the issuing country of the card.
  */
-@property (nonatomic, readonly) NSString *last4;
+@property (nonatomic, nullable, readonly) NSString *country;
 
 /**
- For cards made with Apple Pay, this refers to the last 4 digits of the "Device Account Number" for the tokenized card. For regular cards, it will be nil.
+ This is only applicable when tokenizing debit cards to issue payouts to managed accounts. You should not set it otherwise. The card can then be used as a transfer destination for funds in this currency.
  */
-@property (nonatomic, readonly, nullable) NSString *dynamicLast4;
+@property (nonatomic, nullable, readonly) NSString *currency;
 
 /**
- Whether or not the card originated from Apple Pay.
+ Returns a string representation for the provided card brand; i.e. `[NSString stringFromBrand:STPCardBrandVisa] ==  @"Visa"`.
+
+ @param brand the brand you want to convert to a string
+
+ @return A string representing the brand, suitable for displaying to a user.
  */
-@property (nonatomic, readonly) BOOL isApplePayCard;
++ (NSString *)stringFromBrand:(STPCardBrand)brand;
+
+
+#pragma mark - Deprecated methods
 
 /**
- The card's expiration month. 1-indexed (i.e. 1 == January)
+ The Stripe ID for the card.
  */
-@property (nonatomic) NSUInteger expMonth;
+@property (nonatomic, nullable, readonly) NSString *cardId DEPRECATED_MSG_ATTRIBUTE("Use stripeID (defined in STPSourceProtocol)");
 
 /**
- The card's expiration year.
+ The first line of the cardholder's address
  */
-@property (nonatomic) NSUInteger expYear;
+@property (nonatomic, copy, nullable, readonly) NSString *addressLine1 DEPRECATED_MSG_ATTRIBUTE("Use address.line1");
 
 /**
- The cardholder's name.
+ The second line of the cardholder's address
  */
-@property (nonatomic, copy, nullable) NSString *name;
+@property (nonatomic, copy, nullable, readonly) NSString *addressLine2 DEPRECATED_MSG_ATTRIBUTE("Use address.line2");
 
 /**
- The cardholder's address.
+ The city of the cardholder's address
  */
-@property (nonatomic, copy, nullable) STPAddress *address;
+@property (nonatomic, copy, nullable, readonly) NSString *addressCity DEPRECATED_MSG_ATTRIBUTE("Use address.city");
 
 /**
- The cardholder's address.
+ The state of the cardholder's address
  */
-@property (nonatomic, copy, nullable) NSString *addressLine1;
-@property (nonatomic, copy, nullable) NSString *addressLine2;
-@property (nonatomic, copy, nullable) NSString *addressCity;
-@property (nonatomic, copy, nullable) NSString *addressState;
-@property (nonatomic, copy, nullable) NSString *addressZip;
-@property (nonatomic, copy, nullable) NSString *addressCountry;
+@property (nonatomic, copy, nullable, readonly) NSString *addressState DEPRECATED_MSG_ATTRIBUTE("Use address.state");
 
 /**
- The Stripe ID for the card.
+ The zip code of the cardholder's address
  */
-@property (nonatomic, readonly, nullable) NSString *cardId;
+@property (nonatomic, copy, nullable, readonly) NSString *addressZip DEPRECATED_MSG_ATTRIBUTE("Use address.postalCode");
 
 /**
- The issuer of the card.
+ The country of the cardholder's address
  */
-@property (nonatomic, readonly) STPCardBrand brand;
+@property (nonatomic, copy, nullable, readonly) NSString *addressCountry DEPRECATED_MSG_ATTRIBUTE("Use address.country");
 
 /**
- The funding source for the card (credit, debit, prepaid, or other)
+ Create an STPCard from a Stripe API response.
+
+ @param cardID   The Stripe ID of the card, e.g. `card_185iQx4JYtv6MPZKfcuXwkOx`
+ @param brand    The brand of the card (e.g. "Visa". To obtain this enum value from a string, use `[STPCardBrand brandFromString:string]`;
+ @param last4    The last 4 digits of the card, e.g. 4242
+ @param expMonth The card's expiration month, 1-indexed (i.e. 1 = January)
+ @param expYear  The card's expiration year
+ @param funding  The card's funding type (credit, debit, or prepaid). To obtain this enum value from a string, use `[STPCardBrand fundingFromString:string]`.
+
+ @return an STPCard instance populated with the provided values.
  */
-@property (nonatomic, readonly) STPCardFundingType funding;
+- (instancetype)initWithID:(NSString *)cardID
+                     brand:(STPCardBrand)brand
+                     last4:(NSString *)last4
+                  expMonth:(NSUInteger)expMonth
+                   expYear:(NSUInteger)expYear
+                   funding:(STPCardFundingType)funding DEPRECATED_MSG_ATTRIBUTE("You cannot directly instantiate an STPCard. You should only use one that has been returned from an STPAPIClient callback.");
 
 /**
- Two-letter ISO code representing the issuing country of the card.
+ This parses a string representing a card's funding type into the appropriate `STPCardFundingType` enum value, i.e. `[STPCard fundingFromString:@"prepaid"] == STPCardFundingTypePrepaid`.
+
+ @param string a string representing the card's funding type as returned from the Stripe API
+
+ @return an enum value mapped to that string. If the string is unrecognized, returns `STPCardFundingTypeOther`.
  */
-@property (nonatomic, readonly, nullable) NSString *country;
++ (STPCardFundingType)fundingFromString:(NSString *)string DEPRECATED_ATTRIBUTE;
 
 /**
- This is only applicable when tokenizing debit cards to issue payouts to managed accounts. You should not set it otherwise. The card can then be used as a transfer destination for funds in this currency.
+ This parses a string representing a card's brand into the appropriate STPCardBrand enum value, i.e. `[STPCard brandFromString:@"American Express"] == STPCardBrandAmex`
+
+ @param string a string representing the card's brand as returned from the Stripe API
+
+ @return an enum value mapped to that string. If the string is unrecognized, returns STPCardBrandUnknown.
  */
-@property (nonatomic, copy, nullable) NSString *currency;
++ (STPCardBrand)brandFromString:(NSString *)string DEPRECATED_ATTRIBUTE;
 
 @end
 

Stripe/PublicHeaders/STPCardParams.h

@@ -14,8 +14,9 @@
 #endif
 
 /**
- Representation of a user's credit card details. You can assemble these with information that your user enters and
- then create Stripe tokens with them using an STPAPIClient.
+ Representation of a user's credit card details. You can assemble these with
+ information that your user enters and then create Stripe tokens with them using 
+ an STPAPIClient.
 
  @see https://stripe.com/docs/api#cards
  */
@@ -48,24 +49,60 @@
 
 /**
  The cardholder's name.
+
+ @note Changing this property will also changing the name of the 
+ param's `address` property.
  */
 @property (nonatomic, copy, nullable) NSString *name;
 
 /**
  The cardholder's address.
+
+ @note Changing this property will also changing the name of the 
+ param's `name` property
  */
-@property (nonatomic, copy, nonnull) STPAddress *address;
-
-@property (nonatomic, copy, nullable) NSString *addressLine1;
-@property (nonatomic, copy, nullable) NSString *addressLine2;
-@property (nonatomic, copy, nullable) NSString *addressCity;
-@property (nonatomic, copy, nullable) NSString *addressState;
-@property (nonatomic, copy, nullable) NSString *addressZip;
-@property (nonatomic, copy, nullable) NSString *addressCountry;
+@property (nonatomic, strong, nonnull) STPAddress *address;
 
 /**
- Three-letter ISO currency code representing the currency paid out to the bank account. This is only applicable when tokenizing debit cards to issue payouts to managed accounts. You should not set it otherwise. The card can then be used as a transfer destination for funds in this currency.
+ Three-letter ISO currency code representing the currency paid out to the bank 
+ account. This is only applicable when tokenizing debit cards to issue payouts 
+ to managed accounts. You should not set it otherwise. The card can then be 
+ used as a transfer destination for funds in this currency.
  */
 @property (nonatomic, copy, nullable) NSString *currency;
 
+
+#pragma mark - Deprecated methods
+
+/**
+ The first line of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressLine1 DEPRECATED_MSG_ATTRIBUTE("Use address.line1");
+
+/**
+ The second line of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressLine2 DEPRECATED_MSG_ATTRIBUTE("Use address.line2");
+
+/**
+ The city of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressCity DEPRECATED_MSG_ATTRIBUTE("Use address.city");
+
+/**
+ The state of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressState DEPRECATED_MSG_ATTRIBUTE("Use address.state");
+
+/**
+ The zip code of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressZip DEPRECATED_MSG_ATTRIBUTE("Use address.postalCode");
+
+/**
+ The country of the cardholder's address
+ */
+@property (nonatomic, copy, nullable) NSString *addressCountry DEPRECATED_MSG_ATTRIBUTE("Use address.country");
+
+
 @end

Stripe/STPAPIClient.m

@@ -365,8 +365,8 @@ - (void)uploadImage:(UIImage *)image
 
 @implementation STPAPIClient (CreditCards)
 
-- (void)createTokenWithCard:(STPCard *)card completion:(STPTokenCompletionBlock)completion {
-    NSMutableDictionary *params = [[STPFormEncoder dictionaryForObject:card] mutableCopy];
+- (void)createTokenWithCard:(STPCardParams *)cardParams completion:(STPTokenCompletionBlock)completion {
+    NSMutableDictionary *params = [[STPFormEncoder dictionaryForObject:cardParams] mutableCopy];
     [[STPTelemetryClient sharedInstance] addTelemetryFieldsToParams:params];
     [self createTokenWithParameters:params completion:completion];
     [[STPTelemetryClient sharedInstance] sendTelemetryData];

Stripe/STPCard+Private.h

@@ -13,8 +13,12 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface STPCard () <STPInternalAPIResponseDecodable>
 
++ (STPCardFundingType)fundingFromString:(NSString *)string;
 + (nullable NSString *)stringFromFunding:(STPCardFundingType)funding;
 
++ (STPCardBrand)brandFromString:(NSString *)string;
++ (NSString *)stringFromBrand:(STPCardBrand)brand;
+
 @end
 
 NS_ASSUME_NONNULL_END