Paypal Mobile Payments Library 2012 Ios Developers Guide PP_MPL_Developer_Guide_and_Reference_1 4_iPhone

Mobile Payments Library - 2012 - Developer Guide and Reference – iOS PP_MPL_DG_iPhone_2012 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Mobile-Payments-Library-2012-Ios-Developers-Guide-777966 paypal-mobile-payments-library-2012-ios-developers-guide-777966 paypal pdf

Open the PDF directly: View PDF .
Page Count: 57

Download
Open PDF In Browser	View PDF

Mobile Payments Library
Developer Guide and
Reference –
iOS Edition

Last updated: Augst 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition
Document Number 10105.en_US-201208

© 2011 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a
trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the
written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions.
Registered office: 22-24 Boulevard Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As
such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms
and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no
warranties of any kind (whether express, implied or statutory) with respect to the information contained herein.
PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or
resulting from the use of this document or the information contained in this document or resulting from the
application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to
any information herein without further notice.

Contents
Preface ............................................................................................................... 5
Purpose ........................................................................................................................ 5
Scope............................................................................................................................ 5
Revision History ............................................................................................................ 5
Where to Go for More Information ................................................................................ 6

1. PayPal Mobile Payments Library ............................................................... 7
Mobile Payments Library API Reference ..................................................................... 7
Required Methods in the Mobile Payments Library ............................................... 7
Optional Methods in the Mobile Payments Library .............................................. 11
Delegate Methods in the Mobile Payments Library ............................................. 13
After the Payment ................................................................................................ 14
Simple, Parallel, and Chained Payments ................................................................... 14
Simple Payments ................................................................................................. 16
Parallel Payments ................................................................................................ 16
Chained Payments ............................................................................................... 17
Preapprovals............................................................................................................... 18
How Preapprovals Work ...................................................................................... 18
About Preapproval Keys ...................................................................................... 18
About Preapproval Pins ....................................................................................... 18
Method Signature for Preapproval Checkout....................................................... 19
Method Sequence for Preapproval Checkout ...................................................... 20
Custom Objects in the Mobile Payments Library ....................................................... 21
Enumerated Values in the Mobile Payments Library ................................................. 26
Localization Support in the Mobile Payments Library ................................................ 28
Library Support for the devices and OS versions. ...................................................... 29
Adding the Mobile Payments Library to Your Xcode Project ..................................... 29
Sample Code .............................................................................................................. 30
Header File........................................................................................................... 30
Implementation File .............................................................................................. 31
Placing the Pay with PayPal Button ..................................................................... 32
Creating the PayPalPayment Object ................................................................... 32
Checking Out ....................................................................................................... 33
Handling the Callback .......................................................................................... 33
Dynamic Amount Calculation ............................................................................... 34

2. The Checkout Experience with the Mobile Payments Library ............... 36
Checkout Experience #1 – Goods or Services with Shipping .................................... 36

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Checkout Experience #2 – Goods or Services without Shipping ............................... 37
Checkout Experience #3 – Donations ........................................................................ 38
Checkout Experience #4 – Personal Send Money Payments .................................... 39
Checkout Experience #5 – Create Pin ....................................................................... 40
Checkout Experience #6 – Preapproval ..................................................................... 41
Basic Preapproval Checkout................................................................................ 41
Creating Preapproval PINs During Preapproval Checkout .................................. 42

3. Submitting Your Application to PayPal ................................................... 43
A. Currencies Supported by PayPal ............................................................. 44
B. Countries and Regions Supported by PayPal......................................... 45
C. Creating an Ad Hoc Build ......................................................................... 49
Creating a Distribution Certificate ............................................................................... 49
Creating and Approving a Certificate Signing Request ....................................... 49
Creating a Distribution Certificate ........................................................................ 50
Adding Device IDs ...................................................................................................... 50
Locating your Device ID ....................................................................................... 51
Adding Devices to the iPhone Developer Program Portal ................................... 51
Using Updated Provisioning Profiles for New Devices ........................................ 51
Creating the App ID .................................................................................................... 51
Creating a Distribution Provisioning Profile ................................................................ 53
Creating the Build in Xcode ........................................................................................ 54
Notes .......................................................................................................................... 56
Saving the Private Key and Transferring It to Other Systems ............................. 56
Verifying a Successful Ad Hoc Distribution Build................................................. 57
Correcting an Unsuccessful Ad Hoc Distribution Build ........................................ 57

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Preface
The PayPal Mobile Payments Library provides secure, extensible, and scalable PayPal payment
functionality to the Apple iPhone, iPod and iPad platforms.

Purpose
The PayPal Mobile Payments Library provides an easy way for you to integrate payments into
your iPhone, iPod touch, and iPad applications. You can download the library from X.com and
include it in your application. With the library, you need only a few lines of code to integrate the
library into your application.
When a buyer makes a payment, the library controls the checkout experience – logging in,
reviewing, and completing the payment. After buyers complete their payments, the library returns
them to your application.

Scope
This document describes how to integrate the PayPal Mobile Payments Library with your
application. You must create and provide your build to PayPal so PayPal can review your
application before it is approved to accept payments by way of the library. The approval process
is described later in the document.

Revision History
The following table lists revisions made to the PayPal Mobile Payments Library Developer
Guide and Reference – iOS Edition.
Version

Date Published

Description

1.2.2

June 2011

Added iPad support.

1.2.1

January 2011

Added the initializationStatus method to check
the status of initializeWithAppID. If an error occurs
during initializeWithAppID you can now retry the
method.
Added the ability for merchants to notify the library of an
error condition during dynamic amount calculation.
Disabled Keep Me Logged in functionality.

1.1

December 2010

Added information about preapproval; dropped support for
the enumeration value BUTTON_118x24.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Version

Date Published

Description

1.0

October 2010

Added information on Adaptive Payments support, including
“Refunds can be supported by manual refund using the
PayPal account interface or by means of the
RefundTransaction API. AdaptivePayments Refund API call
is not supported for MPL-generated pay keys. More details
and documentation are available at:
https://cms.paypal.com/cms_content/US/en_US/files/develo
per/PP_AdaptivePayments.pdf

Simple, Parallel, and Chained Payments.”
0.72

July 2010

Added topic “After the Payment” that lists features to let you
track the payment after it is completed; added additional
code samples; code samples are now in plain text so they can
be copied and pasted into applications.

0.71

June 2010

Updated “The Checkout Experience with the Mobile
Payments Library” with use cases for goods with no
shipments, donations, and personal Send Money; added
“Currencies Supported by PayPal” and “

Countries and Regions Supported by PayPal.”
0.7

April 2010

The setPayButton method is renamed the getPayButton
method; the checkout method takes a new
PayPalMEPPayment object as its only parameter.

0.6

March 2010

Added topics “feePayer ” on page 12 and
“dynamicAmountUpdateEnabled ” on page 12; added topics
for new data structures in “Custom Objects in the Mobile
Payments Libary” on page 15; added topic “The Checkout
Experience with the Mobile Payments Library” on page 36.

0.5

February 2010

First publication.

Where to Go for More Information

•

Adaptive Payments Developer Guide

•

Sandbox User Guide

•

Merchant Setup and Administration Guide

•

PayPal X Developer Network (x.com)

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

1. PayPal Mobile Payments Library
This section provides details about the Mobile Payments Library API, and it provides instructions
and examples for integrating the library with your iPhone application.

Mobile Payments Library API Reference
The flow of the library is:
1. Your application initializes the library.
2. The library creates a Pay with PayPal UIButton and returns it to you so you can place it on
the screen.
3. (Optional) Your application enables dynamic amount calculation to recalculate the payment
amount, tax, currency, and shipping values when buyers change the shipping address for the
payment.
4. Your application sets all of the payment parameters including the amount, currency, recipient,
and item details.
5. When buyers select the Pay with PayPal button, the library takes them through the PayPal
Checkout experience. The library displays itself on top of the application’s Window object,
so be sure that you do not take control of the Window after the buyer clicks Pay with
PayPal.
6. (Optional) If you enabled dynamic amount calculation in step 1 above:
a. When a buyer chooses an address for the payment, the library returns a callback to
your application with the address information.
b. Your application recalculates the payment and other amounts, based on the address
and returns those on the callback.
c. The library returns the buyer to the checkout experience, which uses the updated
payment amount, tax, currency, and shipping values.
7. After buyers complete their payments, the library returns a callback to your application with
the transaction id and status of the payment. Note that, at this time, the library is still in
control of the UI and has not returned control to your application.
8. After the library flow is complete, the library returns a callback to your application indicating
it is relinquishing control of the UI.
Required Methods in the Mobile Payments Library
initializeWithAppID Method

The initializeWithAppID method creates and returns the PayPal object.
NOTE:

If you do not set the optional parameter forEnvironment, the library defaults to use
the PayPal production servers. When testing your application, PayPal recommends that
you initialize the library to use the PayPal test servers, instead.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

NOTE:

The Mobile Payments Library binds specific devices to specific application IDs, for
enhanced security. For each of your application IDs, you must use a different sandbox
account for each of your devices or simulators. To switch a device or simulator to use a
different sandbox account, go to the PayPal Sandbox website on your computer, select
Profile > Mobile Applications, and then unbind the device from the application ID.

