Add API to create PaymentMethod

CHANGELOG.md

@@ -6,6 +6,7 @@
   * Renames `STPPaymentMethodTuple` to `STPPaymentOptionTuple`
   * Renames `STPPaymentMethodsViewController` to `STPPaymentOptionsViewController`
   * Renames all properties, methods, comments referencing 'PaymentMethod' to 'PaymentOption'
+* Adds `[STPAPI createPaymentMethodWithParams:completion:]`, which creates a PaymentMethod.
 
 ## 14.0.0 2018-11-14
 * Changes `STPPaymentCardTextField`, which now copies the `cardParams` property. See [MIGRATING.md](/MIGRATING.md) for more details. [#1031](https://github.com/stripe/stripe-ios/pull/1031)

STYLEGUIDE.md

@@ -232,6 +232,8 @@ NS_ASSUME_NON_NULL_END
 @property (<nonatomic / atomic>, <assign>, <readonly / readwrite>) <type> <name>;
 ```
 
+- Omit default properties (`assign`, `readwrite`), except for `strong`
+
 - Use `copy` for classes with mutable counterparts such as `NSString`, `NSArray`, `NSDictionary`
 
 - Leverage auto property synthesis whenever possible

Stripe/PublicHeaders/STPAPIClient.h

@@ -21,7 +21,7 @@ NS_ASSUME_NONNULL_BEGIN
 static NSString *const STPSDKVersion = @"15.0.0";
 
 @class STPBankAccount, STPBankAccountParams, STPCard, STPCardParams, STPConnectAccountParams;
-@class STPPaymentConfiguration, STPPaymentIntentParams, STPSourceParams, STPToken;
+@class STPPaymentConfiguration, STPPaymentIntentParams, STPSourceParams, STPToken, STPPaymentMethodParams;
 
 /**
  A top-level class that imports the rest of the Stripe SDK.
@@ -360,6 +360,27 @@ static NSString *const STPSDKVersion = @"15.0.0";
 
 @end
 
+
+#pragma mark Payment Methods
+
+/**
+ STPAPIClient extensions for working with PaymentMethod objects.
+ */
+@interface STPAPIClient (PaymentMethods)
+
+/**
+ Creates a PaymentMethod object with the provided params object.
+
+ @see https://stripe.com/docs/api/payment_methods/create
+
+ @param paymentMethodParams  The `STPPaymentMethodParams` to pass to `/v1/payment_methods`.  Cannot be nil.
+ @param completion           The callback to run with the returned PaymentMethod object, or an error.
+ */
+- (void)createPaymentMethodWithParams:(STPPaymentMethodParams *)paymentMethodParams
+                           completion:(STPPaymentMethodCompletionBlock)completion;
+
+@end
+
 #pragma mark URL callbacks
 
 /**

Stripe/PublicHeaders/STPBlocks.h

@@ -15,6 +15,7 @@
 @class STPCustomer;
 @protocol STPSourceProtocol;
 @class STPPaymentIntent;
+@class STPPaymentMethod;
 
 /**
  These values control the labels used in the shipping info collection form.
@@ -115,6 +116,14 @@ typedef void (^STPSourceProtocolCompletionBlock)(id<STPSourceProtocol> __nullabl
  */
 typedef void (^STPPaymentIntentCompletionBlock)(STPPaymentIntent * __nullable paymentIntent, NSError * __nullable error);
 
+/**
+ A callback to be run with a PaymentMethod response from the Stripe API.
+
+ @param paymentMethod The Stripe PaymentMethod from the response. Will be nil if an error occurs. @see STPPaymentMethod
+ @param error The error returned from the response, or nil if none occurs. @see StripeError.h for possible values.
+ */
+typedef void (^STPPaymentMethodCompletionBlock)(STPPaymentMethod * __nullable paymentMethod, NSError * __nullable error);
+
 /**
  A callback to be run with a validation result and shipping methods for a 
  shipping address.

Stripe/PublicHeaders/STPPaymentMethod.h

@@ -9,6 +9,7 @@
 #import <Foundation/Foundation.h>
 
 #import "STPAPIResponseDecodable.h"
+#import "STPPaymentMethodEnums.h"
 
 @class STPPaymentMethodBillingDetails, STPPaymentMethodCard;
 
@@ -37,17 +38,18 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly) BOOL liveMode;
 
 /**
- The type of the PaymentMethod, currently only @"card" is supported. The corresponding property (`card`) contains additional information specific to the PaymentMethod type.
+ The type of the PaymentMethod.  The corresponding, similarly named property contains additional information specific to the PaymentMethod type.
+ e.g. if the type is `STPPaymentMethodTypeCard`, the `card` property is also populated.
  */
-@property (nonatomic, nullable, readonly) NSString *type;
+@property (nonatomic, readonly) STPPaymentMethodType type;
 
 /**
  Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
  */
 @property (nonatomic, nullable, readonly) STPPaymentMethodBillingDetails *billingDetails;
 
 /**
- If this is a card PaymentMethod (ie `self.type == @"card"`), this contains details about the card.
+ If this is a card PaymentMethod (ie `self.type == STPPaymentMethodTypeCard`), this contains additional details.
  */
 @property (nonatomic, nullable, readonly) STPPaymentMethodCard *card;
 

Stripe/PublicHeaders/STPPaymentMethodBillingDetails.h

@@ -9,6 +9,7 @@
 #import <Foundation/Foundation.h>
 
 #import "STPAPIResponseDecodable.h"
+#import "STPFormEncodable.h"
 
 @class STPPaymentMethodBillingDetailsAddress;
 
@@ -19,12 +20,12 @@ NS_ASSUME_NONNULL_BEGIN
 
  @see https://stripe.com/docs/api/payment_methods/object#payment_method_object-billing_details
  */
-@interface STPPaymentMethodBillingDetails : NSObject <STPAPIResponseDecodable>
+@interface STPPaymentMethodBillingDetails : NSObject <STPAPIResponseDecodable, STPFormEncodable>
 
 /**
  Billing address.
  */
-@property (nonatomic, nullable) STPPaymentMethodBillingDetailsAddress *address;
+@property (nonatomic, strong, nullable) STPPaymentMethodBillingDetailsAddress *address;
 
 /**
  Email address.

Stripe/PublicHeaders/STPPaymentMethodBillingDetailsAddress.h

@@ -9,13 +9,14 @@
 #import <Foundation/Foundation.h>
 
 #import "STPAPIResponseDecodable.h"
+#import "STPFormEncodable.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 /**
  The billing address, a property on `STPPaymentMethodBillingDetails`
  */
-@interface STPPaymentMethodBillingDetailsAddress : NSObject <STPAPIResponseDecodable>
+@interface STPPaymentMethodBillingDetailsAddress : NSObject <STPAPIResponseDecodable, STPFormEncodable>
 
 /**
  City/District/Suburb/Town/Village.

Stripe/PublicHeaders/STPPaymentMethodCardParams.h

@@ -0,0 +1,47 @@
+//
+//  STPPaymentMethodCardParams.h
+//  Stripe
+//
+//  Created by Yuki Tokuhiro on 3/6/19.
+//  Copyright © 2019 Stripe, Inc. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+#import "STPFormEncodable.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ The user's card details.
+ */
+@interface STPPaymentMethodCardParams : NSObject <STPFormEncodable>
+
+/**
+ The card number, as a string without any separators. Ex. @"4242424242424242"
+ */
+@property (nonatomic, copy, nullable) NSString *number;
+
+/**
+ Two-digit number representing the card's expiration month.
+ */
+@property (nonatomic) NSUInteger expMonth;
+
+/**
+ Two- or four-digit number representing the card's expiration year.
+ */
+@property (nonatomic) NSUInteger expYear;
+
+/**
+ For backwards compatibility, you can alternatively set this as a Stripe token (e.g., for apple pay)
+ */
+@property (nonatomic, copy, nullable) NSString *token;
+
+/**
+ Card security code. It is highly recommended to always include this value.
+ */
+@property (nonatomic, copy, nullable) NSString *cvc;
+
+@end
+
+NS_ASSUME_NONNULL_END

Stripe/PublicHeaders/STPPaymentMethodEnums.h

@@ -0,0 +1,22 @@
+//
+//  STPPaymentMethodEnums.h
+//  Stripe
+//
+//  Created by Yuki Tokuhiro on 3/12/19.
+//  Copyright © 2019 Stripe, Inc. All rights reserved.
+//
+
+/**
+ The type of the PaymentMethod.
+ */
+typedef NS_ENUM(NSUInteger, STPPaymentMethodType) {
+    /**
+     A card payment method.
+     */
+    STPPaymentMethodTypeCard,
+
+    /**
+     An unknown type.
+     */
+    STPPaymentMethodTypeUnknown,
+};

Stripe/PublicHeaders/STPPaymentMethodParams.h

@@ -0,0 +1,69 @@
+//
+//  STPPaymentMethodParams.h
+//  Stripe
+//
+//  Created by Yuki Tokuhiro on 3/6/19.
+//  Copyright © 2019 Stripe, Inc. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+#import "STPFormEncodable.h"
+#import "STPPaymentMethodEnums.h"
+
+@class STPPaymentMethodBillingDetails, STPPaymentMethodCardParams;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ An object representing parameters used to create a PaymentMethod object.
+ @see https://stripe.com/docs/api/payment_methods/create
+ */
+@interface STPPaymentMethodParams : NSObject <STPFormEncodable>
+
+/**
+ The type of payment method.  The associated property will contain additional information (e.g. `type == STPPaymentMethodTypeCard` means `card` should also be populated).
+ */
+@property (nonatomic, readonly) STPPaymentMethodType type;
+
+/**
+ The raw underlying type string sent to the server.
+
+ Generally you should use `type` instead unless you have a reason not to.
+ You can use this if you want to create a param of a type not yet supported
+ by the current version of the SDK's `STPPaymentMethodType` enum.
+
+ Setting this to a value not known by the SDK causes `type` to
+ return `STPPaymentMethodTypeUnknown`
+ */
+@property (nonatomic, copy) NSString *rawTypeString;
+
+/**
+ Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
+ */
+@property (nonatomic, strong, nullable) STPPaymentMethodBillingDetails *billingDetails;
+
+/**
+ If this is a card PaymentMethod, this contains the user’s card details.
+ */
+@property (nonatomic, strong, nullable) STPPaymentMethodCardParams *card;
+
+/**
+ Set of key-value pairs that you can attach to the PaymentMethod. This can be useful for storing additional information about the PaymentMethod in a structured format.
+ */
+@property (nonatomic, copy, nullable) NSDictionary<NSString *, NSString *> *metadata;
+
+/**
+ Creates params for a card PaymentMethod.
+
+ @param card                An object containing the user's card details.
+ @param billingDetails      An object containing the user's billing details.
+ @param metadata            Additional information to attach to the PaymentMethod.
+ */
++ (STPPaymentMethodParams *)paramsWithCard:(STPPaymentMethodCardParams *)card
+                                billingDetails:(nullable STPPaymentMethodBillingDetails *)billingDetails
+                                      metadata:(nullable NSDictionary<NSString *, NSString *> *)metadata;
+
+@end
+
+NS_ASSUME_NONNULL_END

Stripe/PublicHeaders/STPSourceParams.h

@@ -36,7 +36,7 @@ NS_ASSUME_NONNULL_BEGIN
  Setting this to a value not known by the SDK causes `type` to 
  return `STPSourceTypeUnknown`
  */
-@property (nonatomic, copy) NSString *rawTypeString;
+@property (nonatomic, copy, nullable) NSString *rawTypeString;
 
 /**
  A positive integer in the smallest currency unit representing the

Stripe/PublicHeaders/Stripe.h

@@ -47,6 +47,9 @@
 #import "STPPaymentMethodBillingDetailsAddress.h"
 #import "STPPaymentMethodCard.h"
 #import "STPPaymentMethodCardChecks.h"
+#import "STPPaymentMethodCardParams.h"
+#import "STPPaymentMethodEnums.h"
+#import "STPPaymentMethodParams.h"
 #import "STPPaymentMethodThreeDSecureUsage.h"
 #import "STPPaymentOption.h"
 #import "STPPaymentOptionsViewController.h"

Stripe/STPAPIClient.m

@@ -27,6 +27,7 @@
 #import "STPMultipartFormDataEncoder.h"
 #import "STPMultipartFormDataPart.h"
 #import "STPPaymentConfiguration.h"
+#import "STPPaymentMethodParams.h"
 #import "STPPaymentIntent+Private.h"
 #import "STPPaymentIntentParams.h"
 #import "STPSource+Private.h"
@@ -53,6 +54,7 @@
 static NSString * const APIEndpointCustomers = @"customers";
 static NSString * const FileUploadURL = @"https://uploads.stripe.com/v1/files";
 static NSString * const APIEndpointPaymentIntents = @"payment_intents";
+static NSString * const APIEndpointPaymentMethods = @"payment_methods";
 
 #pragma mark - Stripe
 
@@ -621,3 +623,23 @@ - (void)confirmPaymentIntentWithParams:(STPPaymentIntentParams *)paymentIntentPa
 }
 
 @end
+
+#pragma mark - Payment Methods
+
+@implementation STPAPIClient (PaymentMethods)
+
+- (void)createPaymentMethodWithParams:(STPPaymentMethodParams *)paymentMethodParams
+                                 completion:(STPPaymentMethodCompletionBlock)completion {
+    NSCAssert(paymentMethodParams != nil, @"'paymentMethodParams' is required to create a PaymentMethod");
+
+    [STPAPIRequest<STPPaymentMethod *> postWithAPIClient:self
+                                               endpoint:APIEndpointPaymentMethods
+                                             parameters:[STPFormEncoder dictionaryForObject:paymentMethodParams]
+                                           deserializer:[STPPaymentMethod new]
+                                             completion:^(STPPaymentMethod *paymentMethod, __unused NSHTTPURLResponse *response, NSError *error) {
+                                                 completion(paymentMethod, error);
+                                             }];
+
+}
+
+@end

Stripe/STPPaymentMethod+Private.h

@@ -0,0 +1,20 @@
+//
+//  STPPaymentMethod+Private.h
+//  Stripe
+//
+//  Created by Yuki Tokuhiro on 3/12/19.
+//  Copyright © 2019 Stripe, Inc. All rights reserved.
+//
+
+#import "STPPaymentMethod.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface STPPaymentMethod ()
+
++ (STPPaymentMethodType)typeFromString:(NSString *)string;
++ (nullable NSString *)stringFromType:(STPPaymentMethodType)type;
+
+@end
+
+NS_ASSUME_NONNULL_END