Home

PayPal Express Checkout - 2010 Integration Guide

1. Buyer s shipping address The SetExpressCheckout response returns a TOKEN The buyer is redirected to PayPal The buyer reviews their payment and clicks Continue aA nan A 0 Optional Call GetExpressCheckoutDetails The GetExpressCheckoutDetails response returns information about the buyer 7 In the call to DoExpressCheckoutPayment you must pass ALLOWEDPAYMENTMETHOD This is the payment method type For immediate payment the value is InstantPaymentOnly L_EBAYITEMCARTIDn eBay provides you with this value At this time PayPal checks the availability of the eBay item 8 If the item is available and payment is successful the DoExpressCheckoutPayment response returns the eBay transaction ID EBAYITEMAUCTIONTXNID Integrating Immediate Payment for Third Party Checkout To integrate Immediate Payment for third party checkout into your Express Checkout implementation you add a few new fields to SetExpressCheckout and DoExpressCheckoutPayment The Call to SetExpressCheckout You must have Express Checkout integrated into your payment solution It is recommended that you sell one eBay item in a transaction or a quantity of the same item considered a single eBay listing Express Checkout Integration Guide May 2010 93 94 Immediate Payment About Immediate Payment For Express Checkout To integrate Immediate Payment into the SetExpressCheckou
2. 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 pre requisites Provide order line item details to take advantage of the Instant Update API The example in this document uses the order line item details example described PayPal Review Page Order Details 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 on the PayPal Review page e Ensure a consistent and good buyer experience When flat rate shipping options are used you should honor the rates to ensure a consistent and good 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 Express Checkout Integration Guide May 2010 81 82 Im
3. 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 you associate it with your PayPal Secure Merchant Account ID or pal You can obtain your pal by getting it from the Profile page contacting PayPal or calling the GetPalDetails API This is an example call to GetPalDetails request Request Parameters requiredSecurityParameters amp METHOD GetPalDetails Response Parameters This GetPalDetails response returns the value of PAL and your country code LOCALE as shown below successResponseFields amp PAL SFUCXFDLNFR5U 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 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 locations 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 that campaign NOTE If you pass in a pal value matching a merchant account that is not yours PayPal displays the
4. V Gl nam EJ EN value EC RSION value 52 0 gt 1NK66318YB717835M gt lt input lt form gt type submit name Hi If the operation was successful the Get information about the payer such as the THOD value GetExpressCheckoutDetails gt ExpressCheckoutDetails API returns following information amp ACK Success TIMESTAMP 2007 2qd04 2qd05T23 3a44 3a11Z amp CORRELATIONID 6b174e9bac3b3 amp VERSION 52 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M amp EMATL jsmith0O1 example com amp PAYERID 7AKUSARZ7SAT8 amp PAYERSTATUS verified amp FIRSTNAME amp LASTNAME amp COUNTRYCODE US amp BUSINESS amp SHIPTONAME amp SHIPTOSTREET amp SHIPTOCITY amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOCOUNTRYNAME United 20States amp SHIPTOZIP 94666 amp ADDRESSID amp ADDRESSSTATUS Confirmed 6 Invoke a form on your site that invokes t on the Sandbox 46 May 2010 he DoExpressCheckout Payment API operation Express Checkout Integration Guide Testing an Express Checkout Integration aaa lt form method post action https api 3t sandbox paypal com nvp gt lt name USER value API_username gt E name PWD value API_passwora gt name SIGNATURE value API_signature gt name VERSION value 52 0 gt
5. You can provide the buyer with gift options on the PayPal Review page NOTE Gift options are available with API Version 61 0 or later To use this feature you must implement line item details See PayPal Review Page Order Details on page 49 for more information You can enable any of the following gift options May 2010 Express Checkout Integration Guide Customizing Express Checkout Providing 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 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 The following SetExpressCheckout request example sets these options Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp CURRENCYCODE USD amp 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
6. Express Checkout Integration Guide May 2010 113 Smt Handling Recurring Payments Recurring Payments Terms 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 Recurring payments with Express Checkout also has the following limitations e To be able to create a recurring payments profile for the buyer the buyer s PayPal account must include an active credit card e At most ten recurring payments profiles can be created during checkout e You can only increase the profile amount by 20 in each 180 day interval after the profile is created Recurring Payments Terms Some terms are commonly used by PayPal in the context of 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 One payment is made per billing cycle Each billing cycle is made up of two components e The billing period specifies the unit to be used to calculate the billing cycle such as days or month
7. Paypar Express Checkout Image Flavors The Check out with PayPal button and the PayPal Acceptance mark images are available in two flavors e Dynamic image Express Checkout Integration Guide May 2010 19 20 Express Checkout Button and Logo Image Integration Dynamic Images e Static image The dynamic images enable PayPal to change their appearance dynamically If for example you have signed up to participate in a PayPal campaign PayPal can change the appearance of the image dynamically for the duration of that campaign based on parameter information you append to the image URL By default the Express Checkout images appears as shown above The static images cannot be changed dynamically To participate in a PayPal campaign you would have to manually update the image code to change the image displayed and restore the default image when the campaign is over The only way you can have image management taken care of for you is to replace static images in your implementation with dynamic images Dynamic Images To use dynamic images you must pass information 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 parame
8. name PAYMENTACTION value Sale gt name PAYERID value 7AKUSARZ7SAT8 gt name TOKEN value EC 2d1NK66318YB717835M gt name AMT value 19 95 gt lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type hidden lt input type submit form gt name METHOD value DoExpressCheckoutPayment gt 7 Review the response string from the DoExpressCheckoutPayment API operation If the operation was successful the response should include ACK set to Success as follows TI IESTAMP 2007 2d04 2d05T23 3a30 3a162Z amp CORRELATIONID 333f b808bb23 amp ACK Success amp VERS ION 52 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M amp TRANSACTIONID 043144440L4877429 amp amp P RANSACTIONTYPI AYMENTTYPE instant E expresscheckout amp ORDERT IME 2007 2d04 2d05T23 3a30 3a14Z amp AMT 1932e95 amp CURRENCYCODE USD amp TAXAMT 0 2e00 amp P amp P AYMENTSTATUS Completed END INGREASON None amp REASONCODE None amp F Express Checkout Integration G uide EEAMT 0 2e43 May 2010 47 a Testing an Express Checkout Integration 48 May 2010 Express Checkout Integration Guide Customizing Express Checkout You can specify options in Expre
9. PayFlow API is not the same as the NVP API for more information about the PayFlow API see Website Payments Pro Payflow Edition Developer Guide e PayPal API Client Server Architecture e Obtaining API Credentials e Creating an NVP Request e Executing NVP API Operations e Responding to an NVP Response PayPal API Client Server Architecture The PayPal API uses a client server model in which your website is a client of the PayPal server A page on your website initiates an action on a PayPal API server by sending a request to the server The PayPal server responds with a confirmation that the requested action was taken or or indicates that an error occurred The response might also contain additional information related to the request The following diagram shows the basic request response mechanism Request aeaaea Cy PayPal Response For example you might want to obtain the buyer s shipping address from PayPal You can initiate a request specifying an API operation that gets buyer details The response from the PayPal API server contains information about whether the request was successful If the operation succeeds the response contains the requested information in this case the buyer s shipping address If the operation fails the response contains one or more error messages Your Site T1 Express Checkout Integration Guide May 2010 27 28 PayPal Name Value Pair API Basics PayPal API Client Server Ar
10. 10 to September 6 you can increase the payment amount to a maximum of 120 120 of 100 Suppose that during the first 180 day interval you increased the payment amount to 110 Then during the next 180 day interval starting on September 7 in this example you can only increase the amount of the payment to a maximum of 132 120 of 110 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 If another outstanding balance payment is already queued an API error is returned You will be informed by IPN about the success or failure of the outstanding payment For profiles created using Express Checkout the buyer will receive an email notification of the payment May 2010 Express
11. 17C76533PL706495P The figure below shows how the gift options appear to the buyer on the PayPal Review page Add gift options Giftmessage 150 characters left E Gift wrap christmas red 1 00 USD E Include gift receipt with order Apply Cancel NOTE Youcan also configure this option through the PayPal Profile page For details see the Merchant Setup and Administration Guide Express Checkout Integration Guide May 2010 59 60 Customizing Express Checkout Getting Buyer Consent to Receive Promotional Email Getting Buyer Consent to Receive Promotional Email You can get the buyer s consent to receive email promotions on the PayPal Review page PayPal returns the email address that the buyer enters in the response to GetExpressCheckoutDetails and DoExpressCheckoutPayment NOTE This feature is available with API Version 61 0 or later To get the buyer s email address set the BUYEREMAILOPTINENABLE 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 AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale amp BUYEREMAILOPTINENABLE 1 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706495P The figure below shows how
12. 70 2 79 40 Rem 523083 Size Two 24 piece boxes ie archan Item total 99 30 Tax 2 59 Shipping and handling 8 00 UPS Next Day Air 8 00 USD v UPS Ground 7 Days 3 50 USO 3 00 UPS Nest Day Air 9 00 j Insurance 1 00 Yes 1 00 USD Total 107 89 USD nier ifi if rd or discount Payment Method CredivDebit Card Visa 00000 0004 2477 i har ge J Smith 1 Main St San Jose CA 95131 United States Change Ship to Contact Information jsmithOt exarnple com 408 000 0000 Cancel and return to your website PayPal The sater easier way to pay For more information read our User Agreemert and Privacy Pobcy You control which options are displayed and instantly updated on the page Express Checkout Integration Guide May 2010 79 Implementing the Instant Update API How the Callback Works in the Express Checkout Flow How the Callback Works in the Express Checkout Flow The figure below shows how the callback integrates into the Express Checkout flow Callback integrated into Express Checkout flow Place Order Order P Confirmation Ship Tax Ins Continue S Merchant AJAX Call Redirects to PayPal ko PayPal Server Set EC Shipping Get Do Callback URL Address EC EC Flat Rate Token Options a 9 40 Line Item Shipping Details Token Options Merchant System API Call to Carriers From left to right the following events are represented Text in boldface desc
13. 77 Integration Steps ooa a 77 Post Integration Checkout Experience oaoa oaa a 78 How the Callback Works in the Express Checkout Flow a oaoa aaa aa 80 Following Instant Update API Best Practices o oo oa aa a 81 Setting Up the Callback aooaa 82 GetExpressCheckoutDetails and DoExpressCheckoutPayment Changes 83 Other Considerations 1 0 2 ee 83 Using the Callback oaoa 85 SetExpressCheckout 2 s ikasiak a aunda 85 Callback Request ss soam saaa ee 88 Callback Response o oo 0 ce 88 Chapter 8 Immediate Payment anaoa aaa a 91 Overview of Immediate Payment oaa a ee 91 About Immediate Payment For Third Party Checkout aoao aa a 91 Integrating Immediate Payment for Third Party Checkout ao aoao a 93 The Call to SetExpressCheckout oaoa oaa 93 The Call to DoExpressCheckoutPayment oaoa aa a a 94 About Immediate Payment For Express Checkout oaoa 00004 94 Integrating Immediate Payment for Express Checkout oaoa a 95 Chapter 9 Implementing Parallel Payments 97 About Parallel Payments 2 2 aaa a 97 What Is and What Is Not Supported oaa oaa 00000000 eee 97 Express Checkout Integration Guide May 2010 5 a Contents Post Integration Experience a aoaaa aaa a a 98 Name Value Pair Syntax Supporting Parallel Payments a oa aa a 99 Integrating Parallel Payments Using the NVPAPI 04 100 Integrati
14. 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 Review page PayPal returns the response that the buyer chooses in the response to GetExpressCheckoutDetails and DoExpressCheckoutPayment NOTE This feature is available with API Version 61 0 or later The survey question displays in the format of a text string 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 Express Checkout Integration Guide May 2010 61 62 Customizing Express Checkout PayPal Page Style Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale amp SURVEYENABLE 1 amp SURVEYQUESTION How did you hear about us amp L_SURVEYCHOICEO Through a friend amp L_SURVEYCHOICE1 In a newspaper ad Response Parameters succes
15. DoExpressCheckoutPayment you set ALLOWEDPAYMENTMETHOD to InstantPaymentOnLy Express Checkout Integration Guide May 2010 95 ae Immediate Payment Integrating Immediate Payment for Express Checkout 96 May 2010 Express Checkout Integration Guide Implementing Parallel Payments Not only can Express Checkout support payment between a single buyer and merchant but it can support parallel payments Parallel payments enables a single buyer to pay multiple merchants in a single checkout session e About Parallel Payments e Name Value Pair Syntax Supporting Parallel Payments e Integrating Parallel Payments Using the NVP API e Integrating Parallel Payments Using the SOAP API NOTE Parallel payments is available with API version 63 0 and later 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 page summarizing expenses itineraries and other supporting information Buyers see travel information includin
16. Guide May 2010 101 et Implementing Parallel Payments Integrating Parallel Payments Using the NVP API Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTACT ION Order amp PAYMENTREQUEST_O_CURRENCYCODE USD amp PAYMENTREQUEST_0O_AMT 300 amp PAYMENTREQUEST_0O_ITEMAMT 200 amp PAYMENTREQUEST_0O_TAXAMT 100 amp PAYMENTREQUEST_O_DESC Summer Vacation trip amp PAYMENTREQUEST_0O_INSURANCEAMT 0 amp PAYMENTREQUEST_0O_SHIPDISCAMT 0 amp PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID seller 139 paypal com amp PAYMENTREQUEST_0O_INSURANCEOPTIONOFFERED false amp PAYMENTREQUEST_0O_PAYMENTREQUESTID CART26488 PAYMENTO amp PAYMENTREQUEST_1_ CURRENCYCODE USD amp PAYMENTREQUEST_1_AMT 200 amp PAYMENTREQUEST_1_ ITEMAMT 180 amp PAYMENTREQUEST_1_SHIPPINGAMT 0 amp PAYMENTREQUEST_1_ HANDLINGAMT 0 amp PAYMENTREQUEST_1
17. If the buyer s checkout includes eBay auction items you must set additional fields in the call to SetExpressCheckout to enable buyers to choose from eBay issued incentives such as eBay gift certificates coupons vouchers and gift cards that may apply to their order To enable the display of eBay incentives on the PayPal Review page you also must provide line item detail information for each eBay item When the buyer clicks the Enter gift certificate reward or discount link a dialog displays in which the buyer can either enter a redemption code or select from a list of all discounts applicable to eBay items in the cart display as shown below If multiple items display the buyer can select from the discounts they want applied to their order Dialog for entering redemption code or choosing discounts Voyage Travel Review your payment PayPal Secure Payments the information below is correct click Pay now to complete your payment View PayPal policies and your payment source rights Photo 25 00 1 2500 Nokia ND 25 00 1 2500 item totat 50 00 Shipping and handling 6 00 Totat 56 00 USD Enter gif certificate reward or discount Emer redemption code CSTDCOUPON Or select from this ist Apply aes After entering a redemption code or selecting the incentives the PayPal Review page reflects changes to the order Incentives appear as credits and a new Total is calculated as shown below Express Checkout Inte
18. Inc reserves the right to make changes to any information herein without further notice Contents Preface Intended Audience 2 2 a a a a a a a L Where to Go for More Information oaoa aa a a a Revision HIStory s esati sarreraren kanka Ena a Chapter 1 Introducing Express Checkout 11 The Express Checkout Experience 0 000 eee ee ee es 11 Express Checkout Integration Steps 2 2 ee ee 12 Configuring and Customizing the Express Checkout Experience 13 Additional PayPal API Operations 0 00000 eee eee eee 13 Express Checkout Flow oaoa 14 Checkout Entry Point aoaaa 14 Payment Option Entry Point aaa aa a a 15 Express Checkout Building Blocks oaaae a 15 Express Checkout Buttons oaaao a a 16 Express Checkout API Operations a oa oaa a 000000 eee eee 17 Express Checkout Command aaaea a a 17 Express Checkout Token Usage aoaaa a ee 18 Chapter 2 Express Checkout Button and Logo Image Integration 19 About PayPal Button and Logo Images 000000 eee ee 19 Express Checkout Images 2 0 a a 19 Express Checkout Image Flavors oaa oaa a eee ee 19 Dynamiclmages a a d ee 20 Configuring the Dynamiclmage aa 0 0 ee ee 20 Set Up the Default Image 00000 ee 21 Set Up Image for Dynamic Use 200002 eee ee 21 Change the Locale 1 2 0 0 ee ee 22 Feedback to Buyer Meeting an Incent
19. The shipping option to appear in the drop down menu 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 TAXAMT If required an adjusted value INSURANCEAMT 4 If necessary to adjust the callback timeout default 3 seconds provide a value from 1 to 6 for the CALLBACKT IMEOUT parameter 5 Optionally provide values for any of the shipping option description details fields listed below Option weight L_ITEMWEIGHTVALUEn L_ITEMWEITHTUNITn Option height L_ITEMHEIGHTVALUEn L_ITEMHEIGHTUNITn E Option length L_ITEMLENGTHVALUEn L_ITEMLENGTHUNITn Option width L_ITEMWIDTHVALUEn L_ITEMWIDTHUNITn T May 2010 Express Checkout Integration Guide Implementing the Instant Update API Setting Up the Callback 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 G
20. Transfer PDT message e by checking the status of a transaction programatically Programatically 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 programatically by calling the Get TransactionDetails API operation May 2010 Express Checkout Integration Guide Using Other PayPal API Operations ji Handling Payment Review NOTE You must use version 58 0 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 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 Payment
21. 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 Express Checkout Integration Guide May 2010 85 Implementing the Instant Update API Using the Callback 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_NAMEn L_NUMBERn L_DESCn L_AMTn and L_QTYn shown in the example below Provide values for the flat rate shipping options n L_SHIPPINGOPTIONISDEFAULTn L_SHIPPINGOPTIONNAMEn and L_SHIPPINGOPTIONAMOUNTn Set SHIPPINGAMT to the amount set for the default flat rate shipping option If for example L_SHIPPINGISDEFAULT1 t rue and L_SHIPPINGOPTIONAMOUNT1 8 00 then SHIPPINGAMT 8 00 Set MAXAMT to the expected maximum total amount of the complete order It is recommended 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 INSURANCEOPTIONOFFERED to true to inform PayPal that you are off
22. above example 72 May 2010 Express Checkout Integration Guide Customizing Express Checkout em Automatically Filling Out the PayPal Login Page PayPal review page with shipping address override WebsiteName com Review Your Information PayPal scoue Payments Please review the information below If correct click Continue to complete your payment on the WebsiteName com website Learn more about PayPal policies and your payment source rights and remedies Payment Method Credit Card Visa XKXX XXXX XXXX 0084 Shippeng Address 1 Second St Ste 210 San Jose CA 95131 United States Contact Information jomith01 example com Cancel and return to WebsiteName com Automatically Filling Out the PayPal Login Page When you pass the buyer s shipping address and contact information telephone number and email address parameters in the call to SetExpressCheckout PayPal automatically fills out the account creation form fields for the buyer on the PayPal Login page After the call to SetExpressCheckout the buyer is redirected to the PayPal Login page Buyers having a PayPal account can log in with their email address and password Buyers who do not have an account can create one by filling out the form on this page To facilitate filling out the form you can have PayPal automatically fill out the billing address and contact information by passing the shipping address telephone number and email address in the call to SetExpressC
23. accurate as possible ExpressCheckout Obtains information about the buyer from PayPal including shipping information DoExpressCheckout Payment Completes the Express Checkout transaction including the actual total amount of the order Express Checkout Command PayPal provides a command that you use when redirecting your buyer s browser to PayPal This command enables your buyer to log into PayPal to approve an Express Checkout payment When you redirect your buyer s browser to PayPal you must specify the _ExpressCheckout command for Express Checkout You also specify the token that identifies the transaction which was returned by the SetExpressCheckout API operation NOTE To enable PayPal to redirect back to your website you must have already invoked the SetExpressCheckout API operation specifying URLs that PayPal uses to redirect back to your site PayPal redirects to the success URL when the buyer pays on PayPal otherwise PayPal redirects to the cancel URL If the buyer approves the payment PayPal redirects to the success URL with the following information Express Checkout Integration Guide May 2010 17 a Introducing Express Checkout Express Checkout Building Blocks e The token that was included in the redirect to PayPal e The buyer s unique identifier Payer ID If the buyer cancels PayPal redirects to the cancel URL with the token that was included in the redirect to PayPal Express Checkout To
24. action in your SetExpressCheckout and DoExpressCheckoutPayment requests PAYMENTACTION Order An order enables you to create multiple authorizations over the 29 days each authorization you create places the buyer s funds on hold for up to three days You can capture multiple payments for each authorization up to 115 of or USD 75 more than the amount you specify in the DoExpressCheckoutPayment request NOTE The default number of child authorizations in your PayPal account is 1 To do multiple authorizations please contact PayPal to request an increase This payment action provides the most flexibility and should be used when either a sale or one authorization plus one reauthorization do not meet your needs Situations in which orders are appropriate include the handling of e Back orders in which available merchandise is sent immediately and the remaining merchandise is sent when available which may include more than two shipments e Split orders in which merchandise is sent in more than one shipment perhaps to different addresses and you want to collect a payment for each shipment May 2010 Express Checkout Integration Guide Handling Payment Settlements A Order Payment Action for Express Checkout e Drop shipments which are shipments from other vendors for which you accept the payment You cannot reauthorize an authorization You handle the need to reauthorize for example when the hold period or valid period of an author
25. continue until the profile is canceled or suspended If the value is greater than 0 the regular payment period will continue for the specified number of billing cycles You can also specify an optional shipping amount or tax amount for the regular payment period Including an Optional Trial Period You can optionally include a trial period in the profile by specifying the following fields in the CreateRecurringPayment 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 TRIALAMT 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 will not activate the profile if the initial payment amount fails You can override this default beha
26. list use the offset from the beginning of the list starting with 0 as the first element For example L_DESCO is the first line of a description L_DESC1 is the second line and so on NOTE Notall lists follow the L_ prefix convention however all lists start with O as the first element Executing NVP API Operations You execute an PayPal NVP API operation by submitting an HTTP POST request to a PayPal API server Specifying a PayPal Server You execute a PayPal API operation by submitting the request to a PayPal API server To execute a PayPal NVP API operation submit your complete request to one of the following end points Server end point Description https api Sandbox server for use with API signatures use for testing your 3t sandbox paypal com nvp API https api 3t paypal com nvp PayPal live production server for use with API signatures https api sandbox paypal com nvp Sandbox server for use with API certificates use for testing your API https api paypal com nvp PayPal live production server for use with API certificates NOTE You must use different API credentials for each server end point Typically you obtain API credentials when you test in the Sandbox and then obtain another set of credentials for the production server You must change each API request to use the new credentials when you go live Logging API Operations You should log basic information about each PayPa
27. 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 payment1_iteml Amount new B asicAmountType payment1_iteml Amount currencyID CurrencyCodeType USD payment1_item1 Amount Value 1 00 payment1l_item1 Description paymentl_iteml_desc payment1l_item1l Name payment1l_iteml_name paymentl_item1 Number payment1_iteml_number payment1_iteml ItemURL http iteml com payment1l_iteml Quantity 3 payment1l_item1l Tax new BasicAmountType payment1l_item1l Tax currencyID CurrencyCodeType USD payment1_item1l Tax Value 50 PaymentDetailsItemType paymentl_item2 new PaymentDetailsItemType payment1l_item2 Amount new BasicAmountType payment1l_item2 Amount currencyID CurrencyCodeType USD payment1l_item2 Amount Value 1 00 payment1l_item2 Description paymentl_item2_desc payment1l_item2 Name payment1l_item2_name payment1l_item2 Number payment1_item2_number paymentl_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 SetVal
28. number to the seller You can speed through checkout without stopping to enter your card number or address Sign up for 4 PayPal account and continue checkout Cancel and return to WebsiteName com LOG IN TO PAYPAL Email Password Forgot email address or password 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 Login page set the LOCALECODE parameter to one of the following allowable values in the SetExpressCheckout call e AU e DE e FR e GB e IT e ES e JP e US May 2010 Express Checkout Integration Guide Customizing Express Checkout aa Changing the Locale The following example sets LOCALCODE to ES Spain Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp CURRENCYCODE EUR PAYMENTACTION Sale amp LOCALECODE ES amp SHIPTOSTREET 1 Main St amp SHIPTOSTREET2 amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The figure below shows the PayPal Login page when the LOCALECODE is set to ES PayPal login page in Spanish Espa ol v WebsiteName com PayPal es la forma rapida y segura de pagar PayPal Secure
29. of the transaction whose payment you want to refund TRANSACT IONID transaction_id 2 Specify the kind of refund which is either Full or Partial REFUNDTYPE Full or Express Checkout Integration Guide May 2010 127 128 Using Other PayPal API Operations Handling Payment Review REFUNDTYPE Partial 3 For a partial refund specify the refund amount including the currency AMT amount CURRENCYCODE currency D 4 For a partial refund specify the memo description NOTE description 5 Execute the RefundTransact ion operation 6 Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful Handling 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 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 into 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
30. 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 Acceptance Mark image https fpdbs paypal com dynamicimageweb cmd _dynamic image amp pal SFJCXFDLNFR5U buttontype ecmark The default value for buttontype is ecshortcut Dynamic Image Command Reference To set up the information that enables dynamic images you add name value pairs to the dynamic image URL Parameters and values are described below 22 May 2010 Express Checkout Integration Guide Express Checkout Button and Logo Image Integration Poe Dynamic Image Command Reference Dynamic Image Parameters The table below describes the dynamic image name value pair parameters Dynamic Image Command Variable Descriptions pal Type encrypted PayPal account number Optional Unique identification 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 NOTE If pal is not passed PayPal displays the default Check out with PayPal button ordertotal Type numeric Optio
31. shows expanded details on the hotel payment 98 May 2010 Express Checkout Integration Guide Implementing Parallel Payments E 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 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 format shown below where n is 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 If you are upgrading to version 63 0 of the Express Checkout API you will recognize NVPREQUESTFIELDNAME to be the single payment NVP request field name The response name format is PAYMENTREQUEST_n_NVPRESPONSEFIELDNAME NOTE Even if your Express Checkout integration is for single payments you must use this format and specify n O for single payment with version 63 0 and later of the Express Checkout API The payment information returned in the DoExpressCheckout Payment response has the same basic format but the field name starts with PAYMENTINFO as shown below P
32. the callback response This is an example callback request ETHOD CallbackRequest amp CALLBACKVERS ION 57 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 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 88 May 2010 Express Checkout Integration Guide Implementing the Instant Update API Using the Callback METHOD CallbackResponse amp OFFERINSURANCEOPTION t rue amp L_SHIPPINGOPTIONNAMEO UPS Next Day Air amp L_SHIPPINGOPTIONAMOUNT0 20 00 amp L_TAXAMT0 2 20 amp L_INSURANCEAMOUNTO 1 51 amp L_SHIPPINGOPTIONISDEFAULT0 false amp L_SHIPPINGOPTIONNAME1 UPS Express 2 Days amp L_SHIPPINGOPTIONAMOUNT1 10 00 amp L_TAXAMT1 2 00 amp L_INSURANCEAMOUNT1 1 35 amp L_SHIPPINGOP
33. this appears to the buyer on the PayPal Review page Would you like to request promotional emails from Friends n Stitches Needlework Optional Enter your email address NOTE You can also configure this feature through the PayPal Profile page For details see the Merchant Setup and Administration Guide Providing Your Customer Service Number You can display your Customer Service number to the buyer on the PayPal Review page by configuring it on the PayPal Profile page By doing so you can quickly answer the buyer s questions through a telephone call NOTE This feature is available with API Version 61 0 or later To override the Customer Service number configured on the Profile page with a different number on the PayPal Review page set the CUSTOMERSERVICENUMBER field in the call to May 2010 Express Checkout Integration Guide Customizing Express Checkout aa Adding a Survey Question SetExpressCheckout Provide an alphanumeric string that clearly identifies you as the merchant The following request example sets this field Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale amp CUSTOMERSERVICENUMBER 1 800 F LOWERS Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P NOTE For details on configuring the
34. you are selling high risk merchandise If you prefer confirmed addresses be used then do not set ADDROVERRIDE as described in Shipping Address Override 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 The guide is available on the Documentation page linked to the Library tab on Developer Central Alternately you can set a flag in the call to SetExpressCheckout as described below 1 Include the optional REOQCONFIRMSHIPP ING parameter in the call to SetExpressCheckout 2 Set REQCONFIRMSHIPPING to 1 The following example requires the shipping address be a confirmed address NOTE The value of REQCONFIRMSHIPPING overrides the setting in your Merchant Account Profile 68 May 2010 Express Checkout Integration Guide Customizing Express Checkout aa Handling Shipping Addresses Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp PAYMENTACTION Sale ONF IRMSHIPPING 1 PTOSTREET 1 Main St PTOCITY San Jose PTOSTATE CA PTOCOUNTRYCODE US PTOZIP 95131 PTOPHONENUM 4 008 967 4444 HK ll a Q k HHHHHH Response Parameters successRespon
35. your application Do not host copies of the PayPal images locally on your servers Outdated PayPal images reduces buyer confidence in your site Follow the links in the table below to obtain HTML code that displays the PayPal hosted images HTML Code for Displaying PayPal Hosted Button and Mark Images Country Links to HTML Code for Displaying PayPal Hosted Images Australia https www paypal com au cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Express Checkout Integration Guide May 2010 25 26 Express Checkout Button and Logo Image Integration Static PayPal Button and Mark Images Source Requirements Country Links to HTML Code for Displaying PayPal Hosted Images Austria https www paypal com at cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Belgium https www paypal com be cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Canada https www paypal com ca cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside China https www paypal com cn cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside France https www paypal com fr cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Germany https www paypal com de cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Italy https www p
36. 00002 eee 122 Modifying a Recurring Payments Profile 0 0 0020 eee eee 123 Updating Addresses 2 a 124 Updating the Billing Amount 0 000022 124 Billing the Outstanding Amount ofa Profile 2 202008 124 Recurring Payments Notifications 0 00000 ee ee 125 6 May 2010 Express Checkout Integration Guide Contents Chapter 12 Using Other PayPal API Operations 127 Issuing Refunds Handling Payment Review Chapter 13 Integrating giropay with Express Checkout 131 giropay Page Flows Ee ket He Shee eye ee oe Oe Se ne Bees eae ow Go 131 giropay Payment Page Flow 00002 eee ee ee 131 Cancelled or Unsuccessful giropay Payment Page Flow 132 giropay Integration s anr a ee 133 Initiate the Flow with SetExpressCheckout 2 0 0000000 133 Redirect the Buyer to PayPal 0 000 ee 133 Complete the Transaction o ooa a 134 Receive Transaction Status Notification 0 0 000004 eae 134 Express Checkout Integration Guide May 2010 iad Contents 8 May 2010 Express Checkout Integration Guide Preface This document describes Express Checkout integration Intended Audience This document is intended for merchants and developers implementing Express Checkout Where to Go for More Information For information on the administrative tasks you can perform from your PayPal account see the Merchant
37. AYMENT INFO_n_NVPRESPONSEFIELDNAME The NVP API reference documentation shows the proper format and naming for every NVP field that uses this syntax Examples Express Checkout Integration Guide May 2010 99 et Implementing Parallel Payments Integrating Parallel Payments Using the NVP API The following syntax represents the total amount of the first payment PAYMENTREQUEST_O_AMT The following represents the second line of the name for the third payment L_PAYMENTREQUEST_2_ NAME 1 Integrating Parallel Payments Using the NVP API To integrate parallel payments 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 Order in PAYMENTREQUEST_n_PAYMENTACTION Pass a unique value for PAYMENTREQUEST_n_PAYMENTREQUESTID You will use this value to locate the matching payment res
38. Checkout Integration Guide Handling Recurring Payments m Recurring Payments Notifications Recurring Payments Notifications You are notified of recurring payments events through IPN and email however using GetTransactionDetails to obtain the information you need is typically sufficient You are notified of certain events through IPN For recurring payments profiles created using Express Checkout buyers are also notified of specific events by email The following table indicates when IPN and emails are generated 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 update 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 because the success or failure of the call is immediately provided by the API response Express Checkout Integration Guide May 2010 125 tt Handling Recurring Payments Recurring Payments Notifications 126 May 2010 Express Checkout Integration Guide Using Other PayPal API Operations You can use addit
39. Express Checkout Flow e Following Instant Update API Best Practices e Setting Up the Callback e Using the Callback About the Instant Update API The Instant Update API is a server call to your callback server that instantly updates the PayPal review page It enables you to specify a URL for PayPal to call your callback server with the buyer s shipping address so you can provide the buyer with more detailed shipping insurance and tax information NOTE The Instant Update API enhances the Express Checkout flow from the shopping cart page 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 on the Review page 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 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 PayP
40. K https amp CALLBACKTIMEOUT 4 amp INSURANCEOPTIONOFFERED t rue amp INSURANCEAMT 1 00 amp L_SHIPPINGOPTIONISDEFAULT0O 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 w m Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Express Checkout Integration Guide May 2010 87 Implementing the Instant Update API Using the Callback 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 get 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 calculations for you Then send the shipping options insurance amounts and taxes to PayPal in
41. L_AMT0 9 95 amp L_QTY0 2 amp L_NAME1 Coffee Filter bags amp L_NUMBER1 623084 amp L_DESC1 Size Two 24 piece boxes amp L_AMT1 39 70 amp L_QTY1 2 amp ITEMAMT 99 30 amp TAXAMT 2 58 amp SHIPPINGAMT 3 00 amp HANDLINGAMT 2 99 amp SHIPDISCAMT 3 00 amp INSURANCEAMT 1 00 amp AMT 105 87 amp CURRENCYCODE USD amp ALLOWNOTE 1 w m Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P You can provide values for any subset of the Express Checkout parameters shown in SetExpressCheckout Order Details Parameters in the call to SetExpressCheckout If you pass the generic order description parameter D1 ESC and any one line item parameter listed below both parameter values display on the Review page If you pass the generic order description parameter DESC along with any two of the following line item parameters the order description value does not display e L NAMEn e L_NUMBERn e L DESCn If you pass in unit price information L_AMTn without passing in the unit quantity L_OTYn the unit price will not display To show both values you must pass in values for both parameters You can pass in a value of 1 even if the item purchase is uncountable May 2010 Express Checkout Integration Guide Customizing Express Checkout em PayPal Review Page Order Details eBay Issued Incentives
42. OKEN EC 17C76533PL706494P Integrating Parallel Payments 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 Be sure to use structure fields that are not marked as deprecated in the SOAP API reference documentation To integrate parallel payments using the SOAP interface to Express Checkout 1 Create PaymentDetails as an array of PaymentDetailsType structures one for each payment you will be hosting 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 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 PayPalAccountId field 3 Use PaymentDetailsType and PaymentDetailsItemType 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 a Payment InfoType structure corresponding to each payment e The
43. PI username n IGNATURE API_signature Specifying Credentials using cURL The following example shows one way to specify a signature using CURL curl insecure https api 3t sandbox paypal com nvp d METHOD DoDirectPayment amp VERS ION 56 0 amp USER API_username amp PWD API_password amp SIGNATURE API_signatue fee NOTE This example does not establish a secure connection and should not be used live on paypal com URL Encoding All requests to execute PayPal API operations sent via HTTP must be URL encoded The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server You must encode all data sent using the HTTP protocol because data that is not encoded could be misinterpreted as part of the HTTP protocol instead of part of the request Most programming languages provide a way to encode strings in this way You should consistently URL encode the complete API request otherwise you may find that unanticipated data causes an error NOTE An HTTP form is automatically URL encoded by most browsers Express Checkout Integration Guide May 2010 33 4 PayPal Name Value Pair API Basics Executing NVP API Operations List Syntax for Name Value Pairs The PayPal API uses a special syntax for NVP fields defined as lists The NVP interface to the PayPal API requires a unique name for each field In the API lists are prefixed by L_ To identify an element within the
44. Pal 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 is cancelled by the buyer PayPal provides the necessary details for an EFT so that the buyer can complete the transaction by pushing funds from his her bank account If your PayPal account profile blocks non instant payments the transactions is cancelled giropay Payment Page Flow The following diagram illustrates the flow of a successful giropay payment Express Checkout Integration Guide May 2010 131 Integrating giropay with Express Checkout giropay Page Flows Page flow for a successful giropay payment laa Paypal Website Td Your Website Giropay Ce Receipt Shopping Cart Stored Shipping amp Billing Info Pay lama Paypal Website Views Customer views Tha zafer eanier wry to pay B vour Website d biling order review page Customer pays with ays PayPal laa Giropay edirect Page CTT Giropay Giropay Payment Complete Enter PIN Enter TAN P Customer views order confirmation Cancelled 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 Pa
45. PayPal Express Checkout Integration Guide Express Checkout Integration Guide Document Number 100010 en_US 201005 2010 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal
46. 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 Express Checkout Integration Guide May 2010 103 et Implementing Parallel Payments Integrating Parallel Payments Using the SOAP API If errors are returned check the response data in the Payment Info PaymentError field PaymentError 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 money 104 May 2010 Express Checkout Integration Guide Implementing Parallel Payments Integrating Parallel Payments Using the SOAP API PaymentDetailsType PaymentDetailsArray new PaymentDetailsType 9 J RRR RRR RRR KK KKK A A A I I KARR AA A A I II k k k k k merchant 1 J RRR RRR RK KKK KKK I A A I I I ARAKI IK KH PaymentDetailsType paymentl new PaymentDetailsType payment1 PaymentAction PaymentActionCodeType Order payment1 PaymentActionSpecified true payment1 SellerDetails
47. Payments PayPal procesa de forma segura los pagos para WebsiteName com Pague con PayPal con dos pulsaciones Por qu utilizar PayPal Puede utilizar su tarjeta de cr dito sin revelar su n mero de IDENTIFIQUESE EN PAYPAL tarjeta al vendedor Puede realizar r pidamente el pago sin tener que introducir electr nico al n mero de la tarjeta ni la direcadn Contrase a Registrese para obtener una cuenta PayPal y continuar el pago identifiquese Cancelar y volver a WebsiteName com Ha olvidado su direcci n de correo alectr nico o ru contrasefia Express Checkout Integration Guide May 2010 67 o 6 Customizing Express Checkout Handling Shipping Addresses Handling Shipping Addresses You can specify several shipping address options that affect the PayPal Review page In your SetExpressCheckout request you can specify the following options e Require a confirmed address e Not display the shipping address on the review page e Display an alternative address on the review page 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 be a confirmed 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
48. R 2 000 00 must be specified as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00 regardless of the currency used AMT amount CURRI 4 Specify ENCYCODE currencylD the payment action Although the default payment action is a Sale it is a best practice to explicitly specify the payment action as one of the following values PAY ENTACTION Sale PAY ENTACTION Authorization PAY ENTACTION Order 40 May 2010 Express Checkout Integration Guide Implementing the Simplest Express Checkout Integration 4a Completing the Express Checkout Transaction 5 Execute the DoExpressCheckoutPayment API to complete the Express Checkout transaction 6 Examine the values returned by the API if the transaction completed successfully Express Checkout Integration Guide May 2010 41 az Implementing the Simplest Express Checkout Integration Completing the Express Checkout Transaction 42 May 2010 Express Checkout Integration Guide Testing an Express Checkout Integration You can test your Express Checkout integration in the Sandbox This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms You can use this strategy for your initial testing however for more complete testing you will want to replace these forms with your web pages containing actual code The following diagram shows t
49. Review you should not ship merchandise or in the case of electronic media you should not allow download access Because the payment status will change after review you must periodically check the payment status using the Get Transact ionDetails API operation The following diagram shows how to use the payment status to detect payments under review by PayPal Express Checkout Integration Guide May 2010 129 Using Other PayPal API Operations Handling Payment Review DoExpressCheckoutPayment DoReferenceTransaction DoAuthorization DoReautorization API Operation Completed Okay to ship Cancel Reversed Y GetTransaction payr Details review Completed Okay to ship Cancel IMPORTANT For best results call the GetTransactionDetails API operation every six hours PayPal recommends not calling it more frequently than once per hour Reversed 130 May 2010 Express Checkout Integration Guide Integrating giropay with Express Checkout You must modify your Express Checkout implementation to use giropay a common German funding source e giropay Page Flows e giropay Integration 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 Pay
50. Setup and Administration Guide The guide is located on the Documentation page linked to the Library tab in Developer Central Revision History Revision history for Express Checkout Integration Guide TABLE 1 1 Revision history Date Description 05 11 10 Added details for integrating parallel payments using the NVP and SOAP API including use with airlines Added new Immediate Payment functionality Updated billing agreements with functionality to obtain the latest billing address skip billing agreement creation and clarify use of the BAUpdate API 03 10 10 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 10 05 2009 Added Immediate Payment Edited for technical accuracy Removed PayPal placement guidelines 06 30 2009 Added a section on payment review Express Checkout Integration Guide May 2010 i Revision History TABLE 1 1 Revision history Date Description 06 04 2009 Added a chapter on pre populating the PayPal review page 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 chap
51. TIONISDEFAULT1 t rue amp L_SHIPPINGOPTIONNAME2 UPS Ground2 to 7 Days amp L_SHIPPINGOPTIONAMOUNT2 9 99 amp L_TAXAMT2 1 99 amp L_INSURANCEAMOUNT2 1 28 amp L_SHIPPINGOPTIONISDEFAULT2 false Express Checkout Integration Guide May 2010 89 Implementing the Instant Update API Using the Callback 90 May 2010 Express Checkout Integration Guide Immediate Payment Immediate Payment ensures a buyer pays for a purchase immediately after commiting to it e Overview of Immediate Payment on page 91 e About Immediate Payment For Third Party Checkout on page 91 e Integrating Immediate Payment for Third Party Checkout on page 93 e About Immediate Payment For Express Checkout on page 94 e Integrating Immediate Payment for Express Checkout on page 95 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 2 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
52. Type 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 SetExpressCheckoutRequestDetails Payment Details PaymentDetailsArray Express Checkout Integration Guide May 2010 107 ee Implementing Parallel Payments Handling Errors Handling Errors It 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 When this happens the ACK value is PartialSuccess To find the error check the value returned in PAYMENT INF O_n_ERRORCODE in the response to DoExpressCheckoutPayment NOTE Ifan error is generated by any of the payments in the call to SetExpressCheckout the transaction fails 108 May 2010 Express Checkout Integration Guide Handling Payment Settlements You can use PayPal API operations to handle the capture of payments authorized using Express Checkout and manage Express Checkout authorization and order pa
53. You invoke the GetExpressCheckoutDetails API operation from the page specified by return URL which you set in your call to the SetExpressCheckout API Typically you invoke this operation as soon as the redirect occurs and use the information in the response to populate your review page To obtain a buyer s shipping address and Payer ID 1 Specify the token returned by PayPal when it redirects the buyer s browser to your site PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API TOKEN token Value 2 Execute the GetExpressCheckoutDetails API to obtain information about the buyer 3 Access the fields in the GetExpressCheckoutDetails API response NOTE Only populated fields are returned in the response Completing the Express Checkout Transaction To complete an Express Checkout transaction you must invoke the DoExpressCheckoutPayment API operation This example assumes that PayPal redirects your buyer s browser to your website with a valid token after you call the SetExpressCheckout API Optionally you may call the Express Checkout Integration Guide May 2010 39 az Implementing the Simplest Express Checkout Integration Completing the Express Checkout Transaction GetExpressCheckoutDetails API before calling the DoExpressCheckoutPayment API In the simplest case you set the total amount of the or
54. _2 fr_ FR C2 language_0O 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_O 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 May 2010 Express Checkout Integration Guide Express Checkout Button and Logo Image Integration al Static PayPal Button and Mark Images Source Requirements Country code Language priority Locale 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 NL language_0O nl_NL NL language_1 en_US PL language_0O pl_PL PL language_1 en_US RE language_0O 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 Static PayPal Button and Mark Images Source Requirements Using the static image code on the PayPal servers eliminates the need for you to maintain them yourself PayPal requires that you use the Check out with PayPal and the PayPal acceptance mark images hosted on secure PayPal servers When the images are updated the changes appear automatically in
55. _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_ INSURANCEOPTIONOFFERED false amp PAYMENTREQUEST_1_ PAYMENTREQUESTID CART26488 PAYMENT 1 amp L_PAYMENTREQUEST_O_NAME0 Depart San Jose Feb 12 at 12 10PM Arrive in Baltimore at 10 22P amp L_PAYMENTREQUEST_O_NAMF1 Depart Baltimore Feb 15 at 6 13 PM Arrive in San Jose at 10 51 PM amp L_PAYMENTREQUEST_0O_NUMBERO Flight 522 amp L_PAYMENTREQUEST_O_NUMBER1 Flight 961 amp L_PAYMENTREQUEST_0_QTYO 1 amp L_PAYMENTREQUEST_O_OTY1 1 amp L_PAYMENTREQUEST_0O_TAXAMTO 50 amp L_PAYMENTREQUEST_0O_TAXAMT1 50 amp L_PAYMENTREQUEST_0O_AMT0O 50 amp L_PAYMENTREQUEST_0O_AMT1 150 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 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 102 May 2010 Express Checkout Integration Guide Implementing Parallel Payments ina Integrating Parallel Payments Using the SOAP API Response Parameters successResponseFields amp T
56. al redirects your buyer s browser after the buyer finishes on PayPal Other setup also can be performed by this API operation 2 Invoke additional API operations after receiving the buyer s permission on PayPal for example GetExpressCheckoutDetails or DoExpressCheckoutPayment The following diagram shows the execution flow between your site and PayPal May 2010 Express Checkout Integration Guide PayPal Name Value Pair API Basics aa PayPal API Client Server Architecture Your Site LLL PayPal API Server Redirect to PayPal PayPal Login Contirm Details PayPal redirects Continue A Your Site Pal a PayPa API Server Token Usage Typically the API operation that sets up a redirection to PayPal returns a token This token is passed as a parameter in the redirect to PayPal The token also might be required in related API operations Express Checkout Integration Guide May 2010 29 4 PayPal Name Value Pair API Basics Obtaining API Credentials Obtaining API Credentials To use the PayPal API you must have API credentials that identify you as a PayPal Business account holder who is authorized to perform various API operations Although you can use either an API signature or a certificate for credentials PayPal recommends you use a signature IMPORTANT Although you can have both a signature and certificate you cannot use both at the same time Creating an API Signature An API signature consist
57. al requests and send back responses Express Checkout Integration Guide May 2010 77 Implementing the Instant Update API About the Instant Update API 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 GetExpressCheckoutDetails to obtain the buyer s final choices for shipping and insurance if applicable Call DoExpressCheckoutPayment with the buyer s final selections 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 on the PayPal Review page The shipping and insurance options appear in drop down menus as shown below 78 May 2010 Express Checkout Integration Guide Implementing the Instant Update API About the Instant Update API PayPal Review Page With Shipping Options Insurance and Tax Your Website Review your information PayPal E secu amen ifthe information below is correct click Continue You will confirm your payment on the next page View PayPal policies and your payment source rights Description Und Price Quartty Amourt 10 Decaf Kona Blend Coffee 9 95 2 19 90 Rem 623083 Size 6 Boz Coffee Fier bags 39
58. and save it in a valid graphics format such as gif jpg or png Express Checkout Integration Guide May 2010 63 Customizing Express Checkout PayPal Page Style 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 HDRIMG parameter in the call to SetExpressCheckout The following example sets HDRIMG to a custom header image Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp MAXAMT amp PAYMENTACTION Sale amp HDRIMG https www mayadeviimports com ebay websitename logo gif amp SHIPTOSTREET 1 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The figure below shows the review page with a custom header image set in the SetExpressCheckout request 64 May 2010 Express Checkout Integration Guide Customizing Express Checkout PayPal Page Style Review page with custom header image WebsiteName com Review Your Information PayPal Secure Payments Please review the information below If correct click Continue to complete your payment on the Webs
59. ange it later on your final checkout page You might assume for example the buyer lives in California because your business is in California HANDLINGAMT HandlingTotal Total handling cost for this order PayPal calculates the sum of the handling cost and the shipping cost above as shown at 8 in PayPal Review page with order details SHIPDISCAMT ShippingDiscoun Shipping discount for this order You specify this value as a t negative number INSURANCEAMT InsuranceTotal Total shipping insurance cost for this order AMT OrderTotal Total of order including shipping handling tax and any other billing adjustments such as a credit due ALLOWNOT AllowNote Provide a value of 1 to indicate that the buyer may enter a note to you on the PayPal Review page during checkout See Special Instructions text box 5a The following example shows how to set the above parameters in the call to SetExpressCheckout Express Checkout Integration Guide May 2010 53 54 Customizing Express Checkout PayPal Review Page Order Details Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTACTION Sale amp NAME J Smith amp SHIPTOSTREET 1 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp L_NAMEO 10 Decaf Kona Blend Coffee amp L_NUMBERO 623083 amp L_DESCO Size 8 8 oz amp
60. ay Pay Now on the button 1 Get the token from the response to Set ExpressCheckout The response to SetExpressCheckout is the buyer s token For example if the value of RETURNURL passed to SetExpressCheckout is https www websitename com snagECvalues the URL to which PayPal redirects appears as https www websitename com snagI OW8920957N684880R 2 Add the token and the desired useraction value contin to the following URL ECvalues token EC ue or Commit as name value pairs https www paypal com cgi bin webscr cmd _express checkout amp token valueFromSetExpressCheckoutResponse amp useraction commit The figure below shows the PayPal Review page when useraction commit PayPal review page when user commits to purchase on PayPal WebsiteName com Review Your Payment Please review the informaton below If correct payment Leam more about PayP Payment Method Shipping Address Contact Information click Pay Now t complete your al policies and your payment source rights and remedies re a sa X 1054 1 Main Street San Jose CA 95131 United St Change T 01 niple corr Nn to Websitetame com May 2010 Totak 10 00 USD PayPal Seure Payments Express Checkout Integration Guide Implementing the Instant Update API The Instant Update API is a callback you can use to obtain the buyer s shipping address e About the Instant Update API e How the Callback Works in the
61. aypal com it cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Japan https www paypal com j1 cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Netherlands https www paypal com nl cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Poland https www paypal com pl cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Spain https www paypal com es cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside Switzerland https www paypal com ch cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside United Kingdom _https www paypal com uk cgi United States bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside https www paypal com us cgi bin webscr cmd xpt Merchant merchant ExpressCheckoutButtonCode outside May 2010 Express Checkout Integration Guide PayPal Name Value Pair API Basics The Name Value Pair NVP API provides parameter based association between request and response fields of a message and their values The request message is sent via the API from your website and a response message is returned by PayPal using a client server model in which your site is a client of the PayPal server NOTE The PayFlow API also uses name value pairs to provide parameter based association between request and response fields of a message and their values however the
62. buyer has made one trial payment out of a total of three UpdateRecurringPayment sProfile is called to increase the number of billing cycles to five As a result the buyer will have four additional trial payments to make If the call to UpdateRecurringPaymentsProfile is made 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 Express Checkout Integration Guide May 2010 123 124 Handling Recurring Payments Billing the Outstanding Amount of a Profile Updating Addresses When you update the subscriber shipping address you must enter all of address fields not just those that are changing For example if you want to update the subscriber s street address you must specify all of the address fields listed in the Name Value Pair Developer Guide and Reference or SOAP API Reference not just the field for the street address Updating the Billing Amount For profiles created using Express Checkout the total amount of a recurring payment can only be increased 20 in a fixed 180 day interval after the profile is created The 20 maximum is based on the total amount of the profile at the beginning of the 180 day interval including any shipping or tax amount For example if a profile is created on March 10 with a total amount of 100 then during the 180 day interval from March
63. cate only if your website requires it Typically you want to create an API signature for your credentials instead If you do need a certificate follow the instructions at https www paypal com IntegrationCenter ic_api certificate html NOTE The certificate for API credentials is not the same as an SSL certificate for your website they are not related to each other Creating an NVP Request The Name Value Pair request format specifies the API operation to perform credentials that authorize PayPal to access your account and fields containing additional information to be used in the request Express Checkout Integration Guide May 2010 31 4 PayPal Name Value Pair API Basics Creating an NVP Request Specifying the PayPal API Operation For the NVP version of the PayPal API you must specify the name of the PayPal API operation to execute in each request along with the version of the API operation The following diagram shows the API operation part of an NVP request Your Site I NVP Request E METHOD SetExpressCheckout C VERSION 52 0 Pa L2 PayPar API credentials Request specific fields eee eee ee ee eee eer A method specifies the PayPal operation you want to execute and each method is associated with a version Together the method and version define the exact behavior of the API operation Typically the behavior of an API operation does not change between versions however you should carefully retest your co
64. chitecture PayPal Name Value Pair API Requests and Responses API operation Your Site T API credentials Request specific fields a PayPal Multiple To perform a PayPal NVP API operation you send an NVP formatted request to a PayPal NVP server and interpret the response In the following diagram your website generates a request The request is executed on a PayPal server and the response is returned to your site NVP Request I NVP Response Acknowledgement status E Tracking information Response specific fields The request identifies e The name of the API operation to be performed and its version for example SetExpressCheckout for version 62 0 e Credentials that identify the PayPal account making the request e Request specific information that controls the API operation to be performed A PayPal API server performs the operation and returns a response The response contains e Anacknowledgement status that indicates whether the operation was a success or failure and whether any warning messages were returned e Information that can be used by PayPal to track execution of the API operation e Response specific information required to fulfill the request API Operations Some of the features such as Express Checkout require you to call multiple API operations Typically these features require you to 1 Invoke an API operation such as SetExpressCheckout that sets up the return URL to which PayP
65. ction Results Profile ID Success Failure The circled numbers in the diagram correspond to the following steps 118 May 2010 Express Checkout Integration Guide Handling Recurring Payments m Recurring Payments With Express Checkout Recurring payments processing flow Step Merchant PayPal 1 Calls SetExpressCheckout with one or more billing agreement details in the request 2 Returns a token which identifies the transaction to the merchant 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 Allows user 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 merchant 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 sProfileone time for each recurring payment item included in the order Returns ProfileID in CreateRecurringPaymentsProfile response for each profile successfully created 7 Displays successful transaction page Initiating the Proce
66. de whenever you change a version To specify a method and version number 1 Choose the PayPal API operation you want to use METHOD operation 2 Choose the appropriate version In most cases you should use the latest version of the API operation VERS ION version_number Example of setting the API operation and version using PHP function PPHttpPost SmethodName_ S nvpStr_ Sversion urlencode 52 0 NVPRequest for submitting to server Snvpreq METHOD SmethodName_ amp VERSTON Sversion SnvpStr_ Specifying an API Credential You must specify API credentials in each request to execute a PayPal API operation When you execute a PayPal API operation you use credentials such as a signature to authenticate that you are requesting the API operation The following diagram shows the API credentials part of an NVP request 32 May 2010 Express Checkout Integration Guide PayPal Name Value Pair API Basics So Creating an NVP Request Your Site I NVP Request API operation CT S USER sdk three_api1 sdk com PayPal PWD QFZCWN5HZM8VBG7Q SIGNATURE A IzJhZZjhg29 Request specific fields To enable PayPal to authenticate your request 1 Specify the API user name associated with your account USER API_usemame 2 Specify the password associated with the API user name PWD API_ password 3 If you are using an API signature and not an API certificate specify the API signature associated with the A
67. der when you call the SetExpressCheckout API However you can change the amount before calling the DoExpressCheckoutPayment API if you did not know the total amount when you called the SetExpressCheckout API This example assumes the simplest case in which the total amount was specified in the return URL when calling the SetExpressCheckout API Although you can specify additional options this example does not use any additional options To execute 1 Specify an Express Checkout transaction the token returned by PayPal when it redirects the buyer s browser to your site PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API TOKEN tokenValue 2 Specify the Payer ID returned by PayPal when it redirects the buyer s browser to your site PayPal returns the Payer ID to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API Optionally you can obtain the Payer ID by calling the GetExpressCheckoutDetails API PAYERID id 3 Specify the amount of the order including shipping handling and tax include the currency if it is not in US dollars Regardless of the specified currency the format must have decimal point with exactly two digits to the right and an optional thousands separator to the left which must be a comma for example EU
68. ditional pages required for giropay integration NVP Field Description Order Completion The GIROPAYSUCCESSURL page that PayPal redirects the buyer to after a successful giropay payment Order Cancellation The GIROPAYCANCELURL page that PayPal redirects the buyer to after a giropay or bank transfer payment is cancelled or fails Order Pending The BANKTXNPENDINGURL page that PayPal redirects the buyer to 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 134 May 2010 Express Checkout Integration Guide
69. e EUR 2 000 00 must be specified as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00 regardless of the currency used AMT amount CURRENCY CODE currencyID Express Checkout Integration Guide May 2010 37 az Implementing the Simplest Express Checkout Integration Setting Up the Express Checkout Transaction 2 Specify the return URL The return URL is the page to which PayPal redirects your buyer s browser after the buyer logs into PayPal and approves the payment Typically this is a secure page https on your site NOTE You can use the return URL to piggyback parameters between pages on your site For example you can set your Return URL to specify additional parameters using the https www yourcompany com page htm1 param value syntax The parameters become available as request parameters on the page specified by the Return URL RETURNURL return_url 3 Specify the cancel URL The cancel URL is the page to which PayPal redirects your buyer s browser if the buyer does not approve the payment Typically this is the secure page https on your site from which you redirected the buyer to PayPal NOTE You can pass SetExpressCheckout request values as parameters in your URL to have the values available if necessary after PayPal redirects to your URL CANCELURL cancel_url 4 Specify the payment action Although the default payment action is a Sale it is a best practice to
70. eBay auction item it is recommended that you provide the phrase eBay item in this field 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 Express Checkout Integration Guide May 2010 49 8 Customizing Express Checkout PayPal Review Page Order Details 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 These are the respective total of all items in the order and the tax 8 Shipping and handling PayPal sums the shipping and handling amounts in this field You determine actual shipping and handling amounts 9 Shipping discount If the buyer is receiving a discount on shipping the value appears as a credit in this field 10 Insurance If there is insurance on shipping the insurance fee is shown in this field 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 12 Note Yo
71. ent requests PAYMENTACTION Authorization Express Checkout Integration Guide May 2010 109 110 Handling Payment Settlements Order Payment Action for Express Checkout An authorization enables you to capture multiple payments up to 115 of or USD 75 more than the amount you specify in the DoExpressCheckoutPayment request Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately The honor period for which funds can be held is three days The valid period for which the authorization is valid is 29 days You can reauthorize the 3 day honor period at most once within the 29 day valid period You can void an authorization in which case the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured If no part of the payment has been captured the entire payment becomes void and nothing can be captured API operations associated with Authorization payment action in Express Checkout API Operation Description DoCapture Capture an authorized payment DoReauthorization Reauthorize a payment DoVoid Void an order or an authorization Order Payment Action for Express Checkout An order payment action represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days To set up an order specify the following payment
72. eplaces it with one you specify in the call to SetExpressCheckout The buyer cannot edit the overridden address NOTE If you prefer to override addresses it is recommended that you do not set confirmed addresses as required 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 HIP TONAME HIPTOSTREET HIPTOCITY HIPTOSTATE Optional HIP TOCOUNTRYCODE HIPTOZIP SHIPTOSTR NANNnNnNN N T ET2 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 AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale amp ADDROVERRIDE 1 amp SHIPTOSTREET 1 Second St amp SHIPTOSTREET2 Ste 210 amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 57K68322WE343022B The figure below shows the PayPal Review page when the shipping address parameters are overridden by the values shown in the
73. erience flow NOTE Tokens are not shown in the diagram Express Checkout Buttons PayPal provides buttons and images for you to place on your website To implement the Express Checkout shopping cart experience place the following button on your Shopping Cart page The safer easier way to pay To implement PayPal as a payment option which is part of the Express Checkout experience associate the PayPal mark image with your payment options PayPal recommends using radio buttons for payment options 16 May 2010 Express Checkout Integration Guide Introducing Express Checkout oe Express Checkout Building Blocks Payment Options PayPal E vise SS Express Checkout API Operations The PayPal API provides three API operations for Express Checkout which sets up the transaction obtains information about the buyer and handles the payment and completes the transaction API Operation Description Set Get ExpressCheckout Sets up the Express Checkout transaction You can specify information to customize the look and feel of the PayPal site and the information it displays You must include the following information e URL to the page on your website that PayPal redirects to after the buyer logs into PayPal and approves the payment successfully e URL to the page on your website that PayPal redirects to if the buyer cancels e Total amount of the order or your best estimate of the total It should be as
74. ering insurance options Otherwise set INSURANCEOPTIONSOFFERED to false Set line item description details such as L_ITEMWEIGHTUNIT1 and L_ITEMWEIGHTVALUE1 shown in the example below Set CALLBACKTIMEOUT to the amount of time in seconds to process the callback By default CALLBACKTIMEOUT is 3 You can specify a value in the range of 1 to 6 inclusive This is an example SetExpressCheckout request The above parameters appear in boldface text 86 May 2010 Express Checkout Integration Guide Implementing the Instant Update API Using the Callback Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTACTION Sale amp NAME J Smith amp SHIPTOSTREET 1 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp L_NAMEO 10 Decaf Kona Blend Coffee amp L_NUMBERO 623083 amp L_DESCO Size 8 8 o0z amp L_AMT0 9 95 amp L_QTY0 2 amp L_NAME1 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_ITEMWEIGHTVALUE1 0 5 amp L_ITEMWEIGHTUNIT1 l1bs amp ITEMAMT 99 30 amp TAXAMT 2 59 amp MAXAMT 150 00 amp SHIPPINGAMT 8 00 amp SHIPDISCAMT 3 00 amp AMT 107 89 amp CURRENCYCODE USD amp ALLOWNOTE 1 amp CALLBAC
75. etExpressCheckoutDetails API operation to obtain the buyer s final shipping option selections GettExpressCheckoutDetails has been updated to return the buyer s selections Because the cart information passed in the call to SetExpressCheckout is only relevant for display on the PayPal Review page you must call the DoExpressCheckoutPayment API operation with the updated shipping insurance and tax data to ensure the buyer sees it upon redirect to your website Other Considerations When you implement the callback there are other issues you must take into consideration These include e Callback response errors e Minimum and maximum shipping options e Callback times out e You do not ship to the buyer s shipping address Callback Response Errors If there are any callback response errors PayPal responds by displaying the flat rate shipping options on the PayPal Review page 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 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 Callback Times Out If the callback does not return within the timeout period PayPal displays the flat rate shipping options you specified i
76. eturns to obtain shipping information from PayPal and accept the payment to complete the Express Checkout transaction NOTE You also can allow the buyer to pay on the PayPal Review page in which case your checkout flow can omit the Merchant Review page and proceed directly to your Confirmation page For more information see Buyer Pays on PayPal on page 75 Checkout Entry Point The checkout entry point is one of the places where you must implement Express Checkout Buyers initiate the Express Checkout flow on your shopping cart page by clicking the Checkout with PayPal button The following diagram shows how Express Checkout integrates with a typical checkout flow May 2010 Express Checkout Integration Guide Introducing Express Checkout Express Checkout Building Blocks Integrating Express Checkout from the Shopping Cart page a ee Create PayPal Login PayPal Review g address checkout Checkout Confirmation Add To Cart gt bake 2i Purchase i Collect Shipping Merchant Review Confirmation A PayPal Address Pay The safet caster way to pay Shopping Cart Payment Methods Payment Option Entry Point The payment option entry point is one of the places where you must implement Express Checkout Buyers initiate the Express Checkout flow on your payment methods page by selecting PayPal as the default option The following diagram shows how to integrate Express Checkout from your payment methods page Integrating Expre
77. explicitly specify the payment action as one of the following values PAYMENTACTION Sale PAYMENTACTION Authorization PAYMENTACTION Order 5 Execute the SetExpressCheckout API operation to set up the Express Checkout transaction 6 Test that the response to the SetExpressCheckout API operation was successful 7 If calling the SetExpressCheckout API was successful redirect the buyer s browser to PayPal and execute the _express checkout command using the token returned in the SetExpressCheckout response 38 May 2010 Express Checkout Integration Guide Implementing the Simplest Express Checkout Integration 4 Obtaining Express Checkout Transaction Details NOTE The following example uses the PayPal Sandbox server https www sandbox paypal com webscr cmd _express checkout amp token lokenValue amp AMT amount amp CURRENCYCODE currencylD amp RETURNURL retum_url amp CANCELURL cancel_url Obtaining Express Checkout Transaction Details To obtain details about an Express Checkout transaction you can invoke the GetExpressCheckoutDetails API operation This example assumes that PayPal redirects to your buyer s browser with a valid token after the buyer reviews the transaction on PayPal Although you are not required to invoke the GetExpressCheckoutDetails API operation most Express Checkout implementations take this action to obtain information about the buyer
78. 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 DoExpressCheckoutPayment is called 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 Express Checkout Integration Guide May 2010 91 Te Immediate Payment About Immediate Payment For Third Party Checkout e By design it does not support non instant funds like 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 the only payment action supported 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 figure below shows how Immediate Payment for third party checkout integrates into your checkout flow Place Order Order Confirmation O
79. fying a Recurring Payments Profile e Billing the Outstanding Amount of a Profile e Recurring Payments Notifications How Recurring Payments Work 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 After a profile is created 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 When a buyer uses Express Checkout queued payments are funded using the normal funding source hierarchy within the buyer s PayPal account After you create a recurring payments profile you can view recurring payments details or cancel the recurring payments 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
80. g 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 orders that you later capture with the Authorization and Capture APIs 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 not support Accelerated Boarding however single payment transactions are still supported e Does not support parallel billing agreements Express Checkout Integration Guide May 2010 97 Implementing Parallel Payments About Parallel Payments Post Integration Experience After you integrate parallel payments the PayPal Review page shows summary information for each payment The example below shows summary information for an online travel agency with payments to an airline and a hotel Your order summary Description Amount H Vandelay Airlines 300 00 i Central Perk Hotel 200 00 Total USD 500 00 The figure below shows expanded details on the airline purchase Your order summary Description Amount A E Vandelay Airlines 300 00 Depart San Jose Feb 12 at 12 10 PM _ item number Flight 22 item price 50 00 Quantity 1 Depart Baltimore Feb 15 at 6 13 PM ma tem number Flight 961 tem price 150 00 Quantity 1 Total USD 500 00 lt The figure below
81. gPayments L_BILLINGTYPEO RecurringPayments Add an L_BILLINGAGREEMENTDESCRIPTIONn field to correspond to each L_BILLINGTYPEn field you pass n is a value in the range of 0 to 9 inclusive Set the value of each field to the description of the goods or services associated with that billing agreement for example L_BILLINGAGREEMENTDESCRIPTIONO Time Magazine subscription If there is no associated purchase set AMT to 0 AMT 0 Optional Set MAXAMT to the average expected transaction amount PayPal uses the value you pass to validate the buyer s funding source for recurring payments If you do not specify a value the default is 25 00 NOTE When creating the recurring payments profile pass the same L_BILLINGTYPEn value and L_BILLINGAGREEMENTDESCRIPTIONn string describing the goods or service in the call to CreateRecurringPaymentsProfile that you passed in the call to SetExpressCheckout The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls Redirecting the Buyer s Browser to PayPal After you receive a successful response from Set ExpressCheckout add the TOKEN from the SetExpressCheckout response as a name Vvalue pair to the following URL and redirect your buyer s browser to it 120 May 2010 Express Checkout Inte
82. gration Guide Handling Recurring Payments me Recurring Payments With Express Checkout https www paypal com cgi bin webscr cmd _express checkout amp token lt value_from_SetExpressCheckoutResponse gt For redirecting the buyer s browser to the PayPal login page PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response Ensure that you use an SSL enabled server to prevent browser warnings about a mix of secure and insecure graphics 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 The values you specified for the following parameter fields are not returned in the GetExpressCheckoutDet ails response unless the transaction includes a purchase The fields are ignored if you set up a billing agreement for a recurring payment that is not immediately charged e DESC e CUSTOM e INVNUM Creating the Profiles With CreateRecurringPaymentsProfile After your buyer has agreed to the recurring payments billing agreement on
83. gration Guide May 2010 55 a Customizing Express Checkout PayPal Review Page Order Details New Total after applying incentives Voyage Travel Review your payment PayPal secu Payments If the information below is correct click Pay now to complete your payment View PayPal policies and your payment source rights Photo 25 00 1 25 00 Nokia ND 25 00 1 2500 item total 50 00 Shipping and handling 5 00 Subtotal 56 00 Std Coupon Remove 1 00 Total 55 00 USD Integrating eBay Incentives into the Express Checkout Flow To integrate eBay incentives into the checkout flow 1 Pass the following parameters and settings in the call to SetExpressCheckout PAYMENTACTION must be Sale CHANNELTYPE must be eBayItem NOTE For eBay auctions you cannot set PAYMENTACTION to Authorization or Order You must set PAYMENTACTION to Sale 2 For each eBay line item do one of the following mutually exclusive choices in the call to SetExpressCheckout and in the call to DoExpressCheckoutPayment For each individual eBay entry pass the values returned by eBay when setting up the auction item descriptions in the parameters below L_EBAY I TEMNUMBERn and L_EBAYITEMAUCTIONTXNIDn For multiple eBay items offered as a single order pass the value returned by eBay when setting up the auction order description in the parameter below L_EBAYTTEMORDERIDn If you are se
84. h a status of PendingProfile until the initial payment either completes successfully or fails A profile has a status of ExpiredProfile when both the total billing cycles for both the optional trial period and the regular payment period have been completed You can suspend or cancel a profile by using the ManageRecurringPayment sProfileStatus API You can also reactivate a suspended profile If the maximum number of failed payments has already been reached however you will need to increase the number of failed payments before reactivating the profile NOTE You can also suspend cancel or reactive a recurring payments profile through the PayPal website For recurring payments profiles created with Express Checkout the buyer receives an email about the change in status of their recurring payment Getting Recurring Payments Profile Information Use the GetRecurringPayment sProfileDetails API to get 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 in the CreateRecurringPaymentsProfile 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 out
85. he Express Checkout execution flow which uses the Sandbox as the API server The pages on the left represent your site Express Checkout Integration Guide May 2010 43 a Testing an Express Checkout Integration Express Checkout Execution Flow Legend gt Web Flow API Call Token i Request _ __ b ep Pal gt SetExpressCheckout PayPal 2 Sandbox ER Token S PayPal Login L HTTP Redirect mmm 2 amp 4 HTTP Redirect Confirm Detaits ReturnURL Token Sa Continue 5 Request Token GetExpressCheckoutDetails Sandbox Response Customer Details PayPal Sandbox Ooy C a 6 Request Final Transaction Details Thank DoExpressCheckoutPayment PayPal You Sandbox 7 t Response Transaction Results Success Failure The following steps match the circled numbers in the diagram Perform the actions in each step to test Express Checkout 1 Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox To invoke the API set form fields whose names match the NVP names of the fields you want to set specify their corresponding values and then post the form to a PayPal Sandbox server such as https api 3t sandbox paypal com nvp as shown in the following example 44 May 2010 Express Checkout Integration Guide Testing an Express Checkout Integration aaa lt form method post action https api 3t sa
86. heckout as shown in the example below Express Checkout Integration Guide May 2010 73 74 Customizing Express Checkout Automatically Filling Out the PayPal Login Page Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp PAYMENTACTION Sale amp SHIPTOSTREET 1 Main Street amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp EMAIL jsmith01 example com amp SHIPTOPHONENUM 408 559 5948 Response Parameters successResponseFields amp TOKEN EC 6UA07551EA393551U As a convenience PayPal fills out the billing address fields with the buyer s shipping address as shown in the example figure below The buyer can edit the information by clicking the Change links May 2010 Express Checkout Integration Guide Customizing Express Checkout aa Buyer Pays on PayPal Pre populated PayPal Login page WebsiteName com Create a PayPal Account or Log In PayPal Secure Payments Create a PayPal accoum Ak eady have a PayPal accourm Country United States v Please log in Credit Card Number Ema 1 mi Payment Type visal AMOS jsmahO1 exarnple com mat Expiration Date esc Wihar s hes Password Billing Information Jane Smith 1 Main Street _togin San Jose CA95131 United States Change Forget emal address or password Contact information jsrnith0 1 e
87. image for that account Be sure to pass the pal value matching your account Express Checkout Integration Guide May 2010 21 Express Checkout Button and Logo Image Integration Dynamic Image Command Reference 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 Feedback to Buyer Meeting an Incentive 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 discount 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
88. ing values e Success indicates a successful operation e SuccessWithWarning indicates a successful operation however there are messages returned in the response that you should examine e Failure indicates the operation failed the response also contains one or more error messages explaining the failure FailureWithWarning indicates that the operation failed and that there are messages returned in the response that you should examine CORRELATIONID Correlation ID which uniquely identifies the transaction to PayPal TIMESTAMP The date and time that the requested API operation was performed VERSION The version of the API BUILD The sub version of the API Express Checkout Integration Guide May 2010 35 8 PayPal Name Value Pair API Basics Responding to an NVP Response URL Decoding All responses to HTTP POST operations used by the PayPal NVP API must be decoded The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server You must decode all data returned using the HTTP protocol so that it can be displayed properly Most programming languages provide a way to decode strings NoTE Most browsers decode responses to HTTP requests automatically 36 May 2010 Express Checkout Integration Guide Implementing the Simplest Express Checkout Integration The simplest Express Checkout integration requires the following PayPal API operations SetExpressCheckout DoExpressCheckoutPayme
89. ional PayPal API operations to implement additional features for your buyers or to provide back office support e Issuing Refunds e Handling Payment Review Issuing Refunds You can use the RefundTransaction PayPal API operation to issue refunds Use the RefundTransaction API to issue one or more refunds associated with a transaction such as a transaction created by a capture of a payment The transaction is identified by a transaction ID that PayPal assigns when the payment is captured NOTE You cannot make a refund if the transaction occurred after the refund period has passed typically the refund period is 60 days You can refund amounts up to the total amount of the original transaction If you specify aa full refund the entire amount is refunded If you specify a partial refund you must specify the amount to refund the currency and a description of the refund which is called a memo When you call the RefundTransaction API PayPal responds with another transaction ID which is associated with the refund not the original transaction and additional information about the refund This information identifies e the gross amount of the refund which is returned to the payer e the amount of the refund associated with the original transaction fee which is returned to you e the net amount of the refund which is deducted from your balance To issue a refund 1 In the RefundTransaction request specify the transaction ID
90. iteName com website Learn more sbout PayPal policies and your payment source rights and remedies Payment Method Credit Card Visa XXXX KXXX XXXX 0084 Change Shipping Address 1 Main Street San Jose CA 95131 United States Change Contact Information jsmathOil example com Cancel and return to WebsiteName com The following example sets colors for the header background HDRBACKCOLOR and header border HDRBORDERCOLOR Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp MAXAMT amp PAYMENTACTION Sale amp HDRBACKCOLOR FFFF 66 amp HDRBORDERCOLOR 996666 amp SHIPTOSTREET 1 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 408 967 4444 Express Checkout Integration Guide May 2010 65 66 Customizing Express Checkout Changing the Locale Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The figure below shows the PayPal Login page with HDRBACKCOLOR and HDRBORDERCOLOR set to custom colors PayPal Login page with custom header background and border colors PayPal is the safer easier way to pay PayPal secure Payments PayPal securely processes payments for WebsiteName com Pay with PayPal in a couple of clicks Why use PayPal You can use your credit card without exposing your card
91. ive 2 2222000 4 22 Choose the Image 2 0 22 Dynamic Image Command Reference a eee eee eee 22 Dynamic Image Parameters oaoa aa a a a 23 Locale CodeSu s s s s ru am ee ee ee a E a a a a EA ee eee a 23 Express Checkout Integration Guide May 2010 a Contents Static PayPal Button and Mark Images Source Requirements 25 Chapter 3 PayPal Name Value Pair API Basics 27 PayPal API Client Server Architecture o oo 27 PayPal Name Value Pair API Requests and Responses 28 Multiple API Operations 2 2 ee 28 Obtaining API Credentials 2 a a 30 Creating an API Signature ooa aa a 30 Creating an API Certificate o oo aa ee 31 Creating an NVP Request a oaoa aaa a 31 Specifying the PayPal API Operation oao ooa 20 02 0000 2 eae 32 Specifying an API Credential o oo aa 32 URL EDCOMG acna a ea Bee ee we bee ee ee oaa ee de a bes 33 List Syntax for Name Value Pairs 2 aa 34 Executing NVP API Operations 2 2 a 34 Specifying a PayPal Server 2 2 34 Logging API Operations 1 oaa 34 Responding to an NVP Response 00000 ee eee ee eee 35 Common Response Fields 2 2 ee 35 URL Decoding s as aoa a ee hee See Pe eee ee Ok we ee eo OB 36 Chapter 4 Implementing the Simplest Express Checkout Integration 37 Setting Up the Express Checkout Transaction 2 2 2 eee ee ee 37 Obtaining Ex
92. ization expires simply by creating another authorization You can void an order or an authorization created from the order If you void an order the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured If no part of the payment has been captured the entire payment becomes void and nothing can be captured If you void an authorization associated with the order the uncaptured part of the amount specified in the authorization becomes void and can no longer be captured If no part of the authorization has been captured the entire authorized payment becomes void API operations associated with Order payment action in Express Checkout API Operation Description DoAuthorization Authorize a payment DoCapture Capture an authorized payment DoVoid Void an order or an authorization Express Checkout Integration Guide May 2010 111 10 Handling Payment Settlements Order Payment Action for Express Checkout 112 May 2010 Express Checkout Integration 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 e How Recurring Payments Work e Recurring Payments Terms e Options for Creating a Recurring Payments Profile e Recurring Payments With Express Checkout e Recurring Payments Profile Status e Getting Recurring Payments Profile Information e Modi
93. ken Usage Express Checkout uses a token to control access to PayPal and execute Express Checkout API operations The SetExpressCheckout API operation returns a token which is used by other Express Checkout API operations and by the _ExpressCheckout command to identify the transaction The life of the token is approximately 3 hours 18 May 2010 Express Checkout Integration Guide Express Checkout Button and Logo Image Integration PayPal hosts the PayPal button and logo images that you use on your website Using PayPal s buttons and logos is convenient and standardizes appearance on websites that use PayPal as a payment option e About PayPal Button and Logo Images e Dynamic Images e Configuring the Dynamic Image e Dynamic Image Command Reference e Static PayPal Button and Mark Images Source Requirements About PayPal Button and Logo Images To inform buyers that PayPal is accepted on your website you must place PayPal button and logo images in your checkout flow PayPal Express Checkout requires that you integrate two images The Check out with PayPal button and the PayPal Acceptance mark Express Checkout Images The Check out with PayPal button is the image you place on your shopping cart page The US version of the image looks like this PayPal also provides buttons for other locales The safer easier way to pay The PayPal Acceptance Mark is the image you place on your payment methods page It looks like this
94. kout Integration Guide Customizing Express Checkout ae PayPal Review Page Order Details SetExpressCheckout Order Details Parameters NVP Field SOAP Field Description and Comments NAMEn Name Item name NUMBERn Number Item number DESCn 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 L_AMTn Amount Item unit price PayPal calculates the product of the item unit price and item unit quantity below in the Amount column of the PayPal Review page as shown in PayPal Review page with order details 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_OQTYn Quantity Item unit quantity ITEMAMT ItemTotal Sum of cost 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 PayPal calculates the sum of the shipping cost and the handling cost below in the PayPal Review page as shown at 8 in PayPal Review page with order details Pass in a shipping amount that is reasonably accurate because you may need to ch
95. l API operation you execute 34 May 2010 Express Checkout Integration Guide PayPal Name Value Pair API Basics Responding to an NVP Response All responses to PayPal API operations contain information that may be useful for debugging purposes You should log the Correlation ID which identifies the API operation to PayPal and response specific information such as the transaction ID which you can use to review a transaction on the PayPal website or through the API You can log other information that may be useful such as the timestamp You could implement a scheme that logs the entire request and response in a verbose mode however you should never log the password from a request Responding to an NVP Response The Name Value Pair response consists of the answer to the request as well as common fields that identify the API operation and how it was executed The following diagram shows fields in the response to a PayPal NVP API operation Your Site I NVP Response ACK Success i a PayPal TIMESTAMP 2008 2d04 2 P ay Pal CORRELATIONID 63cdacOb VERSION 52 2e000000 BUILD 1 2e0006 Response specific fields Common Response Fields The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation A PayPal API response includes the following fields Field Description ACK Acknowledgement status which is one of the follow
96. l site and provide order details in the transaction history e Use the PayPal confirmation page as your Order Review page to further streamline the user experience when you do not need the benefits associated with paying on your site This strategy can lead to a better order completion rate also known as a conversion rate Configure the look and feel of PayPal pages to match the look and feel of your site by specifying the e Logo to display e Colors for the background and border e Language in which PayPal content is displayed You should include e Order details including shipping and tax during checkout IMPORTANT Not displaying this information is a major cause of shopping cart abandonment during checkout e Shipping information for non digital goods which can be your address information for the buyer or the address on file with PayPal if you use the address on file with PayPal you can specify whether or not it must be a confirmed address You can also activate additional features including e Associate a payment with an eBay auction item e Assign an invoice number to a payment e Accept payments with giropay Germany only Additional PayPal API Operations You can use PayPal API operations to include advanced processing and back office processes with Express Checkout You can e Capture payments associated with authorizations and orders e Process recurring payments e Issue refunds search transactions using various crite
97. lling on eBay you are required to perform this step preferably by setting L_EBAYITEMNUMBERn and L_EBAYITEMAUCTIONTXNIDn for the following reasons 56 May 2010 Express Checkout Integration Guide Customizing Express Checkout PayPal Review Page Order Details Buyer protection programs require it It enables buyers to see the transaction details in My eBay and in PayPal transaction details It enables buyers to redeem coupons and incentives they may have received from eBay NOTE Passing the same order details and eBay incentive parameters in the call to DoExpressCheckoutPayment as well as SetExpressCheckout ensures that this information displays on the PayPal Review page and payment is properly reflected in My eBay and in PayPal transaction details 3 It is recommended that you pass the string eBay item in L_DESCn and the eBay Item Number in 1 NUMBERn 4 If you host the final payment confirmation page on your website by setting useraction cont inue in the redirect you must show the discount amount resulting from eBay incentives on that page You can get the discount amount from the PAYPALADJUSTMENT value returned in the response to GetExpressCheckoutDetails NOTE eBay maintains detailed information about each item sold in eBay auctions If you set the value for SHIPPINGAMT in the call to SetExpressCheckout for example you do not need to be concerned about the shipping cost for individual item
98. m May 2010 nt2_item2 Description payment2_item2_desc Express Checkout Integration Guide Implementing Parallel Payments Integrating Parallel Payments Using the SOAP API payment2_item2 Name payment2_item2_name payment2_item2 Number payment2_item2_number payment2_item2 Quantity 1 e e e payment2_items_array SetValue payment2_iteml 0 payment2_items_array SetValue payment2_item2 1 n e n e bind the items payment2 PaymentDetailsItem payment2_items_array mandatory for api call nt2 PaymentRequestID System Guid NewGuid ToString paym set the totals decimal tax_total2 0 decimal item_total2 0 foreach PaymentDetailsItemType 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 paym paym paym ent2 ShippingTotal new BasicAmountType ent2 ShippingTotal currencyID CurrencyCodeType USD ent2 ShippingTotal Value 3 00 payment2 ItemTotal new BasicAmountType payment2 ItemTotal currencyID CurrencyCodeType USD payment2 ItemTotal Value item_total2 ToString e e e m payment2 TaxTotal new BasicAmount
99. mation 3 Chooses a payment option and provides billing and payment information 4 Reviews the order and pays 5 Receives an order confirmation In an Express Checkout flow a buyer still checks out at the beginning of the flow However the buyer does not enter shipping billing or payment information because PayPal provides the stored information This simplifies and expedites the checkout process Express Checkout Integration Guide May 2010 11 Introducing Express Checkout Express Checkout Integration Steps The following diagram shows the Express Checkout flow Express Checkout Flow Shopping Cat Stored Shipping amp Billing inte A Customer reviews Customer Views Customer views Ro enter cosereuytepey chipping and kiling order review page order confirrstion Customer pays with into then pays PayPal In the Express Checkout flow the buyer 1 Chooses Express Checkout by clicking Check out with PayPal 2 Logs into PayPal to authenticate his or her identity 3 Reviews the transaction on PayPal NOTE Optionally not shown in the diagram the buyer can then proceed to review the order on your site You can also include other checkout steps including upselling on your Review Order page 4 Confirms the order and pays from your site 5 Receives an order confirmation Express Checkout Integration Steps You can implement Express Checkout in 4 steps 1 Place PayPal checkout buttons and PayPal
100. ms To allow the buyer to check out just 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 EBAYITEMAUCTIONTXNID 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 May 2010 Express Checkout Integration Guide Immediate Payment Sonu Integrating Immediate Payment for Express Checkout Immediate Payment for Express Checkout has the following caveats e By design it does not support non instant funds like 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 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 ALLOWEDPAYMENTMETHOD to InstantPaymentOnLy 2 Optional You can call GetExpressCheckoutDetails to obtain information about the buyer 3 In the call to
101. n the call to SetExpressCheckout in the drop down menu on the PayPal Review page The PayPal Review page in the figure below shows 2 shipping options from which the buyer can choose if the callback times out An amount of 1 00 is offered for insurance Express Checkout Integration Guide May 2010 83 Implementing the Instant Update API Setting Up the Callback Example PayPal Review Page When Callback Times Out Your Website Review your information PayPal amp secure Payments ifthe information below is correct click Continue You will confirm your payment on he next page View PayPal policies and your payment source rights Description Und Price Quartty Amourt 10 Decaf Kona Blend Coffee 9 95 2 19 90 Rem 623083 Size 6 Boz Coffee Fier bags 39 70 2 79 40 Rem 523083 Size Two 24 piece boxes 6 tructions to marchar item total 99 30 Tax 2 59 Shipping and handling 8 00 UPS Nest Day Air 8 00 USD v UPS Ground 7 Days 3 50 USO 3 00 UPS Nest Day Air 9 00 USL i Insurance 1 00 Yes 1 00 USD Totak 107 89 USD Mier off certifi reward or discount Payment Method CredivDebit Card Visa 00000 0004 2477 Change Ship to J Smh 1 Main St San Jose CA 95131 United States Change Contact Information jsmithOt exarnple com 408 000 0000 Continue Cancel and return to your website PayPal The sater easier way to pay For more information read our User Agreement and Privacy Pobcy You Do Not Ship
102. nal 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 NOTE If ordertotal is not passed 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 No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma locale Type string Optional The five character locale code See Locale Codes Any other values default to US NOTE The merchant can participate in one campaign per country buttontype Type string Optional Indicates a dynamic image The values are e Default Check out with PayPal button image ecshortcut e PayPal Acceptance Mark image ecmark Locale Codes The table below lists the locale values 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 Express Checkout Integration Guide May 2010 23 24 Express Checkout Button and Logo Image Integration Dynamic Image Command Reference Couniry codes language priorities and locale values 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
103. ndbox paypal com cgi bin webscr cmd _express checkout amp token EC 1NK66318YB717835M NOTE The token in the command line is an HTTP request parameter and not the NVP field this parameter name must be lowercase You may need to replace hexadecimal codes with ASCII codes for example you may need to replace 2d in the token with a hyphen You must log in to https developer paypal com before you log in to a Sandbox test account You then log in to the test account that represents the buyer not the API_username business test account that represents you as the merchant 4 After logging into the buyer test account confirm the details When you confirm the Sandbox redirects your browser to the return URL you specified when invoking the SetExpressCheckout API operation as in the following example Express Checkout Integration Guide May 2010 45 a Testing an Express Checkout Integration http www YourReturnURL com token 5 Invoke a form on your site that calls the on the Sandbox E 1NK66318YB717835M amp PayerID 7AKUSARZ7SAT8 GetExpressCheckoutDetails API operation lt form method post action https api 3t sandbox paypal com nvp hidden hidden type hidden lt input lt input lt input name USI nam typ typ nam ER value API_username gt PWD value API_passwora gt SIGNATURI it value API_signature gt lt input lt input type hidden name TOK
104. ndbox paypal com nvp gt lt input type hidden name USER value API_username gt lt input type hidden name PWD value API_passwora gt lt input type hidden name SIGNATURE value API_signature gt lt input type hidden name VERSION value 52 0 gt lt input type hidden name PAYMENTACTION value Sale gt lt input name AMT value 19 95 gt lt input type hidden name RETURNURL value http www YourReturnURL com gt lt input type hidden name CANCELURL value http www YourCancelURL com gt lt input type submit name METHOD value SetExpressCheckout gt lt form gt NOTE The API username is a Sandbox business test account for which a signature exists See the Test Certificates tab of the Sandbox to obtain a signature If you are not using a signature you must use a different Sandbox server 2 Review the response string from the SetExpressCheckout API operation PayPal responds with a message such as the one shown below Note the status which should include ACK set to Success and a token that is used in subsequent steps TIMESTAMP 2007 2d04 2d05T23 3a23 3a07Z amp CORRELATIONID 63cdac0b67b50 amp ACK Success amp VERS ION 52 2e000000 amp BUILD 1 2e0006 amp TOKEN EC 2d1NK66318YB717835M 3 If the operation was successful use the token and redirect your browser to the Sandbox to log in as follows https www sa
105. ng mandatory for api call payment1 PaymentRequestID System Guid NewGuid ToString add the merchants to the array PaymentDetailsArray SetValue paymentl 0 J RRR RRR RRR KK KKK I KA I I I KARR KAA A II AK merchant 2 J RRR RRR RRR KK KKK I A A I I I KARA AAI II a aaa PaymentDetailsType payment2 new PaymentD payment2 PaymentAction PaymentActionCodel payment2 PaymentActionSpecified true payment2 SellerDetails new SellerDetailsi payment2 S ellerDetails PayPalAccountID items for payment2 Paym ew PaymentDetailsItemType 2 tailsType Type Order Type airline grupellc com ntDetailsItemType payment2_items_array Paym paym ntDetailsItemType payment2_iteml new PaymentDetailsItemType nt2_iteml Amount new BasicAmountType payment2_item Amount Value 1 00 Amount currencyID CurrencyCodeType USD payment2_item payment2_item payment2_item payment2_item Name payment2_iteml_name PPPRPRPPB Quantity 1 Description payment2_iteml_desc Te Ls Number payment2_iteml_number ntDetailsItemType payment2_item2 new PaymentDetailsItemType Paym paym nt2_item2 Amount new BasicAmountType paym paym nt2_item2 Amount Value 1 00 nt2_item2 Amount currencyID CurrencyCodeType USD e e e e e e n e e e payment2_item e e e e e e e e e pay
106. ng Parallel Payments Using the SOAP API anaa aaa 103 Handling EMOS 24 226 2 meee eee ee Pie eee de ee EA kG oe a a 108 Chapter 10 Handling Payment Settlements 109 Sale Payment Action for Express Checkout 0 000 a 109 Authorization Payment Action for Express Checkout 2 4 109 Order Payment Action for Express Checkout 2 0000002 peas 110 Chapter 11 Handling Recurring Payments 113 How Recurring Payments Work 2 2 2 2 aa a 113 Limitations siai ae ee A we a ee ae ee a a A 114 Recurring Payments Terms aoaaa aa 114 Options for Creating a Recurring Payments Profile 115 Specifying the Regular Payment Period 0 002 eee ee 115 Including an Optional Trial Period 2 2 2 0 200020022 116 Specifying an Initial Payment aoaaa a ee 116 Maximum Number of Failed Payments 000000 ee eee 117 Billing the Outstanding Amount 0 000 ee ee 117 Recurring Payments With Express Checkout 0000 eee ee 117 Initiating the Processing Flow With SetExpressCheckout 119 Redirecting the Buyer s Browser to PayPal 2 25000 120 Getting Buyer Details Using GetExpressCheckoutDetails 121 Creating the Profiles With CreateRecurringPaymentsProfile 121 Recurring Payments Profile Status oaoa ee 122 Getting Recurring Payments Profile Information 2 0
107. nt and optionally GetExpressCheckoutDetails e Setting Up the Express Checkout Transaction e Obtaining Express Checkout Transaction Details e Completing the Express Checkout Transaction Setting Up the Express Checkout Transaction To set up an Express Checkout transaction you must invoke the SetExpressCheckout API operation to provide sufficient information to initiate the payment flow and redirect to PayPal if the operation was successful This example assumes that you have set up the mechanism you will use to communicate with the PayPal server and have a PayPal business account with API credentials It also assumes that the payment action is a final sale When you set up an Express Checkout transaction you specify values in the SetExpressCheckout request and then call the API The values you specify control the PayPal page flow and the options available to you and your buyers You should start by setting up a standard Express Checkout transaction which can be modified to include additional options To set up the simplest standard Express Checkout transaction 1 Specify the amount of the transaction include the currency if it is not in US dollars Specify the total amount of the transaction if it is known otherwise specify the subtotal Regardless of the specified currency the format must have decimal point with exactly two digits to the right and an optional thousands separator to the left which must be a comma For exampl
108. ntegration Guide Customizing Express Checkout aa Handling Shipping Addresses Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https amp CANCELURL https amp AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale SNOSHIPPING 1 amp SHIPTOSTREET 1 Main St SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 408 967 4444 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P The figure below shows the PayPal review page when NOSHIPPING is set to 1 PayPal review page with shipping address suppressed WebsiteName com Review Your Information PayPal amp seour Payments Please review the information below If correct click Continue to complete your payment on the WebsiteName com website Learn more about PayPal policies and your payment source rights and remedies Payment Method Credit Card Visa XKXX XXXX XXXX 0084 Chanas Contact Information jsmithO1 example com Cancel and return to Websitellame com Express Checkout Integration Guide May 2010 71 o 6 Customizing Express Checkout Handling Shipping Addresses 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 r
109. o 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 just below the item description on the PayPal Review page 12 When the buyer clicks the Add special instructions to merchant link a text box opens as shown in Special Instructions text box After the buyer enters special instructions and clicks Express Checkout Integration Guide May 2010 51 52 Customizing Express Checkout PayPal Review Page Order Details Continue the instructions are returned in the responses to GetExpressCheckoutDetails and DoExpressCheckoutPayment Special Instructions text box Description 10 DecafKona Blend Coffee tem 623083 Sire Boz Coffee Filter bags tem 623033 Sire Two 24 plece boxes Add special instructions to merchant Payment Method Quantity Amort 2 990 2 79 40 item total 99 30 Tac 259 Shipping and handling 5 99 Shipping discount 3 00 insurance 1 00 Totat 105 87 USD Enter gift certficale reward or discount Credit Card Visa KOO OOK 000 1501 pearon Integrating Order Details into the Express Checkout Flow To integrate order details into the checkout flow pass the Express Checkout parameters described in SetExpressCheckout Order Details Parameters to SetExpressCheckout May 2010 Express Chec
110. 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 Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL https CANCELURL https amp amp AMT 10 00 amp CURRENCYCODE USD amp PAYMENTACTION Sale amp amp PAGESTYLE TestMerchant amp SHIPTOSTREET 1 Main St SHIPTOSTREET2 amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp SHIPTOPHONENUM 4 008 967 4444 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 option from the PayPal Profile tab In cases where you do not want to use the Profile option you can specify any of the individual page style characteristics e Header image e Header border color e Header background color e Page background color To define a header image such as your company logo 1 Create a header image up to 750 pixels wide by 90 pixels high
111. payment 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 If the value of this field is true you redirect the buyer from your Order Review page to https www paypal com webscr cmd _complete express checkout amp t oken lt value_from_SetExpressCheckoutResponse gt PayPal then redirects the buyer from this redirect page to the necessary page for the selected funding source GetExpressCheckoutDetails and DoExpressCheckoutPayment response field NVP Field Description REDIRECTREQUIRED Flag to indicate whether you need to redirect the buyer to back to PayPal The GetExpressCheckoutDetails response contains the REDIRECTREQUIRED field which lets you know if you need to redirect the user 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 Express Checkout Integration Guide May 2010 133 ae Integrating giropay with Express Checkout giropay Integration Complete the Transaction Corresponding to the three fields passed to SetExpressCheckout you must add the following three additional pages to your website Ad
112. payment mark images in your checkout flow 2 For each PayPal button that you place modify your page to handle the button click Use a PayPal Express Checkout API operation to set up the interaction with PayPal and redirect the browser to PayPal to initiate buyer approval for the payment 3 On your order confirmation page obtain the payment authorization from PayPal and use PayPal Express Checkout API operations to obtain the shipping address and accept the payment 4 Test your integration using the PayPal Sandbox before taking your pages live Because PayPal offers you the flexibility to control your checkout flow you should first understand how your current checkout flow works then become familiar with the Express Checkout flow Start by reviewing Express Checkout Flow For additional background information to help you get started see Express Checkout Building Blocks May 2010 Express Checkout Integration Guide Introducing Express Checkout oe Express Checkout Integration Steps Configuring and Customizing the Express Checkout Experience After you implement and test your basic Express Checkout integration you should configure the additional features of Express Checkout to customize it to meet your needs Carefully evaluate each feature because the more you streamline the checkout process and make Express Checkout seamless to buyers the more likely your sales will increase At a minimum you should e Set your logo on the PayPa
113. plementing the Instant Update API Setting Up the Callback Setting Up the Callback To set up the callback you 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 check the IP addresses requests against the list of IP addresses for paypal com as described in the go live checklist 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 For details on how to integrate line item details see Chapter 7 Customizing Express Checkout in the Express Checkout Integration Guide 2 Provide the URL to your callback server PayPal validates the URL as described above 3 Provide values for the flat rate shipping options For each option specify Option name L_SHIPP INGOPT IONNAMEn Option amount L_SHIPPINGOPTIONAMOUNTn
114. ponse details for that payment Pass the merchant s Payer Id secure merchant account Id or the merchant s email address in PAYMENTREQUEST_n_SELLERPAYPALACCOUNTID 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 PAYMENTINFO_n_PAYMENTREQUESTID value matching the PAYMENTREQUEST_n_PAYMENTREQUESTID value you passed in the DoExpressCheckoutPayment request Use this value to locate the response data for each payment e A PAYMENTINFO_nN_SELLERPAYPALACCOUNTID This value is whichever one of the following values was passed in The merchant s email address 100 May 2010 Express Checkout Integration Guide Implementing Parallel Payments E Integrating Parallel Payments Using the NVP API The merchant s Payer Id secure merchant account Id 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 Express Checkout Integration
115. press Checkout Transaction Details 02 004 39 Completing the Express Checkout Transaction 0 00002 39 Chapter 5 Testing an Express Checkout Integration 48 Chapter 6 Customizing Express Checkout 49 PayPal Review Page Order Details 2 aooaa a a 49 Special Instructions to Merchant 2 ee 51 Integrating Order Details into the Express Checkout Flow 52 eBay Issued Incentives 00 2 2 ee 55 Integrating eBay Incentives into the Express Checkout Flow 56 Providing GiftOptions aoa ac dog oani k a AAE ee 58 Getting Buyer Consent to Receive Promotional Email o aa aa 60 Providing Your Customer Service Number oaoa aa 60 4 May 2010 Express Checkout Integration Guide Contents Adding a Survey Question a aooaa 61 PayPal Page Style so asoca carac mas madana i aa a ea a aa 62 Custom Page Style sssr ssssiaris iasa ard ini kiska keka 62 Individual Page Style Characteristics o oao a 63 Changing the Locale o oo aa ee 66 Confirmed Address z aso risau aaaea ae a a aa aa 68 Suppressing the Buyer s Shipping Address aoa oaa a 0000000 70 Shipping Address Override ooa aaa ce 72 Automatically Filling Out the PayPal Login Page 0 4 73 Buyer PaysonPayPal 000 ee ee 75 Chapter 7 Implementing the Instant Update API 77 About the Instant Update API 2 200002 eee ee
116. rder Review Payment Merchant Redirects to PayPal be PayPal Server SetEC DoEC ALLOWED EBAYITEM PAYMENTMETHOD AUCTIONTXNID ALLOWEDPAYMENTMETHOD BUYERUSERNAME GetEC AYITEMCART t A i L_EBAYVITE IDn TOKEN optional pee He 7 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 92 May 2010 Express Checkout Integration Guide Immediate Payment aaa Integrating Immediate Payment for Third Party Checkout 2 In the call to the SetExpressCheckout API operation you must pass the following Immediate Payment information ALLOWEDPAYMENTMETHOD This is the payment method type For immediate payment the value is InstantPaymentOnly BUYERUSERNAME eBay provides you with this value L_EBAYITEMCARTIDn 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_EBAYITEMNUMBERn This is the eBay item number
117. ria and provide other back office operations Express Checkout Integration Guide May 2010 13 Introducing Express Checkout Express Checkout Flow a D gt gt D am aE i gt Express Checkout Flow To implement Express Checkout you must offer it both as a checkout option and as a payment method Typically you initiate the Express Checkout flow on your shopping cart page and on your payment options page You add Express Checkout to your existing flow by placing the Checkout with PayPal button on your Shopping Cart page and by placing the PayPal mark on your Payment Methods page The following diagram shows the complete flow Complete Express Checkout flow a e ee a gt a a Create PayPal Login PayPal Review tt shipping address checkout 3 e a i M a V Confirmation Add To Cart Collect Shipping Merchant Review Confirmation Sma PayPal Address peyrw VISA The astet caster way to pay Shopping Cart Payment Methods Make the following changes to implement the complete Express Checkout flow e On your Shopping Cart page place the Checkout with PayPal button and respond to a click by setting up the Express Checkout request and redirecting your buyer s browser to PayPal e On your Payment Methods page associate the PayPal mark with an option Handle selection of the PayPal mark by setting up the Express Checkout request and redirecting your buyer s browser to PayPal e On the page your buyer r
118. ribes events supporting the callback 1 The Express Checkout flow is initiated on your shopping cart page when the buyer clicks the Checkout with PayPal button 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 receive a token in the response 80 May 2010 Express Checkout Integration Guide Implementing the Instant Update API Following Instant Update API Best Practices 4 The buyer is redirected to PayPal 5 When the buyer first logs in to the PayPal site PayPal obtains the buyer s shipping address and sends it in the callback request red down arrow to your callback server at the specified URL NOTE If the buyer changes their shipping address on the PayPal Review page PayPal will make subsequent calls to the callback request 6 You respond to the callback red up arrow with the shipping option rates 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 Review Page 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
119. s 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 will be two months If the billing period is Week and the billing frequency is 6 the payments will be scheduled 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 a trial period is specified for the profile 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 114 May 2010 Express Checkout Integration Guide Handling Recurring Payments mE Options for Creating a Recurring Payments Profile Term Definition Payment amount The amount to be paid by the buyer for each billing cycle Outstanding balance If a payment fails for any reason that amount is added to the profile s outstanding balance Profile ID An alphanumeric string generated by PayPal that uniquely identifies a recurring 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 paymen
120. s eBay calculates incentives based on its database not from the values you pass in the SetExpressCheckout call The following SetExpressCheckout request example passes order details and eBay incentives for two eBay auction items Express Checkout Integration Guide May 2010 57 58 Customizing Express Checkout Providing Gift Options Request Parameters requiredSecurityParameters E THOD SetExpressCheckout RETURNURL http coffee2go com CANCELURL http cancel com PAYMENTACTION Sale EMATL jsmith01 example com NAME J Smith amp SHIPTOSTREET 1 Main St amp SHIPTOCITY San Jose amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHIPTOZIP 95131 amp L_NAMEO0 Photo amp L_NUMBERO 32768923 amp L_DESCO Plastic Frame An EBay item amp L_AMT0 25 00 amp L_QTYO 1 amp L_EBAYITEMNUMBERO 32768 923 amp L_EBAYITEMAUCTIONTXNIDO0 0 amp L_NAME1 Nokia ND amp L_NUMBER1 32768924 amp L_DESC1 Nokia Mobile An EBay item amp L_AMT1 25 00 amp L_QTY1 1 amp L_EBAYITEMNUMBER1 32768924 amp L_EBAYITEMAUCTIONTXNID1 7225687004 amp CHANNELTYPE eBayItem amp ITEMAMT 50 00 amp SHIPPINGAMT 3 00 amp HANDLINGAMT 3 00 amp AMT 56 00 amp CURRENCYCODE USD amp ALLOWNOTE 1 Response Parameters successResponseFields amp TOKEN EC 2HX34015EC629990M Providing Gift Options
121. s of an API username along with an associated API password and signature all of which are assigned by PayPal You need to include this information whenever you execute a PayPal API operation You must have a PayPal Business account to create a signature To create an API signature 1 Log into PayPal then click Profile under My Account 2 Click API Access 3 Click Request API Credentials 4 Check Request API signature and click Agree and Submit 30 May 2010 Express Checkout Integration Guide PayPal Name Value Pair API Basics oe Creating an NVP Request Log Out Help Security Center PayPal My Account Send Money Request Money Merchant Services Auction Tools Products and Services View or Remove API Signature Back to profile For preconfigured shopping carts Copy and paste the API username password and signature into your shopping cart configuration or administration screen For building custom shopping carts Store the following credential information in a secure location with limited access Credential API Signature API Username dangarcia_api1 paypal com API Password TQJQTNEXUBMNKCH6 Signature AFcWxV21C7fd0v3bYYYRCPSSRI31ACUgV1hSSbCaoz crGvgPCTDjuhW RequestDate Mar 15 2010 14 20 28 PDT Done Remove About Us Contact Us Fees Legal Agreements Privacy Site Feedback 999 2010 PayPal All rigths reserve 5 Click Done to complete the process Creating an API Certificate Create an API certifi
122. sResponseFields amp TOKEN EC 17C76533PL706495P The figure below shows how the survey question appears to the buyer on the PayPal Review page How did you hear about us Optional Select iv NOTE You can also configure this feature through the PayPal Profile page For details see the Merchant Setup and Administration Guide PayPal Page Style You can change the overall appearance of the PayPal review page by defining a custom page style or by customizing individual page style characteristics You define a custom page style in the PayPal Profile and then pass the resulting page style name in the call to SetExpressCheckout Typically you customize individual page style characteristics in the PayPal Profile as well However you can also call SetExpressCheckout and pass in individual page characteristics dynamically Custom Page Style When your buyer logs into 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 Up to three unique Page Style Names can be defined in your account You can specify the following items e Header image e Header border color May 2010 Express Checkout Integration Guide Customizing Express Checkout aa PayPal Page Style e Header background color e Page background color For instructions on how to customize
123. se the AUTOBILLOUTAMT field in the CreateRecurringPayment sProfile request to specify whether or not the outstanding amount should be added 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 that amount at any time Recurring Payments With Express Checkout During the Express 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 Integration Guide May 2010 117 Smt Handling Recurring Payments Recurring Payments With Express Checkout Legend m Web Flow API Call Token A Profile ID Merchant website A Request Shopping Cart SetExpressCheckout PayPal API 2 Server Response Token 3 PayPal Login amp LL HTTP Redirect gt 4 HTTP Redirect m E 5 Request Token PayPal GetExpressCheckoutDetails API Server 4 Response Customer Details 6 Request Final Transaction Details DoExpressCheckoutPayment 4 Response Transaction Results Payment lt _ Created 3 Request Final Transaction Details Recurring PayPal API Server CreateRecurringPaymentsProfile ee J Response Transa
124. seFields amp TOKEN EC 6UA07551EA393551U The figure below shows the PayPal review page when REQCONFIRMSHIPPING is set to 1 Express Checkout Integration Guide May 2010 69 70 Customizing Express Checkout Handling Shipping Addresses PayPal review page with a required address WebsiteName com Review Your Information PayPal Secue Payments Please review the information below If correct click Continue to complete your peyment on the WebsiteName com website Learn more about PayPal policies and your payment source rights and remedies Payment Method Credit Card Vise XXXX XXXX XXXX 0084 Change Shipping Address 1 Main Street San Jose CA 95131 United States c Contact Information jsmith example com Cancel and retum to WebsiteName com 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 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 NOSHIPP ING parameter to 1 in the call to SetExpressCheckout No shipping address displays on the PayPal pages whatsoever The following example suppresses the shipping address May 2010 Express Checkout I
125. ss Checkout API requests that change the appearance behavior and flow of the checkout process e PayPal Review Page Order Details e Providing Gift Options e Getting Buyer Consent to Receive Promotional Email e Providing Your Customer Service Number e Adding a Survey Question e PayPal Page Style e Changing the Locale e Handling Shipping Addresses e Automatically Filling Out the PayPal Login Page e Buyer Pays on PayPal PayPal Review Page Order Details NOTE PayPal Review Page order details are available with API version 53 0 or later The DoExpressCheckoutPayment request includes the same order details as SetExpressCheckout It is strongly recommended that you submit the same parameters in both API calls When a buyer logs into PayPal to check out you can present the buyer with detailed information about each item in the shopping cart see PayPal Review page with 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 Knowing the size helps the buyer decide whether the one they selected was appropriate If the item is an
126. ss Checkout from the Payment Method page ee EE Create a F PayPal Login PayPal Review y 7 mees a fl Checkout gt gt Confirmation Add To Can Collect Shipping Merchant Review Confirmation Sma PayPal address Peyrer VISA The assist caster way to pay Shopping Cart Payment Methods Purchase Express Checkout Building Blocks You implement Express Checkout flows with Express Checkout buttons PayPal API operations PayPal commands and tokens Express Checkout Integration Guide May 2010 15 a Introducing Express Checkout Express Checkout Building Blocks The following conceptual diagram identifies the building blocks that you use to integrate Express Checkout on your website Express Checkout Integration Caleits PayPal Flow hed Poyrel Woekoito PayPal redirects customer to TR Your Webste merchant site Add PayPal Checkout button Call GetExpressCheckoutDetails API f M Shopping Cat Stored Shipping Receipt Contimation amp Billing info ad Pay a ay Chee Customer reviews Customer views Customer vieves Pe aaie sear wey me pey ctigping and kiling order review page order confirmation Custome pays wth info then pays PayPal Call SetExpressCheckout API Call DoExpressCheckoutPayment API Redirect customer to PayPal A token is a value assigned by PayPal that associates the execution of API operations and commands with a specific instance of a user exp
127. ssing 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 ten recurring payments or a mixture of a one time purchase and recurring payments Express Checkout Integration Guide May 2010 119 tt Handling Recurring Payments Recurring Payments With Express Checkout 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 SetCustomerBillingAgreement 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 and confirm the amount in the Dol ExpressCheckoutPayment 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 NOTE Tocreate a billing agreement without purchase use Version 54 0 or higher of the To PayPal API set up one or more billing agreements for recurring payments modify the SetExpressCheckout request as follows 1 Add an L_BILLINGTYPEn 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 Recurrin
128. standing balance May 2010 Express Checkout Integration Guide Handling Recurring Payments mE Modifying a Recurring Payments Profile 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 only modify 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 NOTE You cannot modify the billing frequency or billing period of a profile You can modify the number of billing cycles in the profile NOTE For recurring payments with Express Checkout certain updates such as billing amount are not allowed within 3 days of the scheduled billing date and an error is returned You can modify the following profile information during the trial period or regular payment period e Billing amount e Number of billing cycles The profile changes take effect with the next payment after the call to update the profile Say for example the
129. t call 1 Set ALLOWEDPAYMENTMETHODTYPE to InstantPaymentoOnly This blocks all pending funding sources and transactions that end up in a pending state Pass BUYERUSERNAME and L_EBAYITEMCARTIDn Set CHANNELTYPE to eBayItem 2 3 4 5 6 Set L_EBAYITEMNUMBERn to the number of the eBay item Specify the buyer s shipping address 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 a buyer may have a mixed cart of eBay and non eBay items To allow the buyer to check out just the non Immediate Payment items 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 ALLOWEDPAYMENTMETHODTYPE to InstantPaymentoOnly This blocks all pending funding sources and transactions that end up in a pending state Pass the L_EBAYITEMCARTIDn 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 Say for example you determine that the buyer has a mixed cart of eBay and non eBay ite
130. ter describing the Instant Update Callback API 03 03 2009 Updated to allow useraction continue 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 06 30 2008 Complete revision 10 May 2010 Express Checkout Integration Guide Introducing Express Checkout Express Checkout is PayPal s premier checkout solution which streamlines the checkout process for buyers and keeps them on the merchant s site after making a purchase e The Express Checkout Experience e Express Checkout Integration Steps e Express Checkout Flow e Express Checkout Building Blocks NOTE For information about administrative tasks you can perform from your PayPal account such as adding users setting up custom page styles and managing multiple currency balances see the Merchant Setup and Administration Guide The Express Checkout Experience Express Checkout makes it easier for a buyers to pay online It also enables you to accept PayPal while retaining control of the buyer and the overall checkout flow Consider your buyers experience before implementing Express Checkout A generic flow probably has the following sequence of pages A generic checkout flow Shopping Cart Collect Shipping addresses Confirmation In a typical checkout flow a buyer 1 Checks out from the shopping cart page 2 Provides shipping infor
131. ter 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 It is all handled for you when you set up the dynamic image 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 will return 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 you provide the name value pair parameter information in the image URL You can pass information in the image URL for any of the following options e Set Up the Default Image e Set Up Image for Dynamic Use e Change the Locale e Feedback to Buyer Meeting an Incentive e Choose the Image May 2010 Express Checkout Integration Guide Express Checkout Button and Logo Image Integration Poe 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
132. 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 84 May 2010 Express Checkout Integration Guide 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 ETHOD CallbackResponse NO_SHIPPING_OPTION_DETAILS 1 The figure below illustrates the PayPal Review page when your callback servers sends the above response The page has these features e A message at the top of the page describes the error e The shipping and handling section and the insurance section are dimmed e The buyer can change the shipping address e Anew callback request is sent if the buyer changes the shipping address Example PayPal Review Page When You Do Not Ship to the Buyer s Address Review your payment PayPal A Friends n Stitches Needlework doesnot ship to this location Please use a different address Ifthe information below is correct click Pay Now to complete your payment View PayPal policies and your payment source rights Descri pt ion Unit Price Quantil Iterm1_with_S amp H1 Details 3 00 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
133. ts 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 for activation BILLINGPERIOD ScheduleDetails The unit of measure for the billing cycle PaymentPeriod BillingPeriod Must be one of e Day e Week e SemiMonth e Month e Year BILLINGFREQUENCY ScheduleDetails Number of billing periods that make up PaymentPeriod BillingFreque one billing cycle ncy NOTE The combination of 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 Express Checkout Integration Guide May 2010 115 Sot Handling Recurring Payments Options for Creating a Recurring Payments Profile NVP SOAP Description 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 no value is specified or if the value is 0 the payments
134. u can allow the buyer to send you special instructions about the order in a text box that appears when the buyer clicks this link 50 May 2010 Express Checkout Integration Guide Customizing Express Checkout aa PayPal Review Page Order Details PayPal Review page with order details Your Website Review your information PayPal amp serie Paywents Ethe information below is correct click Cominue You will confum your payment on the next page View PayPal policies and your payment source righis Description Unt Price 2 Quantty Amort H i 10 Decaf Kona Blend Cofee eri 9 95 2 2 19 ID eve Bern F 623083 vorerecenscnvcemtovesueses ace neesuses g H Are BOT cecasasatcnsnsaransnsassnsara esp 3 Coffee Filter Bags 39 70 2 79 40 a O tem 2 623034 Sre Two 24 piece boxes pm E di special instructons to merchant Item total 99 30 ei Sales tax 2 58 ered Shipping and handing 5 99 pasis Shipping discount 3 00 esesesers Insurance 1 00 oon 4 heans Total 105 87 usb x f te et Payment Method CreditDebs Card Visa O0O HOO O 0084 PayPal Plus Credit Card No payments for 3 months __ApolyNow Learn more Change Ship to Jane Smith 1 Main Street San Jose CA 95171 Uniled States Change Coritact Infornation jsmith example com Special Instructions to Merchant You can allow the buyer to send you special instructions about an order This feature is especially helpful to buyers who want t
135. ue 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 Express Checkout Integration Guide May 2010 105 106 Implementing Parallel Payments Integrating Parallel Payments Using the SOAP API if Key Amount null item_total decimal Add item_total decimal Multiply decimal Parse Key Amount Value decimal Parse Key Quantity payment1 ShippingTotal new BasicAmountType payment1 ShippingTotal currencyID CurrencyCodeType USD payment1 ShippingTotal Value 3 00 payment1 ItemTotal new BasicAmountType paymentl 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 ToStri
136. vior by setting the FAILEDINITAMTACTION field to Cont inueOnFailure which indicates that if the initial payment amount fails PayPal should add the failed payment amount to the outstanding balance due on this recurring payment profile 116 May 2010 Express Checkout Integration Guide Handling Recurring Payments me Recurring Payments With Express Checkout If this field is not set or is set to CancelOnFailure PayPal will create the recurring payment profile but will place it into a pending status until the initial payment is completed If the initial payment clears PayPal will notify you by IPN that the pending profile has been activated If the payment fails PayPal will notify you by IPN that the pending profile has been canceled The buyer will receive an email stating that the initial payment cleared or that the pending profile has been canceled if the profile was created using Express Checkout Maximum Number of Failed Payments By including the MAXFAITLEDPAYMENTS field in the CreateRecurringPaymentsProfile request you set the number of failed payments allowed before the profile is automatically suspended You receive an IPN message when the number of failed payments reaches the maximum number specified Billing the Outstanding Amount If a payment fails due to any reason the amount that was to be billed including shipping and tax if applicable is added to the profile s outstanding balance U
137. xample com 408 555 5948 Change Cancel and return to Y ebsitteName com Buyer Pays on PayPal If you do not require the buyer to explicitly review and confirm the payment on your site you can configure Express Checkout such that the user commits the payment on PayPal This configuration reduces a step in the checkout flow You may want to eliminate your Review Your Payment page if there is no additional information you want to collect from the buyer before he or she completes the transaction It is recommended that you collect the information after the buyer completes the purchase You should evaluate each Express Checkout flow separately through the cart page and through the payment methods page In most checkout flow implementations the payment methods page is the last page the buyer sees before committing to a transaction If this is true in your implementation you can use this feature to streamline the buyer experience The feature informs the buyer that they are committing to the transaction if they proceed To invoke this feature use the useract ion variable in the SetExpressCheckout call Setting useraction to commit sets the button text on the PayPal Payment Review page to Express Checkout Integration Guide May 2010 75 76 Customizing Express Checkout Buyer Pays on PayPal read Pay Now After the buyer returns from the PayPal site you must call DoExpressCheckoutPayment to actually complete the transaction To displ
138. yPal receives the funds at which time the transaction will be complete If you have disabled non instant funding transactions for your PayPal account the transaction is cancelled and PayPal redirects the buyer to your Order Cancel page After the bank transfer flow is completed the transaction is pending until the buyer pushes the funds to PayPal If the buyer cancels during the PayPal payment via bank transfer flow your Order Cancel page is displayed 132 May 2010 Express Checkout Integration Guide Integrating giropay with Express Checkout e giropay Integration giropay Integration If you offer the giropay payment option you must take additional steps to integrate with the Express Checkout flow Initiate the Flow with SetExpressCheckout To support giropay payments you pass the following three URLs as part of the SetExpressCheckout request 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 SetExpressCheckout request fields for giropay 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
139. yment actions e Sale Payment Action for Express Checkout e Authorization Payment Action for Express Checkout e Order Payment Action for Express Checkout Sale Payment Action for Express Checkout A sale payment action represents a single payment that completes a purchase for a specified amount A sale is the default Express Checkout payment action however you can also specify the following action in your SetExpressCheckout and DoExpressCheckoutPayment requests PAYMENTACTION Sale A sale is the most straightforward payment action Choose this payment action if the transaction including shipping of goods can be completed immediately To use this payment action e The final amount of the payment must be known when you invoke the DoExpressCheckoutPayment API operation e You should intend to fulfill the order immediately such as would be the case for digital goods or for items you have in stock for immediate shipment After you execute the DoExpressCheckoutPayment API operation the payment is complete and further action is unnecessary You cannot capture a further payment or void any part of the payment when you use this payment action Authorization Payment Action for Express Checkout An authorization payment action represents an agreement to pay and places the buyer s funds on hold for up to three days To set up an authorization specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPaym
140. your confirmation page you must call CreateRecurringPaymentsProfile to create the profile If you are creating multiple recurring payments profiles you must call CreateRecurringPaymentsProfile once for each profile to be created If the transaction includes a mixture of a one time purchase and recurring payments profiles call DoExpressCheckoutPayment to complete the one time purchase transaction and then call CreateRecurringPayment sProfile for each recurring payment profile to be created IMPORTANT The recurring payments profile is not created until you receive a success response from the CreateRecurringPaymentsProfile call The CreateRecurringPayment sProfile response contains a Profile ID which is an encoded string that uniquely identifies the recurring payments profile Express Checkout Integration Guide May 2010 121 122 Handling Recurring Payments Recurring Payments Profile Status 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 e SuspendedProfile e CancelledProfile If the profile is successfully created it has an ActiveProfile status However if a non recurring initial payment fails and FATLEDINITAMTACTION is set to CancelOnFailure in the CreateRecurringPaymentsProfile request the profile is created wit

PayPal Express Checkout - 2010 Integration Guide

Contents

Download Pdf Manuals

Related Search

Related Contents