You have two options for when to call the initializeWithAppID method:
•

Initialize the PayPal object on the main thread, when you need it. Initialize the library
each time before you call the getPayButtonWithTarget method. This implementation is
simple because it uses a single-threaded programming model. The initializeWithAppID
call is blocking, so your application waits for the initialization to complete.
To use this method, you can use one line of code:
[PayPal initializeWithAppID:appID];

Or:
[PayPal initializeWithAppID:appID forEnvironment:env];

On subsequent lines you can then reference the PayPal object with [PayPal
getInstance].

•

Initialize the PayPal object on a separate thread, when your application starts. Initialize
the library once. This implementation is complex because it uses a multiple-threaded
programming model. The initializeWithAppId call is not blocking, so your main
application thread continues while the initialization completes in the background. This way
the button is ready to display when you need it.
The following sample code initializes the PayPal object on a separate thread.
- (void)applicationDidFinishLaunching:(UIApplication *)application {
[window addSubview:navController.view];
[window makeKeyAndVisible];
[NSThread detachNewThreadSelector:@selector(initializePayPal)
toTarget:self withObject:nil];
}
-(void)initializePayPal {
[PayPal initializeWithAppID:@"APP-80W284485P519543T"
forEnvironment:ENV_SANDBOX];
}

Inside the AppDelegate’s applicationDidFinishLaunching method, the code starts the
initializeWithAppId method on a new thread.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

In either case, you need to make sure the initialization is successful by sending an
initializationStatus message to the PayPal object.
The following table lists the possible status values returned from the initializationStatus
query:
Status
STATUS_NOT_STARTED

Definition
Initialization never attempted.

STATUS_COMPLETED_SUCCESS

Initialization completed successfully.

STATUS_COMPLETED_ERROR

Initialization completed with errors. The error is displayed in
the device or simulator logs.

STATUS_INPROGRESS

Initialization in progress. Must wait until the current
initialization attempt completes before attempting to retry
initialization.

You can perform this check on the viewDidLoad method of the UIViewController that will
contain the Pay with PayPal button.
An example to verify that the initialization process completed successfully is:
if ([PayPal initializationStatus] == STATUS_COMPLETED_SUCCESS) {
//We have successfully initialized and are ready to pay
} else {
//An error occurred
}
}
NOTES:

•

The Pay with PayPal button returned by the getPayButtonWithTarget method is
disabled until the initialization is complete. Once the initialization is complete, if it was
successful, the button is enabled.

•

When initialization status returns STATUS_COMPLETED_ERROR - Request timeouts or
host unavailable (Network connection failure) are valid initialization error cases for
initializePayPal retry attempts.

•

If initialization failed due to a buyer error, the error message presents as a UIAlertView.

+(PayPal*)initializeWithAppID:(NSString const *)PayPalApplicationID
(Optional:) forEnvironment:(PayPalEnvironment)env;

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Parameter

Description

PayPalApplicationId:

(Required) PayPal Application ID from X.com. For the Sandbox
environment, you should use APP-80W284485P519543T.

env:

(Optional) Sets the PayPal server to Live, Sandbox, or None. Allowable
values are:
• ENV_LIVE (does not support simulators)
• ENV_SANDBOX
• ENV_NONE
For details of the different servers, see “Enumerated Values in the
Mobile Payments Library.”

getPayButtonWithTarget Method

You must get the Pay with PayPal payment button from the Mobile Payments Library. Use this
method, which returns a UIButton, to place the button on your page. If you need to move the
button, when your application supports rotation for example, change the button frame. The target
parameter sets the delegate property of the PayPal object, which receives the
PayPalPaymentDelegate callbacks. If invalid data is entered, you receive an alert in a
UIAlertView.
See an example of placing the Pay button in “Placing the Pay with PayPal Button.”
-(UIButton *)getPayButtonWithTarget:(const
id)target andAction:(SEL)action
andButtonType:(PayPalButtonType)buttonType
andButtonText:(PayPalButtonText)buttonTextType;
Parameter

Description

target:

(Required) The PayPalPaymentDelegate that is the delegate for
callbacks.

action:

(Required) Called when a buyer taps the Pay with PayPal button.

buttonType:

(Required) Size and appearance of the Pay with PayPal buttons.
Allowable values are:
• BUTTON_152x33
• BUTTON_194x37
• BUTTON_278x43
• BUTTON_294x43
For images of the different button types, see “Enumerated Values in the
Mobile Payments Library.”

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Parameter

Description

buttonTextType:

(Optional) Determines whether the button displays “Pay with PayPal”
or “Donate with PayPal”. The default value is BUTTON_TEXT_PAY.
• BUTTON_TEXT_PAY
• BUTTON_TEXT_DONATE

Checkout Methods

The library provides 2 methods that launch the PayPal Checkout experience. The Checkout
method handles simple payments, which support single receivers of payments with one
transaction. The AdvancedCheckout method handles parallel and chained payments, which
support multiple receivers of payments with one transaction.
When you place the Pay with PayPal button on your mobile screen, specify a method of your
own to call when buyers tap the button. In the method that you specify, call the PayPal checkout
method that supports your business model for payment recipients.
Both checkout methods accept a payment object, which defines different aspects of a payment. If
you provide invalid data, you receive an alert in a UIAlertView.
The library displays itself on top of your application’s Window object. Make sure that you do not
take control of the Window after the buyer clicks Pay with PayPal.
-(void)checkoutWithPayment:(PayPalPayment *)inPayment;
Parameter

Description

inPayment:

(Required) A PayPalPayment object that contains information about
the payment. For the properties of this object type, see
“PayPalPayment.”

-(void)advancedCheckoutWithPayment:(PayPalAdvancedPayment *)inPayment;
Parameter

Description

inPayment:

(Required) A PayPalAdvancedPayment object that contains
information about the payment. For the properties of this object type,
see “PayPalAdvancedPayment.”

Optional Methods in the Mobile Payments Library
lang Property

This property allows you to define the language settings that the library uses. If the property is
not set, the library retrieves the current language settings from the device.
@property (nonatomic, retain) NSString *lang;

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

For a complete list of languages supported by the library, please see the section “Localization
Support in the Mobile Payments Library.”
shippingEnabled Property

This property lets buyers specify shipping addresses. With this property enabled, buyers choose
from the shipping addresses in their PayPal account. The chosen shipping address is used then for
the payment. If this property is disabled, the library does not display shipping options to the
buyer. Shipping is enabled by default, so you need to enable it only if you have previously
disabled it after initializing the library.
@property (nonatomic, assign) BOOL shippingEnabled;
payPalContext Property

Use this property to resume a payment when your application closes and restarts. This lets you
avoid calling the PayPal getPayButtonWithTarget and checkout methods, again. The usage
is to initialize the PayPal object, get the context object from wherever your application stored it,
and then call this method. In order to resume payments later, store the value of this property in the
applicationWillTerminate method of your AppDelegate class.
@property (nonatomic, retain) PayPalContext *payPalContext;
getInstance Method

This method returns the singleton PayPal object.
+(PayPal *)getInstance;
feePayer Property

Set this property to determine who pays any fees. Available values are FEEPAYER_SENDER,
FEEPAYER_PRIMARYRECEIVER, FEEPAYER_EACHRECEIVER, and
FEEPAYER_SECONDARYONLY. The default value is FEEPAYER_EACHRECEIVER.
@property (nonatomic, assign) PayPalFeePayer feePayer;
dynamicAmountUpdateEnabled Property

Setting this property to TRUE lets you recalculate the payment amount, tax, currency, and
shipping values based on the shipping address chosen by a buyer. If you call this method before
the checkout starts, the library calls the delegate's
adjustAmountsForAddress:andCurrency:andAmount:andTax:andShipping: or
adjustAmountsAdvancedForAddress:andCurrency:andReceiverAmounts: method,

depending on the payment checkout method. The library passes the buyer’s address as a
PayPalAddress object. Implement the delegate method in the PayPalPaymentDelegate
protocol, and return the adjusted amount object(s) that contain the updated payment amount,
currency, tax, and shipping.
NOTE:

If shipping is not enabled, this property is ignored.

@property (nonatomic, assign) BOOL dynamicAmountUpdateEnabled;

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

There are two delegate functions, one for Simple Payments and one for Advanced Payments:
-(PayPalAmounts *)adjustAmountsForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andAmount:(NSDecimalNumber const *)inAmount andTax:(NSDecimalNumber
const *)inTax andShipping:(NSDecimalNumber const *)inShipping
andErrorCode:(PayPalAmountErrorCode *)outErrorCode;
-(NSMutableArray *)adjustAmountsAdvancedForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andReceiverAmounts:(NSMutableArray *)recieverAmounts
andErrorCode:(PayPalAmountErrorCode *)outErrorCode;
NOTE: If an error occurs during dynamic amount calculation, you can notify the library using the
outErrorCode parameter of either of the above delegate methods to report the error to the
library. You would do this using code similar to the following:

*outErrorCode = AMOUNT_ERROR_OTHER;
The possible values for the outErrorCode parameter are as follows:
Parameter Value

Description

AMOUNT_ERROR_NONE

This is the default value for the error parameter, and indicates that no
error occurred.

AMOUNT_ERROR_SERVER

