Released version 4.0.0

.gitignore

@@ -19,11 +19,23 @@ DerivedData
 .DS_Store
 project.xcworkspace
 
+# WePay internal documentation and tools
 /Documentation/html
 /Documentation/latex
 /Documentation/rtf
 /wepay-ios-tools/
 
+# Card reader libs are git-ignored by default.
+/SwiftExample/Pods/WePay/G4XSwiper.framework/
+/SwiftExample/Pods/WePay/RPx.framework/
+/SwiftExample/Pods/WePay/RUA.framework/
+/WePayExample/WePayExample/Libs/G4XSwiper.framework/
+/WePayExample/WePayExample/Libs/RPx.framework/
+/WePayExample/WePayExample/Libs/RUA.framework/
+/WePay/Libs/G4XSwiper.framework/
+/WePay/Libs/RPx.framework/
+/WePay/Libs/RUA.framework/
+
 # CocoaPods
 #
 # We recommend against adding the Pods directory to your .gitignore. However

CHANGELOG

@@ -1,3 +1,17 @@
+2016-02-22
+* Released version 4.0.0
+* Added kWPPaymentMethodDip
+* Added kWPCurrencyCodeUSD
+* Added WPAuthorizationDelegate protocol
+* Added WPAuthorizationInfo
+* Added insertPayerEmailWithCompletion:, authorizeAmountWithCompletion: and shouldResetCardReaderWithCompletion: methods to WPCardReaderDelegate
+* Added new error codes in WPErrorCode enum
+* Added new card reader statuses
+* Modified startCardReaderForTokenizing... method by adding an authorizationDelegate parameter
+* Added magic numbers to simulate successful Dip
+* Added support for background threads via WPConfig.callDelegateMethodsOnMainThread
+* WPPaymentInfo.paymentDescription now masks everything except last 4
+
 2015-12-22
 * Released version 3.0.0
 * Card reader functionality is optional and not available by default
@@ -9,6 +23,10 @@
 * Release version 2.0.2
 * Add support for iPhone 6S and 6S Plus
 
+2015-07-14
+* Release version 2.0.1
+* Use extern string definitions in WePay.h
+
 2015-07-10
 * Release version 2.0.1
 * Use extern string definitions in WePay.h

README.md

@@ -16,12 +16,16 @@ There are two types of payment methods:
 
 The WePay iOS SDK supports the following payment methods
  - Card Swiper (Merchant)
-    Using a Card Swiper, a merchant can accept in-person payments by swiping a consumer's card. 
+    Using a Card Swiper, a merchant can accept in-person payments by swiping a consumer's traditional magnetic strip card.
+ - Card Dipper (Merchant)
+    Using an Card Dipper, a merchant can accept in-person payments by prosessing a consumer's EMV-enabled chip card.
  - Manual Entry (Consumer/Merchant)
     The Manual Entry payment method lets consumer and merchant apps accept payments by allowing the user to manually enter card info.
 
 ## Installation
 
+Note: Card reader functionality is not available in this SDK by default. If you want to use this SDK with WePay card readers, send an email to mobile@wepay.com.
+
 #### Using [cocoapods](https://cocoapods.org/) (recommended)
 + Add `pod "WePay"` to your podfile
 + Run `pod install`
