Mobile Payments Library
Developer Guide and
Reference –
Android OS Edition
Last updated: July 2011
PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
Document Number 10116.en_US-201101
© 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
OS and Hardware Support ........................................................................................... 5
Revision History ............................................................................................................ 5
Where to Go for More Information ................................................................................ 7
1. PayPal Mobile Payments Library ............................................................... 8
Mobile Payments Library API Reference ..................................................................... 8
Declaring the Library and Permissions in AndroidManifest.xml ................................... 8
Adding the Library Jar File and Importing Classes....................................................... 9
Required Methods in the Mobile Payments Library ................................................... 10
Optional Methods in the Mobile Payments Library ..................................................... 16
Activity Results for the Mobile Payments Library ....................................................... 16
After the Payment ....................................................................................................... 18
Instant Payment Notification ................................................................................ 18
Transaction Details .............................................................................................. 18
Refunds ................................................................................................................ 18
Simple, Parallel, and Chained Payments ................................................................... 19
Preapprovals............................................................................................................... 21
How Preapprovals Work ...................................................................................... 21
About Preapproval Keys ...................................................................................... 21
About Preapproval Pins ....................................................................................... 22
Sample Call .......................................................................................................... 22
Custom Objects in the Mobile Payments Library ....................................................... 23
Enumerated Values in the Mobile Payments Library ................................................. 28
Localization Support in the Mobile Payments Library ................................................ 29
2. The Checkout Experience with the Mobile Payments Library ............... 31
Checkout Experience #1 – Goods or Services with Shipping .................................... 31
Checkout Experience #2 – Goods or Services without Shipping ............................... 32
Checkout Experience #3 – Donations ........................................................................ 33
Checkout Experience #4 – Personal Send Money Payments .................................... 34
Checkout Experience #5 – Create Pin ....................................................................... 35
Checkout Experience #6 – Preapproval ..................................................................... 36
Basic Preapproval Checkout ................................................................................ 36
Creating Preapproval PINs During Preapproval Checkout .................................. 37
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 3
3. Submitting Your Application to PayPal ................................................... 38
A. Currencies Supported by PayPal ............................................................. 39
B. Countries and Regions Supported by PayPal ......................................... 41
4 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
Version
Date Published
Description
1.5.5
July 2011
Initialization is recallable and completes within 3 sec down from 20-30
sec.
„Keep Me Logged‟ in functionality reinstated.
Merchant has the ability cancel transaction from dynamic amount
calculation.
1.5
February 2011
Improved Tablet Support
1.1.1
January 2011
Eliminated “Keep Me Logged In” functionality
Preface
The PayPal Mobile Payments library provides secure, extensible, and scalable PayPal payment
functionality to the Android platform.
Purpose
The PayPal Mobile Payments Library provides an easy way for you to integrate payments into
your Android 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 payments library
with 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
the buyer 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 via the library. The approval process is
described later in the document.
OS and Hardware Support
The PayPal Mobile Payments Library supports Android OS 1.5 and higher. All Android devices
are supported.
Revision History
The following table lists revisions made to the Mobile Payments Library Developer Guide and
Reference.
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 5
Version
Date Published
Description
1.1
December 2010
Added information about preapproval; dropped support for the
enumeration value BUTTON_118x24
1.0
September 2010
Adaptive Payments Support
0.7
May 2010
First publication
6 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
Where to Go for More Information
Adaptive Payments Developer Guide
Sandbox User Guide
Merchant Setup and Administration Guide
PayPal X Developer Network (x.com)
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 7
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 Android 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 Button and returns it to you so you can place it on
the screen.
3. (Optional) Your application enables Dynamic Amount Calculation (see step 4 below) to
recalculate the payment amount, tax, currency, and shipping values when buyers change the
shipping address for the payment.
4. When buyers select the Pay with PayPal button, the library takes them through the PayPal
Checkout experience.
5. (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 call back to
your application with the address information.
b. Your application recalculates the payment and other amounts, based on the address.
c. The library returns the buyer to the checkout experience, which uses the updated
payment amount, tax, currency, and shipping values.
6. After buyers complete their payments, the library returns a callback to your application with
the status of the payment and the pay key. Note: at this time, the library is still in control of
the UI and has not returned control to your application.
7. After the library flow is complete, an activity result will be posted to be received by your
application.
Declaring the Library and Permissions in AndroidManifest.xml
Since the Mobile Payments Library is an Activity, you must declare it in the
AndroidManifest.xml file of your application. You must also declare Internet and Phone
State permissions that the Library requires. Below is an example AndroidManifest.xml. Sections
specifically relevant to the Library are in bold:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.paypal.MobilePayments.Pizza"
android:versionCode="1"
android:versionName="1.0">
<application android:icon="@drawable/icon"
android:label="@string/app_name">
<activity android:name=".PizzaMain"
8 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
android:label="@string/app_name">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category
android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name="com.paypal.android.MEP.PayPalActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:configChanges="keyboardHidden|orientation/>
</application>
<uses-sdk android:minSdkVersion="3" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.READ_PHONE_STATE"/>
</manifest>
Adding the Library Jar File and Importing Classes
1. Right click on your project and select “Properties”
2. Select “Java Build Path”
3. Select the “Libraries” tab
4. Select the “Add Jars…” button
5. Choose the “PayPal_MPL.jar” file from your folder structure and click “OK”
Also, import the appropriate classes into your application classes. The following classes must be
imported:
import com.paypal.android.MEP.CheckoutButton;
import com.paypal.android.MEP.PayPal;
import com.paypal.android.MEP.PayPalReceiverDetails;
import com.paypal.android.MEP.PayPalPayment;
or
import com.paypal.android.MEP.PayPalAdvancedPayment;
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 9
Parameter
Description
context:
(Required) The context.
appID:
(Required) PayPal Application ID from X.com.
This will be different for each server. Thus, the appID will be
different for Stage and Sandbox. Any appID value can be used when
testing on „none‟ since the library does not contact the server when
set to this.
server:
(Required) Sets the PayPal server to Live, Sandbox, or None.
Allowable values are:
ENV_LIVE – Use the PayPal production servers.
(does not support simulators)
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.
Required Methods in the Mobile Payments Library
initWithAppID Method
The initWithAppID method creates and returns the PayPal object. You must pass in the context
and the unique application ID (appID) that PayPal has provided. You can choose whether to use
the live or sandbox server, or use non-networked (Demo) mode (see below).
static public PayPal initWithAppID(Context context, String appID, int
server)
An example of initializing the Library with this method is:
PayPal ppObj = PayPal.initWithAppID(this.getBaseContext(), "APP80W284485P519543T", PayPal.ENV_SANDBOX);
NOTE: The initWithAppID method should only be invoked once. After initialization,
reference the PayPal object using the getInstance method instead. Calling the
initWithAppID method more than once will throw an IllegalStateException.
NOTE: If you do not set the optional parameter forEnvironment, the library defaults to use
the PayPal production the servers. When testing your application, PayPal recommends that
you initialize the library to use the PayPal test servers, instead.
10 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
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. If you try to login with a different account on a device
after binding, you will get the following error: “This app is attached to another PayPal
account. To remove it, the account holder must visit PayPal.com and select Mobile
Applications from the profile.”
To switch a device or simulator to use a different sandbox account, go to the PayPal
Sandbox website on your computer, login with the account that was used on the device,
select Profile > Mobile Applications, and then unbind the device from the application ID.
getCheckoutButton Method
You must get the Pay with PayPal payment button from the Mobile Payments Library. Use this
method, which returns a CheckoutButton (a subclass of LinearLayout), which you can place
in your application.
public CheckoutButton getCheckoutButton(Context context, int style, int
textType);
Example code of getting the Payment button from the Library is:
CheckoutButton launchPayPalButton = ppObj.getCheckoutButton(this,
PayPal.BUTTON_278x43, CheckoutButton.TEXT_PAY);
RelativeLayout.LayoutParams params = new
RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT,
LayoutParams.WRAP_CONTENT);
params.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);
params.bottomMargin = 10;
launchPayPalButton.setLayoutParams(params);
launchPayPalButton.setOnClickListener(this);
((RelativeLayout)findViewById(R.id.RelativeLayout01)).addView(lau
nchPayPalButton);
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 11
Parameter
Description
style:
(Required) Size and appearance of the Pay with PayPal button
Allowable values are:
PayPal.BUTTON_152x33
PayPal.BUTTON_194x37
PayPal.BUTTON_278x43
PayPal.BUTTON_294x45
For images of the different button types, see “Enumerated Values in the
Mobile Payments Library” on page 28.
context:
(Required) The context
textType:
(Required) The type of button to be used. The type will determine the
text that is to be used on the button. This has no bearing on the payment
and only affects the button itself. Allowable values are:
CheckoutButton.TEXT_PAY
CheckoutButton.TEXT_DONATE
Start the Library Activity
The Library uses the native Android Activity mechanism to start the checkout flow, and to
communicate completion back to you. In addition to the onActivityResult callback, you can
implement PayPalResultDelegate to be informed immediately upon successful completion of
a payment.
To start the PayPal payment, you must start the Library activity, using the Android method
startActivityForResult. Do this when buyers touch the Pay with PayPal button (which
you placed on your page with the getCheckoutButton method)
You must first create the PayPal intent and give it the Payment object. There are two types of
payment objects. PayPalPayment handles simple payments, which support single receivers of
payments with one transaction and a few details. PayPalAdvancedPayment handles parallel
and chained payments, which support multiple receivers of payment with one transaction and
with additional details, such as invoice data.
In the following example, the buyer checks out with a simple payment for a single recipient:
PayPalPayment newPayment = new PayPalPayment();
newPayment.setSubtotal(10.f);
newPayment.setCurrency("USD");
newPayment.setRecipient("my@email.com");
newPayment.setMerchantName("My Company");
Intent paypalIntent = PayPal.getInstance().checkout(newPayment, this);
this.startActivityForResult(paypalIntent, 1);
12 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
Parameter
Description
intent:
(Required) A PayPalPayment object that contains information
about the payment. Create this intent with the following code:
Intent checkoutIntent = new Intent(this,
PayPalActivity.class);
For the properties of this object type, see “PayPalPayment” on page
24.
requestCode:
(Required) Use any integer for the request code. When you get the
onActivityResult() callback from the Library Activity, you
can use this request code to know that the results are coming from the
Library activity.
In the following example, the buyer checks out with a parallel or chained payment for multiple
recipients:
PayPalReceiverDetails receiver0, receiver1;
receiver0 = new PayPalReceiverDetails();
…
//setup receiver details
…
PayPalAdvancedPayment advPayment = new PayPalAdvancedPayment();
advPayment.setCurrency("USD");
advPayment.getReceivers().add(receiver0);
advPayment.getReceivers().add(receiver1);
Intent paypalIntent = PayPal.getInstance().checkout(advPayment, this);
this.startActivityForResult(paypalIntent, 1);
For more information on receivers and how to use them, see “Custom Objects in the Mobile
Payments Library” on page 23.
Note: On older devices and/or firmware, starting the activity may take significant time to
complete, resulting in an “Activity is not responding” popup if the user attempts to enter input
during this time. It is recommended to create a loading thread with an animation of some sort if
you witness this regularly.
Dynamic Amount Calculation
The Mobile Payments Library allows you to modify the payment based on the buyer‟s shipping
address. For instance, you might want to recalculate the tax amount based on the buyer‟s location.
To enable this, use the optional method enableDynamicAmountCalculation() (see
“Optional Methods” below. You must provide the logic that creates the new payment values
based on the buyer‟s address. The library includes a PaymentAdjuster class for this.
To use this feature, one of your classes (not an Activity) must implement “PaymentAdjuster”, as
well as implement “Serializable”. For simplicity, we recommend creating a new class that does
this. This class must include the following methods:
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 13
Parameter
Description
address
The buyer's address that should be used when calculating adjusted tax
and shipping amounts.
currency
The currency of the payment.
amount
The current subtotal amount.
tax
The current tax amount.
shipping
The current shipping amount.
Parameter
Description
address
The buyer's address that should be used when calculating adjusted tax
and shipping amounts.
currency
The currency of the payment.
receivers
A collection of current receivers and the amounts associated with each
receiver.
public MEPAmounts adjustAmount(MEPAddress address, String currency,
String amount, String tax, String shipping);
Your method must return a new MEPAmounts object (see Custom Objects section). This object
contains the new currency and amounts.
public Vector<MEPReceiverAmounts> adjustAmountsAdvanced(MEPAddress
address, String currency, Vector<MEPReceiverAmounts> receivers);
Your method must return a new Vector<MEPReceiverAmounts> to update the library with
adjusted amounts for each receiver. (See Custom Objects section).
Applications may cancel a payment during the PaymentAdjust callback by returning 'null'.
Returning null will cancel the entire payment. A dialog will be presented to the user indicating
that the adjustment failed and the payment is being cancelled. Applications may also call
PayPal.setAdjustPaymentError(String message) to establish the message that will be presented.
Otherwise a standard message will be used. The error message should be established prior to
failing the the payment adjust.
When you create the PayPal Activity, you must pass through the PaymentAdjuster class to
another form of the checkout method. For example, if you created an “AdjustAmounts” class
that implements PaymentAdjuster and contains the adjustAmount method, your code could
be:
AdjustAmounts adjustClass = new AdjustAmounts();
Intent paypalIntent = PayPal.getInstance().checkout([your payment
object], this, adjustClass);
this.startActivityForResult(paypalIntent, 1);
14 July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
Method Sequence
The following diagram illustrates the sequence of methods required to implement the checkout
experience.
Mobile Payments Library Developer Guide and Reference – Android OS Edition July 2011 15
Loading...