If you set outErrorCode to this value, the library displays a fatal
error indicating that a network error occurred and allows the buyer to
return to your app.

AMOUNT_ERROR_OTHER

If you set outErrorCode to this value, the library displays a fatal
error with a generic error message and allows the buyer to return to
your app.

Delegate Methods in the Mobile Payments Library
NOTE: Due to an issue with buyers choosing to exit the application as soon as they saw the
Success screen, the PayPalPaymentDelegate (formerly PayPalMEPDelegate) protocol has
been updated.

paymentSuccess Method

This method is called as soon as the library completes a payment or preapproval. The payKey is
a unique identifier for the payment, while paymentStatus is an enumerated type which can be
STATUS_COMPLETED, STATUS_CREATED, or STATUS_OTHER. The merchant app should store
the fact that the payment succeeded (for later display) and perform any desired bookkeeping at
this point, such as tracking the payment on a merchant-controlled server, but should not perform
any user interface updates. If the transaction is a preapproval, the preapproval key is returned in
place of the payKey.
-(void)paymentSuccessWithKey:(NSString *)payKey
andStatus:(PayPalPaymentStatus)paymentStatus;

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

paymentCanceled Method

This method is called as soon as the buyer cancels the payment for any reason. The merchant app
should store the fact that the payment was canceled (for later display), but should not perform any
user interface updates.
-(void)paymentCanceled;
paymentFailed Method

This method is called as soon as the library fails to complete a payment for any reason. The
correlationID is a code used for tracking the transaction on the server (useful when seeking
assistance from PayPal), the error code is a numerical (or in some cases non-numerical) error
identifier, and the errorMessage is a human-readable error string. The merchant app should
store the fact that the payment failed (for later display), but should not perform any user interface
updates.
-(void)paymentFailedWithCorrelationID:(NSString *)correlationID
andErrorCode:(NSString *)errorCode
andErrorMessage:(NSString*)errorMessage;
paymentLibraryExit Method

This method is called when the library is finished with the device display and is returning control
to the merchant app. The merchant app should handle displaying the payment status
(success/failed/canceled) to the buyer at this point.
-(void)paymentLibraryExit;

After the Payment
After the payment is completed, the Mobile Payments Library returns the payKey. Also, a
number of other features are available to you to assist you with the payment: Instant Payment
Notification, Transaction Details, and Refunds.
Instant Payment Notification

Instant Payment Notification (IPN) is PayPal’s message service that sends a notification when a
transaction is affected. You can integrate IPN with your systems to automate and manage your
back office. More details and documentation are available at: www.paypal.com/ipn. This is
triggered when the payment is completed, even if the consumer closes or quits your application.
You can specify the IPN URL in the payment object of the checkout method.
Transaction Details

You can integrate with the PayPal PaymentDetails API to retrieve details on a payment based
on the payKey. More details and documentation are available at:
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_AdaptivePayments.pdf
Refunds

Refunds can be supported by manual refund using the PayPal account interface or by means of
the RefundTransaction API. AdaptivePayments Refund API call is not supported for MPL-

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

generated pay keys. More details and documentation are available at:
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_AdaptivePayments.pdf

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Simple, Parallel, and Chained Payments
Simple payments have a single recipient. Parallel and chained payments have multiple recipients
and differ in the how the payments are split.
Simple Payments
Simple payments use the PayPalPayment object, which supports a payment to a single
recipient.

Parallel Payments
Parallel payments allow you to make payments for any amount to 2 to 6 recipients. You create a
parallel payment by making a payment with multiple recipients that has no primary recipient.
From the buyer’s standpoint, a parallel payment affects the UI by showing the details for each
recipient. Unlike chain payments, the recipients of a parallel payment are not linked together in
terms of amount.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Chained Payments
A chained payment is a payment from a sender that is indirectly parallel among multiple
receivers. It is an extension of a typical payment from a sender to a receiver; however, a receiver,
known as the primary receiver, passes part of the payment to other receivers, who are called
secondary receivers.
NOTE: Chained payments require a specific permission level on the part of the API caller and
merchant. For information, refer to the section “Adaptive Payments Permission Levels” in the
Adaptive Payments Developer Guide.

You can have at most one primary receiver and from 1 to 5 secondary receivers. Chained
payments are useful in cases when the primary receiver acts as an agent for other receivers. The
sender deals only with the primary receiver and does not know about the secondary receivers,
including how a payment is parallel among receivers. The following example shows a sender
making a payment of $100:

In this example, the primary receiver receives $100 from the sender’s perspective; however, the
primary receiver actually receives only $10 and passes a total of $90 to secondary receivers
Receiver 2 and Receiver 3.
NOTE: The scenario above is an example only and does not take PayPal fees into account.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Preapprovals
The PayPal Mobile Payments Library lets you obtain authorization in advance from buyers for
future payments to you without requiring buyers to authorize each payment individually. For
example, you might use the library to establish preapproval agreements for subscriptions to
mobile content, such as mobile streaming audio or video. Or, you might use the library to
establish preapproval agreements for payments to gain access to higher levels of difficulty in
mobile games.
How Preapprovals Work
There are three steps to setting up and using preapprovals.
1. Obtain a pending preapproval key from PayPal.
From your web server, send a Preapproval request to PayPal with the terms of your
preapproval agreement.
2. Obtain authorization from the buyer for the preapproval agreement.
From your mobile application, call the preapprovalWithKey method with the pending
preapproval key. The library launches the preapproval checkout experience and returns a
confirmed preapproval key.
3. Take payments from the buyer under the terms of the preapproval agreement.
From your web server, send a Pay request to PayPal with the buyer’s confirmed
preapproval key.
For more information about the Preapproval and Pay requests, see the Adaptive Payments
Developer Guide.
About Preapproval Keys
Preapproval keys uniquely identify preapproval your agreements. Preapproval keys that you
obtain by using the Preapproval API identify your pending preapproval agreements. No buyers
have yet agreed to them. Pending approval keys remain valid for 3 hours before expiring without
confirmation from buyers.
Call the preapprovalWithKey method to launch the preapproval checkout experience to
confirm a buyer’s agreement to a pending preapproval. If the buyer completes the preapproval
checkout, the library returns a confirmed preapproval key. Maintain a record of buyers and their
confirmed preapproval keys on your web server. Later on your web server, take payments from
buyers by sending Pay requests with buyers’ preapproval keys to PayPal.
About Preapproval Pins
Confirmed preapproval keys let you take payments from buyers without requiring them to log in
to PayPal to authorize payments individually. Depending on your business model, you may want
to obtain consent quickly from buyers before you take individual payments. Preapproval PINs are

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

special codes that buyers enter to authorize preapproved payments individually without logging in
to PayPal.
For example, you might have a mobile game that requires payment from buyers to enter a higher
level of difficulty. You could take the payment, without notice, when the buyer enters the higher
level. However, the buyer might dispute the payment later, despite the preapproval agreement and
the automatic payment notice from PayPal. Obtain a buyer’s consent before you take the entrance
fee to help improve the buying experience.
Specify that you want your preapprovals to use preapproval PINs when you send Preapproval
requests from your web server to PayPal. Set the PreapprovalRequest.pinType to
REQUIRED. PayPal returns preapproval keys that require buyers to create preapproval PINs
during preapproval checkout.
Later, when you take payments by using a buyer’s confirmed preapproval key, prompt the buyer
for the preapproval PIN. Pass the buyer’s PIN to PayPal when you send the Pay request from
your web server. PayPal recommends that you display the payment reason and payment amount
when you prompt buyers for their preapproval PINs.
Method Signature for Preapproval Checkout
- (void)preapprovalWithKey:(NSString *)preapprovalKey
andMerchantName:(NSString *)merchantName;
NOTE: See

“Delegate Methods in the Mobile Payments Library” for callback method details.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Method Sequence for Preapproval Checkout

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Custom Objects in the Mobile Payments Library
The Mobile Payments Library includes custom objects for passing information between the
library and your application during checkout.
PayPalAddress

This object is passed to the PayPalPaymentDelegate in the AdjustAmounts method. Use
this address to update the payment amount, tax, currency, and shipping values of the payment.
Then, the buyer continues to check out with the new amounts. Use this object if you enable
dynamic amount calculation by calling the DynamicAmountUpdate method.
Property

Description

name

The name of the address.

street1

First line of the street address.

street2

Second line of the street address.

city

Name of the city.

state

Name of the state or province.

postalcode

U.S. ZIP code or other country-specific postal code.

countrycode

The 2-character country code.

country

The name of the country.

PayPalAmounts

This object is returned to the library by the AdjustAmounts method of the
PayPalPaymentDelegate. This object contains the values for the updated payment. Use this
object if you enable dynamic amount calculation by calling the DynamicAmountUpdate
method.
Property

Description

currency

Currency code of the amount. Defaults to @”USD”.

payment_amount

NSDecimalNumber * amount of the payment before tax or
shipping.

tax

NSDecimalNumber * tax amount associated with the item. If no
tax amount, can be nil.

shipping

NSDecimalNumber * shipping amount for the item. If no
shipping amount, can be nil.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

PayPalPayment

This object is passed to the library in the Checkout method. This object contains all the values
for a payment.
Property

Description

subTotal

(Required) NSDecimalNumber* the amount of the payment
(subtotal).

paymentType

