Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy

Close

Documentation

New Documentation Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
Contacts
If you still have questions regarding integration, please email us at devsupport@paymentwall.com

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 ?

  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.com

Add SDK to your project

  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 "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 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 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 typeParameter
NSStringkey
NSStringuid
NSStringwidget
NSStringps
NSString sign_version
NSStringbirthday
NSStringemail
NSStringsex
NSStringevaluation
NSStringlocation_city
NSStringlocation_state
NSStringlocation_address
NSStringlocation_country
NSStringlocation_zip
NSStringcountry_code
NSStringrv
NSStringth
NSStringtm
NSStringpingback_url
NSStringsuccess_url

Parameters of DigitalGoodsDefautWidget

Data typeParameter
NSStringkey
NSStringuid
NSStringwidget
NSStringps
NSString ts
NSString sign_version
NSStringbirthday
NSStringcountry_code
NSStringemail
NSStringsex
NSStringevaluation
NSStringfirstname
NSStringlang
NSStringlastname
NSStringlocation_city
NSStringlocation_state
NSStringlocation_address
NSStringlocation_country
NSStringlocation_zip
NSStringdefault_goodsid
NSStringdisplay_goodsid
NSArrayhide_goodsid
NSStringpingback_url
NSStringsuccess_url

Parameters of DigitalGoodsFlexibleWidget

Data typeParameter
NSStringkey
NSStringuid
NSStringwidget
NSStringamount
NSStringcurrencyCode
NSStringps
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
NSStringbirthday
NSStringcountry_code
NSStringemail
NSStringsex
NSStringevaluation
NSStringfirstname
NSStringlang
NSStringlastname
NSStringlocation_city
NSStringlocation_state
NSStringlocation_address
NSStringlocation_country
NSStringlocation_zip
NSStringshow_trial_non_recurring
NSStringshow_trial_recurring
NSStringshow_post_trial_non_recurring
NSStringshow_post_trial_recurring
NSStringpingback_url
NSStringsuccess_url

Parameters of CartDefaultWidget

Data typeParameter
NSStringkey
NSStringuid
NSStringwidget
NSStringexternal_ids
NSStringprices
NSStringcurrencies
NSStringfirstname
NSStringlastname
NSString sign_version
NSStringbirthday
NSStringemail
NSStringsex
NSStringevaluation
NSStringlocation_city
NSStringlocation_state
NSStringlocation_address
NSStringlocation_country
NSStringlocation_zip
NSStringpingback_url
This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookie Policy.