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.
Contents Preface ............................................................................................................... 5 Purpose ........................................................................................................................ 5 Scope ............................................................................................................................ 5 OS and Hardware Support ...........................................................................................
3. Submitting Your Application to PayPal ................................................... 38 A. Currencies Supported by PayPal ............................................................. 39 B. Countries and Regions Supported by PayPal.........................................
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.
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.
Where to Go for More Information Adaptive Payments Developer Guide Sandbox User Guide Merchant Setup and Administration Guide PayPal X Developer Network (x.
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.
android:label="@string/app_name"> PAGE 10Required 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.
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.
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.
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.
public MEPAmounts adjustAmount(MEPAddress address, String currency, String amount, String tax, String shipping); 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. Your method must return a new MEPAmounts object (see Custom Objects section).
Method Sequence The following diagram illustrates the sequence of methods required to implement the checkout experience.
Optional Methods in the Mobile Payments Library getInstance Method This method returns the singleton PayPal object. PayPal payPal = PayPal.getInstance(); setLanguage Method payPal.setLanguage(String emailOrPhone); Enable / Disable Shipping Method This method lets buyers include display of shipping addresses in the Library. With shipping enabled, buyers can choose an address from the list available in their PayPal accounts. The chosen shipping address is then used for the payment.
Activity.RESULT_OK This result is returned when a PayPal payment succeeds. The pay key is available in the Intent data as PayPalActivity.EXTRA_PAY_KEY. The code to get the pay key as a string is: data.getStringExtra(PayPalActivity.EXTRA_PAY_KEY). Activity.RESULT_CANCELED This result is returned if the buyer cancels the payment during checkout. paymentCanceled(); PayPalActivity.
The interface for providing details on when a payment is completed is defined in com.paypal.android.MEP.PayPalResultDelegate.
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 only supports a payment to a single recipient. Parallel Payments Parallel Payments allow you to make payments for any amount to any number of recipients. A parallel payment is created by making a payment with multiple recipients with no primary recipient.
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.
Preapprovals The PayPal Mobile Payments Library lets you set up 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.
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 special codes that buyers enter to authorize preapproved payments individually without logging in to PayPal.
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. Use these objects if you enable dynamic amount calculation by calling the DynamicAmountUpdate method. MEPAddress This object is passed to your PaymentAdjuster class in the AdjustAmounts method. Use this address to update the payment amount, tax, currency, and shipping values of the payment.
Property Description shipping) MEPReceiverAmounts Similarly to MEPAmounts and MEPAddress, this object is used in dynamic amount calculation for advanced payments. Property Description public MEPAmounts amounts; Amounts for this receiver. public String receiver; The receiver for this amount calculation. PayPalPayment This object is passed to the library through extra data in the Intent when the Library Activity is started.
PayPalAdvancedPayment This object is passed to the library through extra data in the Intent when the Library Activity is started. This object contains all the values for a payment Method Description setCurrencyType(String currency) (Required) - Currency code for the payment. Defaults to USD if not set. setReceivers(ArrayList receivers) or getReceivers() (Required) – Your payment must have at minimum one receiver.
PayPalPreapproval This object is passed to the library through extra data in the Intent when the Library Activity is started. This object contains all the values for a payment Method Description setCurrencyType(String currency) (Required) - Currency code for the payment. Defaults to USD if not set. setType(int type) (Optional) – The type of button to display, either TYPE_AGREE or TYPE_AGREE_AND_PAY. Defaults to TYPE_AGREE_ANDPAY.
PayPalInvoiceItem These items can be added to any InvoiceData. NOTE: The UnitPrice and Quantity must multiply together correctly to equal the TotalPrice. The TotalPrices of all invoiceItems of a PayPalPayment or a PayPalAdvancedPayment must equal the subtotal of the payment. Method Description setName(String name) (Optional) – The name of the item. setID(String ID) (Optional) – A unique ID for the item.
Enumerated Values in the Mobile Payments Library The enumerated values supported by various methods in the library are: PAYPAL_ENVIRONMENT 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.
choose who pays any fees – the sender or the recipient. In India and Germany, recipients always pay any fees. For more information, see “setFeesPayer Method” on page 16. PAYPAL_FAILURE SYSTEM_ERROR RECIPIENT_ERROR APPLICATION_ERROR CONSUMER_ERROR These failures are returned by the PayPalActivity.RESULT_FAILURE result from the PayPal Library activity. Localization Support in the Mobile Payments Library To change the language in the Library, call setLanguage(String localeCode) on the PayPal object.
Language (Country or Region) Locale Code English (Spain) en_ES English (Switzerland) en_CH English (Taiwan) en_TW English (United States) en_US French (Belgium) fr_BE French (Canada) fr_CA French (France) fr_FR French (Switzerland) fr_CH German (Austria) de_AT German (Germany) de_DE German (Switzerland) de_CH Italian (Italy) it_IT Japanese (Japan) ja_JP Spanish (Argentina) es_AR Spanish (Mexico) es_MX Spanish (Spain) es_ES Polish (Poland) pl_PL Portuguese (Brazil) pt
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. Checkout Experience #1 – Goods or Services with Shipping Payment type=Hard Goods or Services / Shipping=enabled In the preceding experience, buyers enter their PayPal log-in credentials in the Log In To PayPal screen.
Checkout Experience #2 – Goods or Services without Shipping Payment type=Hard Goods or Services / Shipping=disabled In the case, shipping is not required (i.e. manual pick up of goods or services). Shipping is disabled by a call to the setShippingEnabled() library method. Buyers enter their PayPal log-in credentials and directly pay by clicking the Pay button on the first screen. Buyers can review funding choices by clicking the Review button on the same page.
Checkout Experience #3 – Donations Payment type=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 can choose another mailing address from the ones in their PayPal accounts.
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 it is funded by PayPal balance or by a bank account on file. The transaction carries a fee when it is funded by payment card – debit or credit or PayPal Credit cards. In some cases, senders choose who pays any fees – sender or recipient.
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 his/her account. By following the on-screen instructions, the user can associate his/her account with a phone number and PIN for easier login in the future. Upon successful creation of the PIN, the user will be returned to your application triggering the paymentSuccess() delegate callback.
Checkout Experience #6 – Preapproval In this experience, you started the Android Activity with the preapproval intent, as discussed under “Preapprovals” on page 21. 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.
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.
3. Submitting Your Application to PayPal Before you 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.
A. Currencies Supported by PayPal PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables. Currency Currency Code Australian Dollar AUD BRL Brazilian Real NOTE:This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.
July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS 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 Country or Region Code BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM IO BN BG 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 ER EE ET FK BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS (KEELING) ISLANDS COLOMBIA COMOROS CONGO CONGO, THE DEMOCRATIC REPUBLIC OF COOK ISLANDS COSTA RICA COTE D'IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK
Country or Region Country or Region Code FAROE ISLANDS FIJI 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 IM IL IT JM 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 IRA
Country or Region Country or Region Code JP JE JORDAN JO KAZAKHSTAN KZ KENYA KE KIRIBATI KI KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KP KOREA, REPUBLIC OF KR KUWAIT KW KYRGYZSTAN KG LAO PEOPLE'S DEMOCRATIC REPUBLIC LA LATVIA LV LEBANON LB LESOTHO LS LIBERIA LR LIBYAN ARAB JAMAHIRIYA LY LIECHTENSTEIN LI LITHUANIA LT LUXEMBOURG LU MACAO MO MACEDONIA, THE FORMER YUGOSLAV MK JAPAN JERSEY REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO M
Country or Region Country or Region Code MOZAMBIQUE MYANMAR 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 PM VC 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 FEDERAT
Country or Region Country or Region Code WS SM SAO TOME AND PRINCIPE ST SAUDI ARABIA SA SENEGAL SN SERBIA AND MONTENEGRO CS SEYCHELLES SC SIERRA LEONE SL SINGAPORE SG SLOVAKIA SK SLOVENIA SI SOLOMON ISLANDS SB SOMALIA SO SOUTH AFRICA ZA SOUTH GEORGIA AND THE SOUTH SANDWICH GS SAMOA SAN MARINO ISLANDS SPAIN SRI LANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC TAIWAN, PROVINCE OF CHINA TAJIKISTAN TANZANIA, UNITED REPUBLIC OF THAILAND TIMOR-LESTE TOGO TOKELAU TON
Country or Region Country or Region Code UKRAINE UNITED ARAB EMIRATES UA AE GB US UM UY UZ VU VE VN VG VI WF EH YE ZM ZW UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS, BRITISH VIRGIN ISLANDS, U.S.
July 2011 PayPal Mobile Payments Developer Guide and Reference – Android OS Edition