(Optional) Purpose of payment. Defaults to TYPE_NOT_SET.

paymentSubType

(Optional) Subtype of the “TYPE_SERVICE” paymentType.
Applicable only if you have been approved for special pricing plans.
Defaults to SUBTYPE_NOT_SET.

recipient

(Required) The email address or phone number of the payment’s
recipient. When specifying a number, include the country code; for
example, “+14029352050”.
Character length and limits: 255 characters.

paymentCurrency

(Optional) Currency code for the payment. Defaults to @”USD”. Can
be nil.

invoiceData

(Optional) PayPalInvoiceData* that contains information
regarding shipping, tax, and a breakdown of the items in the payment.

description

(Optional) Payment note.

customId

(Optional) Merchant's custom ID.

merchantName

(Optional) Displayed at the top of the library screen. If left nil, it
displays as blank.

ipnUrl

(Optional) The URL to be used for instant payment notification.

memo

(Optional)

NOTE:

The recipient should be a registered user on an existing PayPal Sandbox or Live account,
depending on the environment. The recipient does not need to be registered for personal
payments.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

PayPalAdvancedPayment

This object is passed to the library in the AdvancedCheckout method. This object contains all
the values for an advanced payment which can be used to create a parallel or chained payment
(see discussion in “Refunds can be supported by manual refund using the PayPal account
interface or by means of the RefundTransaction API. AdaptivePayments Refund API call is not
supported for MPL-generated pay keys. More details and documentation are available at:
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_AdaptivePayments.pdf

Simple, Parallel, and Chained Payments” section).
Property

Description

receiverPaymentDeta
ils

(Required) An NSMutableArray * containing all of the
PPReceiverPaymentDetails objects that define a payment to a
single recipient of an advanced payment. For more information, please
see the discussion on PPReceiverPaymentDetails below.

paymentCurrency

(Optional) Currency code for the payment. Defaults to @”USD”. Can
be nil.

ipnUrl

(Optional) The URL to be used for instant payment notification.

memo

(Optional)

PPReceiverPaymentDetails

This object is used in the PayPalAdvancedPayment object to specify the details of a single
receiver.
Property

Description

recipient

(Required) The email address or phone number of the payment’s
recipient.
Character length and limits: 255 characters.

subtotal

(Required) NSDecimalNumber* the amount of the payment

isPrimary

(Optional) BOOL specifying whether this receiver is the primary
receiver of a multiple recipient payment. There can be only one
primary receiver per PayPalAdvancedPayment. If there is a
primary receiver, the payment is treated as a Chain Payment; otherwise,
it is treated as a Parallel Payment.

paymentType

(Optional) The payment type of the payment (see “Enumerated Values
in the Mobile Payments Library”). Allowable values are:
• TYPE_SERVICE
• TYPE_GOODS
• TYPE_PERSONAL
• TYPE_NOT_SET

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Property

Description

paymentSubType

(Optional) The payment subtype for a “SERVICES” type payment (see
“Enumerated Values in the Mobile Payments Library”). Applicable
only if you have been approved for special pricing plans. For any
paymentType other than TYPE_SERVICE or if you have not been
approved for special pricing plans, use SUBTYPE_NOT_SET as the
paymentSubType. Allowable values are:
• SUBTYPE_NOT_SET

•

SUBTYPE_AFFILIATE_PAYMENTS

•

SUBTYPE_B2B

•

SUBTYPE_PAYROLL

•

SUBTYPE_REBATES

•

SUBTYPE_REFUNDS

•

SUBTYPE_REIMBURSEMENTS

•

SUBTYPE_DONATIONS

•

SUBTYPE_UTILITIES

•

SUBTYPE_TUITION

•

SUBTYPE_GOVERNMENT

•

SUBTYPE_INSURANCE

•

SUBTYPE_REMITTANCES

•

SUBTYPE_RENT

•

SUBTYPE_MORTGAGE

•

SUBTYPE_MEDICAL

•

SUBTYPE_CHILD_CARE

•

SUBTYPE_EVENT_PLANNING

•

SUBTYPE_GENERAL_CONTRACTORS

•

SUBTYPE_ENTERTAINMENT

•

SUBTYPE_TOURISM

•

SUBTYPE_INVOICE

•

SUBTYPE_TRANSFER

invoiceData

(Optional) PayPalInvoiceData* that contains information
regarding shipping, tax, and a breakdown of the items in the payment.

description

(Optional) Payment note.

customId

(Optional) Merchant's custom ID.

merchantName

(Optional) This is used to identify the recipient of the payment to the
buyer. For simple and chained payments, this is displayed above the
checkout cart. For parallel payments, this is displayed in the shopping
cart. If this is not supplied, the recipient's email or phone number can
be used instead.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

PayPalInvoiceData

This object is an optional parameter to a PayPalPayment or a
PPReceiverPaymentDetails object. This object holds data regarding the tax shipping and
a per-item breakdown of the items included in the payment. While this is an optional class, once
it is added to a container, it must be populated with the following required fields.
Property

Description

totalTax

(Required) NSDecimalNumber * The tax amount for the payment.
This summed up with the totalShipping and the containing object's
subtotal to determine the total amount sent to the receiver.

totalShipping

(Required) NSDecimalNumber * The shipping amount for the
payment. This summed up with the totalTax and the containing object's
subtotal to determine the total amount sent to the receiver.

invoiceItems

(Required) An NSMutableArray * of PayPalInvoiceItems
(see discussion on PayPalInvoiceItem below). These items do not affect
the total amount of the payment but must equal the subtotal.

PayPalInvoiceItem

This object is an optional parameter to a PayPalPayment or a
PPReceiverPaymentDetails object. Note that this is required if the
PayPalInvoiceData parameter is used. This object holds data regarding the tax, shipping
and a per-item breakdown of the items included in the payment. While this is an optional class,
once it is added to a container, it must be populated with the following required fields.
NOTE:

The itemPrice and itemCount multiplied together must equal the totalPrice.
The totalPrices of all invoiceItems to a PayPalPayment or a
PPReceiverPaymentDetails object must equal the subtotal of that object.

Property

Description

name

(Required) The name of the item.

itemId

(Optional)

totalPrice

(Required) NSDecimalNumber * specifying the total price of the
item. The total price can differ from (itemPrice * itemCount),
for example, when you are providing a coupon based on volume.

itemPrice

(Required) NSDecimalNumber *specifying the unit price of the
item.

itemCount

(Required) NSNumber * specifying the quantity of this item.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

PayPalReceiverAmounts

This object is used in the dynamic amount calculation for Advanced Payment types. It is always
contained in an array.
Property

Description

amounts

(Required) PayPalAmounts * specifying details about how much
this receiver should receive.

recipient

(Required) The email address or phone number of this recipient.
Character length and limits: 255 characters

Enumerated Values in the Mobile Payments Library
The enumerated values supported by various methods in the library are:
PayPalEnvironment
•

ENV_LIVE: Use the PayPal production servers.

•

ENV_SANDBOX: Use the PayPal testing servers.

•

ENV_NONE: Do not use any PayPal servers. Operate in demonstration mode, instead.
Demonstration mode lets you view various payment flows without requiring production or
test accounts on PayPal servers. Network calls within the library are simulated by using
demonstration data held within the library.

NOTE:

ENV_LIVE does not support simulators.

PayPalButtonType
BUTTON_152x33

BUTTON_194x37

BUTTON_278x43

BUTTON_294x43

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

NOTE:

If the buttonTextType parameter is set to 'TEXT_DONATE,’ the word “Pay” in the
above buttons is replaced by “Donate.” The language of the button also changes based on
the language you pass into the setLang method or the auto detected language on the
phone.

PayPalPaymentType
TYPE_NOT_SET
TYPE_GOODS
TYPE_SERVICE
TYPE_PERSONAL
NOTE:

For Personal payment types, the PayPal Checkout experience differs slightly from other
payment types. Additionally for Personal payment types, senders in some cases can
choose who pays any fees: the sender or the recipient. In India and Germany, recipients
always pay any fees.

For more information, see “feePayer Property.”
PayPalPaymentSubType
SUBTYPE_NOT_SET
SUBTYPE_AFFILIATE_PAYMENTS
SUBTYPE_B2B
SUBTYPE_PAYROLL
SUBTYPE_REBATES
SUBTYPE_REFUNDS
SUBTYPE_REIMBURSEMENTS
SUBTYPE_DONATIONS
SUBTYPE_UTILITIES
SUBTYPE_TUITION
SUBTYPE_GOVERNMENT
SUBTYPE_INSURANCE
SUBTYPE_REMITTANCES
SUBTYPE_RENT
SUBTYPE_MORTGAGE
SUBTYPE_MEDICAL
SUBTYPE_CHILD_CARE
SUBTYPE_EVENT_PLANNING
SUBTYPE_GENERAL_CONTRACTORS
SUBTYPE_ENTERTAINMENT
SUBTYPE_TOURISM
SUBTYPE_INVOICE
SUBTYPE_TRANSFER
NOTE:

You should only specify a subtype if directed to do so by the vetting team when applying
for business payments. For Service payment types, the PayPalPaymentSubType is used to
further qualify the payment if you are using special pricing plans.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

