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 ?

1. The customer clicks on the Buy button inside your application.
2. The PWLocal SDK is called at this moment and opens application dialog with the list of payment systems.
3. 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.
4. 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

Add SDK to your project

Manually:

1. In the menubar click "File" then "Add file to YOUR_PROJECT".
2. Select the "PWLocalSDK" directory in the downloaded repository.
3. Make sure 'Copy items into destination group's folder (if needed)' is checked.
4. Click "Add"
5. Click on your project, in Targets tab click in "Build Settings"
6. In the "Header Search Paths" add link to include file of SDK such as "$SOURCE_ROOT/PWLocalSDK/include"
7. In the "Library Search Paths" add link to file "libPWLocalSDK.a"

With Cocoapods:

1. Add pod 'PWLocalSDK' into your podfile
2. Run pod install in your terminal
3. If you are using Swift : Create a Project-Bridging-Header.h and add it in your Build settings's Objective-C Bridging Header

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: VirtualCurrency, DigitalGoodsDefautWidget, DigitalGoodsFlexibleWidget and CartDefaultWidget We support 3 API type: VIRTUAL_CURRENCY, DIGITAL_GOODS_FLEXIBLE, DIGITAL_GOODS_DEFAULT, CART For more information, please refer to: https://www.paymentwall.com/en/documentation/Digital-Goods-API/710

Defined request

We defined 4 types request: VirtualCurrency, 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()
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 = [String: String]()
customSetting["key"] = PROJECT_KEY
customSetting["uid"] = USER_ID
customSetting["widget"] = WIDGET_TYPE

Start PWLocal dialog

Defined request

Objective-C

[PWLocalSDK showPWLocalViewControllerWithViewController:self
                                               delegate:self
                                                   type:DIGITAL_GOODS_FLEXIBLE
                                                 params:digitalGoodsdefaultWidget
                                              secretKey:SECRET_KEY];

Swift

PWLocalSDK.showPWLocalViewController(with: self,
                                     delegate: self,
                                     type: .DIGITAL_GOODS_FLEXIBLE,
                                     params: digitalGoodsdefaultWidget,
                                     secretKey: SECRET_KEY)

Custom request

Objective-C

[PWLocalSDK showPWLocalViewControllerWithViewController:self
                                               delegate:self
                                                   type:DIGITAL_GOODS_FLEXIBLE
                                                 params:customSetting
                                              secretKey:SECRET_KEY];

Swfit

PWLocalSDK.showPWLocalViewController(with: self,
                                     delegate: self,
                                     type: .DIGITAL_GOODS_FLEXIBLE,
                                     params: customSetting,
                                     secretKey: SECRET_KEY)

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 your params 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 .PWLOCAL_SUCCESSFUL:
            break
        case .PWLOCAL_CANCELED:
            break
        case .PWLOCAL_FAILED:
            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	email
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	email
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	email
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	email
NSString	sex
NSString	evaluation
NSString	location_city
NSString	location_state
NSString	location_address
NSString	location_country
NSString	location_zip
NSString	pingback_url