@@ -37,14 +41,13 @@ The [SwiftExample app](https://github.com/wepay/wepay-ios/tree/master/SwiftExamp
     - AudioToolbox.framework
     - AVFoundation.framework
     - CoreBluetooth.framework
+    - CoreLocation.framework
     - CoreTelephony.framework
     - MediaPlayer.framework
     - SystemConfiguration.framework
+    - UIKit.framework
     - libstdc++.6.0.9.dylib
 + Also include the framework files you copied:
-    - G4XSwiper.framework
-    - RPx.framework
-    - RUA.framework
     - TrustDefenderMobile.framework
     - WePay.framework
 + Done!
@@ -64,6 +67,7 @@ Detailed reference documentation is available on the reference page for the `WeP
 ### Delegate protocols
 The SDK uses delegate protocols to respond to API calls. You must adopt the relevant protocols to receive responses to the API calls you make.
 Detailed reference documentation is available on the reference page for each protocol:
+- `WPAuthorizationDelegate`
 - `WPCardReaderDelegate`
 - `WPCheckoutDelegate`
 - `WPTokenizationDelegate`
@@ -163,7 +167,10 @@ config.useLocation = YES;
     }  else if (status == kWPCardReaderStatusStopped) {
         // provide feedback to the user that the swiper has stopped
         self.statusLabel.text = @"Card Reader Stopped";
-    }
+    } else {
+        // handle any other status messages
+        self.statusLabel.text = [status description];
+    } 
 }  
 
 - (void) didReadPaymentInfo:(WPPaymentInfo *)paymentInfo 
@@ -176,6 +183,12 @@ config.useLocation = YES;
 {
     // Handle the error
 }
+
+- (void) shouldResetCardReaderWithCompletion:(void (^)(BOOL))completion
+{
+    // Change this to YES if you want to reset the card reader
+    completion(NO);
+}
 ~~~
 + Implement the WPTokenizationDelegate protocol methods
 ~~~{.m}
@@ -192,10 +205,10 @@ config.useLocation = YES;
 ~~~
 + Make the WePay API call, passing in the instance(s) of the class(es) that implemented the delegate protocols
 ~~~{.m}
-[self.wepay startCardReaderForTokenizingWithCardReaderDelegate:self tokenizationDelegate:self];
+[self.wepay startCardReaderForTokenizingWithCardReaderDelegate:self tokenizationDelegate:self authorizationDelegate:nil];
 // Show UI asking the user to insert the card reader and wait for it to be ready
 ~~~
-+ Thats it! The following sequence of events will occur:
++ That's it! The following sequence of events will occur:
     1. The user inserts the card reader (or it is already inserted)
     2. The SDK tries to detect the card reader and initialize it.
         - If the card reader is not detected, the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusNotConnected`
@@ -210,6 +223,89 @@ config.useLocation = YES;
     8. If the tokenization succeeds, the `paymentInfo:didTokenize:` method will be called
     9. Otherwise, if the tokenization fails, the `paymentInfo:didFailTokenization:` method will be called with the appropriate error
 
+### Integrating the Dip payment method
+
++ Adopt the WPAuthorizationDelegate, WPCardReaderDelegate and WPTokenizationDelegate protocols
+~~~{.m}
+\@interface MyWePayDelegate : NSObject <WPAuthorizationDelegate, WPCardReaderDelegate, WPTokenizationDelegate>
+~~~
++ Implement the WPCardReaderDelegate and WPTokenizationDelegate protocol methods (as shown above)
++ Implement the WPAuthorizationDelegate protocol methods
+~~~{.m}
+- (void) authorizeAmountWithCompletion:(void (^)(double amount, NSString *currencyCode, long accountId))completion
+{
+    // obtain transaction info
+    double amount = 10.00;
+    NSString *currencyCode = @"USD";
+    long accountId = 12345678;
+
+    // execute the completion
+    completion(amount, currencyCode, accountId);
+}
+
+- (void) selectEMVApplication:(NSArray *)applications
+                   completion:(void (^)(NSInteger selectedIndex))completion
+{
+    // In production apps, the payer must choose the app id they want to use.
+    // Here, we always select the first application in the array
+    int selectedIndex = 0;
+    completion(selectedIndex);
+}
+
+- (void) insertPayerEmailWithCompletion:(void (^)(NSString *email))completion
+{
+    // obtain email
+    NSString *email = @"emv@example.com";
+    
+    // execute the completion
+    completion(email);
+}
+
+- (void) paymentInfo:(WPPaymentInfo *)paymentInfo
+        didAuthorize:(WPAuthorizationInfo *)authorizationInfo
+{
+    // Send the token Id (authorizationInfo.tokenId) and transaction token (authorizationInfo.transactionToken) to your server
+    // Your server must use the tokenId and transactionToken to make a /checkout/create call to complete the transaction
+}
+
+- (void) paymentInfo:(WPPaymentInfo *)paymentInfo
+didFailAuthorization:(NSError *)error
+{
+    // Handle the error
+}
+~~~
++ Make the WePay API call, passing in the instance(s) of the class(es) that implemented the delegate protocols
+~~~{.m}
+[self.wepay startCardReaderForTokenizingWithCardReaderDelegate:self tokenizationDelegate:self authorizationDelegate:self];
+// Show UI asking the user to insert the card reader and wait for it to be ready
+~~~
++ That's it! The following sequence of events will occur:
+    1. The user inserts the card reader (or it is already inserted)
+    2. The SDK tries to detect the card reader and initialize it.
+        - If the card reader is not detected, the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusNotConnected`
+        - If the card reader is successfully detected, then the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusConnected`.
+    3. Next, the SDK checks if the card reader is correctly configured (the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusCheckingReader`).
+        - If the card reader is already configured, the App is given a chance to force configuration. The SDK calls the `shouldResetCardReaderWithCompletion:` method, and the app must execute the completion method, telling the SDK whether or not the reader should be reset.
+        - If the reader was not configured, or the app requested a reset, the card reader is configured (the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusConfiguringReader`)
+    4. Next, if the card reader is successfully initialized, the SDK asks the app for transaction information by calling the `authorizeAmountWithCompletion:` method. The app must execute the completion method, telling the SDK what the amount, currency code and merchant account id is.
+    5. Next, the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusWaitingForCard` 
+    6. If the user inserts a card successfully, the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusCardDipped`
+    7. If the card has multiple applications on it, the payer must choose one:
+        - The SDK calls the `selectEMVApplication:completion:` method with a list of Applications on the card.
+        - The app must display these Applications to the payer and allow them to choose which application they want to use.
+        - Once the payer has decided, the app must inform the SDK of the choice by executing the completion method and passing in the index of the chosen application.
+    8. Next, the SDK extracts card data from the card.
+        - If the SDK is unable to obtain data from the card, the `didFailToReadPaymentInfoWithError:` method will be called with the appropriate error, and processing will stop (the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusStopped`)
+        - Otherwise, the SDK attempts to ask the App for the payer’s email by calling the `insertPayerEmailWithCompletion:` method
+    9. If the app implements this optional delegate method, it must execute the completion method and pass in the payer’s email address.
+    10. Next, the `didReadPaymentInfo:` method is called with the obtained payment info.
+    11. Next, the SDK will automatically send the obtained EMV card info to WePay's servers for authorization (the `cardReaderDidChangeStatus:` method will be called with `status = kWPCardReaderStatusAuthorizing`)
+    12. If authorization fails, the `paymentInfo:didFailAuthorization:` method will be called and processing will stop.
+    13. If authorization succeeds, the `paymentInfo:didAuthorize:` method will be called.
+    14. Done!
+
+Note: After the card is inserted into the reader, it must not be removed until a successful auth response (or an error) is returned.
+
 ### Integrating the Manual payment method
 
 + Adopt the WPTokenizationDelegate protocol
@@ -247,7 +343,7 @@ WPPaymentInfo *paymentInfo = [[WPPaymentInfo alloc] initWithFirstName:@"WPiOS"
 ~~~{.m}
 [self.wepay tokenizeManualPaymentInfo:paymentInfo tokenizationDelegate:self];
 ~~~
-+ Thats it! The following sequence of events will occur:
++ That's it! The following sequence of events will occur:
     1. The SDK will send the obtained payment info to WePay's servers for tokenization
     2. If the tokenization succeeds, the `paymentInfo:didTokenize:` method will be called
     3. Otherwise, if the tokenization fails, the `paymentInfo:didFailTokenization:` method will be called with the appropriate error
@@ -289,7 +385,7 @@ UIImage *signature = [UIImage imageNamed:@"dd_signature.png"];
                   forCheckoutId:checkoutId
                checkoutDelegate:self];
 ~~~
-+ Thats it! The following sequence of events will occur:
++ That's it! The following sequence of events will occur:
     1. The SDK will send the obtained signature to WePay's servers
     2. If the operation succeeds, the `didStoreSignature:forCheckoutId:` method will be called
     3. Otherwise, if the operation fails, the `didFailToStoreSignatureImage:forCheckoutId:withError:` method will be called with the appropriate error