Documentation
PWLocal iOS SDK
PWLocal iOS SDK
Introduction
Do you need to have an ability to accept payments from mobile users in different countries, considering which payment methods fit best? PWLocal is a global payment gateway that makes it easy to accept payments from customers in more than 200 countries with 100+ alternative payment options. PWLocal iOS SDK will become a native part of your application, it eliminates the necessity to open a web browser for payments, as a result you will receive a higher conversions rate. All you have to do is import the library into your iOS project and start using our SDK to accept in-app payments. It is quick and easy! We'll guide you through the process here.
How does it work ?
- The customer clicks on the "Buy" button inside your application.
- The PWLocal SDK is called at this moment and opens application dialog with the list of payment systems.
- User chooses a payment system and clicks on "Buy". After it, a new application dialog opens. It would be a "thank you" screen or a dialog for providing payment details, such as credit card number, if needed.
- The payment is completed and your callback function is triggered to handle its result. Your backend will be also notified about it.
Credentials
Your mobile integration requires a Project key.
You can obtain these Paymentwall API credentials in the application settings of your Merchant Account at paymentwall.com
Add SDK to your project
- In the menubar click "File" then "Add file to YOUR_PROJECT".
- Select the "PWLocalSDK" directory in the downloaded repository.
- Make sure 'Copy items into destination group's folder (if needed)' is checked.
- Click "Add"
- Click on your project, in Targets tab click in "Build Settings"
- In the "Header Search Paths" add link to include file of SDK such as "$SOURCE_ROOT/PWLocalSDK/include"
- In the "Library Search Paths" add link to file "PWLocalSDK.a"
Accepting your first payment
Import
Objective-C
#import "PWLocalSDK.h"
Swift
Add this command to your Bridging-Header.h file
#import "PWLocalSDK.h"
Create PWLocal request
We have 4 types of PWLocal payment request: VituralCurrency
, DigitalGoodsDefautWidget
, DigitalGoodsFlexibleWidget
and CartDefaultWidget
We support 3 API type: VIRTUAL_CURRENCY
, DIGITAL_GOODS
, CART
For more information, please refer to:
https://www.paymentwall.com/en/documentation/Digital-Goods-API/710
Defined request
We defined 4 types request: VituralCurrency
, DigitalGoodsDefautWidget
, DigitalGoodsFlexibleWidget
and CartDefaultWidget
. You can simply use setters to set required parameters. Please note that all the parameters are changed from under_score to camelCase format.
Example
Objective-C
DigitalGoodsDefautWidget *digitalGoodsdefaultWidget = [DigitalGoodsDefautWidget new];
digitalGoodsdefaultWidget.key = PROJECT_KEY;
digitalGoodsdefaultWidget.uid = USER_ID;
digitalGoodsdefaultWidget.widget = WIDGET_TYPE;
Swift
let digitalGoodsdefaultWidget: DigitalGoodsDefautWidget = DigitalGoodsDefautWidget()
digitalGoodsdefaultWidget.key = PROJECT_KEY
digitalGoodsdefaultWidget.uid = USER_ID
digitalGoodsdefaultWidget.widget = WIDGET_TYPE
Custom request
If our defined request does not match your need. We also supported NSDictionary with key and value you can handler it by yourself. It follows the parameters in https://www.paymentwall.com/en/documentation/Digital-Goods-API/710
Example
Objective-C
NSMutableDictionary *customSetting = [NSMutableDictionary new];
[customSetting setObject: PROJECT_KEY forKey:@"key"];
[customSetting setObject: USER_ID forKey:@"uid"];
[customSetting setObject: WIDGET_TYPE forKey:@"widget"];
Swift
var customSetting: NSMutableDictionary = NSMutableDictionary()
customSetting.setObject(PROJECT_KEY, forKey: "key")
customSetting.setObject(USER_ID, forKey: "uid")
customSetting.setObject(WIDGET_TYPE, forKey: "widget")
Start PWLocal dialog
Defined request
Objective-C
PWLocalViewController *viewController = [PWLocalViewController new];
viewController.delegate = self;
viewController.apiType = DIGITAL_GOODS;
viewController.digitalGoodsDefautWidget = digitalGoodsdefaultWidget;
viewController.appDownloadURL = @"http://example.com"
viewController.secretKey = SECRET_KEY;
[viewController showPWLocalWithParentViewController:self completion:^(int code){
}];
Swfit
var viewController: PWLocalViewController = PWLocalViewController()
viewController.delegate = self
viewController.apiType = Int32(DIGITAL_GOODS.value)
viewController.digitalGoodsDefautWidget = digitalGoodsdefaultWidget
viewController.appDownloadURL = "http://example.com"
viewController.secretKey = SECRET_KEY
viewController.showPWLocalWithParentViewController(self, completion:{ (code) -> Void in
})
Custom request
Objective-C
PWLocalViewController *viewController = [PWLocalViewController new];
viewController.delegate = self;
viewController.apiType = DIGITAL_GOODS;
viewController.customRequestDictionary = customSetting;
viewController.appDownloadURL = @"http://example.com"
viewController.secretKey = SECRET_KEY;
[viewController showPWLocalWithParentViewController:self completion:^(int code){
}];
Swift
var viewController: PWLocalViewController = PWLocalViewController()
viewController.delegate = self
viewController.apiType = Int32(DIGITAL_GOODS.value)
viewController.customRequestDictionary = customSetting
viewController.appDownloadURL = "http://example.com"
viewController.secretKey = SECRET_KEY
viewController.showPWLocalWithParentViewController(self, completion:{ (code) -> Void in
})
Custom signing
Storing secretKey
on your own backend lower your risk of exposing it. Signing your request remotely is recommended to secure your project. You can use this method to get the complete sorted string, you will only need to add secret key at the end to calculate the signature, params
can be Dictionary or any of the pre-made class:
Objective-C
NSString *stringToSign = [PWLocalSDK getStringToSign:params];
Swift
let stringToSign = PWLocalSDK.getStringToSign(params)
Note: Param
"success_url"="pwlocal://paymentsuccessful"
is added by default by this function if yourparams
doesn't have it included, if you use your own webView, track this value to close your webView
Extra headers
Please note that if you want to use your own webview to show the widget, there are few extra headers you have to add to your request, use this method to get them and add to your mutable request with [request setValue:value forHTTPHeaderField:key]
:
Objective-C
NSDictionary *extra = [PWLocalSDK getExtraHeaders];
Swift
let extra = PWLocalSDK.getExtraHeaders()
Handle result
You have to add PWLocalSDKDelegate to your ViewController
Objective-C
@interface YourViewController : UIViewController <PWLocalSDKDelegate>
Swift
class YourViewController: UIViewController, PWLocalSDKDelegate
You can handle payment results by defining your callback function. We recommend syncing up with your server at this point to sync up user's balance, confirm purchased item etc. See the example:
Objective-C
#pragma mark - PWLocal Response
-(void)pwLocalResponse:(PWLocalResponse *)response {
switch (response.code) {
case PWLOCAL_SUCCESSFUL:
break;
case PWLOCAL_FAILED:
break;
case PWLOCAL_CANCELED:
break;
default:
break;
}
}
Swift
// MARK: - PWLocal Response
func pwLocalResponse(response: PWLocalResponse!) {
switch response.code {
case Int32(PWLOCAL_SUCCESSFUL.value):
break
case Int32(PWLOCAL_FAILED.value):
break
case Int32(PWLOCAL_CANCELED.value):
break
default:
break
}
}
response.code
code can have one of the following values:
PWLOCAL_SUCCESSFUL
: the user has completed the payment
PWLOCAL_CANCELED
: the user has aborted the payment
PWLOCAL_FAILED
: the payment cannot be done due to some error:
- Network error
- Invalid supplying request
Payment Status API utils
Our SDK also support Payment Status API.
Get payment status
Unsigned call
Objective-C
#pragma mark - PWLocal Get Payment Status
[PWLocalSDK checkPaymentStatusWithKey:PROJECT_KEY
agExternalId:A_EXTERNAL_ID
uid:UID
signVersion:0
andSecretKey:@""
completion:^(PWLocalStatusResponse *response) {
if(response.code == PWLOCAL_STAUTS_SUCCESSFUL) {
if(response.dataResponse.count > 0) PaymentStatus *paymentStatus = response.dataResponse.firstObject;
}
}
else
NSLog(@"%@", response.message);
}];
Swift
// MARK: - PWLocal Get Payment Status
PWLocalSDK.checkPaymentStatusWithKey(PROJECT_KEY, agExternalId: A_EXTERNAL_ID, uid: UID, signVersion: 0, andSecretKey: "", completion: {
(response) -> Void in
})
Signed call
Objective-C
#pragma mark - PWLocal Get Payment Status
[PWLocalSDK checkPaymentStatusWithKey:PROJECT_KEY
agExternalId:A_EXTERNAL_ID
uid:UID
signVersion:SIGN_VERSION
andSecretKey:SECRET_KEY
completion:^(PWLocalStatusResponse *response) {
if(response.code == PWLOCAL_STAUTS_SUCCESSFUL) {
if(response.dataResponse.count > 0) PaymentStatus *paymentStatus = response.dataResponse.firstObject;
}
}
else
NSLog(@"%@", response.message);
}];
Swift
// MARK: - PWLocal Get Payment Status
PWLocalSDK.checkPaymentStatusWithKey(PROJECT_KEY, agExternalId: A_EXTERNAL_ID, uid: UID, signVersion: SIGN_VERSION, andSecretKey: SECRET_KEY, completion: {
(response) -> Void in
})
Server notification handling
After each successful payment we will notify your server about it. We recommend to use this feature as it is the most reliable way to know when the payment went through. Even if your application crashes for some reason, your server will still be notified, so you can sync up later. Please use pingback processing documentation for more information.
Appendix
Supported parameters
Here's the list of supported parameters in defined requests
Parameters of VirtualCurrency
Data type | Parameter |
NSString | key |
NSString | uid |
NSString | widget |
NSString | ps |
NSString | sign_version |
NSString | birthday |
NSString | |
NSString | sex |
NSString | evaluation |
NSString | location_city |
NSString | location_state |
NSString | location_address |
NSString | location_country |
NSString | location_zip |
NSString | country_code |
NSString | rv |
NSString | th |
NSString | tm |
NSString | pingback_url |
NSString | success_url |
Parameters of DigitalGoodsDefautWidget
Data type | Parameter |
NSString | key |
NSString | uid |
NSString | widget |
NSString | ps |
NSString | ts |
NSString | sign_version |
NSString | birthday |
NSString | country_code |
NSString | |
NSString | sex |
NSString | evaluation |
NSString | firstname |
NSString | lang |
NSString | lastname |
NSString | location_city |
NSString | location_state |
NSString | location_address |
NSString | location_country |
NSString | location_zip |
NSString | default_goodsid |
NSString | display_goodsid |
NSArray | hide_goodsid |
NSString | pingback_url |
NSString | success_url |
Parameters of DigitalGoodsFlexibleWidget
Data type | Parameter |
NSString | key |
NSString | uid |
NSString | widget |
NSString | amount |
NSString | currencyCode |
NSString | ps |
NSString | ts |
NSString | ag_name |
NSString | ag_external_id |
NSString | ag_type |
NSString | ag_period_length |
NSString | ag_period_type |
NSString | ag_recurring |
NSString | ag_promo |
NSString | ag_trial |
NSString | ag_post_trial_period_length |
NSString | ag_post_trial_period_type |
NSString | ag_post_trial_external_id |
NSString | post_trial_amount |
NSString | post_trial_currencyCode |
NSString | ag_post_trial_name |
NSString | hide_post_trial_good |
NSString | sign_version |
NSString | birthday |
NSString | country_code |
NSString | |
NSString | sex |
NSString | evaluation |
NSString | firstname |
NSString | lang |
NSString | lastname |
NSString | location_city |
NSString | location_state |
NSString | location_address |
NSString | location_country |
NSString | location_zip |
NSString | show_trial_non_recurring |
NSString | show_trial_recurring |
NSString | show_post_trial_non_recurring |
NSString | show_post_trial_recurring |
NSString | pingback_url |
NSString | success_url |
Parameters of CartDefaultWidget
Data type | Parameter |
NSString | key |
NSString | uid |
NSString | widget |
NSString | external_ids |
NSString | prices |
NSString | currencies |
NSString | firstname |
NSString | lastname |
NSString | sign_version |
NSString | birthday |
NSString | |
NSString | sex |
NSString | evaluation |
NSString | location_city |
NSString | location_state |
NSString | location_address |
NSString | location_country |
NSString | location_zip |
NSString | pingback_url |