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 (Merchant) Using a Card Swiper, a merchant can accept in-person payments by swiping a consumer's 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
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
- CoreTelephony.framework
- MediaPlayer.framework
- SystemConfiguration.framework
- libstdc++.6.0.9.dylib
- Also include the framework files you copied:
- G4XSwiper.framework
- RPx.framework
- RUA.framework
- TrustDefenderMobile.framework
- WePay.framework
- Done!
Documentation
HTML documentation is hosted on our Github Pages Site.
Pdf documentation is available on the releases page or as a direct download.
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 2 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];
(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.
1 <key>NSLocationUsageDescription</key>
2 <string>Location information is used for fraud prevention</string>
3 <key>NSLocationWhenInUseUsageDescription</key>
4 <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";
}
}
{
}
- (void) didFailToReadPaymentInfoWithError:(NSError *)error
{
}
- 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];
- Thats it! The following sequence of events will occur:
- The user inserts the card reader (or it is already inserted)
- 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
.
- Next, if the card reader is successfully initialized, then the
cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusWaitingForSwipe
- Otherwise,
didFailToReadPaymentInfoWithError:
will be called with the appropriate error, and processing will stop (the cardReaderDidChangeStatus:
method will be called with status = kWPCardReaderStatusStopped
)
- 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 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];
- Thats 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];
- Thats 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