PayPal Mobile Payments Library - 2012 Blackberry OS Developer's Guide
Contents
1. Aan m Biackberry OS Edition w w JERSEY J LH 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 O MACEDONIA THE FORMER YUGOSLAV MK REPUBLIC OF MADAGASCAR MG MALAWI MW MALAYSIA MY MALDIVES MV MALI ML MALTA MT MARSHALL ISLANDS 1H MARTINIQUE 1Q MAURITANIA R MAURITIUS JU MAYOTTE YT MEXICO NX MICRONESIA FEDERATED STATES OF FM MOLDOVA REPUBLIC OF AD MONACO AC MONGOLIA MN MONTSERRAT MS MOROCCO IA Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition Country or Region Country or Region Code MOZAMBIQUE Z MYANMAR il NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTILLES AN NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF NORTHERN MARIANA ISLANDS IP NORWAY NO OMAN OM PAKISTAN PK PALAU PW PALESTINIAN TERRITORY OCCUPIED PS PANAMA PA PAPUA NEW GUINEA PG PARAGUAY PY PERU PE PHILIPPINES PH PITCAIRN PN POLAND PL PORTUGAL E PUERTO RICO PR QATAR QA REUNION RE ROMANIA RO RUSSIAN FEDERATION RU RWANDA RW SAINT HELENA SH SAINT KITTS AND NEVIS KN SAINT LUCIA LC SAINT PIERRE AND MIQUELON P SAINT VINCENT AND THE GRE2. A collection of current receivers and the amounts associated with each receiver Your method must return a new Vector lt PayPalReceiverDetails gt to update the library with adjusted amounts for each receiver See the Custom Objects in the Mobile Payments Library section Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 12 Method Sequence The following diagram illustrates the sequence of methods required to implement the checkout experience B Your Mobile App M duit initWithApplD applD server service eee O getCheckoutButton class FieldSize TextType SEE rent e CheckoutButton a M M checkoutSimplePayment a o ze et ee PayPal Checkout Experience Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 13 Optional Methods in the Mobile Payments Library getinstance Method This method returns the singleton PayPal object PayPal payPal PayPal getinstance setLang Method payPal setLang String localeCode 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 Shipping is enabled by default payPal setShippingEnabled boolean isEnabled setFeesPayer Method This method is valid only for
3. Basic Preapproval Checkout Login Screen Agree and Pay Screen Pizza Express Pizza Express W Billing Summary Y Billing Summary Login E Review PayPal Bank x121 1 47 34 USD Bank x121 2 47 34 usp buyer gmail com i allow Pizza Express to automatically charge my PayPal account If my primary payment method cannot complete a transaction PalPal will try using other payment methods with my accuont To w Keep me logged in this device wiry change or cancel go to your Profile page 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 amp Reference Blackberry OS Edition 33 Creating Preapproval PINs During Preapproval Checkout Depending on your business model you may require buyers to create preapproval PINs during preapproval
4. 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 Chained Payment a Receiver 2 ARA 45 mam Sender Primary receiver 100 10 Receiver 3 45 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 amp Reference Blackberry OS Edition 17
5. Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Shekel ILS Japanese Yen JPY Malaysian Ringgit MYR NoTE This currency is supported as a payment currency and a currency balance for in country PayPal accounts only Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB U S Dollar USD Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition B Countries and Regions Supported by PayPal PayPal uses 2 character ISO 3166 1 codes for specifying countries and regions that are supported in fields and variables Country or Region Country or Region Code AFGHANISTAN AF LAND ISLANDS AX ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGOLA AO ANGUILLA AI ANTARCTICA AQ ANTIGUA AND BARBUDA AG ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD BARBADOS BB BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM BHUTAN BT BOLIVIA BO BOSNIA AND HERZEGOVINA BA BOTSWANA BW BOUVET ISLAND BV BRAZIL BR Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 37 Country or Region Country or Region Code BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE V
6. Sandbox Funding Balance USD Post to Simple Storefront s Test Store 1 Main St San Jose CA 95131 42 00 uso 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 the change funding source or shipping address If satisfied buyers click Pay to complete the payment Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 28 Checkout Experience 2 Goods or Services without Shipping PaymentType GOODS or SERVICE Shipping disabled 9800 merchant paypal com 9780 merchant paypal com Ww My Tota o EJ 1111111111 Y Keep me legged in this device iw 9800 Send to merchant paypal com 9780 merchant paypal com d My total Review PayPal a Funding Balance USD 42 00 USD A My total Review PayPal a Fundit Balance USD 42 00 USD Sandbox In the case shipping is not required that is manual pick up of goods or services Shipping is disabled by a call to the setShippingEnabled library method Buyers enter their PayPal login 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 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 29 Checkout Experience 3 Donations PaymentSubTy
7. 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 Pizza Express Pizza Express Pizza Express x j WS Billing Summary Success PayPal PayPal Create PIN for faster checkout Bank x121 1 47 34 uso Bank x121 2 47 34 uso bow Pura Express to automatic aih PaPa snot c 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 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 34 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
8. in the Mobile Payments Library The enumerated values supported by various methods in the library are PayPalServerType e ENV LIVE Use the PayPal production servers e ENV SANDBOX Use the PayPal testing servers e 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 FieldSize BUTTON 118x24 BUTTON 152x33 BUTTON 194x37 BUTTON 278x43 BUTTON 294x45 Note If the TextType parameter is set to Donate the word Pay in the above buttons is replaced by Donate The language of the button will also change based on the language you pass into the set Lang method or the auto detected language on the phone PaymentType GOOD PERSONAL SERVICE Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 24 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 setFeePaidByReceiver Method on page 15 Paym
9. 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 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 _render content amp content ID 2marketing us send money Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 31 Checkout Experience 5 Create Pin 9800 l merchant paypal com 2 Receipt l merchant paypal com Payment made Payment made PayPal Create a PIN to check out faster next time Create a PIN to check out faster next time Create PIN Create PIN Sandbox In the preceding experience a PayPal member has just completed a payment and does not currently have a PIN associated with his or her account By following the on screen instructions the user can associate the account with a phone number and PIN for easier login in the future Upon successful creation of the PIN the user is returned to your application triggering the paymentSucceeded delegate callback Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 32 Checkout Experience 6 Preapproval In this experience you started the PayPal preapproval flow by calling the checkout Preapproval method as discussed under Preapprovals on page 17
10. 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 Blackberry e Application ID in your calls to initWithAppID e Environment in your calls to initWithAppID e Recipient in the PayPalPayment object Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 35 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 Brazilian Real BRL Note This currency is supported as a payment currency and a currency balance for in country PayPal accounts only Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR
11. DynamicAmountCalculationEnabled 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 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 public Amounts adjustAmount Address address String currency BigDecimal amount BigDecimal tax BigDecimal shipping Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 11 Parameter address currency amount tax shipping Description The buyer s address that should be used when calculating adjusted tax and shipping amounts The currency of the payment The current subtotal amount The current tax amount The current shipping amount Your method must return a new Amounts object see the Custom Objects in the Mobile Payments Library section This object contains the new currency and amounts public Vector lt PayPalReceiverDetails gt adjustAmountsAdvanced Address address receivers BigDecimal currency Vector lt PayPalReceiverDetails gt Parameter address currency receivers Description The buyer s address that should be used when calculating adjusted tax and shipping amounts The currency of the payment
12. ERDE 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 DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS MALVINAS IO BN BG BF B KH CM CA CV KY ola J TE REESE IE Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 38 Country or Region Country or Region Code 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 Country or Region FO FJ EL FR GF QH m n nj 1 e G1 ES WOE aloja ajalala ulala mH n aagp AK Ss 2 Q AIG nN ZA D O w ul zi ul lt IT JM Country or Region Code JAPAN Mobile Payments Library Deveioper Guide amp Reference JE
13. NADINES VC Country or Region Country or Region Code SAMOA WS Aan m Mobile Payments Library Deveioper Guide amp Reference Blackberry OS Edition E E SAN MARINO 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 ISLANDS SPAIN ES SRI LANKA LK SUDAN SD SURINAME SR SVALBARD AND JAN MAYEN SJ SWAZILAND SZ SWEDEN SE SWITZERLAND CH SYRIAN ARAB REPUBLIC SY TAIWAN PROVINCE OF CHINA TW TAJIKISTAN TJ TANZANIA UNITED REPUBLIC OF TZ THAILAND TH TIMOR LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND TOBAGO TT TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS ISLANDS TC TUVALU TV UGANDA UG Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition Country or Region Country or Region Code UKRAINE UA UNITED ARAB EMIRATES AE UNITED KINGDOM GB UNITED STATES US UNITED STATES MINOR OUTLYING ISLANDS U URUGUAY UY UZBEKISTAN UZ VANUATU VU VENEZUELA VE VIET NAM VN VIRGIN ISLANDS BRITISH VG VIRGIN ISLANDS U S VI WALLIS AND FUTUNA VE WESTERN SAHARA EH YEMEN YE ZAMBIA Z ZIMBABWE ZW Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition
14. PayPal Mobile Payments Library Developer Guide and Reference Blackberry OS Edition Last updated August 2011 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 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 result
15. PaymentAdjuster PaymentType SERVICES PaymentSubType B2B catch PayPalBlackberryLibraryException e Dialog alert Error 4 getMessage Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 19 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 adjustAmount 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 Method Description tring getStreetl tring getStreet2 tring getCity tring getState etPostalcode tring etCountrycode S S S S String g S g S tring getCountry First line of the street address Second line of the street address Name of the city Name of the state or province U S ZIP code or other country specific postal code The 2 character country code The name of the country MEPAmounts This object is returned to the library by the adjustAmount method of your PaymentAdjuster class This object contains the values for the updated payment Property Description setCurr
16. Personal payments Call this method to set who pays any fees by default If you do not call this method the receiver pays any fees by default payPal setFeePaidByReceiver boolean feePaidByReceiver setDynamicAmountCalculationEnabled Method This method lets you recalculate the payment amount tax currency and shipping values based on the shipping address chosen by a buyer If you use this method to enable dynamic amount calculation before the checkout starts the library will dynamically update the payment based on logic you provide see above Note If shipping is not enabled this method is ignored payPal setDynamicAmountCalculationEnabled boolean enabled Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 14 After the Payment After the payment is completed the Mobile Payments Library returns the payKey A number of other features are also available to you to enable you to further deal 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 Transaction Details You can integrate with the PayPal PaymentDetails API to retrieve details on a payment based on t
17. Preapprovals The PayPal Mobile Payments Library lets you set up and 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 3 steps to setting up and using preapprovals 1 Obtain a pending preapproval key from PayPal From your application create a PreapprovalPayment object and a PreapprovalRequest object with the terms of your preapproval agreement 2 Obtain authorization from the buyer for the preapproval agreement Obtain the preapproval key and set it with the set PreapprovalKey method After this is set invoke the Preapproval flow by calling the method preapprove method of the PayPal instance passing it objects that implement the PreapprovalPayment and PreapprovalRequest The library launches the preapproval checkout experience and if it is processed successfully the preapprovalSucceeded method is called If the processing fails the preapprovalFailed method is invoked 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
18. ar file from your folder structure and click OK Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 7 Also import the appropriate classes into your application classes The following classes must be imported import com paypal blackberry ui CheckoutButton import com paypal blackberry PayPal import com paypal blackberry components PayPalReceiverDetails import com paypal blackberry PayPalPayment or import com paypal blackberry AdvancedPayPalPayment import com paypal blackberry util BigDecimal Note Since the PayPal Mobile Payments Library uses restricted APIs such as networking all applications implementing it will need to include RIM signing Required Methods in the Mobile Payments Library initWithAppID Method The initwithAppID method creates and returns the PayPal object You must pass in the unique application ID applId that PayPal has provided and the context You can choose whether to use the live or sandbox server or use non networked Demo mode see below static public PayPal initWithAppID String appld PayPalEnvironmentType environmentType An example of initializing the Library with this method is try PayPal ppObj PayPal initWithAppID App 80W284485P519543T PayPal ENV SANDBOX catch PayPalBlackberryLibraryException e Parameter Description appId Required PayPal Application ID from X com This is different for eac
19. bind the device from the application ID getCheckoutButton Method You must obtain the Pay with PayPal payment button from the Mobile Payments Library Create a local instance of CheckoutButtonclass a subclass of ButtonField which you can place in your application and retrieve the button from the PayPal instance As precondition library should be initialized before a call to this method can be made e g initWithAppld method should be called or an exception will be thrown public synchronized Field getCheckoutButton String fieldClassName FieldSize buttonSize TextType textType Example code of adding the Payment button to your application CheckoutButtoncheckoutButton CheckoutButton payPal getCheckoutButton PayPal BUTTON 152x33 CheckoutButton TEXT DONATE add checkoutButton Parameter Description fieldSize Required Size and appearance of the Pay with PayPal button Allowable values are e PayPal BUTTON 152x33 e PayPal BUTTON 194x37 e PayPal BUTTON 278x43 e PayPal BUTTON 294x45 For images of the different button types see Enumerated Values in the Mobile Payments Library on page 24 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 affects only the button itself Allowable values are e CheckoutButton TEXT PAY e CheckoutButton TEXT DONATE Implement th
20. e Blackberry OS Edition 10 PayPalBlackberryLibraryPayPalPaymentDelegateException UiApplication getUiApplication invokeLater new Runnable public void run Dialog alert payment cancelled UiApplication getUiApplication pushScreen new DemoAppScreen The following are the callback events triggered in the PayPalPaymentDelegate interface Method Description paymentCancelled The payment was cancelled by the user paymentFailed String errorld The payment failed for the reason specified by error ID z String errorMessage message paymentIncompleted The payment was incomplete paymentCompleted The payment was successfully completed The PreapprovalDelegate is used in conjuncture with preapproval payments The following callback events are triggered in the PreapprovalDelegate interface Method Description preapprovalCancelled The preapproval was cancelled by the user paymentFailed String errorld The preapproval failed for the reason specified by error ID String errorMessage amp message preapprovalCompleted String The preapproval was successfully completed preapprovalKey Dynamic Amount Calculation The Mobile Payments Library allows you to dynamically modify the payment information any time a buyer selects a 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 set
21. e Delegate If you want to be informed about payment status and payment result and take custom actions e g display custom views you should implement the delegate classes The Library communicates back with your application using Java event listeners and delegates When adding a Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 9 button to your application you add a FieldChangeListener to your buttons which executes when the user selects the corresponding item You can implement PayPalPaymentDelegate to be informed immediately upon the successful completion failure or cancellation of a payment Should you choose not to implement a custom delegate you can use the default implementation which doesn t do anything provided by PayPal library To respond to the button press implement a FieldListener on the PayPal Button In this code you create and manipulate the appropriate objects and settings to create your payment to be processed There are two types of payment delegates PayPalPaymentDelegate and PreapprovalDelegate PayPalPaymentDelegate is used to handle the processing of simple and advanced payments while PreapprovalDelegate is used with preapproval payments In the following example the buyer checks out with a simple payment for a single recipient FieldChangeListener listener new FieldChangeListener public void fieldChanged Field field int context PayPalPayment newPayment new Pa
22. e 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 Sample Call After you obtain a pending approval key construct a PreapprovalPayment object that includes the key and the merchant s name Then use the checkout Preapproval method to execute the call PreapprovalPayment preapproval new PayPalPreapproval preapproval setCurrency USD preapproval setMerchantName Preapproval Merchant try PayPal getInstance checkoutPreapproval preapproval new PreapprovalDelegate new
23. efore it is approved to accept payments by means of the library The approval process is described later in the document OS and Hardware Support The PayPal Mobile Payments Library supports Blackberry OS version 4 6 and higher The list of supported Blackberry devices can be found here Revision History The following table lists revisions made to the PayPal Mobile Payments Library Developer Guide and Reference Blackberry OS Edition Version Date Published Description 1 0 August 2011 First publication Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 5 Where to Go for More Information e Adaptive Payments Developer Guide e Sandbox User Guide e Merchant Setup and Administration Guide e PayPal X Developer Network x com Mobile Payments Library Developer Guide amp Reference Blackberry OS 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 Blackberry application Mobile Payments Library API Reference The flow of the library is 1 Your application initializes the PayPal instance with your unique PayPal application ID 2 You retrieve the PayPal instance 3 You retrieve the PayPal button from the instance using the getCheckoutButton method You can place the button on the screen 4 You create and fill the PayPalPaym
24. ency String currency Optional Currency code of the amount Defaults to USD setPaymentAmount BigDecima Required Amount of the payment before tax or shipping l paymentAmount setTax BigDecimal tax setShipping BigDecimal shipping Optional Tax amount associated with the item Optional Shipping amount for the item Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 20 PayPalPayment This object is passed to the library when the specific checkout method checkoutSimplePayment checkoutPreapprovalPayment etc is called This object contains all the values for a payment Method Description setCurrencyType String Optional Currency code for the payment Defaults to USD if currencyType not set setSubtotal BigDecimal Required Subtotal for the payment subtotal setRecipient Required The email address or phone number of String recipient the payment s recipient setMerchantName String Optional Displayed at the top of the library screen If not name set displays the recipient email or phone number string instead setInvoiceData PayPalInvo Optional Holds information such as tax and shipping iceData invoiceData amounts as well as an optional breakdown of the items included setCustomID String Optional The merchant s custom ID This can be used as a customID pass through field which will later be available on the IPN setIpnUrl Str
25. ent object to store the payment information 5 Optional Your application enables Dynamic Amount Calculation see step 7 to recalculate the payment amount tax currency and shipping values depending on the shipping address The recalculation occurs when the address is first received from the server and any time it is changed 6 When buyers select the Pay with PayPal button the library takes them through the PayPal Checkout experience 7 Optional If you enabled dynamic amount calculation step 5 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 continues the buyer with the checkout experience which uses the updated payment amount tax currency and shipping values This might include returning to library should point a presents a custom view for address information 8 After buyers complete their payments the library triggers the corresponding event in the object implementing the PayPalPaymentDelegate interface returning control to you with the results of the payment Adding the Library Jar File and Importing Classes in Eclipse 1 Right click on your project and select Properties 2 Select Configure Build Path 3 Select the Libraries tab 4 Select the Add External JARs button 5 Choose the PayPal_MPL j
26. entSubType AffiliatePayments B2B ChildCare Donations Entertainment EventPlanning GeneralContractors Government Insurance Invoice Medical Mortgage Payroll Rebates Refunds Reimbursements Remittances Rent Tourism Transfer Tuition Utilities Note The payment subtype for a SERVICE type payment Applicable only if you have been approved for special pricing plans For any PaymentType other than SERVICE or if you have not been approved for special pricing subtype is not processed TextType e Pay Used for payments button will have text Pay or Pay with PayPal e Donate Used for donations button will have text Donate or Donate with PayPal Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 25 Localization Support in the Mobile Payments Library To change the language in the library call setLang String localeCode on the PayPal object Pass through the desired locale code for example for US English use en_US If you do not use this method the library defaults to the locale to which the device is set The library supports the following regions Language Country or Region Locale Code Chinese Hong Kong zh HK Chinese Taiwan zh TW Dutch Belgium nl BE Dutch Netherlands nl NL English Australia en AU English Belgium en BE English Canada en CA English France en FR English Germany en DE English Great Britain en GB E
27. gle recipient Method Description setReceivers Vector PayPalReceiverDetails setSubtotal BigDecimal subtotal setIsPrimary boolean isPrimary setPaymentType Payment Type paymentType setPaymentSubType Paymen tSubType paymentSubType setInvoiceData PayPallInvo iceData invoiceData setCustomID String customID setMerchantName String merchantName Required The email address or phone number of this recipient Required The subtotal of the payment to this recipient Optional Indicates whether or not the receiver is the primary receiver of the payment A payment with multiple recipients may specify the primary recipient of the payment to denote a chained payment Payments with multiple recipients but no primary receivers are parallel payments See the section Chained Parallel and Simple Payments for more details Optional See enumeration values below Optional See enumeration values below Optional The InvoiceData holds information such as tax and shipping amounts as well as an optional breakdown of the items included See PayPallnvoiceData above for more details Optional The recipient s custom ID Optional Displayed at the top of the library screen If not set displays the recipient email or phone number string instead Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 23 Enumerated Values
28. h server thus the appId is different for Live and Sandbox Any appId value can be used when testing on None since the library does not contact the server when set to this environmentType Required Sets the PayPal environment to Live Sandbox or None Allowable values are e ENV LIVE Usethe PayPal production servers e ENV SANDBOX Use the PayPal testing servers e 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 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 8 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 log in with a different account on a device after binding you receive 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 log in with the account that was used on the device select Profile gt Mobile Applications and then un
29. he 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 through the PayPal account interface or by means of the Refund API 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 amp Reference Blackberry OS Edition 15 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 only a single recipient Simple Payment a Sender O Receiver 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 to multiple recipients with no primary recipient From the end user s standpoint a parallel payment will affect the Ul by showing the details for each recipient Contrary to chained payments the recipients of a parallel payment are not linked together in terms of amount Parallel Payment 5 a m Receiver 2 Sender 100 N 45 Receiver 3 45 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 16
30. hod setTax BigDecimal tax setShipping BigDecimal shipping setInvoiceltems Vector invoiceltems Description Required Tax amount to be used for the payment This can be updated after the checkout flow has been started if dynamic amount calculation is enabled The amount can be 0 Required Shipping amount to be used for the payment This can be updated after the checkout flow has been started if dynamic amount calculation is enabled The amount can be 0 Required Sets the list of items in the invoice See PayPalInvoiceItem below for more details These items do not affect the total amount of the payment but must equal the subtotal Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 22 PayPallnvoiceltem These items can be added to any PayPalInvoiceData Note The Price and Quantity must multiply together correctly to equal the Price The TotalPrices of all invoiceItems of a PayPalPayment ora PayPalAdvancedPayment must equal the subtotal of the payment Method setName String name setID String ID setTotalPrice BigDecimal price setQuantity int quantity PayPalReceiverDetails Description Optional The name of the item Optional A unique ID for the item Required The total cost of this item unit cost quantity Required The quantity of this item This object is used in the AdvancedPayPalPayment to identify a sin
31. ing IpnUrl Optional The IPN URL setDescription String Optional Description of the item Defaults to Item if not set description Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 21 PayPalAdvancedPayment This object is passed to the library when the associated non simple Checkout method is called This object contains all the values for a payment Method Description setCurrencyType String currencyType setReceivers Vector PayPalReceiverDetails setIpnUrl String ipnUrl setMemo String memo PayPallnvoiceData Optional Currency code for the payment Defaults to USD if not set Required Your payment must have at minimum one receiver The receiver itself should be set up before adding it to the payment See PayPalReceiverDetails below for more details The getReceivers call can be used to alter the current Vector Optional The IPN URL Optional Note for the payment This is an optional object to be set for any receiver The PayPalPayment simple payment has only one receiver and the InvoiceData is added directly to the payment object itself The PayPalAdvancedPayment can support multiple receivers each of which can have an InvoiceData added to it While InvoiceData is an optional parameter for any given receiver once added the InvoiceData must be populated with certain required parameters see below Met
32. ing 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 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition Table of Contents PU CPC Oca e RE EE 5 PURPOSE mc E 5 a 5 OS and Hardware SUpport ccccscessssccecececssseseaecececeseesesaeaeeeeecesseesaeaeseeesesseseuaeaeeeesceseeseuaeaeeeeseesseenaeaneeesens 5 REVISION FISTORY ia at sands artes Aces ee A a Bete dacs A ae 5 Where to Go for More Information ceccceecceeceeeeceeceeececeaeceaeceaeceaeceaeseeeeseeeeeeseaeeeaeeeaeesaaesaaeeaaeceaeeeaeeeaeees 6 1 PayPal Mobile Payments Library esses nennen nennen menn nns nenne neni nasse snnt ania nsn nnn 7 Mobile Payments Library API Reference ccccccccsssscceessssececsssseceesessececsessececsessececsesseeecsesaeeeesesaeeeesesaeeeceeaaes 7 Adding the Library Jar File and Importing Classes in EcliDS ssssccccccecsssssssseceeecesesseneaeseceesssessseaeeeesens 7 Required Methods in the Mobile Payments Library cccscccccccessssesseceeeeecesseseaeseeeescesseseuaeseeeessesseseaaees 8 initWithAppID Method tette ita enana iaa 8 getCheckoutButton Methodiste ereus eeno iaaea aerea nennen E EErEE Re EE I a
33. nglish Hong Kong en HK English India en IN English Japan en JP English Mexico en MX English Netherlands en NL English Poland en PL English Singapore en SG Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 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 BR Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 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 means of the getCheckoutButton method Checkout Experience 1 Goods or Services with Shipping PaymentType GOOD or SERVICE Shipping enabled 9800 merchant paypal com A My total 9780 merchant paypal com Review PayPal Funding Balance USD 42 00 USD Review PayPal Postt Simple Storefront s Test Store 1 Main St San Jose CA 95131
34. pe Donations Shipping enabled 9800 9780 Send to person paypal com merchant paypal com Bass wW My total Review iding Balance USD 42 00 USD Total 42 00 usp Review Simple Storefront s Test Store 1 Main St San jose CA 95131 in Balance USD 42 00 uso Simple Storefront s Test Store 1 Main St San Jose CA 95131 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 but can choose another mailing address from the ones in their PayPal accounts Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 30 Checkout Experience 4 Personal Send Money Payments Payment Type PERSONAL Shipping disabled 9800 Send to merchant paypal com 9780 merchant paypal com ez My total Review PayPal Sy My total Review PayPal Balance USD 42 00 USD s Balance USD 42 00 USD Simple Storefront s Test Store 1 Main St San Jose CA 95131 Sandbox Simple Storefront s Test Store 1 Main St San Jose CA 95131 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
35. preapproval key For more information about the Preapproval and Pay requests see the Adaptive Payments Developer Guide About Preapproval Keys Preapproval keys uniquely identify your preapproval 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 To launch the preapproval checkout experience to confirm a buyer s agreement to a pending preapproval set the preapproval key in the PayPal instance using the set PreapprovalKey method This preapproval key is retuned if the buyer completes the preapproval checkout 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 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 18 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 For example you might have a mobil
36. sas asses senes 9 Implement the Delegate a add 9 Method Sequerica CREO O 13 Optional Methods in the Mobile Payments Library esee eene ener 14 getinstance Mei as 14 setLang Metodista ios 14 Enable Disable Shipping Method ccccccssccesssecessseessececssecesseceaesecsaeceeseecsseeeaaeesesaecesseeesaneseaaeeeeaeeees 14 setFeesPayer Method 14 setDynamicAmountCalculationEnabled Method esses sees nena 14 After the Payment eoi n a I NIRE SERERE aE GER dr HLMIRERN RENTE iia 15 Instant Payment Notification eeeessseeseseeee eene nnne eene nenne nnns nsa ET EEK OR sanas senses EENE aranea 15 Transaction Detail Sucina M 15 RETURNOS tacto M a I M UU E eld UT a 15 Simple Parallel and Chained PayMent ccccccccccccsssessssesecececsesesseaeeeeecscessesneseeeeecsscesesaeseeeeecesseseaeaeeeesens 16 Simple Payments aeae eE E E E A E E e EE dais 16 Parallel Payments oi iba 16 Chained PI MENS aan aan id 17 Prop aa 18 How Preapprovals Work tr tec diia 18 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 3 About Preapproval Keys ii teet PR A a aa e aa iaaea koe ended dag 18 About Preapproval PAS ss da ss 19 Sample ii iia 19 Custom Objects in the Mobile Payments Library ooooococncncncnonononnnnonononanonononononononanononnnnnnnncnnnnnnnoncnnnanons 20 MERA eS ivi a 20 MEPAMO ntsc 20 PayPalPa
37. secsssesesaeaeeeeesesseseaaeaeeeenens 32 Basic Preapproval CheckoUt ettet t et e tes t tee REX Ee da ue de dT Eo T eda kon te ka beads 33 Creating Preapproval PINs During Preapproval Checkout enne 34 Submitting Your Application to PayPal cccccsssscccecsceesesseaecececesesseseaeeeeeesseesesaeaeeeeeesseeseaeaeeeesesseeees 35 Currencies Supported by PayPal it cessi a exa ua eda Ree ee asa cence 36 Countries and Regions Supported by enirn nete oiea aie A eE AREE E Ea A AAEE 37 Mobile Payments Library Developer Guide amp Reference Blackberry OS Edition 4 Preface The PayPal Mobile Payments Library provides secure extensible and scalable PayPal payment functionality to the Blackberry platform Purpose The PayPal Mobile Payments Library provides an easy way for you to integrate payments into your Blackberry 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 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 the buyers 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 b
38. yPalPayment Set the payment amount newPayment setCurrency USD Set the sub total newPayment setSubtotal new BigDecimal 100 Set the payment tax amount InvoiceData invoiceData new InvoiceData invoiceData setTotalTax new BigDecimal 9 65 invoiceData setTotalShipping new BigDecimal 2 00 newPayment setInvoiceData invoiceData try PayPal getInstance checkoutSimplePayment newPayment new SimplePayPalPaymentDelegate new SimplePaymentAdjuster PaymentType SERVICES PaymentSubType B2B catch PayPalBlackberryLibraryException e Dialog alert Error 4 getMessage he The call to the checkoutSimplePayment method transfers control to the library which the user interacts with to complete the purchase The library executes the transaction on the PayPal server and based upon the result of the transaction transfers control back to your application and calls the corresponding callback event to indicate the results of the transaction In the following example the class implements the PayPal PaymentDelegate interface and responds to a paymentCancelled event initiated by the Library by popping up the applications main screen public class ReviewOrderScreenPaymentDelegate implements PayPalPaymentDelegate setup class details public void paymentCancelled throws Mobile Payments Library Developer Guide amp Referenc
39. ymetnit sso ee ees eds e Lia BIG 21 PayPalAdvancedPayrmient ae nct ted bot ttt t ode oeste t delude atta dede inea e Eae deos 22 PayPallnvolceData 5 rtt e eer d RB RET e e RR a e A Ve rete saevus s 22 PayPallnvoicelter A e e eiiim ion 23 PayPalReceiverDetal Sica mette a neteme tt coca aa cata hc dette kai e de iue e REPE aes 23 Enumerated Values in the Mobile Payments Library eeeeesseseeeseeee nennen enne enne nnns 24 PayPal EVE np Dn EIS 24 FleldSizei i erret EH eren hp etr pe ae e eee ee a eines 24 PaymehtLyDe tere ter he e iis VERRE eR E ETE Y eden ERR VENE SE EY T ee 24 PaymentSubType RR n uai 25 Text Ty D ao ee ee itor eem cedo A A ate enean Sedet etn AAA EM nya reve eek eleva uxo et du eene te dd 25 Localization Support in the Mobile Payments Library esses eene enne nnne nnns 26 The Checkout Experience withthe Mobiles arene eeii ene E Ar E aE a R 28 Checkout Experience 1 Goods or Services with Shipping eese 28 Checkout Experience 42 Goods or Services without Shipping eese nnne 29 Checkout Experience 43 Donations cscccccccecssssssnsecececsesesssansececessesssusausececessessasaesececessenssasaeseceesess 30 Checkout Experience 44 Personal Send Money Payments s sccccccsssssesssaecececsssesesssseeeeseessessnssaeeeesens 31 Checkout Experience 5 Create Pin cccccssscccccecessessnaececececessesseaesececssesseaeaese
Download Pdf Manuals
Related Search