PayPalPaymentStatus
STATUS_COMPLETED: The payment has completed on the back end.
STATUS_CREATED: The payment has been created but not completed.
STATUS_OTHER: The payment success state is other than created or completed.
PayPalAmountErrorCode
AMOUNT_ERROR_NONE: No error occurred during dynamic amount calculation.
AMOUNT_ERROR_SERVER: A connectivity or server error occurred during dynamic amount
calculation.
AMOUNT_ERROR_OTHER: A generic error occurred during dynamic amount calculation.
PayPalInitializationStatus
STATUS_NOT_STARTED: Initialization never attempted.
STATUS_COMPLETED_SUCCESS: Initialization completed successfully.
STATUS_COMPLETED_ERROR: Initialization completed with errors. The error is displayed in
the device or simulator logs.
STATUS_INPROGRESS: Initialization in progress. Must wait until the current initialization
attempt completes before attempting to retry initialization.

Localization Support in the Mobile Payments Library
The Mobile Payments Library supports many locales. Set the locale when you initialize the
library. The default is the locale of the device. If the library does not support the device locale,
the library uses en_US, instead.
How to Set the Language and the Region

Set the locale using the lang property. You can set this property any time after you initialize the
library. Set the lang property before you call the getPayButtonWithTarget method so you
obtain a localized Pay with PayPal button.
Locales Supported by the Mobile Payments Library

The library supports the following locale codes:

Country or Region

Supported Locale Codes

Argentina

es_AR

Brazil

pt_BR

Australia

en_AU

Belgium

en_BE nl_BE fr_BE

Canada

en_CA fr_CA

France

fr_FR en_FR

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Country or Region

Supported Locale Codes

Germany

de_DE en_DE

Hong Kong

zh_HK en_HK

India

en_IN

Italy

it_IT

Japan

ja_JP en_JP

Mexico

es_MX en_MX

Netherlands

nl_NL en_NL

Poland

pl_PL en_PL

Singapore

en_SG

Spain

es_ES en_ES

Switzerland

de_CH en_CH fr_CH

Taiwan

zh_TW en_TW

United States

en_US

Library Support for the devices and OS versions.
The Mobile Payments Library fully supports OS 4.0 as well as the Apple iPad. You can compile
the library files into the following configurations:
•
•
•
•

3.0, 3.1.x (iPhone only)
3.2 (iPad only)
3.x (Universal)
4.x

The demo application also fully supports OS 4.0 and the Apple iPad. You can compile the demo
application into the preceding configurations.
The single library file can be used to support armv6 and armv7 architectures for SDK 4.0 and
below. Support is provided only for Xcode 3.2.3 at this time.

Adding the Mobile Payments Library to Your Xcode Project
PayPal provides a package that contains 11 header files:
•
•
•
•
•
•

PayPal.h
PayPalAddress.h
PayPalAdvancedPayment.h
PayPalAmounts.h
PayPalContext.h
PayPalInvoiceData.h

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

•
•
•
•
•

PayPalInvoiceItem.h
PayPalPayment.h
PayPalPreapprovalDetails.h
PayPalReceiverAmounts.h
PPReceiverPaymentDetails.h

Also, the package contains a static library file: libPayPalMEP.a.
1. Open your Xcode project.
2. CONTROL+CLICK your project, and then select Add > Existing Files….
3. Select the .h and .a files, and then click Add.
NOTE:

You need to add only the PayPalAmounts.h, PayPalReceiverAmounts.h and
PayPalAddress.h files if you are using the Dynamic Amount Calculation feature.

Sample Code
The following section provides an example library implementation. The demo application
initializes the library and places the Pay with PayPal button on the screen where buyers review
the order (PaymentViewController.m). The callback is handled in the same class.
Header File
#import
#import "PayPal.h"
@interface PaymentViewController : UIViewController
{
}
-(void)payWithPayPal;
@end

Details:
#import “PayPal.h”

The preceding line imports the library header file.

The preceding line states that this class implements the PayPalPaymentDelegate protocol.
-(void)payWithPayPal;

