Advanced Features Guide

ManualsBrandsPayPal ManualsSoftwarePayPal Express Checkout - 2012

Table Of Contents

Express Checkout Advanced Features Guide

Express Checkout

Advanced Features

Guide

Last updated: April 2012

Summary of content (108 pages)

PAGE 1
Express Checkout Advanced Features Guide Last updated: April 2012
PAGE 2
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.
PAGE 3
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 4
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 . . .
PAGE 5
Contents API Operations for Reference Transactions . . . . . . . . . . . . . . . . . . . . . . . 58 Setting Up a Billing Agreement Using the Express Checkout API . . . . . . . . . . . . . . 59 Initiating a Payment Using a Reference Transaction . . . . . . . . . . . . . . . . . . . . 60 About Cancelling Agreements and Getting the Billing Address . . . . . . . . . . . . . . . 61 Canceling a Billing Agreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6
Contents Other Callback Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Using the Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Callback Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Callback Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Chapter 8 Payment Review . . . . . . .
PAGE 7
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.
PAGE 8
Documentation Feedback 8 April 2012 Express Checkout Advanced Features Guide
PAGE 9
1 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 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. NOT E : The DoExpressCheckoutPayment request includes the same order details as SetExpressCheckout.
PAGE 10
1 Customizing Express Checkout PayPal Review Page Order Details (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.
PAGE 11
Customizing Express Checkout PayPal Review Page Order Details 1 (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.
PAGE 12
1 Customizing Express Checkout PayPal 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_QTYm Quantity Item unit quantity.
PAGE 13
Customizing Express Checkout Providing Gift Options 1 Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=http://... &CANCELURL=http://... &PAYMENTREQUEST_0_PAYMENTACTION=Sale &L_PAYMENTREQUEST_0_NAME0=10% Decaf Kona Blend Coffee &L_PAYMENTREQUEST_0_NUMBER0=623083 &L_PAYMENTREQUEST_0_DESC0=Size: 8.8-oz &L_PAYMENTREQUEST_0_AMT0=9.
PAGE 14
1 Customizing Express Checkout Providing Gift Options  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.
PAGE 15
Customizing Express Checkout Obtaining Buyer Consent to Receive Promotional Email 1 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. NOT E : Obtaining buyer consent to receive promotional email is available with API Version 61.0 or later.
PAGE 16
1 Customizing Express Checkout Overriding Your Customer Service Number NOT E : 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 SetExpressCheckout request. NOT E : This feature is available with API Version 61.
PAGE 17
Customizing Express Checkout Adding a Survey Question 1 Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &PAYMENTREQUEST_0_AMT=10.
PAGE 18
1 Customizing Express Checkout PayPal Page Style Response Parameters [successResponseFields] &TOKEN=EC-17C76533PL706495P The survey question appears to the buyer in the cart review area. NOT E : 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 appearance of the PayPal pages by defining a custom page style or by customizing individual page style characteristics.
PAGE 19
Customizing Express Checkout PayPal Page Style 1 Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &PAYMENTREQUEST_0_AMT=10.
PAGE 20
1 Customizing Express Checkout Changing the Locale Response Parameters [successResponseFields] &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. Changing the Locale You can change the locale of PayPal pages to match the language on your website.
PAGE 21
Customizing Express Checkout Changing the Locale  BR – Brazil  CA – Canada  CH – Switzerland  CN – China  DE – Germany  ES – Spain  GB – United Kingdom  FR – France  IT – Italy  NL – Netherlands  PL – Poland  PT – Portugal  RU – Russia  US – United States  The following 5-character codes are also supported for languages in specific countries: – – – – – – – – – – – – – 1 da_DK – Danish (for Denmark only) he_IL – Hebrew (all) id_ID – Indonesian (for Indonesia onl
PAGE 22
1 Customizing Express Checkout Handling Shipping Addresses Response Parameters [successResponseFields] &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: Handling Shipping Addresses You can specify several shipping address options that affect the PayPal pages.
PAGE 23
Customizing Express Checkout Handling Shipping Addresses 1 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 confirmed address.
PAGE 24
1 Customizing Express Checkout Handling Shipping Addresses  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.
PAGE 25
Customizing Express Checkout Automatically Filling Out Shipping and Contact Information – – – – – 1 PAYMENTREQUEST_0_SHIPTOCITY PAYMENTREQUEST_0_SHIPTOSTATE (Optional) PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE PAYMENTREQUEST_0_SHIPTOZIP PAYMENTREQUEST_0_SHIPTOSTREET2 (Optional) The following example overrides the shipping address with the address values shown. Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &PAYMENTREQUEST_0_AMT=10.
PAGE 26
1 Customizing Express Checkout Automatically Filling Out Shipping and Contact Information Request Parameters [requiredSecurityParameters] &METHOD=SetExpressCheckout &RETURNURL=https://... &CANCELURL=https://... &PAYMENTREQUEST_0_AMT=10.00 &PAYMENTREQUEST_0_PAYMENTACTION=Sale &PAYMENTREQUEST_0_SHIPTOSTREET=1 Main Street &PAYMENTREQUEST_0_SHIPTOCITY=San Jose &PAYMENTREQUEST_0_SHIPTOSTATE=CA &PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US &PAYMENTREQUEST_0_SHIPTOZIP=95131 &PAYMENTREQUEST_0_EMAIL=jsmith01@example.
PAGE 27
Customizing Express Checkout Automatically Filling Out Shipping and Contact Information Express Checkout Advanced Features Guide April 2012 1 27
PAGE 28
1 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.
PAGE 29
2 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 can 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.
PAGE 30
2 Express Checkout on Mobile Devices Mobile Platforms Supported by Express Checkout 4. Confirms the order and pays on your mobile website or app. 5. Views order confirmation on your mobile site or app. NOT E : 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.
PAGE 31
Express Checkout on Mobile Devices 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 2 About Mobile Express Checkout Integration PayPal supports several implementations of Mobile Express Checkout.
PAGE 32
2 Express Checkout on Mobile Devices Integrating Express Checkout With Your Mobile Website redirect as cmd=_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.
PAGE 33
Express Checkout on Mobile Devices Integrating Express Checkout With Your Mobile Website 2 Result: When you redirect to PayPal and the buyer pays on PayPal, the following Login page appears on an iOS device: When the buyer logs in to PayPal, the following Review page appears on an iOS device: Express Checkout Advanced Features Guide April 2012 33
PAGE 34
2 Express Checkout on Mobile Devices Enabling PayPal Account Optional Checkout on Mobile Devices Related information: "Features Not Supported by Express Checkout on Mobile Devices" on page 41 Enabling PayPal Account Optional 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.
PAGE 35
Express Checkout on Mobile Devices Enabling PayPal Account Optional Checkout on Mobile Devices 2 To enable account optional checkout using Express Checkout, you must set the PayPal Account Optional preference to On in Profile > 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.
PAGE 36
2 Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices 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.
PAGE 37
Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices 2 NVP Request Fields Supported by Express Checkout on Mobile Devices Express 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 REQCONFIRMSHIPPING NOSHIPPING ADDROVERRIDE LOCALECODE The following values are not supported:  AD – Andorra  AL – Albania  AM – Armenia  BR
PAGE 38
2 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 PAYMENTREQUEST_n_AMT AMT (deprecated) PAYMENTREQUEST_n_CURRENCYC ODE CURRENCYCODE (deprecated) PAYMENTREQUEST_n_ITEMAMT ITEMAMT (deprecated) PAYMENTREQUEST_n_SHIPPINGA MT SHIPPINGAMT (deprecated) PAYMENTREQUEST_n_INSURANCE AMT INSURANCEAMT (deprecated) PAYMENTREQUEST_n_SHIPDISCA MT SHIPPINGDISCAMT (deprecated) PAYMEN
PAGE 39
Express Checkout on Mobile Devices Request Fields Supported by Express Checkout on Mobile Devices 2 SOAP Request Fields Supported by Express Checkout on Mobile Devices Express Checkout on mobile devices supports only these SOAP fields: SOAP SetExpressCheckout Request Fields Supported on Mobile Devices OrderTotal ReturnURL CancelURL Token MaxAmount OrderDescription Custom InvoiceID Address ReqConfirmShipping NoShipping AddressOverride LocaleCode The following values are not supported:  AD – An
PAGE 40
2 Express Checkout on Mobile Devices Locales Supported by Express Checkout on Mobile Devices SOAP PaymentDetailsItemType Fields Supported by Express Checkout on Mobile Devices Name Description Amount Number Quantity Tax ItemWeight ItemURL 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.
PAGE 41
Express Checkout on Mobile Devices Features Not Supported by Express Checkout on Mobile Devices 2 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:  SMS security keys for mobile PayPal login, in which buyers can sign up for an extra layer of security with a secure token.
PAGE 42
2 42 Express Checkout on Mobile Devices Features Not Supported by Express Checkout on Mobile Devices April 2012 Express Checkout Advanced Features Guide
PAGE 43
3 Handling Recurring Payments Set up a recurring payment to handle subscription and other payments that occur on a fixed schedule.  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.
PAGE 44
3 Handling Recurring Payments Recurring Payments Terms Recurring Payments with Express Checkout also has the following limitations:  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.  You can create a maximum of 10 recurring payments profiles during checkout.  You can increase the profile amount by only 20% in each 180-day interval after you create the profile.
PAGE 45
Handling Recurring Payments Options for Creating a Recurring Payments Profile 3 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.
PAGE 46
3 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 CreateRecurringPaymentsProfile 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.
PAGE 47
Handling Recurring Payments Recurring Payments With the Express Checkout API 3 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 CreateRecurringPaymentsProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle.
PAGE 48
3 Handling Recurring Payments Recurring Payments With the Express Checkout API 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. 2 48 Returns a token, which identifies the transaction, to the merchant.
PAGE 49
Handling Recurring Payments Recurring Payments With the Express Checkout API Step Merchant... 3 Redirects buyer’s browser to: https://www.paypal.com/cgibin/webscr?cmd=_express-checkout &token= 3 PayPal... Displays login page and allows buyer to select payment options and shipping address. 4 5 Redirects buyer’s browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description.
PAGE 50
3 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 SetExpressCheckout request, you can create a billing agreement without initiating a payment. NOT E : To create 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.
PAGE 51
Handling Recurring Payments Recurring Payments With the Express Checkout API 3 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.
PAGE 52
3 Handling Recurring Payments Recurring Payments Profile Status Request Parameters [requiredSecurityParameters] &METHOD=CreateRecurringPaymentsProfile TOKEN=EC-13W99099UU817504D &PROFILESTARTDATE:20XX-03-05T03:00:00 &DESC=Movie clips &BILLINGPERIOD=Month &BILLINGFREQUENCY=12 &AMT=1.00 &CURRENCYCODE=USD &EMAIL=payername@bbb.net &L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital &L_PAYMENTREQUEST_0_NAME0=Kitty Antics &L_PAYMENTREQUEST_0_AMT0=1.
PAGE 53
Handling Recurring Payments Getting Recurring Payments Profile Information NOT E : 3 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 GetRecurringPaymentsProfileDetails API to obtain information about a profile.
PAGE 54
3 Handling Recurring Payments Modifying a Recurring Payments Profile NOT E : You cannot 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 regular payment period.
PAGE 55
Handling Recurring Payments Billing the Outstanding Amount of a Profile 3 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. NOT E : 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:  The profile status must be active or suspended.
PAGE 56
3 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.
PAGE 57
4 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.
PAGE 58
4 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 flow, as in the case of purchasing a mobile phone purchase or downloading a music video.
PAGE 59
Reference Transactions Setting Up a Billing Agreement Using the Express Checkout API 4 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 obtain a billing agreement ID for later use. (Do not call DoExpressCheckoutPayment, because no payment is involved.
PAGE 60
4 Reference Transactions Initiating a Payment Using a Reference Transaction 1. Call SetExpressCheckout and pass a BillingAgreementDetails element that contains the following information: – A billing type. PayPal recommends that you use MerchantInitiatedBillingSingleAgreement if you need only one billing agreement between you and the buyer. Use MerchantInitiatedBilling to create a billing agreement between you and the buyer each time you call DoExpressCheckoutPayment.
PAGE 61
Reference Transactions About Cancelling Agreements and Getting the Billing Address 4 Call DoReferenceTransaction and include the following information:  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.  A payment action, such as an authorization, order, or final sale.  Payment details, including the amount of the payment.
PAGE 62
4 Reference Transactions About Cancelling Agreements and Getting the Billing Address Canceling a Billing Agreement You can use BAUpdate (NVP: METHOD=BillAgreementUpdate) to cancel a billing agreement. To cancel an agreement, call BAUpdate and include the following information:  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.
PAGE 63
5 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.
PAGE 64
5 Implementing Parallel Payments About Parallel Payments The following figure shows expanded details on the airline purchase. The following figure shows expanded details on the hotel payment.
PAGE 65
Implementing Parallel Payments Name-Value Pair Syntax Supporting Parallel Payments 5 Name-Value Pair Syntax Supporting Parallel Payments The PayPal API uses a special 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 n is a number in the range 0 to 9 representing a payment.
PAGE 66
5 Implementing Parallel Payments Integrating Parallel Payments by Using the NVP API PAYMENTREQUEST_0_AMT The following represents the second line of the name for the third payment: L_PAYMENTREQUEST_2_NAME1 Integrating Parallel Payments by Using the NVP API To integrate 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.
PAGE 67
Implementing Parallel Payments Integrating Parallel Payments by Using the NVP API 5 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 SetExpressCheckoutrequest with parallel payments integrated.
PAGE 68
5 Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API &L_PAYMENTREQUEST_0_DESC0=SJC Terminal 1. Flight time: 7 hours 12 minutes &L_PAYMENTREQUEST_0_DESC1=BWI Terminal 1.
PAGE 69
Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API 5 Result: For each payment in the transaction, the DoExpressCheckoutPayment response returns a PaymentInfoType structure corresponding to each payment:  The PaymentRequestID will match the value you passed in the DoExpressCheckoutPayment request. Use this value to locate the response data for each payment.  SellerDetailsType.
PAGE 70
5 Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API payment1_item2.Number = "payment1_item2_number"; payment1_item2.ItemURL = "http://item2.com"; payment1_item2.Quantity = "2"; payment1_item2.Tax = new BasicAmountType(); payment1_item2.Tax.currencyID = CurrencyCodeType.USD; payment1_item2.Tax.Value = ".25"; payment1_items_array.SetValue(payment1_item1, 0); payment1_items_array.SetValue(payment1_item2, 1); //bind the items payment1.
PAGE 71
Implementing Parallel Payments Integrating Parallel Payments by Using the SOAP API 5 payment2.PaymentAction = PaymentActionCodeType.Order; payment2.PaymentActionSpecified = true; payment2.SellerDetails = new SellerDetailsType(); payment2.S ellerDetails.PayPalAccountID = "airline@grupellc.com"; //items for payment2 PaymentDetailsItemType[] payment2_items_array = new PaymentDetailsItemType[2]; PaymentDetailsItemType payment2_item1 = new PaymentDetailsItemType(); payment2_item1.
PAGE 72
5 Implementing Parallel Payments Best Practices for Online Travel Agencies Implementing Parallel Payments payment2.ItemTotal = new BasicAmountType(); payment2.ItemTotal.currencyID = CurrencyCodeType.USD; payment2.ItemTotal.Value = item_total2.ToString(); payment2.TaxTotal = new BasicAmountType(); payment2.TaxTotal.currencyID = CurrencyCodeType.USD; payment2.TaxTotal.Value = tax_total2.ToString(); decimal order_total2 = decimal.Add(decimal.Add(tax_total2, item_total2), decimal.Parse(payment2.ShippingTotal.
PAGE 73
Implementing Parallel Payments Best Practices for Online Travel Agencies Implementing Parallel Payments 5 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.
PAGE 74
5 Implementing Parallel Payments Handling Errors Recommended item description information Merchant Item description information Flight Primary information Flight No. Departure Location, Date & Time Arrival Location, Date & Time Secondary information Duration Terminal No.
PAGE 75
6 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.
PAGE 76
6 Integrating 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.
PAGE 77
Integrating giropay with Express Checkout giropay Integration NVP Field Description REDIRECTREQUIRED Flag to indicate whether you need to redirect the buyer to back to PayPal 6 If the value of this field is true, redirect the buyer from your Order Review page to https://www.paypal.com/webscr?cmd=_complete-expresscheckout&token=. PayPal then redirects the buyer from this redirect page to the necessary page for the selected funding source.
PAGE 78
6 78 Integrating giropay with Express Checkout giropay Integration April 2012 Express Checkout Advanced Features Guide
PAGE 79
7 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.
PAGE 80
7 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.
PAGE 81
Implementing the Instant Update API About the Instant Update API Express Checkout Advanced Features Guide April 2012 7 81
PAGE 82
7 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 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.
PAGE 83
Implementing the Instant Update API Following Instant Update API Best Practices NOT E : 7 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.
PAGE 84
7 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 business rules. To verify that callback requests originate from PayPal.
PAGE 85
Implementing the Instant Update API Setting Up the Callback 7 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.
PAGE 86
7 Implementing the Instant Update API Using the Callback The sample code below illustrates the callback response when you do not ship to the buyer’s address. METHOD=CallbackResponse NO_SHIPPING_OPTION_DETAILS =1 When your callback server sends the previous response, the Review your information page has these features:  A message at the top of the page indicates that your business does not ship to this location.  The shipping and handling section and the insurance section are dimmed.
PAGE 87
Implementing the Instant Update API Using the Callback NOT E :  7 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. Optionally, provide values for the following parameters: – Set PAYMENTREQUEST_n_INSURANCEOPTIONOFFERED to true to inform PayPal that you are offering insurance options. Otherwise, set PAYMENTREQUEST_n_INSURANCEOPTIONSOFFERED to false.
PAGE 88
7 Implementing the Instant Update API Using the Callback &L_SHIPPINGOPTIONISDEFAULT0=false &L_SHIPPINGOPTIONNAME0=UPS Ground 7 Days &L_SHIPPINGOPTIONAMOUNT0=3.50 &L_SHIPPINGOPTIONISDEFAULT1=true &L_SHIPPINGOPTIONNAME1=UPS Next Day Air &L_SHIPPINGOPTIONAMOUNT1=8.00 Response Parameters [successResponseFields] &TOKEN=EC-17C76533PL706494P Callback Request The PayPal sends the parameters in the callback request to the location you specified for CALLBACK.
PAGE 89
Implementing the Instant Update API Using the Callback 7 &SHIPTOCITY=San Jose &SHIPTOSTATE=CA &SHIPTOCOUNTRY=US &SHIPTOZIP=95131 &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: METHOD=CallbackResponse &OFFERINSURANCEOPTION=true &L_SHIPPINGOPTIONNAME0=UPS Next Day Air &L_SHIPPINGOPTIONAMOUNT0=20.00 &L_TAXAMT0=2.20 &L_INSURANCEAMOUNT0=1.
PAGE 90
7 90 Implementing the Instant Update API Using the Callback April 2012 Express Checkout Advanced Features Guide
PAGE 91
8 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.
PAGE 92
8 Payment Review Handling Payment Review 1. Check the payment status in the response to the API operation; specifically, check whether PaymentStatus is set to Pending. 2. If the PaymentStatus 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 PaymentStatus is set to Pending; however, its PendingReason is set to authorization, which is not related to payment review.
PAGE 93
Payment Review Handling Payment Review IM PORT AN T : 8 For best results, call the GetTransactionDetails API operation every six hours. PayPal recommends not calling GetTransactionDetails more frequently than once per hour.
PAGE 94
8 94 Payment Review Handling Payment Review April 2012 Express Checkout Advanced Features Guide
PAGE 95
9 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 information to PayPal as parameters appended to the image URL.
PAGE 96
9 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.
PAGE 97
Express Checkout Dynamic Image Integration Configuring the Dynamic Image 9 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.
PAGE 98
9 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 (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 API request on behalf of this merchant.
PAGE 99
Express Checkout Dynamic Image Integration Dynamic Image Command Reference 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_0 de_DE CH language_1 fr_FR CH language_2 en_US CN language_0 zh_CN default language_0 en_US default language_1 fr_XC default language_2 es_XC default language_3 zh_XC DE language_0 de_DE DE language_1 en_US ES language_0 es_ES ES language_1 en_US FR lan
PAGE 100
9 100 Express Checkout Dynamic Image Integration Dynamic Image Command Reference Country code Language priority Locale NL language_0 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_0 en_US US language_1 fr_XC US language_2 es_XC US language_3 zh_XC April 2012 Express Checkout Advanced Features Guide
PAGE 101
10 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 purchase. PayPal offers two applications of Immediate Payment.
PAGE 102
10 Immediate Payment About Immediate Payment For Third-Party Checkout  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: From left to right, the following events are represented. The numbered callouts in the figure directly correspond to the numbered comments below: 1.
PAGE 103
Immediate Payment Integrating Immediate Payment for Third-Party Checkout 10 3. The SetExpressCheckout response returns a TOKEN. 4. The buyer is redirected to PayPal. 5. The buyer reviews their payment and clicks Continue. 6. (Optional) Call GetExpressCheckoutDetails. The GetExpressCheckoutDetails response returns information about the buyer. 7. In the call to DoExpressCheckoutPayment, you must pass: – PAYMENTREQUEST_n_ALLOWEDPAYMENTMETHOD: This is the payment method type.
PAGE 104
10 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 noneBay 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.
PAGE 105
Immediate Payment Integrating Immediate Payment for Express Checkout 10 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 InstantPaymentOnly. 2. (Optional) You can call GetExpressCheckoutDetails to obtain information about the buyer. 3.
PAGE 106
10 106 Immediate Payment Integrating Immediate Payment for Express Checkout April 2012 Express Checkout Advanced Features Guide
PAGE 107
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 this guide. 05/02/2011 Revised Express Checkout on Mobile Devices chapter and added support information for iPad.
PAGE 108
Date Description 06/30/2008 Complete revision.