Introduction
The WePay iOS SDK enables collection of payments via various payment methods(described below).
It is meant for consumption by WePay partners who are developing their own iOS apps aimed at merchants and/or consumers.
Regardless of the payment method used, the SDK will ultimately return a Payment Token, which must be redeemed via a server-to-server API call to complete the transaction.
Payment methods
There are two types of payment methods:
- Consumer payment methods - to be used in apps where consumers directly pay and/or make donations
- Merchant payment methods - to be used in apps where merchants collect payments from their customers
The WePay iOS SDK supports the following payment methods
- Card Swiper: Using a Card Swiper, a merchant can accept in-person payments by swiping a consumer's traditional magnetic strip card.
- Card Dipper: Using an Card Dipper, a merchant can accept in-person payments by prosessing a consumer's EMV-enabled chip card.
- Manual Entry: The Manual Entry payment method lets consumer and merchant apps accept payments by allowing the user to manually enter card info.
Installation
Using cocoapods (recommended)
- Add
pod "WePay"
to your podfile
- Run
pod install
- Done!
The SwiftExample app also utilizes cocoapods
.
Using library binaries
- Download the latest zip file from our releases page
- Unzip the file and copy the contents anywhere inside your project directory
- In Xcode, go to your app's target settings. On the
Build Phases
tab, expand the Link Binary With Libraries
section.
- Include the following iOS frameworks:
- AudioToolbox.framework
- AVFoundation.framework
- CoreBluetooth.framework
- CoreLocation.framework
- CoreTelephony.framework
- ExternalAccessory.framework
- MediaPlayer.framework
- SystemConfiguration.framework
- UIKit.framework
- libstdc++.6.0.9.dylib
- libstdc++.dylib
- libz.dylib
- Also include the framework files you copied:
- TrustDefender.framework
- WePay.framework
- Done!
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 mobil.nosp@m.e@we.nosp@m.pay.c.nosp@m.om.
Documentation
HTML documentation is hosted on our Github Pages Site.
Pdf documentation is available on the releases page or as a direct download.
General documentation about the WePay mobile point of sale (mPOS) program is available here.
SDK Organization
WePay.h
is the starting point for consuming the SDK, and contains the primary class you will interact with. It exposes all the methods you can call to accept payments via the supported payment methods. Detailed reference documentation is available on the reference page for the WePay
class.
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:
Data Models
All other classes in the SDK are data models that are used to exchange data between your app and the SDK. Detailed reference documentation is available on the reference page for each class.
Next Steps
Head over to the documentation to see all the API methods available. When you are ready, look at the samples below to learn how to interact with the SDK.
Error Handling
WPError.h
serves as documentation for all errors surfaced by the WePay iOS SDK.
Samples
See the WePayExample app for a working implementation of all API methods.
See the SwiftExample app for a working implementation of all API methods in a Swift 3 application. Note: make sure to open the project using SwiftApp.xcworkspace
and not SwiftApp.xcodeproj
.
Initializing a Bridging Header (for Swift apps)
- For using Objective-C modules in a Swift application, you will need to create a bridging header.
- Make sure you are working in
{app_name}.xcworkspace
file.
- Under your target application folder, create a header file:
{app_name}-Bridging-Header.h
- In the Header file, import the modules you need:
- Click on the main application project to get to
Build Settings
.
- Search for
bridging header
in your target application to find a setting called Swift Compiler - Code Generation
.
- Double click in the column next to
Objective-C Bridging Header
and add your Header file: {app_name}/{app_name}-Bridging-Header.h
- There's no need to import the module in your code; you can use the module by calling it directly in your Swift application.
Initializing the SDK
- Complete the installation steps (above).
- Include WePay.h
- Define a property to store the WePay object
\
@property (nonatomic, strong)
WePay *wepay;
- Create a WPConfig object
WPConfig *config = [[
WPConfig alloc] initWithClientId:@"your_client_id" environment:kWPEnvironmentStage];
- Initialize the WePay object and assign it to the property
self.wepay = [[
WePay alloc] initWithConfig:config];
Providing permission to use microphone for card reader communication
- Open your app's Info.plist file and add an entry for NSMicrophoneUsageDescription.
<key>NSMicrophoneUsageDescription</key>
<string>Microphone permission is required for operating card reader</string>
(optional) Providing permission to use location services for fraud detection
- In Xcode, go to your projects settings. On the Build Phases tab, expand the Link Binary With Libraries section and include the CoreLocation.framework iOS framework.
- Open your app's Info.plist file and add entries for NSLocationUsageDescription and NSLocationWhenInUseUsageDescription.
<key>NSLocationUsageDescription</key>
<string>Location information is used for fraud prevention</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location information is used for fraud prevention</string>
- Set the option on the config object, before initializing the WePay object
Integrating the Swipe payment method
- Adopt the WPCardReaderDelegate and WPTokenizationDelegate protocols
- Implement the WPCardReaderDelegate protocol methods
- (void) cardReaderDidChangeStatus:(id) status
{
if (status == kWPCardReaderStatusNotConnected) {
self.statusLabel.text = @"Connect Card Reader";
} else if (status == kWPCardReaderStatusWaitingForSwipe) {
self.statusLabel.text = @"Swipe Card";
} else if (status == kWPCardReaderStatusSwipeDetected) {
self.statusLabel.text = @"Swipe Detected...";
} else if (status == kWPCardReaderStatusTokenizing) {
self.statusLabel.text = @"Tokenizing...";
} else if (status == kWPCardReaderStatusStopped) {
self.statusLabel.text = @"Card Reader Stopped";
} else {
self.statusLabel.text = [status description];
}
}
{
}
- (void) didFailToReadPaymentInfoWithError:(NSError *)error
{
}
- (void) shouldResetCardReaderWithCompletion:(void (^)(BOOL))completion
{
completion(NO);
}
- (void) selectCardReader:(NSArray *)cardReaderNames
completion:(void (^)(NSInteger selectedIndex))completion
{
int selectedIndex = 0;
completion(selectedIndex);
}
- Implement the WPTokenizationDelegate protocol methods
{
}
- (void) paymentInfo:(
WPPaymentInfo *)paymentInfo didFailTokenization:(NSError *)error
{
}
- Make the WePay API call, passing in the instance(s) of the class(es) that implemented the delegate protocols
[self.wepay startCardReaderForTokenizingWithCardReaderDelegate:self tokenizationDelegate:self authorizationDelegate:nil];
- That's it! The following sequence of events will occur:
- The user inserts the card reader (or it is already inserted), or powers on their Bluetooth card reader.
- The SDK tries to detect the card reader and initialize it.
- The
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusSearching
- If any card readers are discovered, the
selectCardReader:
method will be called with an array of discovered devices. If anything is plugged into the headphone jack, "AUDIOJACK"
will be one of the devices discovered.
- If no card readers are detected, the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusNotConnected
- Once the card reader selection completion block is called, the SDK will attempt to to connect to the selected card reader.
- If the card reader is successfully connected, then the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusConnected
.
- If the card reader successfully initialized, it will wait for the user to swipe a card
- If a recoverable error occurs during swiping, the
didFailToReadPaymentInfoWithError:
method will be called. After a few seconds, the cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusWaitingForSwipe
and the card reader will again wait for the user to swipe a card
- If an unrecoverable error occurs during swiping, or the user does not swipe, the
didFailToReadPaymentInfoWithError:
method will be called, and processing will stop
- Otherwise, the user swiped successfully, and the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusSwipeDetected
followed by the didReadPaymentInfo:
method
- Next, the SDK will automatically send the obtained card info to WePay's servers for tokenization (the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusTokenizing
)
- If the tokenization succeeds, the
paymentInfo:didTokenize:
method will be called
- 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
- Implement the WPCardReaderDelegate and WPTokenizationDelegate protocol methods (as shown above)
- Implement the WPAuthorizationDelegate protocol methods
- (void) authorizeAmountWithCompletion:(void (^)(double amount, NSString *currencyCode, long accountId))completion
{
double amount = 10.00;
NSString *currencyCode = @"USD";
long accountId = 12345678;
completion(amount, currencyCode, accountId);
}
- (void) selectEMVApplication:(NSArray *)applications
completion:(void (^)(NSInteger selectedIndex))completion
{
int selectedIndex = 0;
completion(selectedIndex);
}
- (void) insertPayerEmailWithCompletion:(void (^)(NSString *email))completion
{
NSString *email = @"emv@example.com";
completion(email);
}
{
}
didFailAuthorization:(NSError *)error
{
}
- Make the WePay API call, passing in the instance(s) of the class(es) that implemented the delegate protocols
[self.wepay startCardReaderForTokenizingWithCardReaderDelegate:self tokenizationDelegate:self authorizationDelegate:self];
- That's it! The following sequence of events will occur:
- The user inserts the card reader (or it is already inserted), or powers on their Bluetooth card reader.
- The SDK tries to detect the card reader and initialize it.
- The
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusSearching
- If any card readers are discovered, the
selectCardReader:
method will be called with an array of discovered devices. If anything is plugged into the headphone jack, "AUDIOJACK"
will be one of the devices discovered.
- If no card readers are detected, the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusNotConnected
- Once the card reader selection completion block is called, the SDK will attempt to to connect to the selected card reader.
- If the card reader is successfully connected, then the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusConnected
.
- 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
)
- 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.
- Next, the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusWaitingForCard
- If the user inserts a card successfully, the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusCardDipped
- 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.
- 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
- If the app implements this optional delegate method, it must execute the completion method and pass in the payer’s email address.
- Next, the
didReadPaymentInfo:
method is called with the obtained payment info.
- 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
)
- If authorization fails, the
paymentInfo:didFailAuthorization:
method will be called and processing will stop.
- If authorization succeeds, the
paymentInfo:didAuthorize:
method will be called.
- 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
- Implement the WPTokenizationDelegate protocol methods
{
}
- (void) paymentInfo:(
WPPaymentInfo *)paymentInfo didFailTokenization:(NSError *)error
{
}
- Instantiate a WPPaymentInfo object using the user's credit card and address data
lastName:@"Example"
email:@"wp.ios.example@wepay.com"
billingAddress:[[
WPAddress alloc] initWithZip:@"94306"]
shippingAddress:nil
cardNumber:@"5496198584584769"
cvv:@"123"
expMonth:@"04"
expYear:@"2020"
virtualTerminal:YES];
- Make the WePay API call, passing in the instance of the class that implemented the WPTokenizationDelegate protocol
[self.wepay tokenizeManualPaymentInfo:paymentInfo tokenizationDelegate:self];
- That's it! The following sequence of events will occur:
- The SDK will send the obtained payment info to WePay's servers for tokenization
- If the tokenization succeeds, the
paymentInfo:didTokenize:
method will be called
- Otherwise, if the tokenization fails, the
paymentInfo:didFailTokenization:
method will be called with the appropriate error
Integrating the Store Signature API
- Adopt the WPCheckoutDelegate protocol
- Implement the WPCheckoutDelegate protocol methods
- (void) didStoreSignature:(NSString *)signatureUrl
forCheckoutId:(NSString *)checkoutId
{
}
- (void) didFailToStoreSignatureImage:(UIImage *)image
forCheckoutId:(NSString *)checkoutId
withError:(NSError *)error
{
}
- Obtain the checkout_id associated with this signature from your server
NSString *checkoutId = [self obtainCheckoutId];
- Instantiate a UIImage containing the user's signature
UIImage *signature = [UIImage imageNamed:@"dd_signature.png"];
- Make the WePay API call, passing in the instance of the class that implemented the WPCheckoutDelegate protocol
[self.wepay storeSignatureImage:signature
forCheckoutId:checkoutId
checkoutDelegate:self];
- That's it! The following sequence of events will occur:
- The SDK will send the obtained signature to WePay's servers
- If the operation succeeds, the
didStoreSignature:forCheckoutId:
method will be called
- Otherwise, if the operation fails, the
didFailToStoreSignatureImage:forCheckoutId:withError:
method will be called with the appropriate error
Integrating the the Battery Level API
- Adopt the WPBatteryLevelDelegate protocol
- Implement the WPCheckoutDelegate protocol methods
- (void) didGetBatteryLevel:(int)batteryLevel
{
}
- (void) didFailToGetBatteryLevelwithError:(NSError *)error
{
}
- Make the WePay API call, passing in the instance(s) of the class(es) that implemented the WPCardReaderDelegate and WPBatteryLevelDelegate protocols
[self.wepay getCardReaderBatteryLevelWithCardReaderDelegate:self batteryLevelDelegate:self];
- That's it! The following sequence of events will occur:
- The SDK will attempt to read the battery level of the card reader
- If the operation succeeds, WPBatteryLevelDelegate's
didGetBatteryLevel:
method will be called with the result
- Otherwise, if the operation fails, WPBatteryLevelDelegate's
didFailToGetBatteryLevelwithError:
method will be called with the appropriate error
Configuring the SDK
The experiences described above can be modified by utilizing the configuration options available on the WPConfig object. Detailed descriptions for each configurable property is available in the documentation for WPConfig.
Test/develop using mock card reader and mock WepayClient
- To use mock card reader implementation instead of using the real reader, instantiate a MockConfig object and pass it to Config:
config.mockConfig = mockConfig;
- To use mock WepayClient implementation instead of interacting with the real WePay server, set the corresponding option on the mockConfig object:
- Other options are also available:
Integration tests and unit tests
All the integration tests and unit tests are located in the /WePayTests/
directory.
From Xcode
From the Tests Navigator tab:
- To run a single test, right-click the test method and select "Test <name>".
- To run all test methods in a class, right-click the class and select "Run <name>".
- To run all tests in a directory, right-click the directory and select "Run <name>".
- To run all tests in the project, use the menu option Product > Test or press (Cmd + U).
From the command line
Go to this repo directory and execute:
xcodebuild test -project WePay.xcodeproj -scheme "Release Framework" -destination 'platform=iOS Simulator,name=iPhone 7'