Home

PayPal Express Checkout - 2012 Advanced Features Guide

1. 101 Overview of Immediate Payment aoaaa a a ee 101 About Immediate Payment For Third Party Checkout a oaoa a a 101 Integrating Immediate Payment for Third Party Checkout aoaaa aa 103 The Call to SetExpressCheckout oaa aa 103 The Call to DoExpressCheckoutPayment aooaa aa a 104 About Immediate Payment For Express Checkout oaa oaa a a 104 Revision History aaao la ew TOT 6 April 2012Express Checkout Advanced Features Guide Preface About This Guide This document describes advanced features of Express Checkout integration Intended Audience This document is for merchants and developers implementing Express Checkout who want to learn about its extra features which can enhance their integrations with PayPal Where to Go for More Information e Express Checkout Integration Guide e Name Value Pair API Developer Guide e SOAP API Developer Reference e Merchant Setup and Administration Guide Documentation Feedback Help us improve this guide by sending feedback to documentationfeedback paypal com Express Checkout Advanced Features Guide April 2012 pe Documentation Feedback 8 April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout You can specify options in Express Checkout API requests that change the appearance behavior and flow of the checkout process PayPal Review Page Order Details When a buyer logs in
2. default CALLI The following is an example SetExpressCheckout request Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp PAYMENTREQUEST_0O_SHIPTONAME J Smith amp PAYMENTREQUEST_0_SHIPTOSTREET 1 Main St amp PAYMENTREQUEST_O_SHIPTOCITY San Jose amp PAYMENTREQUEST_O_SHIPTOSTATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOZIP 95131 amp L_PAYMENTREQUEST_0_NAME0 10 Decaf Kona Blend Coffee amp L_PAYMENTREQUEST_0_NUMBERO 623083 amp L_PAYMENTREQUEST_0_DESC0O Size 8 8 o0z amp L_PAYMENTREQUEST_0_AMTO0 9 95 amp L_PAYMENTREQUEST_0_QTY0 2 amp L_PAYMENTREQUEST_0_NAME1 Coffee Filter bags amp L_PAYMENTREQUEST_0_NUMBER1 6230 amp L_PAYMENTREQUEST_0_DESC1 Size Two 24 piece boxes amp L_PAYMENTREQUEST_0_AMT1 39 70 amp L_PAYMENTREQUEST 0 _OQTY1 2 amp L_PAYMENTREQUEST_0_ITEMWEIGHTVALUEO 0 5 amp L_PAYMENTREQUEST_0_ITEMWEIGHTUNITO l1bs amp PAYMENTREQUEST_0_ITEMAMT 99 30 amp PAYMENTREQUEST_O_TAXAMT 2 59 amp PAYMENTREQUEST_0_MAXAMT 150 00 amp PAYMENTREQUEST_0_SHIPPINGAMT 8 00 amp PAYMENTREQUEST_0_SHIPDISCAMT 3 00 amp PAYMENTREQUEST_0_AMT 107 89 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp ALLOWNOTE 1 amp CALLBACK https a
3. In step 6 call CreateBillingAgreement instead of DoExpressCheckoutPayment If you offer a store account you can control whether PayPal creates the billing agreement based on buyer signup To skip the creation of a billing agreement ID if the buyer does not sign up set SKIPBACREATION to true in the call to DoExpressCheckout The numbered steps correspond to the circled numbers Your site must take the specified actions at each step as follows Initiating a Payment Using a Reference Transaction After you establish a billing agreement you can initiate a payment which withdraws funds from the buyer s PayPal account without manual intervention Call DoReferenceTransaction to use a reference transaction 60 April 2012 Express Checkout Advanced Features Guide Reference Transactions 4 About Cancelling Agreements and Getting the Billing Address Call DoReferenceTransaction and include the following information e A reference ID that associates the buyer to a billing agreement Typically the ID is the billing agreement ID however you can also use the ID associated with a reference transaction e A payment action such as an authorization order or final sale e Payment details including the amount of the payment PayPal responds with a reference transaction ID that you can keep for future reference and other information about the transaction You most likely call DoReferenceTransaction in response to
4. e Streamline the checkout flow Existing partners and merchants with Express Checkout integrations can eliminate the current shipping options page e Use the default callback timeout Use the recommended 3 second callback response timeout e Follow PayPal defined semantics and syntax Adhere to well formed variable names and syntax rules in the callback response to PayPal If errors occur in the response PayPal uses the flat rate shipping options e Call GetExpressCheckoutDetails You must call GetExpressCheckoutDetails to find out what options the buyer selected e Ensure a consistent and good buyer experience With flat rate shipping options you should honor the rates to ensure a consistent and correct buyer experience e Localize shipping options Return localized shipping options based on the buyer s country and locale which PayPal sends in the callback request Related information PayPal Review Page Order Details on page 9 Express Checkout Advanced Features Guide April 2012 83 Implementing the Instant Update API Setting Up the Callback Setting Up the Callback To set up the callback establish a connection with PayPal by providing the location where PayPal calls your callback server along with your shipping options To start you must build and operate a secure reliable and fast callback server that computes shipping options corresponding insurance options and tax based on your busine
5. After creating a profile PayPal automatically queues payments based on the billing start date billing frequency and billing amount Payments reoccur until the profile expires there are too many failed payments to continue or you cancel the profile NOTE When using Express Checkout the buyer can also cancel a recurring payments profile PayPal funds queued payments using the normal payment method hierarchy within the buyer s PayPal account After creating a recurring payments profile you can view profile details or cancel the profile from your PayPal account You can also access recurring payments reports from the PayPal Business Overview page Also after creating a recurring payments profile you can use the Recurring Payments API to do the following e Get information details about a recurring payments profile e Change the status of a recurring payments profile e Update the details of the recurring payments profile e Bill the outstanding amount of the recurring payments profile Limitations The current release of the Recurring Payments API has the following limitations e A profile can have at most one optional trial period and a single regular payment period e The profile start date may not be earlier than the profile creation date Express Checkout Advanced Features Guide April 2012 43 4 Handling Recurring Payments Recurring Payments Terms Recurring Payments with Express Checkout also has the following limita
6. Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices El Jefe s Taco Stand x X My total 60 00 usp E Login PayPal a ED Log in with email and password myCustomer myDomain com E D E Pay with a card Go to the full PayPal website for checkout From the PayPal mobile login page the buyer can choose to log in to PayPal pay with a debit or credit card or log in to PayPal using the non mobile payment flow The buyer enters debit or credit card information on the billing page after clicking Pay with a card 3 Fill in all required fields and optional fields in the SetExpressCheckout request and call the SetExpressCheckout API operation 4 Redirect your buyer s browser to PayPal s mobile endpoint Related information About the Express Checkout Experience on Mobile Devices on page 29 Request Fields Supported by Express Checkout on Mobile Devices Express Checkout on mobile devices supports a subset of the API request fields that Express Checkout supports when it runs on personal computers PayPal ignores API request fields for features that Express Checkout does not support when it runs on mobile devices 36 April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices Poa Request Fields Supported by Express Checkout on Mobile Devices NVP Request Fields Supported by Express Checkout on Mobile Devices Expre
7. This feature is especially helpful to buyers who want to customize merchandise A buyer also might want to tell you to ship their order at a later date because they are out of the country NOTE Users of this feature should be sure to read the instructions the buyer sends This feature appears as the link on the Review your information page When the buyer clicks Add a Note to seller text box opens in which the buyer can enter special instructions to the merchant and click Save The instructions are returned in the responses to GetExpressCheckoutDetails and DoExpressCheckoutPayment Integrating Order Details into the Express Checkout Flow To integrate order details into the checkout flow pass any of the following Express Checkout parameters to SetExpressCheckout NVP Field SOAP Field Description and Comments PAYMENTREQUEST_n_NAMEMm Name Item name PAYMENTREQUEST_n_NUMBERM Number Item number PAYMENTREQUEST_n_DESCm Description Item description The DESC NVP and OrderDescription SOAP fields still exist for backwards compatibility However L_DESCn and Description enable you to provide a more precise description for each different item purchased such as hiking boots or cooking utensils rather than one general purpose description such as camping supplies Express Checkout Advanced Features Guide April 2012 11 a Customizing Express Checkout P
8. e By design it does not support non instant funds such as Electronic Funds Transfer eCheck or ELV e Itis open for use by all merchants whether or not they are selling on eBay e Sale is the only payment action supported April 2012 Express Checkout Advanced Features Guide Immediate Payment a Integrating Immediate Payment for Express Checkout Integrating Immediate Payment for Express Checkout Immediate Payment for Express Checkout requires that you specify one value for ALLOWEDPAYMENTMETHOD in the Express Checkout API 1 In the call to the SetExpressCheckout API operation you set PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD to InstantPaymentoOnl y 2 Optional You can call GetExpressCheckoutDetails to obtain information about the buyer 3 In the call to DoExpressCheckoutPayment you set PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD to InstantPaymentoOn1y Express Checkout Advanced Features Guide April 2012 105 10 Immediate Payment Integrating Immediate Payment for Express Checkout 106 April 2012 Express Checkout Advanced Features Guide Revision History Revision history for PayPal Express Checkout Advanced Features Guide Date Description 03 22 2012 Updated graphics and information related to account optional checkout on mobile devices 02 13 2012 Updated user experience graphics 06 21 2011 Added chapters on recurring payments and reference transactions and changed the order of chapters in t
9. including any shipping or tax amount If for example you create a profile on March 10 with a total amount of 100 during the 180 day interval from March 10 to September 6 you can increase the amount to a maximum of 120 120 of 100 Suppose that during the first 180 day interval you increased the payment amount to 110 During the next 180 day interval starting September 7 you can only increase the amount of the payment to a maximum of 132 120 of 110 April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Billing the Outstanding Amount of a Profile Billing the Outstanding Amount of a Profile Use the BillOutstandingAmount API to immediately bill the buyer for the current past due or outstanding amount for a recurring payments profile NOTE You can also bill the buyer for the current past due or outstanding amount for a recurring payments profile from the PayPal website To bill the outstanding amount e The profile status must be active or suspended NOTE The BillOutstandingAmount API does not reactivate a suspended profile You need to call ManageRecurringProfileStatus to do this e The profile must have a non zero outstanding balance e The amount of the payment cannot exceed the outstanding amount for the profile e The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile NOTE Anerror occurs when another outstanding ba
10. merchant specific messages such as charged now You 11 later cancellation charges for post paid offline make a payment directly to transactions This information does not merchant name display on the PayPal Review page If you cancel the order Instead it appears in the buyer s email and in Transaction Details Note to merchant Do not use the ALLOWNOTE parameter It is ignored for parallel payments Pass at least the primary information below PayPal recommends that you also pass the secondary information If the style of payment is a reservation with deposit pass the deposit only in the item description Express Checkout Advanced Features Guide April 2012 73 74 Implementing Parallel Payments Handling Errors Recommended item description information Merchant Item description information Flight Hotel Insurance Cruise Primary information Flight No Departure Location Date amp Time Arrival Location Date amp Time Secondary information Duration Terminal No Distance Primary information Location Check in Date Checkout Date Secondary information Check in Time Room Type Bed Size Primary information Pickup Location Date amp Time Drop off Location Date amp Time Secondary information Car Model amp Make Telephone No Primary information Insurance Company Name amp Description Primary information Date Time amp Description Handling Errors I
11. Advanced Features Guide April 2012 21 Customizing Express Checkout Handling Shipping Addresses Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The following figure shows the Log in to PayPal page when the is set to ES The following figure shows the PayPal Choose a way to pay page when the LOCALECODE is set to ES Resumen de su pedido Seleccione una forma de pago Descripciones TAANA v Pagar con mi cuenta PayPal PayPal Correo electr nico harsingh us per paypal com Podr ver los datos de su pedido antes de pagar Contrase a de PayPal Problemas para iniciar sesi n gt Pagar con una tarjeta de d bito o de cr dito Si no dispone de una cuenta PayPa Cancelar y volver a Joe s Generic Business Comentarios Handling Shipping Addresses You can specify several shipping address options that affect the PayPal pages In your SetExpressCheckout request you can specify the following options e Require a confirmed address e Do not display the shipping address on the review page e Display an alternative address on the review page April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout oa Handling Shipping Addresses Confirmed Address A confirmed address is a shipping address that PayPal has established as belonging to the PayPal account holder To be protected by PayPal s Seller Protection Policy you must require the shipping address to be a con
12. File bags temdescrp len Se Two 24 plece tem number 6230 Item price 39 70 Quantity 2 Express Checkout Advanced Features Guide Item total Tax Shipping and handling Shipping diecourt haurarce Total 107 89 USD April 2012 About the Instant Update API 81 Implementing the Instant Update API How the Callback Works in the Express Checkout Flow How the Callback Works in the Express Checkout Flow The Express Checkout flow is initiated on your shopping cart page when the buyer clicks Checkout with PayPal Callback integrated into Express Checkout flow uLS a mmm mmm Place Order gt Confirmation gt gt A A O Order o CT PayPal Tas aatas analar ay to pay AJAX Call Merchant Redirects to PayPal PayPal Server t O a OO SetEC TOKEN Shipping Shipping GetEC DoEC Callback URL Address Options Flat Rate Token Options Line Item Details 4 4 Merchant System Merchant Callback Server API Call to Carriers From left to right the following events are represented 1 The Express Checkout flow is initiated on your shopping cart page when the buyer clicks Checkout with PayPal 2 In the call to the SetExpressCheckout API operation you provide the URL where PayPal can call your callback server the flat rate shipping options and cart line item details 3 You retrieve the token from the response 4 You redirect the buyer s browser to PayPal 5 When the buyer
13. appearance of the PayPal pages by defining a custom page style or by customizing individual page style characteristics You define a custom page style in your profile and pass the resulting page style name when you call SetExpressCheckout Typically you customize individual page style characteristics in your profile as well However you can also call SetExpressCheckout and pass in individual page characteristics dynamically Custom Page Style When your buyer logs in to PayPal to check out you can make the PayPal pages the buyer sees appear to have a similar look and feel to those on your website You can customize any of these page characteristics and save the results as a Page Style Name You can define up to three unique Page Style Names in which you can specify the following characteristics e Header image e Header border color e Header background color e Page background color For instructions on how to customize page styles and create Page Style Names see the Merchant Setup and Administration Guide To set a custom page style in a call to SetExpressCheckout 1 Include the optional PAGESTYLE parameter in the call to SetExpressCheckout 2 Set PAGESTYLE to the Page Style Name you defined in your account The following example sets PAGESTYLE to the Page Style Name April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout oa PayPal Page Style Request Parameters
14. billing agreement To cancel an agreement call BAUpdate and include the following information e A reference ID that associates the buyer to a billing agreement Typically the ID is the billing agreement ID however you can also use a ID from a reference transaction e Anaction which must be Canceled in the BillingAgreementStatus field PayPal responds with the billing agreement ID and other information about the buyer whose agreement was canceled Although a buyer can log in to PayPal to manage agreements the BAUpdate API operation enables the buyer to cancel the agreement from your site without logging in to PayPal You can provide your own page for maintaining agreements with the buyer The following diagram shows the message flow to cancel a billing agreement from your page Legend gt API Call Agreement ID Merchant Website m f Request Cancel h E Agreement Agreement ID BAUpdate PayPal 4 Response API Server Cancel Agreement ID Agreement ID Obtaining the Most Recent Billing Address You can use BAUpdate NVP METHOD Bil 1lAgreement Update to obtain the buyer s most recent billing address NOTE This feature applies to all new and existing reference transaction based billing agreements and preapproved payment originated agreements To obtain the billing address call BAUpdate without passing a value in the BillingAgreement Status field The billing address is returned in the BAUpdate re
15. first logs in to the PayPal site PayPal obtains the buyer s shipping address and sends it in the callback request shown as the red down arrow to your callback server at the specified URL 82 April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API Following Instant Update API Best Practices NOTE If the buyer changes their shipping address on the PayPal pages during checkout PayPal will make subsequent requests to the callback server 6 Your callback server responds with the shipping option rates shown by the red up arrow based on the buyer s shipping address You can also adjust the tax amount and send insurance options Depending on your business processes you may send an API call to your carrier to calculate the rates and options based on the shipping address 7 PayPal updates the cart review area and Review your information page content to show the options and rates based on your response 8 The buyer makes final selections and clicks Continue 9 You must call GetExpressCheckoutDetails to obtain the buyer s final shipping option selections 10 You call DoExpressCheckoutPayment to perform the transaction Following Instant Update API Best Practices PayPal recommends its list of best practices as a checklist for completing your implementation of the Instant Update API e Meet the prerequisites Provide order line item details to take advantage of the Instant Update API
16. flow as in the case of purchasing a mobile phone purchase or downloading a music video Or the buyer can agree before initiating a payment as in the case of signing up for automatic utility payments PayPal creates a billing agreement ID that represents the agreement The billing agreement ID is also associated with a transaction You can use the billing agreement ID to derive a subsequent transaction in the same way that you use a reference transaction ID A reference transaction must have occurred within the past 365 days because the ID may not be available after a year The billing agreement ID does not establish a time frame It is good until canceled by the buyer A buyer may have more than one billing agreement ID for your site This could occur if the buyer established separate agreements for different kinds of service If you use a reference transaction ID to initiate a reference transaction you must make sure that the ID is associated with the correct billing agreement To avoid confusion PayPal recommends that you use the billing agreement ID whenever it is available instead of the reference transaction ID API Operations for Reference Transactions Several API operations implement recurring payments using reference transactions e Express Checkout API operations enable you to set up a billing agreement as part of the checkout processing as in the examples of a mobile phone purchase or a music video download These operations elim
17. grupellc com payme payme payme payme items for payment2 PaymentDetailsItemType payment2_items_array new PaymentDetailsItemType 2 entDetailsItemType payment2_iteml new PaymentDetailsItemType ent2_iteml Amount new BasicAmountType ent2_iteml Amount currencyID CurrencyCodeType USD ent2_item1 Amount Value 1 00 ent2_iteml Description payment2_iteml_desc payment2_item1l Name payment2_iteml_name payment2_item1 Number payment2_iteml_number payment2_iteml Quantity 1 e e e e e e e e e e n e n e Paym paym paym paym paym 1 1 1 l 1 1 PaymentDetailsItemType payment2_item2 new PaymentDetailsItemType payment2_item2 Amount new BasicAmountType paym 2 Amount currencyID CurrencyCodeType USD paym 2 Amount Value 1 00 payment2_item2 Description payment2_item2_desc payment2_item2 Name payment2_item2_name 2 2 Ss Ss nt2_item nt2_item payment2_item2 Number payment2_item2_number nt2_item2 Quantity 1 nt2_items_array SetValue payment2_iteml 0 nt2_items_array SetValue payment2_item2 1 bind the items payment2 PaymentDetailsItem payment2_items_array mandatory for api call nt2 PaymentRequestID System Guid NewGuid ToString paym paym paym paym set the totals decimal tax_total2 0 decimal item_total2 0 foreach PaymentDetailsI
18. iveProfile status However if a non recurring initial payment fails and you set FAILEDINITAMTACTION to CancelOnFailure in the CreateRecurringPayment sProfile request PayPal creates the profile with a status of PendingProfile The profile remains in this status until the initial payment either completes successfully or fails A profile has a status of ExpiredProfile when PayPal completes the total billing cycles for the optional trial and the regular payment periods You can suspend or cancel a profile by using the ManageRecurringPaymentsProfileStatus API You can also reactivate a suspended profile If PayPal has already reached the maximum number of failed payments however you must increase the number of failed payments before reactivating the profile April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Getting Recurring Payments Profile Information NOTE You can also suspend cancel or reactive a recurring payments profile through the PayPal website For recurring payments profiles created with the Express Checkout API the buyer receives an email about the change in status of their recurring payment Getting Recurring Payments Profile Information Use the Get RecurringPaymentsProfileDetails API to obtain information about a profile NOTE You can also get information about recurring payments profiles from the PayPal website Along with the information that you specified i
19. only 30 April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices Poi About Mobile Express Checkout Integration Supported Mobile Devices Software Versions Android based devices All iPhone 2 3G 3GS 4 iPhone OS 2 x 3 x iOS 4 0 iPod touch 2G 3G iPhone OS 2 x 3 x iPad iPad 2 All BlackBerry Research in Motion BlackBerry OS version 4 6 and higher About Mobile Express Checkout Integration PayPal supports several implementations of Mobile Express Checkout You can provide a complete mobile website or you can create a mobile phone app in which the checkout button is integrated into the app itself or is on your mobile website Your preferred integration determines what you must do to convert an existing Express Checkout integration to provide a mobile experience Typically your decision depends on whether you create a native app for the devices you want to support e If you are not providing an app you must modify your pages to the recommended size for your device When a buyer uses Express Checkout to check out PayPal attempts to determine whether the buyer is using a mobile device and the kind of device and redirects the mobile browser to PayPal s mobile Express Checkout webpages The call to SetExpressCheckout occurs as a result of the buyer clicking Checkout with PayPal e If you are providing an app you must include the Mobile Express Checkout Library in your app and init
20. purchase PayPal offers two applications of Immediate Payment Use the one that is appropriate for your integration e Immediate Payment for third party checkout For third parties who sell items on eBay and host Express Checkout on their website e Immediate Payment for Express Checkout For any merchant who integrates Express Checkout About Immediate Payment For Third Party Checkout Immediate Payment for third party checkout ensures that the buyer pays for an item you are selling on eBay at the time the buyer commits to it You add a few Express Checkout parameters to your integration and use your own off eBay checkout flow NOTE This feature is available with API version 60 0 and higher The SetExpressCheckout request parameters ensure the eBay item is available to ship to the buyer when you call DoExpressCheckoutPayment The successful transaction returns the eBay transaction ID as an additional parameter value in the DoExpressCheckoutPayment response NOTE PayPal recommends that you do not mix eBay and non eBay items in an immediate payment transaction Immediate Payment for third party checkout has the following caveats e By design it does not support non instant funds such as Electronic Funds Transfer eCheck or ELV e Itis limited to Express Checkout for eBay auctions only e Itis limited to processing a single payment per transaction the buyer can check out with only one item at a time e Sale is
21. the Buyer to PayPal After you receive a successful response from SetExpressCheckout add the TOKEN from the SetExpressCheckout response as a name Vvalue pair to the following URL and redirect your buyer to it https www paypal com cgi bin webscr cmd _express checkout amp token lt value_returned_by_SetExpressCheckoutResponse gt When redirecting the buyer to PayPal PayPal recommends that you use the HTTPS response 302 Object Moved with the URL as the value of the Location header in the HTTPS response Make sure that you use an SSL enabled server to prevent browser warnings about a mix of secure and insecure graphics 50 April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Recurring Payments With the Express Checkout API Getting Buyer Details Using GetExpressCheckoutDetails The GetExpressCheckoutDetails method returns information about the buyer including name and email address stored on PayPal You can optionally call this API after PayPal redirects the buyer s browser to the ReturnURL you specified in the SetExpressCheckout request The GetExpressCheckoutDetails request has one required parameter TOKEN which is the value returned in the SetExpressCheckout response PayPal does not return the values you specified for the following parameter fields in the GetExpressCheckoutDetails response unless the transaction includes a purchase PayPal ignores the fields if
22. to PayPal to check out you can present the buyer with detailed information about each item being purchased PayPal order details are available with API version 53 0 or later NOTE The DoExpressCheckoutPayment request includes the same order details as SetExpressCheckout PayPal recommends that you submit the same parameters in both API calls The following diagram shows all of the details that you can include Express Checkout Advanced Features Guide April 2012 a Customizing Express Checkout PayPal Review Page Order Details Your order summary Descriptions Amount 0 Decaf Kona Blend Coffee 19 90 6 We offee Fiker Bags 79 40 ize Two 24 piece Item total 99 3 EO Tax 2 58 Shipping and handing 5 99 M 8 3 00 Shipping discount 1 00 Bo Total 105 87 USD nsurance 1 Item name The item name can identify this item to distinguish it from other line items in the order 2 Item number Each item can be further identified by an item number If the item is an eBay auction item it is recommended that you provide the eBay item number in this field 3 Item description This field identifies which of several items the buyer is purchasing For example you may be offering an item in different sizes Knowing the size helps the buyer decide whether the one they selected was appropriate If the item is an eBay auction item it is recommended that you provide the phrase eBay item in this fiel
23. to receive promotional email is available with API Version 61 0 or later To obtain the buyer s email address set the BUYEREMATLOPTINENABLE field to 1 in the call to SetExpressCheckout The following request example sets this field Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp BUYEREMAILOPTINENABLE 1 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706495P The following figure shows how this appears to the buyer in the cart review area Express Checkout Advanced Features Guide April 2012 15 a Customizing Express Checkout Overriding Your Customer Service Number Your order summary Descriptions Current purchase You ll be able to see your order details before you pay I Fd like to receive special offers and promotional emails from Joe s Generic Business Optional NOTE You can also configure this feature in your profile For details see the Merchant Setup and Administration Guide Overriding Your Customer Service Number You can display your Customer Service number to the buyer on Express Checkout pages by configuring it in your profile You can override this number by specifying another number in the Set
24. up a secure fast web service to accept HTTP requests from PayPal On the live site it needs to be secured by means of SSL 2 Enable the callback service to process PayPal requests and return responses 3 Modify the existing Express Checkout API calls to accommodate new parameters Send the callback URL shipping insurance and tax information to PayPal in the call to SetExpressCheckout Call GetExpressCheckoutDet ails to obtain the buyer s final choices for shipping and insurance if applicable Call DoExpressCheckoutPayment with the buyer s final selections Express Checkout Advanced Features Guide April 2012 79 Implementing the Instant Update API About the Instant Update API 4 Eliminate your shipping options page 5 Test your integration for the callback and flat rate shipping options Post Integration Checkout Experience After you integrate the Instant Update API you can display the shipping options related insurance options and the tax amount You control what to display which is instantly updated on the page The shipping options related insurance options and the tax amount appear on the page as follows 80 April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API Joe s Generic Business Your order summary Nescziptinias Amant 10 Decaf Kona Elend Coffee tem deacrpcicn Sec 8 02 Mem number 623085 item price 9 95 Quantity 2 70 90 Colles
25. API request on behalf of this merchant By default PayPal displays the default Check out with PayPal button Optional The total cost of the order to the buyer If shipping and sales tax are known include them in this value If not this value should be the current subtotal of the order By default PayPal does not display the incentive image even if the buyer is eligible for the incentive Character length and limitations Must not exceed 10 000 00 USD in any currency Do not specify the currency symbol You must include two decimal places The decimal separator must be a period and the optional thousands separator must be a comma Optional The five character locale code See Locale Codes and Priorities Any other values default to US NOTE The merchant can participate in one campaign per country Optional Indicates a dynamic image The values are e Check out with PayPal button image ecshortcut default e PayPal mark image ecmark Locale Codes and Priorities A country code is the two letter code for the country Language priority is the language associated with the country code where Language_0 is the default priority Country code Language priority Locale AT language_0O de_DE AT language_1 en_US AU language_0O en_AU BE language_0O en_US BE language_1 nl NL BE language_2 fr_FR April 2012 Express Checkout Advanced Features Guide Express Checkout Dynamic Image Integration e Dynamic Image Command R
26. ATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOZIP 95131 amp PAYMENTREQUEST_0_SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 6UA07551EA393551U Suppressing the Buyer s Shipping Address You can suppress the display of the buyer s shipping address on the PayPal pages You might want to do this in these cases e You are selling a product or service that does not require shipping Express Checkout Advanced Features Guide April 2012 23 24 Customizing Express Checkout Handling Shipping Addresses e You prefer to handle addresses completely on your own and do not want to let buyers choose from their PayPal address book To suppress the display of the buyer s shipping address set the NOSHIPPING parameter to 1 in the call to SetExpressCheckout No shipping address displays on Express Checkout pages The following example suppresses the shipping address Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout S amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp NOSHIPPING 1 amp PAYMENTREQUEST_0_SHIPTONAME J Smith amp PAYMENTREQUEST_0_SHIPTOSTREET 1 Main St amp PAYMENTREQUES
27. April 2012 77 o 6 Integrating giropay with Express Checkout giropay Integration 78 April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API The Instant Update API is a callback you can use to obtain the buyer s shipping address About the Instant Update API The Instant Update API is a server call to your callback server that instantly updates PayPal pages and enhances the Express Checkout experience on the Review your information page The Instant Update API enables you to specify a URL with which PayPal can call your callback server with the buyer s shipping address so you can provide the buyer with more detailed shipping insurance and tax information Here is how the Instant Update API works 1 When a buyer logs in to PayPal the PayPal server calls your callback server with the buyer s default shipping address which is stored in the PayPal system 2 Your callback server responds with the shipping options available for that address along with any insurance options and tax adjustments on the order 3 PayPal displays this information in the cart review area so buyers can choose from the options 4 The buyer s final choices are returned in the GetExpressCheckoutDetails response Integration Steps Integrating the Instant Update API requires some preparation and modification to the Express Checkout API calls To integrate the server API follow these steps 1 Set
28. CANCELURL http amp PAYMENTREQUEST_O_CURRENCYCODE USD amp PAYMENTREQUEST_0O_AMT 300 amp PAYMENTREQUEST_0O_ITEMAMT 200 amp PAYMENTREQUEST_O_TAXAMT 100 amp PAYMENTREQUEST_O_DESC Summer Vacation trip amp PAYMENTREQUEST_0O_INSURANCEAMT 0 amp PAYMENTREQUEST_0O_SHIPDISCAMT 0 amp PAYMENTREQUEST_0O_SELLERPAYPALACCOUNTID seller 139 paypal com amp PAYMENTREQUEST_0O_INSURANCEOPTIONOFFERED false amp PAYMENTREQUEST_0O_PAYMENTACTION Order amp PAYMENTREQUEST_0O_PAYMENTREQUESTID CART26488 PAYMENTO amp PAYMENTREQUEST_1_ CURRENCYCODE USD amp PAYMENTREQUEST_1_AMT 200 amp PAYMENTREQUEST_1_ITEMAMT 1 80 amp PAYMENTREQUEST_1_SHIPPINGAMT 0 amp PAYMENTREQUEST_1_HANDLINGAMT 0 amp PAYMENTREQUEST_1_TAXAMT 20 amp PAYMENTREQUEST_1_DESC Summer Vacation trip amp PAYMENTREQUEST_1_INSURANCEAMT 0 amp PAYMENTREQUEST_1_SHIPDISCAMT 0 amp PAYMENTREQUEST_1_SELLERPAYPALACCOUNTID seller 140 paypal com amp PAYMENTREQUEST_1_TINSURANCEOPTIONOFFERED false amp PAYMENTREQUEST_1_PAYMENTACTION Order amp PAYMENTREQUEST_1_PAYMENTREQUESTID CART26488 PAYMENT1 amp L_PAYMENTREQUEST_O_NAME0 Depart San Jose Feb 12 at 12 10PM Arrive in Baltimore at 10 22PM amp L_PAYMENTREQUEST_O_NAMF1 Depart Baltimore Feb 15 at 6 13 PM Arrive in San Jose at 10 51 PM amp L_PAYMENTREQUEST_O_NUMBERO Flight 522 amp L_PAYMENTREQUEST_O_NUMBER1 Flight 961 amp L_PAYMENTREQUEST_0O_OTY0 amp L_PAYMENTREQUEST_O_OTY1 1 amp L_PAYMENTREQUEST_0O_TAXAMTO 50 amp L_PAYMENTREQUE
29. Checkout 4 Confirms the order and pays on your mobile website or app 5 Views order confirmation on your mobile site or app NOTE To pay with debit or credit cards buyers click the pay by card at the bottom of the login page to enter their billing information this flow is called PayPal account optional checkout Buyer Pays on PayPal You can shorten the Express Checkout experience on mobile devices by letting buyers pay on PayPal Merchant Mobile Page PayPal Mobile Page EEE cog m _ _ D e e o p gt _ Pay Now _ b Shopping cart Log in to pay Review your Order Buyer pays Buyers with information confirmation with PayPal Buyer confirms Buyer views purchase details order confirmation before continuing When buyers pay on PayPal the buyer 1 Clicks Checkout with PayPal on your mobile website or from your app 2 Enters login credentials on the mobile PayPal login page and then clicks Log in 3 Reviews payment details on the mobile PayPal review page and then presses Pay Now 4 Views order confirmation on your mobile site or app Related information Enabling PayPal Account Optional Checkout on Mobile Devices on page 34 Mobile Platforms Supported by Express Checkout Express Checkout supports the mobile checkout experience on specific mobile devices and their embedded mobile browsers
30. ExpressCheckout request NOTE This feature is available with API Version 61 0 or later Displaying your Customer Service number to the buyer enables you to quickly answer the buyer s questions through a telephone call To override the Customer Service number configured in your profile with a different number on Express Checkout pages set the CUSTOMERSERVICENUMBER field in the call to SetExpressCheckout The following request example sets this field 16 April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout oe Adding a Survey Question Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp CUSTOMERSERVICENUMBER 1 800 F LOWERS Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P NOTE For details on configuring the Customer Service number on the PayPal Profile page see the Merchant Setup and Administration Guide Adding a Survey Question You can add one survey question to the PayPal pages PayPal returns the choice that the buyer selected in the response to GetExpressCheckoutDetails and DoExpressCheckoutPayment NOTE This feature is available with API Version 61 0 or later The survey question displays i
31. Pay with debit or credit card section expanded with the buyer shipping and contact fields filled out 26 April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout Automatically Filling Out Shipping and Contact Information gt Pay with my PayPal account v Pay with a debit or credit card If you dont have a PayPal account Credit card number Payment types Expiration date csc What is this Billing information Contact information United States v ve ES mas yy I J Smith 1 Main St San Jose CA 95131 United States Change 408 559 5948 jsmith01 example com Change I Save your information with PayPal This transaction will appear on your statement as JOESGENERIC Secure payments by PayPal Cancel and return to Joe s Generic Business Express Checkout Advanced Features Guide April 2012 27 28 Customizing Express Checkout Buyer Pays on PayPal Buyer Pays on PayPal With Express Checkout you can shorten your checkout flow to let buyers complete their purchases on PayPal Then you can skip your order confirmation page Generally buyers select payment methods as the last step before they complete their purchases If you collect no additional information after buyers return from PayPal you can skip the confirm order page on your website If you collect additional information that does not affect the payment PayPal recommends that you collect it after buy
32. PayPal Express Checkout Advanced Features Guide PayPal Express Checkout Advanced Features Guide Document Number 10121 en_US 201204 2010 2012 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 des
33. REQUEST_n_SHIPDISCA SHIPPINGDISCAMT deprecated MT PAYMENTREQUEST_n_HANDLINGA HANDLINGAMT deprecated PAYMENTREQUEST_nN_TAXAMT MT TAXAMT deprecated PAYMENTREQUEST_nN_DESC DESC deprecated PAYMENTREQUEST_nN_CUSTOM CUSTOM deprecated PAYMENTREQUEST_n_INVNUM INVNUM deprecated BUTTONSOURCE PAYMENTREQUEST_n_NOTIFYURL NOTIFYURL deprecated PAYMENTREQUEST_nN_NOTETEXT NOTETEXT deprecated PAYMENTREQUEST_n_TRANSACTI TRANSACTIONID deprecated PAYME NTREQUEST_nN_ALLOWEDPA ONID YMENTME THOD ALLOWEDPAYMENTME THOD PAYMENTREQUEST_n_PAYMENTAC PAYMENTACTION deprecated deprecated TION PAYMENTREQUEST_n_PAYMENTRE PAYMENTREQUESTID deprecated QUESTID NVP Payment Deiails ltem Type Fields Supported by Express Checkout on Mobile Devices L_PAYMENTREQUEST_n_NAMEm NAMEN deprecated L_PAYMENTRE QUEST_nN_DESCM DESCn deprecated L_PAYMENTREQUEST_n_AMTm L_AMTn deprecated L_PAYMENTREQUEST_n_NUMBERMm L NUMBERN deprecated L_PAYMENTREQUEST_n_OTYm L_OTYn deprecated L_PAYMENTREQUEST_n_TAXAMTm L_TAXAMTn deprecated L_PAYMENTREQUEST_n_ITEMWEI _ I TEMWEIGHTVALUEN and L_PAYMENTREQUEST_nN_ITEMURL GHTVALUEm and ITEMWETGHTUNITnN m L_PAYMENTREQUEST_nN_ITEMWEI deprecated T ITEMURLn deprecate
34. STID value you passed in the DoExpressCheckoutPayment request Use this value to locate the response data for each payment e A PAYMENT INFO_N_ S ELL ERPAYPALACCOUNTID This value is whichever one of the following values was passed in The merchant s email address The merchant s Payer ID secure merchant account ID 66 April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments T Integrating Parallel Payments by Using the NVP API If errors are returned check the response data in the PAYMENTERROR field for each payment It is possible that errors are returned only for a subset of the payments while other payments are successful For failed payments you should ask the buyer for an alternate payment method Example The following is an example SetExpressCheckout request with parallel payments integrated Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp
35. ST_0O_TAXAMT1 50 amp L_PAYMENTREQUEST_0O_AMT0O 50 amp L_PAYMENTREQUEST_0O_AMT1 150 Express Checkout Advanced Features Guide April 2012 67 ie Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API amp L_PAYMENTREQUEST_O_DESCO SJC Terminal 1 Flight time 7 hours 12 minutes amp L_PAYMENTREQUEST_O_DESC1 BWI Terminal 1 Flight time 7 hours 38 minutes amp L_PAYMENTREQUEST_1_NAMEO0O Night s stay at 9990 Deereco Road Timonium MD 21093 amp L_PAYMENTREQUEST_1_NUMBERO 300 amp L_PAYMENTREQUEST_1_ OTYO 1 amp L_PAYMENTREQUEST_1_TAXAMT0 20 amp L_PAYMENTREQUEST_1_AMTO 180 amp L_PAYMENTREQUEST_1_DESCO King No Smoking Check in after 4 00 PM Check out by 1 00 PM Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Integrating Parallel Payments by Using the SOAP API Parallel payments uses the PaymentDetailsType structure to pass data for each merchant receiving payment You can pass up to a 10 structures in a single call to SetExpressCheckout and DoExpressCheckoutPayment NoTE Besure to use structure fields that are not marked as deprecated in the SOAP API reference documentation To integrate parallel payments by using the SOAP interface to Express Checkout 1 Create PaymentDetails as an array of PaymentDetailsType structures o
36. TIONISDEFAULT1 true PPINGOPTIONNAME2 UPS Ground2 to 7 Days PPINGOPTIONAMOUNT2 9 99 2 1 99 URANCEAMOUNT2 1 28 PP INGOPTIONISDEFAULT2 false n U H H WN D A TIEFE H wn I wn I vn H Go HHHU wn I Hw za I T S RR R SI S SM SI SM SM SM SI R R KL Ew Et aS Ew ot ea et ee a Ee Peto de Et S S O O DG S S R DWH I H Express Checkout Advanced Features Guide April 2012 89 Implementing the Instant Update API Using the Callback 90 April 2012 Express Checkout Advanced Features Guide Payment Review Payment Review is an Express Checkout feature that identifies high risk transactions and notifies you so that you can hold shipments until the risk has been evaluated by PayPal Handling Payment Review You are immediately notified that a payment is under review and you should not ship merchandise or in the case of electronic media you should not allow download access while the payment is under review You are notified of the resolution within 24 hours NOTE Payment Review is not applicable to Direct Payment You can determine the status of a payment in the following ways e By logging in to https www paypal com and viewing the status information in the Transaction History e By email sent by PayPal e By Instant Payment Notification IPN message e By Payment Data Transfer PDT message e By checking the status of a transactio
37. TIONNAME TYM Provide values for the flat rate shipping options n L_SHIPPINGOPTIONISDEFAULTn n and L_SHIPPINGOPTIONAMOUNTn Set PAYMENTREQUEST_n_SHIPPINGAMT to the amount set for the default flat rate shipping option If for example L_SHIPPINGOPTIONISDEFAULTO t rue and L_SHIPPINGOPTIONAMOU PAYMENTREQUEST_O_SHI NTO 8 00 then PPINGAMT 8 00 Set MAXAMT to the expected maximum total amount of the complete order April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API Using the Callback NOTE PayPal recommends that the maximum total amount be slightly greater than the sum of the line item order details tax and the shipping option of greatest value e Optionally provide values for the following parameters Set PAYMENTREQUEST_n_INSURANCEOPTIONOFFER you are offering insurance options Otherwise set PAYMENTREQUEST_nN_INSURANCEOPTIONSOFFERED to false ED to true to inform PayPal that T EMW G i LGHTUNI Set line item description details such as L_PAYMENTR and L_ PAY EQU EST_N_I ENTREQUEST_N_ITEMWEIGHTVALUEO shown in the example below TO Set CALLBACKTIMEOUT to the amount of time in seconds to process the callback By
38. T_0_SHIPTOCITY San Jose amp PAYMENTREQUEST_0_SHIPTOSTATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOZIP 95131 amp PAYMENTREQUEST_0_SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The PayPal Review your information page does not display a shipping address when NOSHIPPINGis set to 1 Shipping Address Override You can override the buyer s shipping address stored on PayPal You would want to do this if for example your website registration already requested the buyer s shipping address Overriding the shipping address stored on PayPal replaces it with one you specify in the call to SetExpressCheckout The buyer cannot edit the overridden address NOTE If you prefer to override addresses PayPal recommends that you do not require confirmed addresses as described in Confirmed Address To override the shipping address 1 Set the ADDROVERRIDE parameter to 1 in the call to SetExpressCheckout 2 Set the following shipping address parameters in the call to SetExpressCheckout to the address values you want to use for the new address PAYMENTREQUEST_O_SHIPTONAME PAYMENTREQUEST_O_SHIPTOSTREET April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout Automatically Filling Out Shipping and Contact Informatio
39. Tax currencyID CurrencyCodeType USD payment1_item1 Tax Value 50 PaymentDetailsItemType paymentl_item2 new PaymentDetailsItemType payment1l_item2 Amount new BasicAmountType payment1_item2 Amount currencyID CurrencyCodeType USD payment1l_item2 Amount Value 1 00 payment1l_item2 Description paymentl_item2_desc paymentl_item2 Name payment1_item2_name Express Checkout Advanced Features Guide April 2012 69 ie Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API paymentl_item2 Number payment1_item2_number payment1l_item2 ItemURL http item2 com payment1l_item2 Quantity 2 payment1l_item2 Tax new BasicAmountType payment1l_item2 Tax currencyID CurrencyCodeType USD payment1l_item2 Tax Value 25 payment1_items_array SetValue paymentl_iteml 0 payment1_items_array SetValue paymentl_item2 1 bind the items payment1 PaymentDetailsItem paymentl_items_array set the totals decimal tax_total 0 decimal item_total 0 foreach PaymentDetailsItemType Key in payment1l_items_array if Key Tax null tax_total decimal Add tax_total decimal Multiply decimal Parse Key Tax Value decimal Parse Key Quantity if Key Amount null item_total decimal Add item_total decimal Multiply decimal Parse Key Amount Value decimal Parse Key Quantity
40. _0_TAXAMT 2 58 amp PAYMENTREQUEST_0_SHIPPINGAMT 3 00 amp PAYMENTREQUEST_0_HANDLINGAMT 2 99 amp PAYMENTREQUEST_0_SHIPDISCAMT 3 00 amp PAYMENTREQUEST_0_INSURANCEAMT 1 00 amp PAYMENTREQUEST_0_AMT 105 87 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp ALLOWNOTE 1 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Related information Providing Gift Options on page 13 Following Instant Update API Best Practices on page 83 Setting Up the Callback on page 84 Providing Gift Options You can provide the buyer with gift options on PayPal To use this feature you must implement line item details NOTE Gift options are available with API Version 61 0 or later You can enable any of the following gift options e Gift message This feature displays a text box in which the buyer can enter a gift message e Gift receipt This feature provides a checkbox for the buyer to check if they would like a gift receipt included Express Checkout Advanced Features Guide April 2012 13 il Customizing Express Checkout Providing Gift Options e Gift wrap This feature provides a checkbox for the buyer to check if they would like to have the gift wrapped The gift wrap feature can include a label describing the gift wrapping for example Decorator box and bow Optionally you can provide the amount to be charged to the buyer for gift wrapping T
41. a pending status until the initial payment completes If the initial payment clears PayPal notifies you by Instant Payment Notification IPN that it has activated the pending profile If the payment fails PayPal notifies you by IPN that it has canceled the pending profile If you created the profile using Express Checkout the buyer receives an email stating that PayPal cleared the initial payment or canceled the pending profile Maximum Number of Failed Payments By including the MAXFAILEDPAYMENTS field in the CreateRecurringPaymentsProfile request you set the number of failed payments allowed before PayPal automatically suspends the profile PayPal sends you an IPN message when the number of failed payments reaches the maximum number specified 46 April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Recurring Payments With the Express Checkout API Billing the Outstanding Amount If a payment fails for any reason PayPal adds the billing amount including shipping and tax if applicable to the profile s outstanding balance Use the AUTOBILLOUTAMT field in the CreateRecurringPayment sProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle Whether or not you choose to include the outstanding amount with the payment for the next billing cycle you can also use the BillOutstandingAmount API to programmatically collect
42. al syntax for NVP fields to support parallel payments The NVP interface to the PayPal API supports up to a maximum of 10 parallel payments in a transaction To accommodate this request fields have the following format where nis a number in the range 0 to 9 representing a payment PAYMENTREQUEST_n_NVPREQUESTFIELDNAME The first numbered field in a list of payments starts with n equal to 0 the second field has n equal to 1 and so forth The response name format is PAYMENTREQUEST_n_NVPRESPONSEFIELDNAME NOTE Even if your Express Checkout integration supports single payments only you must use this format Specify n 0 for single payment with version 63 0 or higher of the Express Checkout API The payment information returned in the DoExpressCheckoutPayment response has the same basic format however the field name starts with PAYMENT INFO PAYMENT INFO_n_NVPRESPONSEFIELDNAME The NVP API reference documentation shows the proper format and naming for every NVP field that uses this syntax Examples The following syntax represents the total amount of the first payment Express Checkout Advanced Features Guide April 2012 65 ie Implementing Parallel Payments Integrating Parallel Payments by Using the NVP API PAYMENTREQUEST_0O_AMT The following represents the second line of the name for the third payment L_PAYMENTREQUI EST_2 NAM E Integrating Parallel Payments by Using the NVP API To int
43. ated shipping insurance and tax data to ensure the buyer sees it upon redirect to your website Other Callback Considerations When you implement the callback you must consider callback response errors timeouts and shipping options Callback Response Errors If there are any callback response errors PayPal responds by displaying the flat rate shipping options on the PayPal pages To obtain the richer set of options available through the callback exercise care in the syntax and values you specify and test the callback integration Callback Timeouts If the callback does not return within the timeout period PayPal displays the flat rate shipping options you specified in the call to SetExpressCheckout Minimum and Maximum Shipping Options You can specify up to 10 shipping options for the flat rate options in the call to SetExpressCheckout and for the detailed options based on shipping address in the callback response You must specify at least 1 shipping option You Do Not Ship to the Buyer s Shipping Address If you do not ship to the buyer s shipping address that PayPal sends in the callback request set NO_SHIPPING_OPTION_DETAILS to 1 in the callback response NOTE The CALLBACKVERSION must have been set to 61 0 or greater in the SetExpressCheckout request Express Checkout Advanced Features Guide April 2012 85 86 Implementing the Instant Update API Using the Callback The samp
44. ayPal Review Page Order Details NVP Field SOAP Field Description and Comments L_PAYMENTREQUEST_n_AMTm Amount Item unit price PayPal calculates the product of the item unit price and item unit quantity below in the Amount column of the cart review area The item unit price can be a positive or a negative value but not 0 You may provide a negative value to reflect a discount on an order for example L_PAYMENTREQUEST_n_OQTYm Quantity Item unit quantity ITEMAMT ItemTotal Sum of costs of all items in this order TAXAMT TaxTotal Sum of tax for all items in this order SHIPPINGAMT ShippingTotal Total shipping cost for this order 8 PayPal calculates the sum of the shipping cost and the handling cost Although you may change the value later try to pass in a shipping amount that is reasonably accurate PAYMENTREQUEST_n_HANDLINGAMT HandlingTotal Total handling cost for this order PAYMENTREQUEST_n_SHIPDISCAMT ShippingDiscount Shipping discount for this order You specify this value as a negative number PAYMENTREQUEST_nN_INSURANCEAMT InsuranceTotal Total shipping insurance cost for this order PAYMENTREQUEST_n_AMT OrderTotal Total of order including shipping handling tax and any other billing adjustments such as a credit due 12 If you pass the generic order description parameter PAYMENTREQUEST_n_DESC al
45. ayPal and lets you respond with your actual shipping charges and handling charges e International addresses which lets buyers add international addresses during checkout after logging in to PayPal e Promotional offers which lets buyers pay with coupons incentives and buyer credit e Dynamic currency conversion which lets you list an item in one currency and then accept payment in a different currency e Keep me logged in in which buyers remain logged in to PayPal between transactions Related information Integrating Express Checkout With Your Mobile Website on page 31 Express Checkout Advanced Features Guide April 2012 41 Express Checkout on Mobile Devices Features Not Supported by Express Checkout on Mobile Devices 42 April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments Set up a recurring payment to handle subscription and other payments that occur on a fixed schedule e Recurring Payments Demo How Recurring Payments Work To view a video that demonstrates how to set up Recurring Payments navigate to Recurring Payments Demo When you support recurring payments for a buyer you create a recurring payments profile The profile contains information about the recurring payments including details for an optional trial period and a regular payment period Both periods contain information about the payment frequency and payment amounts including shipping and tax if applicable
46. calculations for you Then send the shipping options insurance amounts and taxes to PayPal in the callback response This is an example callback request ETHOD CallbackRequest amp CALLBACKVERS ION XX 0 amp TOKEN EC 0EE85728D547104V amp CURRENCYCODE USD amp LOCALECODE en_US amp L_NAME0 10 Decaf Kona Blend Coffee amp L_NUMBERO 623083 amp L_DESCO Size 8 oz amp L_AMT0 9 95 amp L_QTY0 2 amp L_NAMF1 Coffee Filter bags amp L_NUMBER1 6230 amp L_DESC1 Size Two 24 piece boxes amp L_AMT1 39 70 amp L_QTY1 2 amp L_ITEMWEIGHTUNIT1 l1bs amp L_ITEMWEIGHTVALUE1 0 5 amp SHIPTOSTREET 1 Main St x T 88 April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API Using the Callback amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRY US amp SHIPTOZIP 95131 amp SHIPTOSTREET2 Callback Response Each time your callback server receives a request from PayPal it must process the request and respond with the appropriate details This is an example callback response ETHOD CallbackResponse OFFERINSURANCEOPTION t rue HIPPINGOPTIONNAMEO UPS Next Day Air HIPPINGOPTIONAMOUNTO 20 00 0 2 20 URANCEAMOUNTO 1 51 PPINGOPTIONISDEFAULT0 false PPINGOPTIONNAME1 UPS Express 2 Days PPINGOPTIONAMOUNT1 10 00 T1 2 00 URANCEAMOUNT1 1 35 PP INGOP
47. cales Supported by Express Checkout on Mobile Devices SOAP PaymentDeiailsltemType Fields Supported by Express Checkout on Mobile Devices Name Number TtemWeight Description Amount Quantity Tax TtemURL Locales Supported by Express Checkout on Mobile Devices You can set the locale for Express Checkout pages on mobile devices to any of the countries generally supported by PayPal with a few exceptions PayPal displays the Login page in the default language for the country that you specify The default locale is United States Locale Codes Not Supported by Express Checkout on Mobile Devices The following locale codes are not supported by Express Checkout on mobile devices Country or Region Code Albania AL Andorra AD Armenia AM Brazil BR Georgia GE Holy See Vatican City State VA India IN Moldova Republic of MD Monaco MC Ukraine UA Handling Locales Not Supported by Express Checkout on Mobile Devices If you attempt use use an unsupported locale the following actions occur e Merchants If you set the locale code to an unsupported country PayPal switches buyers to the full website checkout experience e Buyers Ifa buyer logs in with a PayPal account for an unsupported country PayPal stops the mobile checkout experience and the buyer cannot pay April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices OER Features Not Supported by Express Checkout on Mobile Devic
48. chant review page for buyer 6 Calls DoExpressCheckoutPayment if the order includes one time purchases as well as a recurring payment Otherwise skip this step Returns DoExpressCheckoutPayment response Calls CreateRecurringPayment sProfile one time for each recurring payment item included in the order Returns ProfileIDin CreateRecurringPayment sProfile response for each profile successfully created 7 Displays successful transaction page Initiating the Processing Flow With SetExpressCheckout As in the Express Checkout flow the SetExpressCheckout request notifies PayPal that you are e Initiating an order that can be either a one time purchase up to 10 recurring payments or a mixture of a one time purchase and recurring payments e Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one time purchase or recurring payment NOTE You can also initiate the processing flow using Set CustomerBillingAgreement for orders that contain only a single recurring payment Typically you set the amount of the payment for an Express Checkout transaction when you call the SetExpressCheckout request You confirm the amount in the Express Checkout Advanced Features Guide April 2012 49 jE Handling Recurring Payments Recurring Payments With the Express Checkout API DoExpressCheckoutPayment request If however you set the amount of the payment to 0 in the SetEx
49. cribed herein PayPal Inc reserves the right to make changes to any information herein without further notice Contents Preface goes eal en he eS ew we ew oe ee Ree Se eT About This Guides lt 2 s s ok cei eee ele ee ee a a ew ee ee ei 7 Intended Audience aooaa a a 7 Where to Go for More Information a oa 1 a 7 Documentation Feedback oaoa aoaaa a 7 Chapter 1 Customizing Express Checkout 49 PayPal Review Page Order Details 2 oa o a a a a 9 Special Instructions to Merchant a aoao a 11 Integrating Order Details into the Express Checkout Flow 11 Providing Gift Options ooa eaa ee 13 Obtaining Buyer Consent to Receive Promotional Email 15 Overriding Your Customer Service Number aooaa 2 ee 16 Adding a Survey Question 2 aoa a 17 PayPal Page Style 2 2 naked kaare ka sikai 18 Custom Page Style aoaaa 18 Individual Page Style Characteristics 2 a a 19 Changing the Locales a s ia eee ee Ba Oa awe ee eae eae 20 Handling Shipping Addresses 2 2 2 22 Confirmed Address 1 1 23 Suppressing the Buyer s Shipping Address 2 000000 23 Shipping Address Override aooo 24 Automatically Filling Out Shipping and Contact Information 25 Buyer Pays on PayPal ss a aip a 4 6 ee ha oe ee er ee a a a 28 Express Checkout Redirect to Let Buyers PayonPayPal 28 Chapter 2 Express Checkou
50. d 38 April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices SOAP Request Fields Supported by Express Checkout on Mobile Devices Express Checkout on mobile devices supports only these SOAP fields SOAP SeiExpressCheckout Request Fields Supported on Mobile Devices OrderTotal MaxAmount Address LocaleCode The following values are not supported e AD Andorra e AL Albania AM Armenia BR Brazil GE Georgia VA Holy See IN India MC Monaco MD Moldova UA Ukraine ChannelType value must be merchant ReturnURL OrderDescription ReqConfirmShipping PaymentAction CancelURL Custom NoShipping BuyerEmail BrandName Token InvoiceID AddressOverride SolutionType value must be mark SOAP AddressType Fields Supported by Express Checkout on Mobile Devices Streetl Street2 CityName StateOrProvince Country PostalCode Phone SOAP PaymentDeitailsType Fields Supported by Express Checkout on Mobile Devices OrderTotal ItemTotal ShippingTotal InsuranceTotal ShippingDiscount HandlingTotal TaxTotal OrderDescription Custom InvoiceID ButtonSource NotifyURL ShipToAddress PaymentDetailsItem NoteText TransactionId AllowedPaymentMethodType PaymentAction PaymentRequest ID Express Checkout Advanced Features Guide April 2012 39 40 Express Checkout on Mobile Devices Lo
51. d 4 Item unit price This field specifies exactly how much one unit of the item costs It can be a positive or negative value but not zero 5 Item unit quantity This field identifies the number of units the buyer is ordering PayPal calculates the value in the Amount 6 column as the product of line item unit price and line item unit quantity You can also show other detailed information about the order 7 Item total and tax which are the total of all items in the order and the tax respectively 8 Shipping and handling which is the sum of the shipping and handling amounts NOTE You must determine actual shipping and handling amounts 10 April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout ie PayPal Review Page Order Details 9 Shipping discount If the buyer is receiving a discount on shipping the value appears as a credit in this field 10 Insurance This field shows the insurance fee when there is insurance on shipping 11 Total This is the total of the order including shipping handling tax and other price adjustment related items NoTE The Enter gift certificate reward or discount link enables the buyer to redeem certificates rewards or discounts that PayPal issues The link does not enable the buyer to redeem incentives that you issue Special Instructions to Merchant You can allow the buyer to send you special instructions about an order
52. e L_PAYMENTREQUEST_n_EBAYITEMCARTIDm eBay provides you with this value Additionally in the call to the SetExpressCheckout API operation you must pass the following Express Checkout API parameter data CHANNELTYPE The value of the channel type which is eBayItem L_PAYMENTREQUEST_n_EBAYITEMNUMBERM This is the eBay item number Buyer s shipping address 102 April 2012 Express Checkout Advanced Features Guide A on A U0 Immediate Payment A Integrating Immediate Payment for Third Party Checkout The SetExpressCheckout response returns a TOKI The buyer is redirected to PayPal response returns information about the buyer PAYM L_PAYM In the call to DoExpressCheckoutPaym ENTREQUEST_n_ALLOWEDPAYM For immediate payment the value is 1 The buyer reviews their payment and clicks Continue ENTREQUEST_n_EBAYITEMCART EN F EN Optional Call GetExpressCheckoutDetails The GetExpressCheckoutDetails ent you must pass ENTMETHOD This is the payment method type nstantPaymentOnly Dn eBay provides you with this value At this time PayPal checks the availability of the eBay item response returns the eBay transaction ID PAYMENTR EQUEST_n_EBAYTTEMAUCTIONTXNID If the item is available and payment is successful the DoExpressCheckoutPayment Integrating Immediate Payment for Th
53. e of that color in the call to SetExpressCheckout The following example sets a custom header image and adds a border color Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0O_MAXAMT amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp LOGOIMG https www YourLogo gif amp CARTBORDERCOLOR 0000CD Express Checkout Advanced Features Guide April 2012 19 Customizing Express Checkout Changing the Locale Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The figure below shows the cart review area with a custom logo and border color around it that were set in the call to SetExpressCheckout YourLogo Your order summary Description Amount ltem des cription 1 79 00 Item 123 Item price 7900 Oty 1 Item des cription 2 89 00 Item 12 Item price 89 00 Oty 1 tem total 168 00 Tax 15 54 Shipping and handling 1850 Total 202 04 USD Changing the Locale You can change the locale of PayPal pages to match the language on your website To change the language displayed on the PayPal pages set the LOCALECODE parameter to one of the following allowable values in the SetExpressCheckout call e AU Australia e AT Austria e BE Belgium 20 April 2012 Express Checkout Advanced Fea
54. eceive Transaction Status Notification a aoaaa a 77 Chapter 7 Implementing the Instant Update API 79 About the Instant Update API oaoa aa a 79 Integration Steps 2 a 79 Post Integration Checkout Experience oaoa a a 80 How the Callback Works in the Express Checkout Flow a oa oaa a a 82 Following Instant Update API Best Practices 2 2 200 83 Setting Up the Callback 2 1 oe Noe a aaa 84 GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes 85 Express Checkout Advanced Features Guide April 2012 5 a Contents Other Callback Considerations 2 0 000 0 ee 85 Using the Callback 2 2 ee 86 SetExpressCheckout oaoa 86 Callback Request 2 aa ee 88 Callback Response 1 0 0 89 Chapter 8 Payment Review 2 eee ee ee ee ee ee GT Handling Payment Review aaa aaa a 91 Chapter 9 Express Checkout Dynamic Image Integration 95 Dynamic Mages s a sraa s ea k aao A a e a a a a AA a a A 95 Configuring the Dynamic Image oaoa oa a 95 Set Up the Default Image ooa a a 2 ee ee 96 Set Up Image for Dynamic Use aoaaa a 96 Change the Locale aooaa ee 97 Provide Incentive Eligibility Feedback to Buyer a aoaaa aaa a 97 Choose the Image oaoa aa 97 Dynamic Image Command Reference aooaa aa a a 98 Dynamic Image Parameters oa aa aaa a a 98 Locale Codes and Priorities o oo aa a a 98 Chapter 10 Immediate Payment
55. ectively of your call to SetExpressCheckout The following steps assume you already have a working Express Checkout integration that you want to port to your mobile website If you are providing an app you must include the Mobile Express Checkout Library in your app and initialize it For information about he Mobile Express Checkout Library see the Mobile Express Checkout Library Developer Guide and Reference for your device s operating system iOS or Android To support Mobile Express Checkout integration 1 Change the command in your redirect to the Express Checkout flow to _expresscheckout mobile If the buyer checks out on PayPal your redirect will include https www paypal com cgi bin webscr cmd _express checkout mobile amp token valueFromSetExpressCheckoutResponse If the buyer checks out on your website also set useraction commit https www paypal com cgi bin webscr cmd _express checkout mobile amp useract ion commit amp token valueFromSetExpressCheckoutResponse NOTE While it is not strictly required that you change the cmd value PayPal recommends that you make this change to improve performance 2 Change the RETURNURL field in your call to SetExpressCheckout to the page you want your buyer to return to on your mobile website RETURNURL ht tps mobileWebsitePage htm1 3 Change the CANCELURL field in your call to SetExpressCheckout to the page you want your buyer to
56. eference Country code Language priority Locale C2 language_0 en_US C2 language_1 zh_XC C2 language_2 fr_XC C2 language_3 es_XC CH language_0O de_DE CH language_1 fr_FR CH language_2 en_US CN language_0O zh_CN default language_0O en_US default language_1 fr_XC default language_2 es_XC default language_3 zh_XC DE language_0O de_DE DE language_1 en_US ES language_0O es_ES ES language_1 en_US FR language_0O fr_FR FR language_1 en_US GB language_0O en_GB GF language_0O fr_ FR GF language_1 en_US GI language_0O en_US GP language_0O fr_ FR GP language_1 en_US IE language_0O en_US IT language_0O it_IT IT language_1 en_US JP language_0O ja_JP JP language_1 en_US MQ language_0O fr_FR MQ language_1 en_US Express Checkout Advanced Features Guide April 2012 99 100 Express Checkout Dynamic Image Integration Dynamic Image Command Reference Country code Language priority Locale NL language_0O nl NL NL language_1 en_US PL language_0 pl PL PL language_1 en_US RE language_0 fr_FR RE language_1 en_US US language_0O en_US US language_1 fr_XC US language_2 es_XC US language_3 zh_XC April 2012 Express Checkout Advanced Features Guide Immediate Payment Immediate Payment ensures a buyer pays for a purchase immediately after commiting to it Overview of Immediate Payment Immediate Payment supports instant funding sources only ensuring that you receive payment at the time the buyer commits to a
57. egrate parallel payments by using the NVP API you need to use the syntax for creating unique NVP request field names and create a unique set of fields for each payment You also need to set a few required variables To integrate parallel payments using the NVP interface to Express Checkout 1 Create a unique set of NVP request fields for each payment you will be hosting on your marketplace using the syntax PAYMENTREQUEST_n_NVPREQUESTFIELDNAME where n is a value from 0 9 2 You are required to pass values in the following Payment Details Type fields in the call to SetExpressCheckout and DoExpressCheckoutPayment For each of the n payments you host Pass the value Sale or Order in PAYMENTREQUEST_n_PAYMENTACTION Pass a unique value for PAYMENTREQUEST_n_PAYMENTREQUESTID You will use this value to locate the matching payment response details for that payment Pass the merchant s Payer ID secure merchant account ID or the merchant s email address in PAYMENTRI EQUEST_n_SELLERPAYPALACCOUNT ID 3 Use the Payment Details Item Type fields as appropriate in the call to SetExpressCheckout and DoExpressCheckoutPayment to pass data about each payment Result For each payment in the transaction the DOExpressCheckoutPayment response returns e A PAYMENT PAYMENTREQUI INFO_n_PAYMENTREQUESTID value that matches the EST_n_PAYMENTREQUE
58. ents the transaction is canceled giropay Payment Page Flow The following diagram illustrates the flow of a successful giropay payment Legend WE PayPal Website 1i Your Website jay Giropay ae e Checkout gt m gt cosy gt Add To Cort 8 _PayNow Redirect page a Choose a way Review your Confirm order to pay information er wey bo pt Shopping cart N ee D o T giropay giropay gropay Enter PIN gt Enter TAN gt cre gt Order confirmation Express Checkout Advanced Features Guide April 2012 75 76 Integratin g giropay with Express Checkout giropay Integration Canceled or Unsuccessful giropay Payment Page Flow If the giropay payment fails for any reason such as insufficient funds or the buyer cancels PayPal provides details to the buyer to do a bank transfer from their bank account This transaction will remain pending until PayPal receives the funds at which time the transaction is complete If you have disabled non instant funding transactions for your PayPal account the transaction is canceled and PayPal redirects the buyer to your Order Cancel page After the bank transfer flow completes the transaction is pending until the buyer pushes the funds to PayPal If the buyer cancels during the PayPal payment in the bank transfer flow your Order Cancel page is displayed giropay Integration If you offer the giropay payment option you must take additional steps to in
59. ers complete their purchases The useraction URL parameter in your redirect to PayPal determines whether buyers complete their purchases on PayPal or on your website If you set useraction to commit PayPal sets the button text to Pay Now on the PayPal Review your informaton page This text lets buyers know that they complete their purchases if they click the button Legend Merchant Website ag PayPal Website il a 00 Checkout Confirmation ana D m gt lu ind n A Choose a way Review your Order to pay information confirmation The cate sasior way bo poy Shopping cart After PayPal redirects buyers to your site call GetExpressCheckoutDetails and DoExpressCheckoutPayment to have PayPal complete the payment successfully Call DoExpressCheckoutPayment without waiting for buyer interaction Use information in the GetExpressCheckoutDetails response to fill out your order confirmation page Express Checkout Redirect to Let Buyers Pay on PayPal The following sample code shows the redirect to let buyers pay on PayPal https www paypal com cgi bin webscr cmd _express checkout amp useract ion commit amp t oken valueFromSetExpressCheckoutResponse April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices Express Checkout on mobile devices runs in mobile browsers with pages optimized for smaller mobile screens and mobile keyboards If you have an Express Checkout implementation you ca
60. es Features Not Supported by Express Checkout on Mobile Devices Before implementing Express Checkout on mobile devices examine the list of features that are not supported Express Checkout does not support the following features when it runs on mobile devices e SMS security keys for mobile PayPal login in which buyers can sign up for an extra layer of security with a secure token Buyers add a one time secure code to their password or mobile PIN when they log in to PayPal Buyers can use secure codes from hardware tokens but not from software tokens sent by SMS to the buyer s mobile phone e Forgotten email or password in which buyers can request their email address or password during checkout before logging in to PayPal e Parallel payments which lets buyers pay multiple merchants in a single checkout session e Dynamic images which lets PayPal update the images on your website for the Checkout With Express Checkout button and PayPal acceptance mark automatically to coincide with PayPal campaigns e Buyer experience enhancements which lets you offer gift wrap ask a survey question or display your customer service number during checkout e Custom payment page styles which lets you change the overall appearance of the Review your information page with a custom page style or with individual page style characteristics e Instant Update API which is a callback that sends you the buyer s shipping address during checkout on P
61. f you need only one billing agreement between you and the buyer Use Merchant InitiatedBilling to create a billing agreement between you and the buyer each time you call DoExpressCheckoutPayment A description of the goods or services associated with the agreement Optionally the kind of PayPal payment you require Optionally a string that you can use for any purpose PayPal returns a token which you use in the subsequent steps Redirect the buyer s browser to PayPal which allows the buyer to log in or set up an account to pay for the purchase PayPal presents the buyer with a confirmation page PayPal redirects the buyer s browser to your return page Call GetExpressCheckoutDet ails to obtain information about the buyer and the buyer s checkout status PayPal returns checkout details Call DoExpressCheckoutPayment to initiate the purchase If the buyer accepts the billing agreement PayPal returns information about the purchase and a billing agreement ID Save the ID for reference transactions or recurring payments To obtain a billing agreement ID without also initiating a purchase modify the previous procedure as follows In step 1 specify 0 for the amount of purchase in the payment details Optional Set MAXAMT to the expected average transaction amount default is 25 00 PayPal uses the value to validate the buyer s payment method for future payments Skip step 5
62. firmed address NOTE Because many buyers prefer to ship to a non confirmed address they may for example be shipping a gift to someone PayPal does not recommend requiring a confirmed address unless you are selling high risk merchandise If you prefer that confirmed addresses be used then do not set ADDROVERRIDE To require a confirmed address for the shipping address ensure that the shipping address matches the address on record with PayPal You can do this through your account profile as described in the Merchant Setup and Administration Guide Alternately you can set a flag in the call to SetExpressCheckout as follows 1 Include the optional REQCONFIRMSHIPPING parameter in the call to SetExpressCheckout 2 Set REQCONFIRMSHIPPING to 1 The following example shows how to require the shipping address to be a confirmed address NOTE The value of REOCONFIRMSHIPPING overrides the setting in your Merchant Account Profile Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp REQCONF IRMSHIPP ING 1 amp PAYMENTREQUEST_0_SHIPTOSTREET 1 Main St amp PAYMENTREQUEST_O_SHIPTOCITY San Jose amp PAYMENTREQUEST_0_SHIPTOST
63. for activation BILLINGPERIOD ScheduleDetails The unit of measure for the billing cycle PaymentPeriod BillingPeriod Must be one of the following e Day e Week e SemiMonth e Month e Year BILLINGFREQUENCY ScheduleDetails The number of billing periods that make PaymentPeriod BillingFreque up one billing cycle The combination of ncy billing frequency and billing period must be less than or equal to one year NOTE If the billing period is SemiMonth the billing frequency must be 1 AMT ScheduleDetails Amount to bill for each billing cycle PaymentPeriod Amount You can optionally include a value for TOTALBILLINGCYCLES SOAP field ScheduleDetails PaymentPeriod TotalBillingCycles which specifies the total number of billing cycles in the regular payment period If you either do not specify a value or specify the value 0 the payments continue until PayPal or the buyer cancels or suspends the profile If the value is greater than 0 the regular payment period continues for the specified number of billing cycles You can also specify an optional shipping amount or tax amount for the regular payment period Express Checkout Advanced Features Guide April 2012 45 4 Handling Recurring Payments Options for Creating a Recurring Payments Profile Including an Optional Trial Period You can optionally include a trial period in the profile by specifying the following fields in the CreateRecurringPaymen
64. he following SetExpressCheckout request example sets these options Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp GIFTMESSAGEENABLE 1 amp GIFTRECEIPTENABLE 1 amp GIFTWRAPENABLE 1 amp GIFTWRAPNAME Bow and Ribbon amp GIFTWRAPAMOUNT 6 00 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706495P The following figure shows how the gift options appear to the buyer Include a message with your gift no charge Write a message to the recipient here 150 characters left l Giftwrap Bow 6 00 USD Giftreceipt no charge J Mi d a NOTE You can also configure this option from your profile For details see the Merchant Setup and Administration Guide 14 April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout oa Obtaining Buyer Consent to Receive Promotional Email Related information PayPal Review Page Order Details on page 9 Obtaining Buyer Consent to Receive Promotional Email You can obtain the buyer s consent to receive email promotions on PayPal pages PayPal returns the email address in the response to GetExpressCheckoutDetails and DoExpressCheckoutPayment NOTE Obtaining buyer consent
65. heckoutRequestDetails Payment Details PaymentDetailsArray Best Practices for Online Travel Agencies Implementing Parallel Payments PayPal provides special recommendations to online travel agencies implementing parallel payments to help the buyer complete the payment flow Best practices address ways that you as an online travel agency designer can meet the needs of the merchants hosted on your marketplace The following are examples of special needs of these merchants e Merchants providing travel services must offer different styles of payment e Merchants offering a service with reservations would want the buyer to know about the cancellation policy and fees Styles of Payment Merchants hosted by online travel agencies might be using one or more of the following styles of payment e Prepaid Prepaid payments are paid in full at the time of checkout This style is typical of most online purchases e Deposit A deposit is paid before a service is rendered Usually it is a flat rate equal to a small percentage of the total such as a 50 00 deposit on a cruise The balance is paid offline at some point before the cruise or other service takes place e Postpaid A postpaid expense is not paid until after the service is rendered Hotel stays for example are typically paid at the time of checkout Express Checkout displays to the buyer a total amount for all goods or services For a good buyer exper
66. his guide 05 02 2011 Revised Express Checkout on Mobile Devices chapter and added support information for iPad 08 11 2010 Divided the Express Checkout Integration Guide into 2 guides the Express Checkout Integration Guide and the Express Checkout Advanced Features Guide 05 11 2010 Added details for integrating parallel payments using the NVP and SOAP API including use with airlines Added new Immediate Payment functionality Updated billing agreements to obtain the latest billing address skip billing agreement creation and clarified the use of the BAUpdate API 03 10 2010 Added support for parallel payments 01 21 2010 Added new Express Checkout fields to provide the buyer contact information gift options promotions and a survey question on the PayPal pages Added a new callback response API field providing no shipping details 03 10 2010 Added support for parallel payments 10 05 2009 Added Immediate Payment Removed PayPal placement guidelines 06 30 2009 Added a section on payment review 06 04 2009 Added a chapter on filling out the PayPal review page automatically Updated PayPal Review pages Moved some customization topics out of this guide They are now in the Merchant Setup and Administration Guide 04 30 2009 Created first edition for Enterprise level merchants and added chapter on reference transactions 04 08 2009 Added a chapter describing the Instant Update Callback API 03 03 2009 Updated to allow useraction c
67. ialize it For information about the Mobile Express Checkout Library see the Mobile Express Checkout Library Developer Guide and Reference for your device s operating system iOS or Android The library also provides additional functions that you can call from your app IMPORTANT You cannot call SetExpressCheckout or any PayPal API directly from your app If the page that hosts the Pay with PayPal button is on your app and not on a secure webpage on your server you must make the call from your secure server and pass the response to your app otherwise the credentials used to make the call are not protected Integrating Express Checkout With Your Mobile Website To integrate Express Checkout on you mobile website specify return and cancel URLs on your mobile website in your call to SetExpressCheckout and specify the command in the Express Checkout Advanced Features Guide April 2012 31 32 Express Checkout on Mobile Devices Integrating Express Checkout With Your Mobile Website redirect as cnd _expresscheckout mobile Not all features of Express Checkout are supported on mobile websites Your mobile website should conform to the standards of the browser in which it runs for example Safari on an iPad or Chrome on an Android phone It must contain a page or pages to which PayPal redirects the buyer s browser when the payment flow completes or is canceled You specify these pages in the RETURNURL and CANCELURL fields resp
68. ience you can pass additional information about a deposit or postpaid expense April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments TE Best Practices for Online Travel Agencies Implementing Parallel Payments using the Express Checkout PaymentDetailsType and PaymentDetailsItemType parameter fields To eliminate potential buyer confusion you can let the buyer making a deposit through Express Checkout know for example that they will need another payment instrument to complete their purchase Payment Details The following table provides PayPal s recommendations for passing payment information Best practices for passing payment information Item Best practices Example content Merchant name You do not need to pass this data PayPal PayPal presents the obtains the merchant s name that business name for example displays on the PayPal Review your Airline Name information page from the merchant s account record Item description Use L_PAYMENTREQUEST_n_DESCn to See the table below pass item description information as a continuous text string Pass at least the primary information shown in the table below PayPal recommends that you also pass the secondary information If the style of payment is a reservation with deposit pass the deposit only in the item description Order description Use PAYMENTREQUEST_n_DESCto pass Your account will not be
69. ile Trial period An optional subscription period before the regular payment period begins A trial period may not have the same billing cycles and payment amounts as the regular payment period Payment amount The amount the buyer pays for each billing cycle Outstanding balance If a payment fails for any reason PayPal adds that amount to the profile s outstanding balance Profile ID An alphanumeric string generated by PayPal that uniquely identifies a recurring profile You can specify the Profile ID in the Transact ionSearch API operation to obtain all payments associated with the identified profile 44 April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Options for Creating a Recurring Payments Profile Options for Creating a Recurring Payments Profile You can create a recurring payments profile that allows a regular payment period an optional trial period an initial payment and other options Specifying the Regular Payment Period Each recurring payments profile has a regular payment period that defines the amount and frequency of the payment The following table lists the required fields for specifying the regular payment period Required fields for specifying a regular payment period NVP SOAP Description PROF ILESTARTDATE RecurringPaymentsProfileDet The date when billing for this profile ails BillingStartDate begins NOTE The profile may take up to 24 hours
70. ilure of the call April 2012 Express Checkout Advanced Features Guide Reference Transactions A reference transaction is a financial transaction from which subsequent transactions can be derived For example a buyer can make a purchase on your site and the PayPal transaction ID becomes the ID of a reference transaction that can later be used to initiate another transaction Introduction to Reference Transactions Recurring payments using reference transactions enables you to handle payments for varying amounts of money on a varying schedule The buyer can sign up for recurring payments as part of the Express Checkout flow or sign up before making a purchase Consider the following examples e A buyer purchases a mobile phone and selects a carrier The buyer pays for the phone using Express Checkout and agrees to pay monthly for the service e A buyer downloads a music video and pays for it with Express Checkout During checkout the buyer agrees to make a payment whenever the account balance exceeds a specified minimum amount e A buyer agrees to pay monthly for utilities such as gas or electricity The buyer makes no payment at the time of agreement PayPal deducts payments monthly for actual use These examples represent payment transactions that reoccur periodically either for a specific time period or when transactions reach a certain threshold The amount of each transaction varies by use These kinds of recurring payme
71. inate the need for a separate step to create the billing agreement e The DoReferenceTransaction API operation initiates a payment which is sometimes called a merchant pull payment because you initiate the payment not the buyer After a billing agreement has been established this is the only API operation you must call e The CreateBillingAgreement API operation enables you to set up a billing agreement without requiring a purchase Use it in place of DoExpressCheckoutPayment to allow a buyer to set up a billing agreement before making a payment as in the example of a buyer preparing to make a monthly utility payment e You can use the BAUpdate API NVP METHOD BillAgreementUpdate to enable a buyer to cancel a billing agreement while on your site The buyer also can cancel a billing agreement by logging in to PayPal directly thus this API operation may not be required e You can use BAUpdate NVP METHOD BillAgreement Update to obtain the buyer s most recent billing address 58 April 2012 Express Checkout Advanced Features Guide Reference Transactions 4 Setting Up a Billing Agreement Using the Express Checkout API Setting Up a Billing Agreement Using the Express Checkout API You must set up a billing agreement using the Express Checkout API before you can use a reference transaction Specify 0 as the amount of the purchase in SetExpressCheckout and call CreateBillingAgreement if you only want to ob
72. ird Party Checkout To integrate Immediate Payment for third party checkout into your Express Checkout implementation you add a few new fields to Set DoExpressCheckoutPayment The Call to SetExpressCheckout ExpressCheckout and You must have Express Checkout integrated into your payment solution PayPal recommends that you sell one eBay item in a transaction or a quantity of the same item considered a single eBay listing To integrate Immediate Payment into the SetExpressCheckout call 1 NA un A V N Set PAYM ENTREQU EST_n_ALLOWEDPAYMENTMETHOD to InstantPaymentOnly This blocks all pending funding sources and transactions in a pending state Pass BUYE RUSERNAME and L_PAYMENTREQU EST_N E iBAY ITEMCARTIDM Set C HANN ELTYPE to eBayItem Express Checkout Advanced Features Guide Specify the buyer s shipping address April 2012 Be prepared to handle Immediate Payment errors Set L_PAYMENTREQUEST_n_EBAYITEMNUMBERM to the number of the eBay item 103 104 Immediate Payment About Immediate Payment For Express Checkout For errors you choose to handle you need to send the buyer error messages appropriate to the situations generating the errors For example a buyer may have a mixed cart of eBay and non eBay items To allow the buyer to check out only the non Immediate Payment item
73. l Checkout on Mobile Devices PayPal account optional checkout enables buyers to pay using debit and credit cards on your mobile website without logging in to PayPal whether or not the buyer has a PayPal account You cannot use this kind of checkout with recurring payments or reference transactions because these features require buyers to log in to PayPal to complete the initial payment 34 April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices Enabling PayPal Account Optional Checkout on Mobile Devices To enable account optional checkout using Express Checkout you must set the PayPal Account Optional preference to On in Profile gt Website Payment Preferences after you log in to PayPal To enable account optional checkout modify your SetExpressCheckout request to include the following information 1 Specify that the buyer is not required to have a PayPal account SOLUTIONTYPE Sole 2 Specify whether the buyer lands on the checkout billing page or the PayPal mobile login page to complete the payment LANDINGPAGE Billing places the buyer on the billing page El Jefe s Taco Stand 4 X My total 60 00 usD Pay with a card Powered by PayPal United States gt Card type Expiration E 2011 Security code LANDINGPAGE Login places the buyer on the PayPal login page Express Checkout Advanced Features Guide April 2012 35
74. lance payment is already queued PayPal informs you by IPN about the success or failure of the outstanding payment For profiles created using Express Checkout the buyer receives an email notification of the payment Recurring Payments Notifications PayPal notifies you of recurring payments events through IPN and email Typically however you can call Get Transact ionDetails to obtain the information you need PayPal notifies you of certain events through IPN For recurring payments profiles created using Express Checkout PayPal also notifies buyers of specific events by email The following table indicates when PayPal generates IPN and emails Express Checkout Advanced Features Guide April 2012 55 56 Handling Recurring Payments Recurring Payments Notifications Recurring payments IPN messages and email Event IPN Buyer Email Profile successfully created Yes Yes Profile creation failed Yes Yes Profile canceled from paypal com interface Yes Yes Profile status changed using API No Yes Profile updated using API No Yes Initial payment either succeeded or failed Yes Yes Payment either succeeded or failed during either trial Yes Yes period or regular payment period Outstanding payment either succeeded or failed Yes Yes Maximum number of failed payments reached Yes No NOTE API transactions such as ManangeRecurringPaymentsProfileStatus do not trigger IPN notification The API response immediately provides the success or fa
75. le code below illustrates the callback response when you do not ship to the buyer s address ETHOD CallbackResponse NO_SHIPPING_OPTION_DETAILS 1 When your callback server sends the previous response the Review your information page has these features e A message at the top of the page indicates that your business does not ship to this location e The shipping and handling section and the insurance section are dimmed e The buyer can change the shipping address e A new callback request is sent if the buyer changes the shipping address Using the Callback To use the callback you add parameter fields to SetExpressCheckout provide PayPal a URL for sending a callback request and send PayPal the callback response in Name Value pair NVP format SetExpressCheckout In the call to SetExpressCheckout set the following parameters e Set the CALLBACK field to the URL where PayPal can call your callback server PayPal makes the HTTPS callback request each time either of the following events occur The buyer changes their shipping address The buyer enters a new shipping address e Provide values for the following required parameters Provide values for the line item details parameters such as L_PAYMENTREQUEST_n_NAMEm L_PAYMENTREQUEST_n_NUMBERM L_PAYMENTREQUEST_n_DESCm L_PAYMENTREQUEST_n_AMTm and L_PAYMENTREQUEST_n_O L_SHIPPINGOP
76. le response contains a Profile ID which is an encoded string that uniquely identifies the recurring payments profile The following is a Creat eRecurringPayment sProfile example that enables you to obtain the best rates for digital goods items Express Checkout Advanced Features Guide April 2012 51 52 Handling Recurring Payments Recurring Payments Profile Status Request Parameters requiredSecurityParameters amp METHOD CreateRecurringPaymentsProfile TOKEN EC 13W99099UU817504D amp PROFILESTARTDATE 20XX 03 05T03 00 00 amp DESC Movie clips amp BILLINGPERIOD Month amp BILLINGFREQUENCY 12 amp AMT 1 00 amp CURRENCY CODE USD amp EMATL payername bbb net amp L_PAYMENTREQUEST_0O_ITEMCATEGORY0 Digital amp L_PAYMENTREQUEST_O_NAMEO0O Kitty Antics amp L_PAYMENTREQUEST_0O_AMTO 1 00 amp L_PAYMENTREQUEST_0O_OQTYO 1 Response Parameters successResponseFields amp PROF ILEID I G7ALAX80 95JY amp PROFILESTATUS Active Recurring Payments Profile Status The recurring payments actions you may take depend on the status of the profile A recurring payments profile can have one of the following status values e ActiveProfile e PendingProfile e ExpiredProfile jeu Ju e SuspendedPro e e CancelledProfile If PayPal successfully creates the profile the profile has an Act
77. mation to PayPal as parameters appended to the image URL Your unique ID tells PayPal whether or not you are participating in events that require image changes Other information you pass instructs PayPal on the types of images to return If for example you are participating in a PayPal campaign that you have signed up for with PayPal and you have passed the appropriate parameter information to PayPal PayPal automatically updates the image to reflect the campaign information When the campaign is over PayPal restores the default image You are not responsible for scheduling or making changes to your website application code before during or after the campaign Because you set up the dynamic image PayPal handles these activities for you If you require localized campaign images you can have the localized button image display for each country in which you participate Simply assign the correct code for the country to the locale parameter you append to the dynamic image URL PayPal returns to the default button image associated with each locale when the campaign is not available Configuring the Dynamic Image To set up the dynamic image provide the name value pair parameter information in the image URL You can pass information in the image URL for each option e Set Up the Default Image e Set Up Image for Dynamic Use e Change the Locale e Provide Incentive Eligibility Feedback to Buyer e Choose the Image Express Checkout Advanced Feat
78. mp CALLBACKTIMEOUT 4 amp PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED t rue amp PAYMENTREQUEST_0_INSURANCEAMT 1 00 Express Checkout Advanced Features Guide April 2012 BACKTIMEOUT is 3 You can specify a value in the range of 1 to 6 inclusive 87 Implementing the Instant Update API Using the Callback amp L_SHIPPINGOPTIONISDEFAULT0 false amp L_SHIPPINGOPTIONNAMEO UPS Ground 7 Days amp L_SHIPPINGOPTIONAMOUNTO 3 50 amp L_SHIPPINGOPTIONISDEFAULT1 true amp L_SHIPPINGOPTIONNAME1 UPS Next Day Air amp L_SHIPPINGOPTIONAMOUNT1 8 00 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Callback Request The PayPal sends the parameters in the callback request to the location you specified for CALLBACK The callback request parameters include e Line item details you sent in the call to SetExpressCheckout PayPal also sends back any line item description details you may have specified such as the L_ITEMWEIGHTUNIT1 and L_ITEMWEIGHTVALUE1 values shown in the example below By passing this data back to you PayPal expedites your callback response by eliminating the need for you to perform a database query to obtain this information e Shipping address of the buyer Using the information in the callback request calculate the rates and options yourself or send the information in an API call to your carrier to perform the
79. n PAYMENTREQUEST_0O_SHIPTOCITY PAYMENTREQUEST_0O_SHIPTOSTATE Optional PAYMENTREQUEST_0O_SHIPTOCOUNTRYCODE PAYMENTREQUEST_0O_SHIPTOZIP PAYMENTREQUEST_0O_SHIPTOSTREET2 Optional The following example overrides the shipping address with the address values shown Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp ADDROVERRIDE 1 amp PAYMENTREQUEST_0_SHIPTOSTREET 1 Second St amp PAYMENTREQUEST_0_SHIPTOSTREET2 Ste 210 amp PAYMENTREQUEST_O_ SHIPTOCITY San Jose amp PAYMENTREQUEST_0_SHIPTOSTATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOZIP 95131 amp PAYMENTREQUEST_0_SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 57K68322WE343022B The PayPal Review your information page shows the shipping address parameter values you specified in the SetExpressCheckout request Automatically Filling Out Shipping and Contact Information PayPal can automatically fill out form fields for the buyer based on the buyer s shipping contact information passed in the call to SetExpressCheckout When you
80. n programmatically Programmatically the merchant can determine the status of a payment by checking the initial status of a transaction using any of the following the API operations e DoExpressCheckoutPayment e DoReferenceTransaction e DoAuthorization e DoReauthorization You can check the subsequent status of a transaction programmatically by calling the Get TransactionDetails API operation NOTE You must use version 58 0 or higher to obtain the initial status information provided by DoExpressCheckoutPayment DoReferenceTransaction DoAuthorization or DoOReauthorization To use payment review with the DoExpressCheckoutPayment DoReferenceTransaction DoAuthorization and DoReauthorization PayPal API operations you must Express Checkout Advanced Features Guide April 2012 91 Te Payment Review Handling Payment Review 1 Check the payment status in the response to the API operation specifically check whether Payment Status is set to Pending 2 If the Payment Status Is set to Pending check whether the PendingReason is set to PaymentReview because there are other reasons that a transaction may become pending For example an unsettled authorization s Payment Status is set to Pending however its PendingReason is set to authorization which is not related to payment review If Payment Status is set to Pending and the PendingReason is set to PaymentReview you should not ship merchandise or in the case
81. n take advantage of the mobile checkout experience with only minimal programming changes About the Express Checkout Experience on Mobile Devices On mobile devices Express Checkout provides payment pages tailored for faster checkout and for smaller mobile screens and keyboards You can either set up the experience so that the buyer pays on your site or on PayPal e Buyer Pays on Your Site e Buyer Pays on PayPal Buyer Pays on Your Site The Express Checkout experience on mobile devices begins on your mobile website when a buyer is ready to pay you ma Merchant Mobile Page a PayPal Mobile Page Se be Payrer i T lt _ Continue Eata _ a Shopping cart Log in to pay Review your Confirm order Order Buyers pay Buyers with information Buyers confirm confirmation with PayPa PayPal accounts Buyers confirm purchase details Buyers views order log in to pay purchase details before paying confirmation before continuing With Express Checkout on mobile devices the buyer 1 Clicks Checkout with PayPal on your mobile website or from your app 2 Enters login credentials on the mobile PayPal login page and then clicks Log in 3 Reviews payment details on the mobile PayPal review page and then clicks Continue Express Checkout Advanced Features Guide April 2012 29 Express Checkout on Mobile Devices Mobile Platforms Supported by Express
82. n the CreateRecurringPayment sProfile request GetRecurringPayment sProfileDetails also returns the following summary information about the profile e Profile status e Next scheduled billing date e Number of billing cycles completed in the active subscription period e Number of billing cycles remaining in the active subscription period e Current outstanding balance e Total number of failed billing cycles e Date of the last successful payment received e Amount of the last successful payment received Modifying a Recurring Payments Profile Use the UpdateRecurringPaymentsProfile API to modify a recurring payments profile NOTE You can also modify recurring payments profiles from the PayPal website You can modify only the following specific information about an active or suspended profile e Subscriber name or address e Past due or outstanding amount e Whether to bill the outstanding amount with the next billing cycle e Maximum number of failed payments allowed e Profile description and reference e Number of additional billing cycles e Billing amount tax amount or shipping amount Express Checkout Advanced Features Guide April 2012 53 54 Handling Recurring Payments Modifying a Recurring Payments Profile NOTE Youcannot modify the billing frequency or billing period of a profile You can modify the number of billing cycles in the profile You can modify the following profile information during the trial period or reg
83. n the format of a text string on the PayPal Review your information page The buyer responds by selecting from choices in a drop down menu To enable the display of the survey question and choices set the SURVEYENABLE field to 1 in the call to SetExpressCheckout e Set the SURVEYENABLE field to 1 in the call to SetExpressCheckout e Set SURVEYQUESTION to the string containing your question e Provide at least two L_SURVEYCHOICEn options from which the buyer can select one The following request example sets these fields Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0O_AMT 10 00 amp PAYMENTREQUEST_0O_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp SURVEYENABLE 1 amp SURVEYQUESTION How did you hear about us amp L_SURVEYCHOICEO friend amp L_SURVEYCHOICE1 newspaper ad Express Checkout Advanced Features Guide April 2012 17 Customizing Express Checkout PayPal Page Style Response Parameters successResponseFields amp TOKEN EC 17C76533PL706495P The survey question appears to the buyer in the cart review area NOTE You can also configure this feature in your profile For details see the Merchant Setup and Administration Guide PayPal Page Style You can change the overall
84. ncluding an Optional Trial Period 2 2 a 46 Specifying an Initial Payment aoa a ee 46 Maximum Number of Failed Payments 0 000000 eee 46 Billing the Outstanding Amount 0 00 47 Identifying Items as Digital or Physical Goods aooaa a 47 Recurring Payments With the Express Checkout API aoaaa aaa 47 Initiating the Processing Flow With SetExpressCheckout 49 Redirecting the Buyer to PayPal 000000 eee eee 50 Getting Buyer Details Using GetExpressCheckoutDetails 51 Creating the Profiles With CreateRecurringPaymentsProfile 51 Recurring Payments Profile Status 2 ee 52 Getting Recurring Payments Profile Information 0 2 00000 53 Modifying a Recurring Payments Profile 2 20 0 00 eee ee ee 53 Updating Addresses o aooaa a a 54 Updating the Billing Amount a aoaaa 0200002 eee eee 54 Billing the Outstanding Amount of a Profile aoaaa eee 55 Recurring Payments Notifications oaoa a a eee ee 55 Chapter 4 Reference Transactions aaao a 57 Introduction to Reference Transactions o oo ao a a a 57 Reference Transactions 2 a a a a a a a a a a a L 57 Billing Agreements ssa sssrssssisesarisa nsss ereas sxn 58 April 2012Express Checkout Advanced Features Guide Contents a API Operations for Reference Transactions 002 00045 58 Setting Up a Billing Agreement Using the Expres
85. ne for each payment you host on your marketplace 2 You are required to pass values in the following PaymentDetailsType fields in the call to SetExpressCheckout and DoExpressCheckoutPayment Pass the value Sale or Order in PaymentAction Pass a unique value in PaymentRequest ID You will use this value to locate the matching response details for that payment Pass the merchant s Payer ID secure merchant account ID or the merchant s email address in the SellerDetailsType PayPalAccount Id field 3 Use PaymentDetailsType and PaymentDetailsItemType fields as appropriate in the call to SetExpressCheckout and DoExpressCheckoutPayment to pass data about each payment 68 April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments aa Integrating Parallel Payments by Using the SOAP API Result For each payment in the transaction the DoExpressCheckoutPayment response returns a Payment InfoType structure corresponding to each payment e The PaymentRequest ID will match the value you passed in the DoExpressCheckoutPayment request Use this value to locate the response data for each payment e SellerDetailsType PayPalAccountId returns one of the following values that was passed in The merchant s email address The merchant s Payer ID secure merchant account ID If errors occur check the response data in the Payment Info PaymentError field PaymentError
86. ns in your web application The pal alerts PayPal to campaigns in which you are participating PayPal obtains this information from your account and replaces the default image with the appropriate campaign image during the relevant campaign NOTE Ifyou pass in a pal value for a merchant account that is not yours PayPal displays the image for that account Be sure to pass the pal value for your account April 2012 Express Checkout Advanced Features Guide Express Checkout Dynamic Image Integration Configuring the Dynamic Image Change the Locale To specify the locale of the image append the locale parameter set to the code for the appropriate country to the image URL If a country does not have a localized image or if you do not pass a locale value the default US image displays This example displays the image for the Spanish locale https fpdbs paypal com dynamicimageweb cmd _dynamic image pal SFJCXFDLNFR5U amp locale es_ES If you are participating in a campaign across multiple countries you can set the image locale for each country in which you participate PayPal returns the default image associated with the locale when the campaign is over Provide Incentive Eligibility Feedback to Buyer Pass the order total amount in the ordertotal parameter so PayPal can determine if the buyer is eligible for an incentive Say for example that you are participating in a campaign in which the buyer is eligible for a 20 discoun
87. nts are well suited for processing with reference transactions which are used in the same way as reference transactions in credit card processing When implementing recurring payments using reference transactions you control transaction initiation and the transaction amount You can also include payment for multiple items in one checkout NOTE PayPal must enable you to use reference transactions Contact PayPal for details Reference Transactions A reference transaction is a financial transaction from which you can derive subsequent transactions For example a buyer makes a purchase on your site and you use the PayPal transaction ID or reference transaction ID later to initiate another transaction In the music video example you might use the transaction generated by the purchase to initiate a monthly transaction for renting videos from the service Similarly you can use the transaction for the first download to generate another transaction for other downloads Express Checkout Advanced Features Guide April 2012 57 az Reference Transactions Introduction to Reference Transactions Billing Agreements You must have the buyer s agreement to obtain funds from the buyer s account The buyer must log in to PayPal once to agree but after that PayPal does not require the buyer to log in This agreement represents a billing agreement between you and the buyer PayPal maintains the agreement The buyer can agree during the Express Checkout
88. of electronic media you should not allow download access Because the payment status changes after review you must periodically check the payment status using the Get TransactionDetails API operation The following diagram shows how to use the payment status to detect payments under review by PayPal 92 April 2012 Express Checkout Advanced Features Guide Payment Review ana Handling Payment Review DoExpressCheckoutPayment DoReferenceTransaction DoAuthorization DoReautorization API Operation Completed Okay to ship Cancel Reversed Y Pending GetTransaction payment 5 Details review Completed Okay to ship Cancel IMPORTANT For best results call the GetTransactionDetails API operation every six hours PayPal recommends not calling GetTransactionDetails more frequently than once per hour Reversed Express Checkout Advanced Features Guide April 2012 93 Te Payment Review Handling Payment Review 94 April 2012 Express Checkout Advanced Features Guide Express Checkout Dynamic Image Integration PayPal hosts the PayPal buttons and logo images that you use on your website Using only hosted buttons and images standardizes their appearance on websites that use PayPal as a payment option which is convenient for you and gives your buyers confidence that their transaction will be safe and secure Dynamic Images To use dynamic images you must pass infor
89. ong with any two of the following line item parameters the order description value does not display e L PAYMENTREQU e L_PAYMENTREQU EST_N_NAMEM EST_n_NUMBERM e L PAYMENTREQU If you pass in unit price information L_PAYM EST_n_DESCm ENTREQUEST_n_AMTm without passing in the unit quantity L_PAYMENTR values you must pass in values for both parameters You can pass in a value of 1 even if the item purchase is uncountable EQUEST_n_OTY m the unit price does not display To show both The following example shows how to set line item parameters in the call to set ExpressCheckout April 2012 Express Checkout Advanced Features Guide Customizing Express Checkout Providing Gift Options Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTREQUEST_0O_PAYMENTACTION Sale amp L_PAYMENTREQUEST_0O_NAME0 10 Decaf Kona Blend Coffee amp L_PAYMENTREQUEST_0_NUMBERO 623083 amp L_PAYMENTREQUEST_0_DESC0 Size 8 8 o0z amp L_PAYMENTREQUEST_0_AMT0 9 95 amp L_PAYMENTREQUEST_0_QTY0 2 amp L_PAYMENTREQUEST_0_NAME1 Coffee Filter bags amp L_PAYMENTREQUEST_0_NUMBER1 623084 amp L_PAYMENTREQUEST_0_DESC1 Size Two 24 piece boxes amp L_PAYMENTREQUEST_0_AMT1 39 70 amp L_PAYMENTREQUEST_0_OTY1 2 amp PAYMENTREQUEST_0_ITEMAMT 99 30 amp PAYMENTREQUEST
90. ontinue for eBay incentives 11 13 2008 Added information about integrating dynamic images and added information about order details that can be displayed on the PayPal Review page Express Checkout Advanced Features Guide April 2012 107 Date Description 06 30 2008 Complete revision 108 April 2012 Express Checkout Advanced Features Guide
91. pass the buyer s shipping address telephone number and email address in the call to SetExpressCheckout PayPal automatically fills out this information in the debit or credit card form fields on the PayPal Choose a way to pay page After the call to SetExpressCheckout the buyer is redirected to the PayPal On the Choose a way to pay page buyers having a PayPal account can log in with their email address and password Buyers who do not have an account can use their debit or credit card to pay and will have their shipping and contact information filled out See the following SetExpressCheckout example Express Checkout Advanced Features Guide April 2012 25 a Customizing Express Checkout Automatically Filling Out Shipping and Contact Information Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp PAYMENTREQUEST_0_SHIPTOSTREET 1 Main Street amp PAYMENTREQUEST_0O SHIPTOCITY San Jose amp PAYMENTREQUEST_0_SHIPTOSTATE CA amp PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE US amp PAYMENTREQUEST_0_SHIPTOZIP 95131 amp PAYMENTREQUEST_0_EMATL 7jsmith01 example com amp PAYMENTREQUEST_0_SHIPTOPHONENUM 408 559 5948 Response Parameters successResponseFields amp TOKEN EC 6UA07551EA393551U The figure below shows the
92. payment1 ShippingTotal new BasicAmountType payment1 ShippingTotal currencyID CurrencyCodeType USD payment1 ShippingTotal Value 3 00 payment1 ItemTotal new BasicAmountType paymentl1 ItemTotal currencyID CurrencyCodeType USD payment1 ItemTotal Value item_total ToString payment1 TaxTotal new BasicAmountType payment1 TaxTotal currencyID CurrencyCodeType USD paymentl TaxTotal Value tax_total ToString decimal order_total decimal Add decimal Add tax_total item_total decimal Parse payment1 ShippingTotal Value payment1 OrderTotal new BasicA mountType payment1 OrderTotal currencyID CurrencyCodeType USD payment1 OrderTotal Value order_total ToString mandatory for api call payment1 PaymentRequestID System Guid NewGuid ToString add the merchants to the array PaymentDetailsArray SetValue paymentl 0 J RRR RRR RK RK KKK KK I A a I I I KIA AK KK A A IK AK KK merchant 2 J RRR RRR RK RK KR KK KK I a I I AAR KA A I I AK KA PaymentDetailsType payment2 new PaymentDetailsType 70 April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API nt2 PaymentAction PaymentActionCodeType Order nt2 PaymentActionSpecified true nt2 SellerDetails new SellerDetailsType nt2 S ellerDetails PayPalAccountID airline
93. press payment Checkout request you can create a billing agreement without initiating a NOTE Tocreate a billing agreement without purchase use Version 54 0 or higher of the PayPal API To set up one or more billing agreements for recurring payments modify the SetExpressCheckout request as follows 1 Add an L_BILLI NGTYPEn field for each billing agreement you want to create n is a value in the range of 0 to 9 inclusive Set the value of each field to RecurringPayments L_BILLINGTYPEO RecurringPayments 2 Add an L BILLI NGAGREEMENTDESCRIPTIONz field to correspond to each L_BILLINGTYPE n field you pass n is a value in the range of 0 to 9 inclusive Set the value of each fie ld to the description of the goods or services associated with that billing agreement for example L_BILLINGAGR EEMENTDESCRIPTIONO Time Magazine subscription 3 If there is no associated purchase set PAYMENTREQUEST_0O_AMT to 0 PAYMENTREQU EST_O_AMT 0 4 Optional Set MAXAMT to the average expected transaction amount PayPal uses the value you pass to validate the buyer s payment method for recurring payments If you do not specify a value the default is 25 00 The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls Redirecting
94. rect mE Ganime e p N Receipt ees Request Token lt GetExpressCheckoutDetails PayPal PayNow A lt Q Response Customer Details API Server v E ees Request Final Transaction Details gt TREE DoExpressCheckoutPayment lt Response Transaction Results s PayPal Request Final Transaction Details API Server CreateRecurringPaymentsProfile lt lt V Response Transaction Results s m Profile ID Success Failure The circled numbers in the diagram correspond to the numbered steps in the following table Recurring payments processing flow Step Merchant PayPal 1 Calls SetExpressCheckout setting up one or more billing agreements in the request Returns a token which identifies the transaction to the merchant April 2012 Express Checkout Advanced Features Guide Handling Recurring Payments So Recurring Payments With the Express Checkout API Step Merchant PayPal 3 Redirects buyer s browser to https www paypal com cgi bin webscr cmd _express checkout amp token lt token returned by SetExpressCheckout gt Displays login page and allows buyer to select payment options and shipping address 4 Redirects buyer s browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description 5 Calls GetExpressCheckoutDetails to get buyer information optional Returns GetExpressCheckoutDetails response Displays mer
95. requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp PAYMENTREQUEST_0_AMT 10 00 amp PAYMENTREQUEST_0_CURRENCYCODE USD amp PAYMENTREQUEST_0_PAYMENTACTION Sale amp PAGESTYLE TestMerchant Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Individual Page Style Characteristics Typically you create a custom page style for the PayPal pages using the custom payment pages in your Account Profile In cases where you do not want to use the Account Profile option you can specify these individual page style characteristics using variables in your program code e Logo image a URL to an image of your logo e Cart review area border color your principal identifying color PayPal blends your color to white in a gradient fill that borders the cart review area To define your logo image 1 Create a logo image up to 90 pixels wide by 60 pixels high and save it in a valid graphics format such as gif jpg or png 2 Store the URL to the image on a secure https server so your buyer s web browser does not display a message that the payment contains insecure items 3 Assign the URL to the LOGOIMG parameter in the call to SetExpressCheckout To display the border in your principal identifying color set the CARTBORDERCOLOR parameter to the 6 digit hexadecimal valu
96. return to if they cancel out of the Express Checkout payment flow CANCELURL https mobileWebsitePage htm1 4 Remove any non supported fields from your SetExpressCheckout and DoExpressCheckoutPayment calls Include only fields for supported features April 2012 Express Checkout Advanced Features Guide Express Checkout on Mobile Devices POER Integrating Express Checkout With Your Mobile Website Result When you redirect to PayPal and the buyer pays on PayPal the following Login page appears on an iOS device ll ATT A 15 16 mag JD Sports Fashion x N My total 69 99 GBP Login PayPal Log in with email and password Email Password Don t have a PayPal account Pay with a card When the buyer logs in to PayPal the following Review page appears on an iOS device Express Checkout Advanced Features Guide April 2012 33 r Express Checkout on Mobile Devices Enabling PayPal Account Optional Checkout on Mobile Devices lt 4 D QA commit amp token 6C 7JU406023V263851M Gary McCue s Test Store My total 19 95 USD Review Payment method Bank xx 3509 19 95 USD Ship to Test User 1 Main St San Jose CA 95131 United States Other info A Please include information below Note to seller Checkout using iPad Related information Features Not Supported by Express Checkout on Mobile Devices on page 41 Enabling PayPal Account Optiona
97. returns the ErrorType information It is possible that errors are returned only for a subset of payments while other payments are successful For failed payments you should ask the buyer for an alternate payment method The following SOAP example sets up the merchants receiving funds PaymentDetailsType PaymentDetailsArray new PaymentDetailsType 9 J RRR RRR RRR KKK KK A A A I I IAA KAA A A II KK merchant 1 J RRR RRR RRR KK KKK IK A III KARR AA ee IIA A PaymentDetailsType paymentl new PaymentDetailsType payment1 PaymentAction PaymentActionCodeType Order payment1 PaymentActionSpecified true payment1 SellerDetails new SellerDetailsType payment1 SellerDetails PayPalAccountID support lstimagehosting com set up the line items for the first merchant PaymentDetailsItemType paymentl_items_array new PaymentDetailsItemType 2 PaymentDetailsItemType paymentl_iteml new PaymentDetailsItemType payment1l_iteml Amount new B asicAmountType payment1l_iteml Amount currencyID CurrencyCodeType USD payment1_item1 Amount Value 1 00 payment1l_item1 Description paymentl_iteml_desc payment1_item1l Name payment1_iteml_name payment1l_item1 Number payment1_iteml_number payment1_iteml ItemURL http iteml com payment1l_iteml Quantity 3 payment1_item1l Tax new BasicAmountType payment1l_item1
98. s you must provide an appropriate message to the buyer remove the Immediate Payment item and retry the transaction The Call to DoExpressCheckoutPayment To integrate Immediate Payment into the DoExpressCheckoutPayment call 1 Set PAYMENTREQUEST_n_ALLOWEDPAYMENTME THOD to InstantPaymentOn1y This blocks all pending funding sources and transactions in a pending state 2 Pass the L_PAYMENTREQUEST_n_EBAYITEMCARTIDm 3 Be prepared to handle Immediate Payment errors For errors you choose to handle you need to send the buyer error messages appropriate to the situations generating the errors For example you determine that the buyer has a mixed cart of eBay and non eBay items To allow the buyer to check out only the non Immediate Payment items you must provide an appropriate message to the buyer remove the Immediate Payment item and retry the transaction If payment is successful the DoExpressCheckoutPayment response returns the eBay transaction ID PAYMENTREQUEST_n_EBAYTTEMAUCTIONTXNID About Immediate Payment For Express Checkout Immediate Payment for Express Checkout ensures the buyer pays for purchases at the time the buyer commits This application is available to any merchant integrating Express Checkout NOTE This feature is available with API version 63 0 and higher Immediate Payment for Express Checkout has the following caveats
99. s Checkout API 59 Initiating a Payment Using a Reference Transaction 60 About Cancelling Agreements and Getting the Billing Address 61 Canceling a Billing Agreement oaoa 62 Obtaining the Most Recent Billing Address 0 2 20000 62 Chapter 5 Implementing Parallel Payments 63 About Parallel Payments 2 2 a 63 What Is and What Is Not Supported 2 2 a 63 Post Integration Experience 22 0002 eee ee ee 63 Name Value Pair Syntax Supporting Parallel Payments 65 Integrating Parallel Payments by Using the NVP API 66 Integrating Parallel Payments by Using the SOAP API 2 4 68 Best Practices for Online Travel Agencies Implementing Parallel Payments 72 Styles of Payment 2 72 Payment Details lt a 4 404 405 a ee Ad ae oe RY oe Ee Ree ee a a 73 Panding EMOS s 6 2c hee bah bo ee bot eck oe ee SED 2 me wee db ek amp de eB 74 Chapter 6 Integrating giropay with Express Checkout 75 giropay Page Flows 2 2 a LE AR 75 giropay Payment Page Flow 0000 2 eee ee es 75 Canceled or Unsuccessful giropay Payment Page Flow 76 giropay Integration s sss ea a wa a ald ha ae a a a a A L E 76 Initiate the Flow with SetExpressCheckout aooaa a 0002 ee eee 76 Redirect the Buyer to PayPal aaua aaa a 76 Complete the Transaction oa aoo 77 R
100. sponse April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments Parallel payments enables a single buyer to pay multiple merchants in a single checkout session Parallel payments is available with API version 63 0 and higher About Parallel Payments Parallel payments enables buyers to pay multiple merchants on a marketplace in a single Express Checkout session An online travel agency marketplace is a typical example of parallel payments in use The buyer purchases airline tickets and makes reservations from various merchants such as hotels car rental agencies and entertainment venues hosted on the site By implementing parallel payments through Express Checkout the marketplace host accepts PayPal as a payment method The host also provides the buyer with a consolidated order on the PayPal Review your information page summarizing expenses itineraries and other supporting information Buyers see travel information including cancellation fees directly from the supplier on the Transaction Details page and in an email message What Is and What Is Not Supported Parallel payments e Supports sales and orders that you later capture with the authorization and capture API operations e Supports up tol0 payments in one Express Checkout session NOTE The same merchant can receive multiple payments in one Express Checkout session e Does not support use of the Instant Update API callback e Does no
101. ss checkout amp token lt value_from_SetExpressCheckoutResponse gt PayPal then redirects the buyer from this redirect page to the necessary page for the selected funding source The GetExpressCheckoutDetails response contains the REDIRECTREQUIRED field which lets you know if you need to redirect the buyer after your Order Review page You can use this value to inform the buyer on your Order Review page that they will be sent to the giropay website to complete the order Complete the Transaction Corresponding to the three fields passed to SetExpressCheckout you must add the following three additional pages to your website Your website s pages Description Order Completion The page specified in GIROPAYSUCCESSURL to which PayPal redirects the buyer after a successful giropay payment Order Cancelation The page specified in GIROPAYCANCELURL to which PayPal redirects the buyer after a giropay or bank transfer payment is canceled or fails Order Pending The page specified in BANKTXNP ENDINGURL to which PayPal redirects the buyer after a bank transfer payment Receive Transaction Status Notification After PayPal redirects the buyer to giropay you receive transaction status information in the following ways e IPN Notification e Email only for successful giropay or bank transfer transactions e PayPal Account Overview e PayPal reports Express Checkout Advanced Features Guide
102. ss Checkout on mobile devices supports only these NVP fields NVP SetExpressCheckout Request Fields Supported on Mobile Devices AMT RETURNURL CANCELURL TOKEN MAXAMT DESC CUSTOM INVNUM REQCONF IRMSHIPPING NOSHIPPING ADDROVERRIDE LOCALECODE The following values are not supported e AD Andorra e AL Albania e AM Armenia e BR Brazil o GE Georgia e VA Holy See e e e e IN India MC Monaco MD Moldova UA Ukraine PAYMENTACTION EMAIL SOLUTIONTYPE CHANNELTYPE value must be mark value must be merchant BRANDNAME NVP Address Type Fields Supported by Express Checkout on Mobile Devices STREET STREET2 CITY STATE COUNTRYCODE ZIP SHIPTOPHONENUM Express Checkout Advanced Features Guide April 2012 37 Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices NVP Payment Details Type Fields Supported by Express Checkout on Mobile Devices PAYME NTRE QUEST_nN_AMT AMT deprecated PAYME INTREQUEST_N_CURRENCYC ODE CURRENCYCODE deprecated PAYMENTREQUEST_nN_ITEMAMT ITEMAMT deprecated PAYMENTREQUEST_n_SHIPPINGA SHIPPINGAMT deprecated PAYMENTREQUEST_n_INSURANCE MT AMT INSURANCEAMT deprecated PAYMENT
103. ss rules To verify that callback requests originate from PayPal The HTTP protocol to specify in your callback URL depends on the integration environment you are using e The callback URL must start with HTTPS for production integration e The callback URL must start with HTTP or HTTPS for PayPal Sandbox integration In the call to SetExpressCheckout you must complete the steps 1 through 3 below Steps 4 and 5 are optional 1 Provide line item details for the merchandise the buyer selected 2 Provide the URL to your callback server which PayPal validates 3 Provide values for the flat rate shipping options For each option specify Option name L_SHIPPINGOPTIONNAME n Option amount L_SHIPPINGOPTIONAMOUNT n The shipping option to appear as the default t rue L_SHIPPINGOPTIONISDEFAULTn NOTE Set L_SHIPPINGOPTIONISDEFAULTn to true default for one and only one shipping option Set L_SHIPPINGOPTIONISDEFAULTn to false for each of the remaining options If required an adjusted value for PAYMENTREQUEST_n_TAXAMT Ifrequired an adjusted value PAYMENTREQUEST_n_INSURANCEAMT 4 If necessary to adjust the callback timeout default 3 seconds provide a value from 1 to 6 for the CALLBACKTIMEOUT parameter 5 Optionally provide values for any of the shipping option description details fields lis
104. t is possible for some merchant payments to succeed while others fail Parallel payments creates multiple independent payments and each payment is subject to its own validation and review If part of a payment fails the ACK value is PartialSuccess To find the error check the value returned in PAYMENTINFO_n_ERRORCODE in the response to Dol ExpressCheckoutPayment NOTE Ifan error is generated by any of the payments in the call to SetExpressCheckout the transaction fails Express Checkout Advanced Features Guide Integrating giropay with Express Checkout You must modify your Express Checkout implementation to use giropay a common German funding source giropay Page Flows If you accept giropay you must redirect to the giropay website to collect the funds after completing the Express Checkout transaction When your buyer selects giropay as a funding source during the Express Checkout flow you redirect the buyer to a static PayPal URL after your order review page PayPal then redirects the buyer to the giropay website to push the funds to the merchant After the giropay payment is successfully completed the transaction is confirmed If the giropay payment fails or the buyer cancels PayPal provides the necessary details for an electronic funds transfer EFT so that the buyer can complete the transaction by pushing funds from his or her bank account If your PayPal account profile blocks non instant paym
105. t on Mobile Devices 29 About the Express Checkout Experience on Mobile Devices 29 Buyer Pays on Your Site 2 a 29 Buyer PaysonPayPal 0 000 pee ee 30 Mobile Platforms Supported by Express Checkout 2 00005 30 About Mobile Express Checkout Integration 0 00 202000004 31 Express Checkout Advanced Features Guide April 2012 3 a Contents Integrating Express Checkout With Your Mobile Website 31 Enabling PayPal Account Optional Checkout on Mobile Devices 34 Request Fields Supported by Express Checkout on Mobile Devices 36 NVP Request Fields Supported by Express Checkout on Mobile Devices 37 SOAP Request Fields Supported by Express Checkout on Mobile Devices 39 Locales Supported by Express Checkout on Mobile Devices 40 Locale Codes Not Supported by Express Checkout on Mobile Devices 40 Handling Locales Not Supported by Express Checkout on Mobile Devices 40 Features Not Supported by Express Checkout on Mobile Devices 41 Chapter 3 Handling Recurring Payments 43 How Recurring Payments Work 2 2 a 43 Limitations e 3 0 44 244 a4 Ge ook ea bee a eRe BAR a ee eS 43 Recurring Payments Terms aoaaa aaa a 44 Options for Creating a Recurring Payments Profile 45 Specifying the Regular Payment Period 2 2 2 ee ee 45 I
106. t sProfile request The following table lists the required fields for creating an optional trial period Required fields for specifying a trial period NVP SOAP TRIALBILLINGPERIOD ScheduleDetails TrialPeriod BillingPeriod TRIALBILLINGFREQUENCY ScheduleDetails TrialPeriod BillingFrequency TRIALAM ScheduleDetails TrialPeriod Amount TRIALTOTALBILLINGCYCLES ScheduleDetails TrialPeriod TotalBillingCycles Specifying an Initial Payment You can optionally specify an initial non recurring payment when the recurring payments profile is created by including the following fields in the CreateRecurringPaymentsProfile request Required fields for specifying an initial payment NVP SOAP INITAMT ScheduleDetails ActivationDetails InitialAmount FAILEDINITAMTACTION ScheduleDetails ActivationDetails FailedInitAmountAction By default PayPal does not activate the profile if the initial payment amount fails To override this default behavior set the FAILEDINITAMTACTION field to ContinueOnFailure If the initial payment amount fails Cont inueOnFailure instructs PayPal to add the failed payment amount to the outstanding balance due on this recurring payment profile If you do not set FATLEDINITAMTACTION or set it to CancelOnFailure PayPal creates the recurring payment profile However PayPal places the profile into
107. t support accelerated boarding however single payment transactions are still supported e Does not support parallel billing agreements Post Integration Experience After you integrate parallel payments the PayPal cart review area shows summary information for each payment The following figure is an example of summary information for an online travel agency with payments to an airline and a hotel Express Checkout Advanced Features Guide April 2012 63 ine Implementing Parallel Payments About Parallel Payments Your order summary Description Amount H Vandelay Airlines 300 00 1 Central Perk Hotel 200 00 Total USD 500 00 The following figure shows expanded details on the airline purchase Your order summary Description Amount I Vandelay Airlines 300 00 Depart San Jose Feb 12 at 12 10 PM item number Flight 22 tem price 50 00 Quantity 1 Depart Battimore Feb 15 at 6 13 PM z tem number Flight 961 tem price 150 00 Quantity 1 Total USD 500 00 ix The following figure shows expanded details on the hotel payment 64 April 2012 Express Checkout Advanced Features Guide Implementing Parallel Payments aaa Name Value Pair Syntax Supporting Parallel Payments Your order summary Description Amount insurance 0 00 K Central Perk Hotel 200 00 Night s stay at 9990 Deereco Road Total USD 500 00 Name Value Pair Syntax Supporting Parallel Payments The PayPal API uses a speci
108. t when their order meets a minimum of 50 00 You can pass that value to PayPal in the ordertotal parameter as shown here https fpdbs paypal com dynamicimageweb cmd _dynamic image amp pal SFJCXFDLNFR5U ordertotal 50 00 When a buyer s order meets or exceeds 50 00 PayPal displays the incentive image informing the buyer of their eligibility for the discount When a buyer s order is less than 50 00 PayPal displays the default image NOTE If ordertotal is not passed PayPal does not display the incentive image even if the buyer is eligible for the incentive Choose the Image To specify the image that you want to display set the value of buttont ype This example sets buttontype to the PayPal mark image https fpdbs paypal com dynamicimageweb cmd _dynamic image amp pal SFJCXFDLNFR5U buttont ype ecmark The default value for buttontype is ecshortcut Express Checkout Advanced Features Guide April 2012 97 98 Express Checkout Dynamic Image Integration Dynamic Image Command Reference Dynamic Image Command Reference To set up the information that enables dynamic images add parameters to the dynamic image URL Dynamic Image Parameters pal ordertotal locale buttontype Optional The encrypted PayPal account number When merchants sign up for a PayPal business account PayPal assigns them an account number The pal value represents the pay to merchant account not a third party making the
109. tain a billing agreement ID for later use Do not call DoExpressCheckoutPayment because no payment is involved Otherwise call DoExpressCheckoutPayment to obtain the billing agreement ID and to initiate an Express Checkout payment The following diagram shows the flow for obtaining a billing agreement ID during an Express Checkout payment Legend a gt Web Flow API Call Token w Agreement IO lerchant Site Pa ay t Page Payl 0 n Request SetExpressCheckout PayPal A94 To Ganl rs Response Token API Server The set comer wary be pay Merchant website k L HTTP Redirect mm pom a PEN Fy HTTP Redirect EEE Agree _____ Confirm Order es Request Token GetExpressCheckoutDetails PayPal Pay O lt Response Customer Details API Server Vv Request Final Transaction Details gt Thank You DoExpressCheckoutPayment PayPal v Response Transaction Results ume AP Server Agreement Success Failure The numbered steps correspond to the circled numbers Your site must take the specified actions at each step as follows Express Checkout Advanced Features Guide April 2012 59 az Reference Transactions Initiating a Payment Using a Reference Transaction Call SetExpressCheckout and pass a BillingAgreementDetails element that contains the following information A billing type PayPal recommends that you use Merchant InitiatedBillingSingleAgreement i
110. ted below Option weight L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEM L_PAYMENTREQUEST_n_ITEMWEITHTUNITm Option height L_PAYMENTREQUEST_n_ITEMHETGHTVALUEM L_PAYMENTREQUEST_n_ITEMHEIGHTUNITmM R T E z Option length L_PAYMENTREQUEST_n_ITEMLENGTHVALUEM L_PAYMENTREQUEST_n_ITEMLENGTHUNITm Option width L_PAYMENTREQUEST_n_ITEMWIDTHVALUEM L_PAYMENTREQUEST_n_ITEMWIDTHUNITm a z 84 April 2012 Express Checkout Advanced Features Guide Implementing the Instant Update API Setting Up the Callback Related information PayPal Review Page Order Details on page 9 GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes When you implement the callback you need to call GetExpressCheckoutDetails and DoExpressCheckoutPayment GetExpressCheckoutDetails and DoExpressCheckoutPayment include new parameter fields in support of the Instant Update API You must call the GetExpressCheckoutDetails API operation to obtain the buyer s final shipping option selections GetExpressCheckoutDetails has been updated to return the buyer s selections Because the cart information passed in the call to SetExpressCheckout is relevant only for display on the PayPal pages you must call the DoExpressCheckoutPayment API operation with the upd
111. tegrate with the Express Checkout flow Initiate the Flow with SetExpressCheckout To support giropay payments pass the following three URLs as part of the SetExpressCheckout request NVP Field Description GIROPAYSUCCESSURL The URL on the merchant site to redirect to after a successful giropay payment GIROPAYCANCELURL The URL on the merchant site to redirect to after a giropay or bank transfer payment is cancelled or fails BANKTXNPENDINGURL The URL on the merchant site to transfer to after a bank transfer payment These URLs tell PayPal where to redirect the buyer based on the success or failure of each type of payment transaction See the PayPal Name Value Pair Developer Guide and Reference for more information Redirect the Buyer to PayPal After selecting a funding source on PayPal the buyer is redirected back to your website as in the regular Express Checkout flow There is one additional field REDIRECTREQUIRED returned in the response from both GetExpressCheckoutDetails and DoExpressCheckoutPayment April 2012 Express Checkout Advanced Features Guide Integrating giropay with Express Checkout giropay Integration aa NVP Field Description REDIRECTREQUIRED Flag to indicate whether you need to redirect the buyer to back to PayPal If the value of this field is t rue redirect the buyer from your Order Review page to https www paypal com webscr cmd _complete expre
112. temType Key in payment2_items_array if Key Tax null tax_total2 decimal Add tax_total2 decimal Multiply decimal Parse Key Tax Value decimal Parse Key Quantity if Key Amount null item total2 decimal Add item_total2 decimal Multiply decimal Parse Key Amount Value decimal Parse Key Quantity payment2 ShippingTotal new BasicAmountType payment2 ShippingTotal currencyID CurrencyCodeType USD payment2 ShippingTotal Value 3 00 Express Checkout Advanced Features Guide April 2012 71 72 Implementing Parallel Payments Best Practices for Online Travel Agencies Implementing Parallel Payments nt2 ItemTotal new BasicAmountType payment2 ItemTotal currencyID CurrencyCodeType USD payment2 ItemTotal Value item_total2 ToString payme e e payment2 TaxTotal new BasicAmountType e e m payment2 TaxTotal currencyID CurrencyCodeType USD payment2 TaxTotal Value tax_total2 ToString decimal order_total2 decimal Add decimal Add tax_total2 item_total2 ecimal Parse payment2 ShippingTotal Value nt2 OrderTotal new BasicAmountType nt2 OrderTotal currencyID CurrencyCodeType USD nt2 OrderTotal Value order_total2 ToString the merchants to the array ntDetailsArray SetValue payment2 1 bind the merchants to the request SetECReq SetExpressCheckoutRequest SetExpressC
113. that amount at any time Identifying Items as Digital or Physical Goods Set all the payment details item fields in the following table in the CreateRecurringPayment sProfile request If all items are digital goods be sure to set the item category field to Digital to get the discount rate for digital goods Required fields for specifying item details NVP SOAP Description L_PAYMENTREQUEST_0O_ ItemCategory For digital goods this field must be set to ITEMCATEGORYN Digital e Digital e Physical PAYMENTREQUEST_O Name Item name NAMEN PAYMENTREQUEST_O_ Amount Cost of item AMTn PAYMENTREQUEST_O_ Quantity Item quantity OTYN Recurring Payments With the Express Checkout API During the checkout flow you can create one or more recurring payments and mix recurring payments with other purchases The following diagram illustrates the typical processing flow to create recurring payments during checkout Express Checkout Advanced Features Guide April 2012 47 48 Handling Recurring Payments Recurring Payments With the Express Checkout API Legend m Web Flow API Call Token v Profile ID JayPal Payment Pages PayPal Servers e ees Rel cst Checkout SetExpressCheckout PayPal API Server SOS Response Token The ssia aasma way io pey Merchant website L HTTP Redirect mm mn v n HTTP Redi
114. the buyer confirming a purchase on your site The following diagram shows the DoReferenceTransaction message flow for a buyer making a purchase from your site Legend gt API Call w Agreement ID Merchant Website Request pres ser ip DoReferenceTransaction p PayPal Response API Server Agreement ID Transaction ID PayPal does not require that you have a buyer on your site For example you could call DoReferenceTransaction for each buyer in a batch of buyers whose utility bills are due The following diagram shows the DoReferenceTransaction message flow for a server initiated recurring payment Legend gt APICall w Agreement ID f Request i Merchant Agreement ID DoReferenceTransaction PayPal Server Response API Server SSS Agreement ID Es Transaction ID About Cancelling Agreements and Getting the Billing Address You can use the BAUpdate API operation NVP METHOD BillAgreementUpdate to perform two distinct functions cancel a billing agreement or obtain the buyer s latest billing address NOTE To update a billing agreement as the operation name implies you call BAUpdate to cancel the agreement Then you must create a new billing agreement Express Checkout Advanced Features Guide April 2012 61 62 Reference Transactions About Cancelling Agreements and Getting the Billing Address Canceling a Billing Agreement You can use BAUpdate NVP METHOD Bi11lAgreement Update to cancel a
115. the only payment action supported Express Checkout Advanced Features Guide April 2012 101 10 Immediate Payment About Immediate Payment For Third Party Checkout e It does inventory checking at eBay and attempts to purchase the item After the buyer selects the item on eBay the buyer is redirected to your website Express Checkout flow The following figure shows how Immediate Payment for third party checkout integrates into your checkout flow cml mmm Me Place Order eckout onfirmation Jil gt u gt b C Order The sehe oem way ie pey Merchant Redirects to PayPal PayPal Server SetEC GetEC DoEC eBay Payment optional Payment transaction method type method type ID Buyer user name TOKEN eBay item eBay item cart ID cart ID Merchant System From left to right the following events are represented The numbered callouts in the figure directly correspond to the numbered comments below 1 The eBay flow for third party checkout redirects the buyer from an eBay payment review page to your shopping cart page On your shopping cart page the buyer initiates Express Checkout by clicking the Checkout with PayPal button 2 In the call to the SetExpressCheckout API operation you must pass the following Immediate Payment information PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD This is the payment method type For immediate payment the value is Instant PaymentOnLly BUYERUSERNAME eBay provides you with this valu
116. tions e To be able to create a recurring payments profile for the buyer you must ensure that the buyer s PayPal account includes an active credit card e You can create a maximum of 10 recurring payments profiles during checkout e You can increase the profile amount by only 20 in each 180 day interval after you create the profile Recurring Payments Terms The following table lists and describes terms that are commonly used in the context of PayPal recurring payments Recurring Payments Terms Term Definition Recurring payments profile Your record of a recurring transaction for a single buyer The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval Billing cycle Make one payment per billing cycle Each billing cycle has 2 components e The billing period specifies the unit to calculate the billing cycle such as days or months e The billing frequency specifies the number of billing periods that make up the billing cycle For example if the billing period is Month and the billing frequency is 2 the billing cycle is 2 months If the billing period is Week and the billing frequency is 6 PayPal schedules the payments every 6 weeks Regular payment period The main subscription period for this profile which defines a payment amount for each billing cycle The regular payment period begins after the trial period if you specify a trial period for the prof
117. tures Guide B e CA Canada C Cc Customizing Express Checkout as Changing the Locale R Brazil H Switzerland N China e DE Germany e ES Spain e GB United Kingdom e FR France e IT Italy e NL Netherlands e PL Poland e PT Portugal e RU Russia e US United States e The following 5 character codes are also supported for languages in specific countries da_DK Danish for Denmark only he_ id_ IL Hebrew all ID Indonesian for Indonesia only jp_JP Japanese for Japan only no_NO Norwegian for Norway only pt ru_ BR Brazilian Portuguese for Portugal and Brazil only RU Russian for Lithuania Latvia and Ukraine only sv_SE Swedish for Sweden only th_TH Thai for Thailand only tr_TR Turkish for Turkey only zh_CN Simplified Chinese for China only zh_HK Traditional Chinese for Hong Kong only zh_TW Traditional Chinese for Taiwan only The following example sets LOCALCODE to ES Spain Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETU RNURL https amp CANC EN amp PAY ELURL https REQUEST_O_AMT 10 00 amp PAY EN REQUEST_0O_CURRENCYCODE EUR amp PAY EN REQUEST_0_PAYMENTACTION Sale amp LOCALECODE ES Express Checkout
118. ular payment period e Billing amount e Number of billing cycles NOTE For recurring payments with the Express Checkout API PayPal does not allow certain updates such as billing amount within 3 days of the scheduled billing date The profile changes take effect with the next payment after the call to update the profile Say for example the buyer has made 1 trial payment out of a total of 3 You call UpdateRecurringPaymentsProfile to increase the number of billing cycles to 5 This provides the buyer with 4 additional trial payments If you call UpdateRecurringPaymentsProfile during the regular payment period the changes take effect with the buyer s next scheduled regular payment For complete details see the Name Value Pair Developer Guide and Reference or the SOAP API Reference Updating Addresses When you update the subscriber shipping address you must enter all of address fields not just those that are changing To update the subscriber s street address for example specify all the address fields listed in the Name Value Pair Developer Guide and Reference or SOAP API Reference Do not specify only the street address field Updating the Billing Amount For profiles created using Express Checkout you can increase the recurring payment total amount by 20 maximum in a fixed 180 day interval after profile creation The 20 maximum is based on the total amount of the profile at the beginning of the 180 day interval
119. ures Guide April 2012 95 96 Express Checkout Dynamic Image Integration Configuring the Dynamic Image Set Up the Default Image The following URL points to the default Check out with PayPal image https fpdbs paypal com dynamicimageweb cmd _dynamic image To make the image dynamic you need only add parameters to this URL to specify the changes you want displayed To test in the Sandbox environment send the image to the following Sandbox URL https fpdbs sandbox paypal com dynamicimageweb cmd _dynamic image Set Up Image for Dynamic Use To set up the image URL for dynamic use associate the URL with your PayPal Secure Merchant Account ID or pal Use the Secure Merchant Account ID in your Profile or call GetPalDetails This is an example call to GetPalDet ails request Request Parameters requiredSecurityParameters amp METHOD GetPalDetails Response Parameters This GetPalDetails response returns the value of PAL and your country code LOCALE wma successResponseFields amp PAL SFICXFDLNFR5U amp LOCALE en_US 1 Append the pal parameter to the image URL and set the parameter to the value of your encrypted PayPal merchant account number https fpdbs paypal com dynamicimageweb cmd _dynamic image amp pal SFJCXFDLNFR5U 2 You can optionally change the value of LOCALE See Change the Locale for details 3 Place the URL with parameter information at the appropriate image locatio
120. you set up a billing agreement for a recurring payment that is not immediately charged e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_CUSTOM e PAYMENTREQUEST_n_INVNUM Creating the Profiles With CreateRecurringPaymentsProfile After your buyer has agreed to the recurring payments billing agreement on your confirmation page you must call CreateRecurringPaymentsProfile to create the profile If you are creating multiple recurring payments profiles you must call CreateRecurringPayment sProfile once for each profile you plan to create If the transaction includes a mixture of a one time purchase and recurring payments profiles call DoExpressCheckoutPayment to complete the one time purchase transaction Then call CreateRecurringPayment sProfile for each recurring payment profile you plan to create IMPORTANT PayPal does not create the recurring payments profile until you receive a success response from the CreateRecurringPaymentsProfile call To obtain the best rates for digital goods set values for the following required payment details item fields e I PAYMENTREQUEST_O_NAMEN e I PAYMENTREQUEST_O_AMTn e IL PAYMENTREQUEST_O_OTYnN e L PAYMENTREQUEST_0O_ITEMCATEGORYn you must set the value to Digital NOTE The payment details item fields are available with version 69 0 and later of the CreateRecurringPaymentsProfile API The CreateRecurringPayment sProfi

PayPal Express Checkout - 2012 Advanced Features Guide

Contents

Download Pdf Manuals

Related Search

Related Contents