This preceding line is called by the Pay with PayPal button when a buyer taps it.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Implementation File
The following snippet shows a simplified version of the PaymentViewController and
illustrates the library methods for an advanced parallel payment. For reference, see the demo
application source.
- (void)viewDidLoad {
PayPalPaymentType paymentType = HARD_GOODS;
//Get the PayPal Library button.
//We will be handling the callback,
//so we declare 'self' as the target.
//We want a large button, so we use BUTTON_278x43.
//Our checkout method is 'payWithPayPal',
//and we pass through our payment type.
//We can move the button afterward if desired.
UIButton *button = [[PayPal getInstance]
getPayButtonWithTarget:self andAction:@selector(payWithPayPal)
andButtonType:BUTTON_278x43;
[super viewDidLoad];
}
-(void)payWithPayPal {
//Advanced Payment
PayPal *ppMEP = [PayPal getInstance];
ppMEP.shippingEnabled = forDelivery;
ppMEP.dynamicAmountUpdateEnabled = TRUE;
ppMEP.feePayer = FEEPAYER_EACHRECEIVER;
PayPalAdvancedPayment *payment = [[[PayPalAdvancedPayment alloc]
init] autorelease];
payment.paymentCurrency = @"USD";
payment.paymentType = paymentType;
payment.paymentSubType = paymentSubType;
payment.receiverPaymentDetails = [NSMutableArray array];

NSArray *emails = [NSArray arrayWithObjects:
@"recipient1@email.com",
@"recipient2@email.com",
@"recipient3@email.com",
nil];
for (int i = 0; i < emails.count; i++) {
PPReceiverPaymentDetails *details =
[[[PPReceiverPaymentDetails
alloc] init] autorelease];
String order, tax, shipping;
order = orderAmount[i];

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

tax = taxAmount[i];
shipping = shippingAmount[i];
details.invoiceData = [[[PayPalInvoiceData
alloc] init] autorelease];
details.invoiceData.totalShipping = [NSDecimalNumber
decimalNumberWithString:order];
details.invoiceData.totalTax = [NSDecimalNumber
decimalNumberWithString:tax];
details.invoiceData.totalShipping = [NSDecimalNumber
decimalNumberWithString:shipping];
details.description = description;
details.recipient = [emails objectAtIndex:i];
details.merchantName = [NSString
stringWithFormat:@"Recipient %d",i+1];
[payment.receiverPaymentDetails addObject:details];
}
[ppMEP advancedCheckoutWithPayment:payment]; }

Placing the Pay with PayPal Button
UIButton *button = [[PayPal getInstance] getPayButtonWithTarget:self
andAction:@selector(payWithPayPal) andButtonType:BUTTON_278x43
andButtonText:BUTTON_TEXT_PAY];
[self.view addSubview:button];
[super viewDidLoad];

The getPayButtonWithTarget method returns the Pay with PayPal button. Then, you can
add the button to your UIViewController. The demo application payWithPayPal method is
passed through so the Pay with PayPal button can call it on touchUpInside. For this example
payment, the payment type is Hard Goods. Set the left and top position of the button by
specifying those parameters.
The getPayButtonWithTarget method follows standard memory management conventions
and is autoreleased.
For a list of button image types, see PayPalButtonType.
Creating the PayPalPayment Object
PayPalPayment *currentPayment = [[[PayPalPayment alloc] init]
autorelease];
currentPayment.paymentCurrency = @”USD”;
currentPayment.paymentType = TYPE_GOODS;
currentPayment.subTotal = [NSDecimalNumber
decimalNumberWithString: @”10.00”];
currentPayment.recipient = @”recipient@paypal.com”;
currentPayment.merchantName = @“Recipient Name”;

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

currentPayment.invoiceData = [[[PayPalInvoiceData
alloc] init] autorelease];
currentPayment.invoiceData.totalTax = [NSDecimalNumber
decimalNumberWithString: @”1.00”];
currentPayment.invoiceData.totalShipping = [NSDecimalNumber
decimalNumberWithString: @”2.00”];

The PayPalPayment object is created and the properties are set.
After the checkout method is called, the library releases the currentPayment object.
Checking Out
[ppMEP checkoutWithPayment:currentPayment];

The payment object is passed through to the library. The library displays itself on top of the
application’s Window object, so be sure that you do not take control of the Window after the
checkout call is invoked.
Handling the Callback
-(void)paymentSuccessWithKey:(NSString *)payKey
andStatus:(PayPalPaymentStatus)paymentStatus;

This method is called as soon as the library completes a payment or preapproval. You could use
this message to trigger your own background bookkeeping. This message occurs while the library
is still using the device display, so your application should wait to do any user interface actions
until it receives the paymentLibraryExit message.
-(void)paymentCanceled

This method is called as soon as the buyer cancels the transaction. As with the
paymentSuccess callback, your application should perform no user interface updates until it
receives the paymentLibraryExit message.
-(void)paymentFailedWithCorrelationID:(NSString *)correlationID
errorCode:(NSString *)errorCode errorMessage:(NSString
*)errorMessage;

This method is called immediately upon failure of the payment, and you could do background
bookkeeping at this point. However, you should wait until you receive the
paymentLibraryExit method before doing any user interface updates.
-(void)paymentLibraryExit;

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Dynamic Amount Calculation
This method is called by the library when buyers choose a shipping address. The demo
application calculates the tax based on the state of the shipping address, and then it passes the
updated amounts to the library.
Your method must be implemented as shown:
-(PayPalAmounts *)adjustAmountsForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andAmount:(NSDecimalNumber const *)inAmount andTax:(NSDecimalNumber
const *)inTax andShipping:(NSDecimalNumber const *)inShipping
andErrorCode:(PayPalAmountErrorCode *)outErrorCode;
-(NSMutableArray *)adjustAmountsAdvancedForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andReceiverAmounts:(NSMutableArray *)recieverAmounts
andErrorCode:(PayPalAmountErrorCode *)outErrorCode;

The demo application implements this method like this:
- (PayPalAmounts *)adjustAmountsForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andAmount:(NSDecimalNumber const *)inAmount
andTax:(NSDecimalNumber const *)inTax
andShipping:(NSDecimalNumber const *)inShipping
andErrorCode:(PayPalAmountErrorCode *)outErrorCode {
//do any logic here that would adjust the amount based on the shipping
address
PayPalAmounts *newAmounts = [[[PayPalAmounts alloc] init]
autorelease];
newAmounts.currency = @"USD";
newAmounts.payment_amount = (NSDecimalNumber *)inAmount;
//change tax based on the address
if ([inAddress.state isEqualToString:@"CA"]) {
newAmounts.tax = [NSDecimalNumber
decimalNumberWithString:[NSString
stringWithFormat:@"%.2f",[inAmount floatValue] * .1]];
} else {
newAmounts.tax = [NSDecimalNumber
decimalNumberWithString:[NSString
stringWithFormat:@"%.2f",[inAmount floatValue] * .08]];
}
newAmounts.shipping = (NSDecimalNumber *)inShipping;
//if you need to notify the library of an error condition, do one of
the following
//*outErrorCode = AMOUNT_ERROR_SERVER;
//*outErrorCode = AMOUNT_ERROR_OTHER;
return newAmounts;
}

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

- (NSMutableArray *)adjustAmountsAdvancedForAddress:(PayPalAddress const
*)inAddress andCurrency:(NSString const *)inCurrency
andReceiverAmounts:(NSMutableArray *)receiverAmounts
andErrorCode:(PayPalAmountErrorCode *)outErrorCode {
NSMutableArray *returnArray = [NSMutableArray
arrayWithCapacity:[receiverAmounts count]];
for (PayPalReceiverAmounts *amounts in receiverAmounts) {
//leave the shipping the same, change the tax based on the
state
if ([inAddress.state isEqualToString:@"CA"]) {
amounts.amounts.tax = [NSDecimalNumber
decimalNumberWithString:[NSString
stringWithFormat:@"%.2f",[amounts.amounts.payment_amount floatValue] *
.1]];
} else {
amounts.amounts.tax = [NSDecimalNumber
decimalNumberWithString:[NSString
stringWithFormat:@"%.2f",[amounts.amounts.payment_amount floatValue] *
.08]];
}
[returnArray addObject:amounts];
}
//if you need to notify the library of an error condition, do one of
the
following
//*outErrorCode = AMOUNT_ERROR_SERVER;
//*outErrorCode = AMOUNT_ERROR_OTHER;
return returnArray;
}

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

2. The Checkout Experience with the
Mobile Payments Library
The following screen shots illustrate several different PayPal Checkout experiences that occur
after buyers click the PayPal button that your application obtains from the library by using the
getPayPalButton()method.
NOTE: The checkout experience is in Portrait orientation only. Landscape orientation is currently
not supported.

Checkout Experience #1 – Goods or Services with Shipping
Payment type = Hard Goods or Services / Shipping = enabled

In the preceding experience, buyers enter their PayPal login credentials in the Log In To PayPal
screen. Then, they can review details of the payment in the second screen and change funding
source or shipping address. If satisfied, buyers click Pay to complete the payment.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Checkout Experience #2 – Goods or Services without Shipping
Payment type = Hard Goods or Services / Shipping = disabled

In this case, shipping is not required (such as, manual pick up of goods or services). Shipping is
disabled by a call to the disableShipping library method. Buyers enter their PayPal login
credentials and directly pay by clicking Pay on the first screen. Buyers can review funding
choices by clicking Review on the same page.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Checkout Experience #3 – Donations
Payment type = Service / Button text = Donations / Shipping = enabled

In the preceding experience, buyers make a donation to a charity or other cause. In this context,
the charity or cause wants to leverage PayPal members’ addresses as mailing addresses for
donation receipts. By enabling shipping in the library, buyers are presented with their primary
mailing address, or they can choose another mailing address from the ones in their PayPal
accounts.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Checkout Experience #4 – Personal Send Money Payments
Payment type = Personal payments / Shipping = disabled

In the preceding experience, PayPal members make personal payments to other PayPal members.
There are no transaction fees when the transaction is funded by PayPal balance or by a bank
account on file. The transaction carries a fee when it is funded by a credit or debit card. In some
cases, senders choose who pays any fees – sender or recipient. In India and Germany, recipients
always pay any fees.
For more information on PayPal Send Money and pricing, refer to:
https://cms.paypal.com/us/cgi-bin/?cmd=_rendercontent&content_ID=marketing_us/send_money

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Checkout Experience #5 – Create Pin

In the preceding experience, a PayPal member has just completed a payment and does not
currently have a PIN associated with their account. By following the on-screen instructions, the
buyer can associate their account with a phone number and PIN for easier login in the future.
Upon successful creation of the PIN, the buyer is returned to your application triggering the
paymentSuccess() delegate callback.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Checkout Experience #6 – Preapproval
In this experience, you executed the preapproval checkout method, as discussed under
“Preapprovals” on page 18.
Basic Preapproval Checkout
Login Screen

Agree and Pay Screen

During a preapproval checkout, the buyer agrees to the terms of a preapproval agreement. The
agreement authorizes you to take payments without requiring the buyer to log in to PayPal to
authorize the payments individually. After the buyer completes the checkout, PayPal returns the
buyer’s confirmed preapproval key to your mobile application.
Use the buyer’s confirmed preapproval key to take the preapproved payments. The library does
not take the payments for you. After UI control returns to your mobile application, store the
buyer’s preapproval key on you web server. Then, take your first preapproved payment by
sending a Pay request with the buyer’s preapproval key from your web server to PayPal.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Creating Preapproval PINs During Preapproval Checkout
Depending on your business model, you may require buyers to create preapproval PINs during
preapproval checkout. Preapproval PINs are special codes that buyers specify during checkout to
let them consent quickly later to individual payments. If your preapproval agreements require
PINs, PayPal displays the optional Create a code screen during preapproval checkout.
Login Screen

Create a Code Screen

Agree and Pay Screen

After logging in to PayPal, the buyer enters a code that only the buyer and PayPal know. Later,
before you take a preapproved payment, prompt the buyer to enter the preapproval PIN. Then
from your web server, include the PIN that the buyer entered with the Pay request that you send
to PayPal. PayPal recommends that you display the payment reason and payment amount when
you prompt the buyer for the preapproval PIN.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

3. Submitting Your Application to PayPal
Before you submit your application to Apple and distribute your mobile application publicly, you
need an authorized application ID from PayPal. PayPal tests all mobile applications before
issuing application IDs. Test your mobile application thoroughly in the PayPal Sandbox by using
APP-80W284485P519543T as your test application ID. Then, submit your test application to
PayPal.
1. Log in or sign up on PayPal’s developer website, x.com.
2. After logging in successfully, click the My Apps tab.
3. Click SUBMIT NEW APP.
4. Fill in the 2-page “Submit New App” form.
If you need more time, you can save your form as a draft and return later to complete it.
5. Click Submit.

Result:
For those using simple or parallel payments, PayPal reviews your application within 24 hours
and responds by sending you your PayPalApplicationID. Reviewers at PayPal follow up
by email with questions, should they arise, before they approve your mobile application. For
those using chained payments or preapprovals, the review may take longer.
After completing this task:
Wait until PayPal sends you your application ID. Then, make sure that you update your
software with the following changes before you submit your mobile application to Apple:
•
•
•

Application ID: in your calls to initWithApplicationId
Environment: in your calls to initWithApplicationId
Recipient: in the PayPalPayment object

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

A. Currencies Supported by PayPal
PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.
Currency

Currency Code

Australian Dollar
Brazilian Real

AUD

BRL

NOTE: This currency is supported as a payment currency

and a currency balance for in-country PayPal
accounts only.
CAD

Canadian Dollar
Czech Koruna
Danish Krone
Euro
Hong Kong Dollar
Hungarian Forint
Israeli New Shekel
Japanese Yen
Malaysian Ringgit

CZK
DKK
EUR
HKD
HUF
ILS
JPY
MYR

NOTE: This currency is supported as a payment currency

and a currency balance for in-country PayPal
accounts only.
Mexican Peso
Norwegian Krone
New Zealand Dollar
Philippine Peso
Polish Zloty
Pound Sterling
Singapore Dollar
Swedish Krona
Swiss Franc
Taiwan New Dollar
Thai Baht
U.S. Dollar

August 2012

MXN
NOK
NZD
PHP
PLN
GBP
SGD
SEK
CHF
TWD
THB
USD

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

B. Countries and Regions Supported by
PayPal
PayPal uses 2-character IS0-3166-1 codes for specifying countries and regions that are supported
in fields and variables.
Country or Region

Code

Country or Region

Code

Aghanistan
Åland Islands
Albania
Algeria
American Samoa
Andorra
Angola
Anguilla
Antarctica
Antigua and Barbuda
Argentina
Armenia
Aruba
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgiium
Belize
Benin
Bermuda
Bhutan
Bolivia
Bosnia and Herzegovina
Botswana
Bouvet Island
Brazil
Britiish Indian Ocean
Territory
Brunei Darussalam

Bulgaria
Burkina Faso
Burundi
Cambodia
Cameroon
Canada
Cape Verde
Caymen Islands
Central African Republic
Chad
Chile
China
Christmas Island
Cocos (Keeling) Islands
Columbia
Comoros
Congo
Congo, The Democratic
Republic of
Cook Islands
Costa Rica
Côte d’Ivoire
Croatia
Cuba
Cyprus
Czech Republic
Denmark
Djibouti
Dominica
Dominican Republic
Ecuador
Egypt
El Salvador
Eqautorial Guinea

AX
AL
DZ
AS
AD
AO
AI
AQ
AG
AR
AM
AW
AU
AT
AZ
BS
BH
BD
BB
BY
BE
BZ
BJ
BM
BT
BO
BA
BW
BV
BR
IO
BN

Mobile Payments Library Developer Guide and Reference –iOS Edition

BF
BI
KH
CM
CA
CV
KY
CF
TD
CL
CN
CX
CC
CO
KM
CG
CD
CK
CR
CI
HR
CU
CY
CZ
DK
DJ
DM
DO
EC
EG
SV
GQ

August 2012

Country or Region

Code

Country or Region

Code

Eritrea
Estonia
Ethiopia
Falkland Islands
(Malvinas)
Faroe Islands
Fiji
Finland
France
French Guiana
French Polynesia
French Southern
Territories
Gabon
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Grenada
Guadeloupe
Guam
Guatemala
Guernsey
Guinea
Guinea-Bissau
Guyana
Haiti
Heard Island and
McDonald Islands
Holy See (Vatican City
State)
Honduras
Hong Kong
Hungary
Iceland
India
Indonesia
Iran, Islamic Republic of
Iraq
Ireland

Isle of Man
Israel
Italy
Jamaica
Japan
Jersey
Jordan
Kazakhstan
Kenya
Kiribati
Korea, Democratic
People’s Republic of
Korea, Republic
Kuwait
Kyrgyzstan
Lao People’s Democratic
Republic
Latvia
Lebanon
Lesotho
Liberia
Libyan Arabjamahiriya
Liechtenstein
Lithuania
Luxembourg
Macao
Macedonia, The Former
Yugoslav Republic of
Madagascar
Malawi
Malaysia
Maldives
Mali
Malta
Marshall Islands
Martinique
Mauratania
Mauritius
Mayotte
Mexico
Micronesia, Federated
States of
Moldova, Republic of

August 2012

EE
ET
FK
FO
FJ
FI
FR
GF
PF
TF
GA
GM
GE
DE
GH
GI
GR
GL
GD
GP
GU
GT
GG
GN
GW
GY
HT
HM
VA
HN
HK
HU
IS
IN
ID
IR
IQ
IE

IL
IT
JM
JP
JE
JO
KZ
KE
KI
KP
KR
KW
KG
LA
LV
LB
LS
LR
LY
LI
LT
LU
MO
MK
MG
MW
MY
MV
ML
MT
MH
MQ
MR
MU
YT
MX
FM
MD

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Country or Region

Code

Country or Region

Monaco
Mongolia
Monstserrat
Morocco
Mozambique
Myanmar
Namibia
Nauru
Nepal
Netherlands
Netherlands Antilles
New Caledonia
New Zealand
Nicaragua
Niger
Nigeria
Niue
Norfolk Island
Northern Mariana Islands
Norway
Oman
Pakistan
Palau
Palestinian Territory,
Occupied
Panama
Papua New Guinea
Paraguay
Peru
Philippines
Pitcairn
Poland
Portugal
Puerto Rico
Qatar
Reunion
Romania
Russian Federation
Rwanda
Saint Helena
Saint Kitts and Nevis
Saint Lucia

Saint Pierre and Miquelon PM
VC
Saint Vincent and the
Grenadines
WS
Samoa
SM
San Marino
Sao Tome and Principe ST
SA
Saudi Arabia
SN
Senegal
Serbia and Montenegro CS
SC
Seychelles
SL
Sierra Leone
SG
Singapore
SK
Slovakia
SI
Slovenia
SB
Solomon Islands
SO
Somalia
ZA
South Africa
GS
South Georgia and the
South Sandwich Islands
ES
Spain
LK
Sri Lanka
SD
Sudan
SR
Suriname
Svalbard and Jan Mayen SJ
SZ
Swaziland
SE
Sweden
CH
Switzerland
SY
Syrian Arab Republic
Taiwan, Province of ChinaTW
TJ
Tajikistan
Tanzania, United Republic TZ
of
TH
Thailand
TL
Timor-Leste
TG
Togo
TK
Tokelau
TO
Tonga
TT
Trinidad and Tobago
TN
Tunisia
TR
Turkey
TM
Turkmenistan
Turks and Caicos Islands TC
TV
Tuvala

MN
MS
MA
MZ
MM
NA
NR
NP
NL
AN
NC
NZ
NI
NE
NG
NU
NF
MP
NO
OM
PK
PW
PS
PA
PG
PY
PE
PH
PN
PL
PT
PR
QA
RE
RO
RU
RW
SH
KN
LC

Mobile Payments Library Developer Guide and Reference –iOS Edition

Code

August 2012

Country or Region

Code

Country or Region

Code

Uganda
Ukraine
United Arab Emirates
United Kingdom
United States
United States Minor
Outlying Islands
Ururguay
Uzbekistan
Vanuatu

Venezuela
Viet Nam
Virgin Islands, British
Virgin Islands, U.S.
Wallis and Futuna
Western Sahara
Yemen
Zambia
Zimbabwe

August 2012

UA
AE
GB
US
UM
UY
UZ

VN
VG
VI
WF
EH
YE
ZM
ZW

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

C. Creating an Ad Hoc Build
The Ad Hoc distribution method for iPhone apps allows for distribution of the build to internal or
external sources. PayPal provides the Device ID values for PayPal’s devices. In the process below, you
add PayPal’s devices to your Ad Hoc Provisioning Profile. You then compile the build, sign it with
your Ad Hoc Provisioning Profile, and deliver the zipped build and the Ad Hoc Provisioning Profile to
PayPal.

Creating a Distribution Certificate
Distribution Certificates are paired with private keys linked to computers. A Distribution Certificate is
one component of the Distribution Provisioning Profile that you use to sign the build in Xcode.
Creating and Approving a Certificate Signing Request
To request an iPhone Development Certificate, generate a Certificate Signing Request (CSR) utilizing
the Keychain Access application in Mac OS X Leopard. When you create a CSR, Keychain Access
generates your public and private key pair to establish your iPhone Developer identity. Your private key
is stored in the login Keychain by default, and you can view it in the Keychain Access application
under the Keys category.
1. In your Applications folder, open the Utilities folder and launch Keychain Access.
2. In the Preferences menu, set Online Certificate Status Protocol (OSCP) and Certificate
Revocation List (CRL) to Off.
3. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate
Authority.

NOTE:

If you highlight a non-compliant private key in the Keychain during this process, the
Program Portal does not accept the resulting Certificate Request. Confirm that you are
selecting Request a Certificate From a Certificate Authority… and not selecting Request
a Certificate From a Certificate Authority with ….

4. In the User Email Address field, enter your email address.
Ensure that the email address entered matches the information that you submitted when you
registered as an iPhone Developer.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

5. In the Common Name field enter your name.
Ensure that the name entered matches the information that you submitted when you registered as an
iPhone Developer. No CA (Certificate Authority) Email Address is required. The ‘Required’
message is removed after you complete the following step.
6. Select the Saved to Disk radio button and if prompted, select Let me specify key pair information
and click Continue.
7. If you selected Let me specify key pair, specify a file name and click Save.
8. In the screen that follows, select 2048 bits for the Key Size and RSA for the Algorithm. Then,
click Continue.
9. The Certificate Assistant creates a CSR file on your desktop.
IMPORTANT: Export the private key immediately and share it with all developers who need to compile
and sign builds for distribution. For more details, see “Saving the Private Key and
Transferring It to Other Systems” on page 56.
Creating a Distribution Certificate
After creating the Certificate Signing Request (CSR), you can create a Distribution Certificate.
1. Log in to the iPhone Developer Program Portal and navigate to Certificates > Distribution and
click Add Certificate.
2. Click Upload file, select your CSR and click Submit.
If the Key Size was not set to 2048 bits during the CSR creation process, the Portal rejects the CSR.
3. Click Approve to approve your iPhone Distribution Certificate.
4. In the Certificates > Distribution section of the Portal, CONTROL+CLICK the WWDR
Intermediate Certificate link and select Saved Linked File to Downloads to initiate download of
the certificate.
5. After downloading, double-click the certificate to launch Keychain Access and install.
6. In the same area of the Program Portal, click the name of the iPhone Distribution Certificate to
download.
7. On your local machine, double-click the downloaded .cer file to launch Keychain Access and
install your certificate.

Adding Device IDs
The Devices section of the iPhone Developer Program Portal lets you enter the Apple devices that you
use for iPhone OS development. To install your iPhone OS application on an Apple device, enter the
Unique Device Identifier (UDID) for each iPhone, iPod touch, and iPad in the Program Portal. A UDID
is a 40-character string that is tied to a single device. UDIDs are similar to hardware serial numbers.
These UDIDs are included in the provisioning profiles that you create later. Enter a maximum of 100
devices for your development team.
You need to add your devices, as well as PayPal’s devices. You receive UDID values for PayPal’s
devices from PayPal.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Locating your Device ID
1. Connect your device to your Mac and open Xcode.
2. In Xcode, navigate to the Window drop-down menu and select Organizer.

The 40 hex character string in the Identifier field is your device’s UDID.
Adding Devices to the iPhone Developer Program Portal
1. Navigate to the Devices section of the Program Portal and click Add Device.
2. Enter a descriptive name for the device, as well as the UDID, and then click Submit.
Using Updated Provisioning Profiles for New Devices
If any new devices must be supported, add them to the Program Portal using the above steps. Then edit
the provisioning profile and select the new devices for support.
Import the updated provisioning file into Xcode and use them to sign new builds. The old provisioning
profile does not work for builds signed with the updated profile, so you must distribute the new profile
to all Ad Hoc users who use the new build, not only to users of newly-added devices.

Creating the App ID
An App ID is a unique identifier that iPhone OS uses to allow your application to connect to the Apple
Push Notification service, to share keychain data between applications, and to communicate with
external hardware accessories that you want paired with your iPhone OS application. To install your
application on an iPhone OS device, you must create an App ID.
Each App ID consists of a universally unique 10-character “Bundle Seed ID” prefix generated by Apple
and a “Bundle Identifier” suffix that is entered by a Team Admin in the Program Portal. PayPal
recommends the use of a reverse-domain-name-style string for the “Bundle Identifier” portion of the
App ID. An example App ID is:
8E549T7128.com.apple.AddressBook

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

1. Navigate to the App ID section of the Program Portal.
2. Click Add ID.

3. Enter a common name for your App ID.
This is a name for easy reference and identification within the Program Portal.
4. Enter a Bundle Identifier in the free-form text field.
PayPal recommends a reverse-domain-name-style string, such as
com.domainname.applicationname. For application suites that share the same Keychain
access, use a wild-card character in the Bundle Identifier, such as com.domainname.* or *. Your
Bundle Identifier must match the CF Bundle Identifier that you use for your application in Xcode.
5. Click Submit.
The 10-character Bundle Seed ID is generated and concatenated with the Bundle Identifier that you
entered. The resulting string is your App ID.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Creating a Distribution Provisioning Profile
To successfully build your application in Xcode for Ad Hoc distribution, you must create and download
an Ad Hoc Distribution Provisioning Profile.
1. Navigate to the Provisioning section of the Program Portal.
2. Click the Distribution tab.

3.
4.
5.
6.
7.
8.
9.

Select the Ad Hoc radio button.
Enter the name for your Ad Hoc Distribution Provisioning Profile.
Confirm that your iPhone Distribution Certificate has been created and is displayed.
Select the App ID for the application or application suite that you want to distribute.
Select up to 100 UDIDs on which you want to run your application.
Click Submit.
Download the .mobileprovision file by clicking the name of the Distribution Provisioning
Profile.
10. Install the .mobileprovision file by dragging it onto the Xcode or iTunes icon in the dock.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Creating the Build in Xcode
After the Distribution Provisioning Profile is created, you can compile and sign your application.
1. Open the project in Xcode and duplicate the Release configuration in the Configurations pane of
the Info panel for the project.
2. Rename this new configuration “Distribution”.

3. In the Target Info window, click the Build tab and set the Configuration to Distribution.
4. In the Target Info window, navigate to the Build pane.
5. Click the Any iPhone OS Device pop-up menu below the Code Signing Identity field. Then,
select the iPhone Distribution Certificate/Provisioning Profile pair that you want to use to sign and
install your code. Your iPhone Distribution certificate is in bold, with its associated Provisioning
Profile in grey above it.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

The preceding example shows ‘iPhone Distribution: Example Corp, Inc.’ as the Distribution
Certificate and ‘My App Store Distribution Provisioning Profile’ as its associated
.mobileprovision file.
6. In the Properties Pane of the Target Info window, enter the Bundle Identifier portion of your App
ID. If you used an explicit App ID, enter the Bundle Identifier portion of the App ID in the
Identifier field. For example, enter com.domainname.applicationname if your App ID is
A1B2C3D4E5.com.domainname.applicationname. If you used a wildcard asterisk character in
your App ID, replace the asterisk with any string.
7. In the project window, select the Distribution Active Configuration from the overview popup and
set the Active SDK to the desired Device.
8. In the File Menu, select New File > iPhone OS > Code Signing > Entitlements.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

9. Name the file “Entitlements.plist” and click Finish.
This creates a copy of the default entitlements file within the project.
10. Select the new Entitlments.plist file, uncheck the get-task-allow property, and save the
Entitlements.plist file.
11. Select the Target and open the Build settings inspector.
12. In the Code Signing Entitlements build setting, type the filename of the new
Entitlements.plist file, including the extension.
Do not specify a path unless you put the Entitlements.plist file somewhere other than the top
level of the project.
13. Click Build.
14. Highlight the app located within the Products sub-folder and select Reveal in Finder from the
Action popup.
15. Use the compress option in Finder to create a .zip file that contains your application. Be sure to
compress only the .app file only and not the entire build folder.
16. Provide this .zip file to PayPal, along with the Distribution Provisioning Profile
(.mobileprovision) file. You upload this file to x.com as an attachment when you submit your
application.

Notes
Saving the Private Key and Transferring It to Other Systems
It is critical that you save your private key somewhere for safekeeping in case you need to develop on
multiple computers or you decide to reinstall your system OS. Without your private key, you cannot
sign binaries in Xcode nor test your application on Apple devices.
When a CSR is generated, the Keychain Access application creates a private key on your login
keychain. This private key is tied to your user account and cannot be reproduced if lost. If you plan to
develop and test on multiple systems, you must import your private key to all of the systems on which
you work.
1. Open up the Keychain Access application and select the Keys category.
2. CONTROL+CLICK the private key associated with your iPhone Development Certificate, and then
click Export Items in the menu.
The private key is identified by the iPhone Developer: public
certificate that is paired with it.
3. Save your key in the Personal Information Exchange (.p12) file format.
4. When prompted, create a password to use when you import this key on another computer.
Result:
You can transfer this .p12 file between systems by double-clicking the .p12 file to install it on a
system. When prompted, use the password that you entered in Step 4 above.

August 2012

PayPal Mobile Payments Developer Guide and Reference – iOS Edition

Verifying a Successful Ad Hoc Distribution Build
1. Open the Build Log detail view and confirm the presence of the “embedded.mobileprovision”
file.
This takes you to the line in the build log that shows the provisioning profile was called
successfully. Ensure that the embedded.mobileprovision file is located in the proper
“Distribution” build directory and not a “Debug” or “Release” build directory. Also, make sure the
destination path at the end of the build message is the app that you are building.
2. Search for the term “CodeSign” in the Build Log detail view.
This takes you to the line in the build log that confirms your application was signed by your iPhone
Certificate.
Correcting an Unsuccessful Ad Hoc Distribution Build
Distribution builds can fail if your project is lacking the embedded.mobileprovision file or points
to the wrong directory.
1. Select the Target and open the Build Settings Inspector.
Make sure you are in the Distribution Configuration.
2.
3.
4.
5.
6.

Delete the Code Signing Identity: iPhone Distribution: COMPANYNAME
In the Xcode Build Menu, select Clean all Targets.
Delete any existing build directories in your Xcode project by using the Finder.
Re-launch Xcode and open your Project.
Re-enter the code-signing identity iPhone Distribution: COMPANYNAME in the Target Build
Settings Inspector.
7. Rebuild your project.

Mobile Payments Library Developer Guide and Reference –iOS Edition

August 2012

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : Yes
Author                          : jbillimoria
Create Date                     : 2012:08:02 17:41:37-07:00
Modify Date                     : 2012:08:02 17:41:37-07:00
XMP Toolkit                     : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26
Creator Tool                    : PScript5.dll Version 5.2.2
Format                          : application/pdf
Title                           : Microsoft Word - PP_MPL_Developer_Guide_and_Reference_1-4_iPhone.doc
Creator                         : jbillimoria
Producer                        : Acrobat Distiller 10.1.3 (Windows)
Document ID                     : uuid:662edb2e-15ae-40b6-87f6-7413635e093c
Instance ID                     : uuid:badfc511-9abc-4922-8024-445114a9088f
Page Count                      : 57

EXIF Metadata provided by EXIF.tools

Paypal Mobile Payments Library 2012 Ios Developers Guide PP_MPL_Developer_Guide_and_Reference_1 4_iPhone

Mobile Payments Library - 2012 - Developer Guide and Reference – iOS PP_MPL_DG_iPhone_2012 Free User Guide for PayPal Software, Manual

Navigation menu

Versions of this User Manual:

Views

Navigation