PayPal Digital Goods - 2012 - EC Edition Integration Guide
Contents
1. e L_PAYMENTREQUEST_n_ITEMCATEGORYM NVP GetExpressCheckoutDetails Response Fields e TOKEN e INVNUM e PHONENUM e NOTE e REDIRECTREQUIRED e CHECKOUTSTATUS Digital Goods Integration Guide EC Edition January 2012 55 Express Checkout API Fields Supported By Digital Goods Express Checkout NVP API Fields Supported By Digital Goods DoExpressCheckoutPayment NVP Request Fields DoExpressCheckoutPayment Request Fields e METHOD Must be set to DOExpressCheckoutPayment e TOKEN e RETURNURL e CANCELURL e NOSHIPPING e ALLOWNOTE e LOCALECODE Payment Details Type Fields e PAYMENTREQUEST_n_AMT e PAYMENTREQUEST_n_CURRENCYCODE e PAYMENTREQUEST_n_ITEMAMT e PAYMENTREQUEST_n_TAXAMT e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_INVNUM e PAYMENTREQUEST_n_NOTIFYURL e PAYMENTREQUEST_n_PAYMENTACTION e PAYMENTREQUEST_n_PAYMENTREQUESTID Payment Details Item Type Fields e PAYMENTREQUEST_n_NAMEM e PAYMENTREQUEST_n_DESCm e PAYMENTREQUEST_n_AMTm e PAYMENTREQUEST_n_NUMBERm e PAYMENTREQUEST_n_QTYm e PAYMENTREQUEST_n_TAXAMTm e PAYMENTREQUEST_n_ITEMCATEGORYM DoExpressCheckoutPayment NVP Response Fields DoExpressCheckoutPayment Response Fields e TOKEN e NOTE s REDIRECTREQUIRED 56 January 2012 Digital Goods Integration Guide EC Edition Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods Payment Details Type Fields e2. Handle error cases success function response Replace content on page initiate download etc f lt script gt lt head gt lt body gt lt Include non JavaScript content here gt If this page does not redirect lt a href page to deliver content to non JS customer gt Click Here lt a gt lt body gt lt html gt Digital Goods Integration Guide EC Edition January 2012 27 im Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout JavaScript Functions For Digital Goods Payments Include dg js on any page that invokes or terminates the digital goods payments flow The JavaScript functions in dg js set up and control the PayPal lightbox and mini browser Function and Signature Description PAYPAL apps DGFlow function Sets up the digital goods payment flow trigger Set the experience type variable expType to HTML_id_of_event_triggering_flow e instant DG flow in lightbox with overlay mask expType experience_type e mini DG flow in mini browser with overlay mask e popup DG flow in mini browser Leave expType unset for the legacy DG flow setTrigger function id Adds a trigger for the flow where idis the HTML ID of the event that triggers the flow The flow must first be set up by calling PAYPAL apps DGF low startFlow function url Explicitly starts the digital goods flow where ur1 is the URL that t
3. How Recurring Payments Work To view a video that demonstrates how to set up Recurring Payments navigate to Recurring Payments Demo When you support recurring payments for a buyer you create a recurring payments profile The profile contains information about the recurring payments including details for an optional trial period and a regular payment period Both periods contain information about the payment frequency and payment amounts including shipping and tax if applicable After creating a profile PayPal automatically queues payments based on the billing start date billing frequency and billing amount Payments reoccur until the profile expires there are too many failed payments to continue or you cancel the profile NOTE When using Express Checkout the buyer can also cancel a recurring payments profile PayPal funds queued payments using the normal payment method hierarchy within the buyer s PayPal account After creating a recurring payments profile you can view profile details or cancel the profile from your PayPal account You can also access recurring payments reports from the PayPal Business Overview page Also after creating a recurring payments profile you can use the Recurring Payments API to do the following e Get information details about a recurring payments profile Digital Goods Integration Guide EC Edition January 2012 33 az Handling Recurring Payments Recurring Payments Terms e Change t
4. 1 Create the Flash movie game swf with the following code The code assumes the button click on dg_button initiates payment create local connection var conn LocalConnection conn new LocalConnection allow cross domain connection conn allowDomain identify this movie as the receiver i e client conn client this dg_button addEventListener MouseEvent MOUSE_UP function evt MouseEvent void following URL will begin the DG API call var payment_URL String lt Merchant URL to initiate API call gt following JS opens a new window to the appropriate size for DG checkout var jscommand String window open payment_URL win height 550 width 400 toolbar no scrollbars no var url URLRequest new URLRequest javascript jscommand void 0 navigateToURL url _self initiate listening on connection conn connect paymentConn H function paymentComplete responseText void use responseText to do any customizations close the LocalConnection conn close 2 Specify another Flash movie return swf as the return URL in the API call 3 Use FlashVars or ExternallInterface in return swf to gather any required values from the API response 4 Use the LocalConnection from step 1 in return swf to communicate with game swf for example var sendingLC LocalConnection new LocalCo
5. e PAYMENTREQUEST_n_NUMBERM e PAYMENTREQUEST_n_QTYm e PAYMENTREQUEST_n_TAXAMTm e PAYMENTREQUEST_n_ITEMCATEGORYm SetExpressCheckout NVP Response Fields SetExpressCheckout Response Fields e TOKEN GetExpressCheckoutDetails NVP Request Fields GetExpressCheckoutDetails Request Fields s METHOD Must be set to GetExpressCheckoutDetails e TOKEN GetExpressCheckoutDetails NVP Response Fields GetExpressCheckoutDetails Response Fields e TOKEN e INVNUM e PHONENUM e NOTE e REDIRECTREQUIRED e CHECKOUTSTATUS Payer Information Fields e EMAIL e PAYERID e PAYERSTATUS e COUNTRYCODE e BUSINESS 54 January 2012 Digital Goods Integration Guide EC Edition Express Checkout API Fields Supported By Digital Goods Express Checkout NVP API Fields Supported By Digital Goods Payer Name Fields e SALUTATION e FIRSTNAME e MIDDLENAME e LASTNAME e SUFFIX Payment Details Type Fields e PAYMENTREQUEST_n_AMT e PAYMENTREQUEST_n_CURRENCYCODE e PAYMENTREQUEST_n_ITEMAMT e PAYMENTREQUEST_n_TAXAMT e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_INVNUM e PAYMENTREQUEST_n_NOTIFYURL e PAYMENTREQUEST_n_TRANSACTIONID e PAYMENTREQUEST_n_PAYMENTREQUESTID Payment Details Item Type Fields e L_PAYMENTREQUEST_n_NAMEm e L_PAYMENTREQUEST_n_DESCMm e L_PAYMENTREQUEST_n_AMTm e L_PAYMENTREQUEST_n_NUMBERM e L PAYMENTREQUEST_n_OTYm e L_PAYMENTREQUEST_n_TAXAMTm
6. L_PAYMENTREQUEST_0O_QTYO 1 amp L_PAYMENTREQUEST_0O_OQTY1 1 amp L_PAYMENTREQUEST_0O_AMT0O 100 amp L_PAYMENTREQUEST_0O_AMT1 100 Response Parameters successResponseFields amp TOKEN EC 17C76533PL706494P Redirecting the Buyer to PayPal To redirect your buyer to the PayPal digital goods payments flow specify this URL along with the token returned by the SetExpressCheckout API operation https www paypal com incontext token TOKENReturned 24 January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout After the buyer approves the payment or cancels PayPal redirects back to the return or cancel URL e Return URL TIf the buyer approves the payment PayPal redirects to the return URL with the token you passed in the redirect to PayPal and the buyer s unique identifier Payer ID s Cancel URL TIf the buyer cancels PayPal redirects to the cancel URL with the token that you passed in the redirect to PayPal After PayPal Redirects the Buyer To Your Web Page The actions you take after PayPal redirects the buyer back to your web page depend upon whether the buyer approves or cancels the order If the buyer approves the order and pays for the digital goods do the following 1 Optionally call the GetExpressCheckoutDetails API operation to obtain details abou
7. 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 38 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Recurring Payments With the Express Checkout API Legend Web Hew gt APicall Token es Profile ID Merchant Site PayPal Payment Pages PayPal Servers z GY Request lt k Ao Response Token sees API Server F Add JavaScript to create iframe Ran 8 HTTP Redirect lil HTTP Redirect Retum URL Cancel URL De Request 8 gt Response Customer Details PayPal Request Final Transaction Details fe API Server L pre ieckoutPayment lt m Response Transaction Results Request Final Transaction Details E den 7 Response Transaction Results Load Content Download Purchase Confirmation The circled numbers in the diagram correspond to the numbered steps in the following table NOTE For digital goods you must use API version 65 1 or greater Digital Goods Integration Guide EC Edition January 2012 39 az Handling Recurring Payments Recurring Payments With the Express Checkout API Recurring payments processing flow Step Merchant PayPal 1 Adds JavaScript to your webpage to create the PayPal digital goods payments flow which appears in a lightbox over
8. paypal com incontext token TOKENReturnedsuseraction com mit 4 Specify the cancel URL The cancel URL is the page to which PayPal redirects your buyer 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 the PayPal digital goods payments flow 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 5 If you pass a value for PAYMENTREQUEST_O_PAYMENTACTION you must pass the value Sale default 6 Set PAYMENTREQUEST_0O_ITEMAMT to the total of all items in the order 7 Pass values for the following parameters for each item the buyer is purchasing L_PAYMENTREQUEST_O NAMEN L_PAYMENTREQUEST_O_AMTnN L_PAYMENTREQUEST_O_OTYN L_PAYMENTREQUEST_0_ITEMCATEGORYn you must set the value to Digital NOTE Make sure L_PAYMENTREQUEST_0O_ITEMCATEGORY is set to Digital for every item in the DoExpressCheckoutPayment request as well as SetExpressCheckout Failing to do so will result in incorrect fee calculations 8 Set REQCONFIRMSHIPPING to 0 9 Set NOSHIPPING to 1 Digital Goods Integration Guide EC Edition January 2012 23 im Integrating Digital Goods
9. the number of billing periods that make up the billing cycle For example if the billing period is Month and the billing frequency is 2 the billing cycle is 2 months If the billing period is Week and the billing frequency is 6 PayPal schedules the payments every 6 weeks Regular payment period The main subscription period for this profile which defines a payment amount for each billing cycle The regular payment period begins after the trial period if you specify a trial period for the profile 34 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Options for Creating a Recurring Payments Profile Term Definition Trial period An optional subscription period before the regular payment period begins A trial period may not have the same billing cycles and payment amounts as the regular payment period Payment amount The amount the buyer pays for each billing cycle Outstanding balance If a payment fails for any reason PayPal adds that amount to the profile s outstanding balance Profile ID An alphanumeric string generated by PayPal that uniquely identifies a recurring profile You can specify the Profile ID in the Transact ionSearch API operation to obtain all payments associated with the identified profile 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 initia
10. value_returned_by_SetExpressCheckoutResponse gt When redirecting the buyer to PayPal PayPal recommends that you use the HTTPS response 302 Object Moved with the URL as the value of the Location header in the HTTPS response Make sure that you use an SSL enabled server to prevent browser warnings about a mix of secure and insecure graphics 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 GetExpressCheckout Details request has one required parameter TOKEN which is the value returned in the SetExpressCheckout response PayPal does not return the values you specified for the following parameter fields in the GetExpressCheckoutDet ails response unless the transaction includes a purchase PayPal ignores the fields if you set up a billing agreement for a recurring payment that is not immediately charged e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_CUSTOM e PAYMENTREQUEST_n_INVNUM Creating the Profiles With CreateRecurringPaymentsProfile After your buyer has agreed to the recurring payments billing agreement on your confirmation page you must call CreateRecurringPaymentsProfile to create the profile If you are cre
11. Details Setting Up A Digital Goods Payment Transaction To set up a digital goods payment transaction call the SetExpressCheckout API request operation Provide sufficient information to initiate and redirect the buyer to the digital goods payment flow This example assumes that you have set up the mechanism to communicate with the PayPal server and you have a PayPal Business account with API credentials It also assumes that the payment action is a final sale NOTE Use API version 65 1 or greater for all API calls for digital goods payments To set up a transaction you specify values in the SetExpressCheckout request and then call the API The values you specify control the options available to you and the buyer NOTE Inthe call to SetExpressCheckout you are required to pass values for each digital goods item the buyer is purchasing and to set the item category field to Digital For details on these parameters see step 7 in the setup procedure that follows To obtain the discount rate for digital goods you also must pass these parameters and values in the call to DoExpressCheckoutPayment To set up the transaction 1 Pass the total amount of the payment as the value of PAYM the currency if it is not in US dollars For example PAYMENTREQUEST_0_AMT amount PAYMENTREQUEST_0_CURRENCYCODE currency D ENTREQUEST_0O_AMT include Specify the total amount of the transaction
12. Express Checkout API Step Merchant PayPal 10 Adds JavaScript to close the lightbox Digital Goods only 11 Fulfills the buyer s order and displays a successful transaction page Initiating the Processing Flow With SetExpressCheckout As in the Express Checkout flow the SetExpressCheckout request notifies PayPal that you are s Initiating an order that can be either a one time purchase up to 10 recurring payments or a mixture of a one time purchase and recurring payments e Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one time purchase or recurring payment NOTE You can also initiate the processing flow using 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 You confirm the amount in the DoExpressCheckoutPayment request If however you set the amount of the payment to 0 in the SetExpressCheckout request you can create a billing agreement without initiating a payment NOTE Tocreate a billing agreement without purchase use Version 54 0 or higher of the PayPal API To set up one or more billing agreements for recurring payments modify the SetExpressCheckout request as follows 1 Add an L_BILLINGTYPEn field for each billing agreement you want to create n is a
13. HOD CreateRecurringPaymentsProfile TOKEN EC 13W99099UU817504D amp PROFILESTARTDATE 20XX 03 05T03 00 00 amp DESC Movie clips amp BILLINGPERIOD Month amp BILLINGFREQUENCY 12 amp AMT 1 00 amp CURRENCY CODE USD amp EMATL payername bbb net amp L_PAYMENTREQUEST_0O_ITEMCATEGORY0 Digital amp L_PAYMENTREQUEST_O_NAMEO0 Kitty Antics amp L_PAYMENTREQUEST_0O_AMTO 1 00 amp L_PAYMENTREQUEST_0O_QTYO 1 Response Parameters successResponseFields amp PROF ILEID I G7ALAX80 95JY amp PROFILESTATUS Active Digital Goods Integration Guide EC Edition January 2012 43 44 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 e CancelledProfile If PayPal successfully creates the profile the profile has an ActiveProfile status However if a non recurring initial payment fails and you set FAILEDINITAMTACTION to CancelOnFailure in the CreateRecurringPaymentsProfile request PayPal creates the profile with a status of PendingProfile The profile remains in this status until the initial payment either completes successfully
14. Om Return URL Cancel URL Response Customer Details PayPal Request Final Transaction Details gt fh P Server DoExpressCheckoulPaymel Response Transaction Results Add JavaScript to close iframe 10 Load Content Download Purchase Confirmation 20 January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout oa Overview of Digital Goods Integration The numbers in the figure correspond to the following steps 1 Add the dg js JavaScript provided by PayPal to the webpage on which you implement the Pay With PayPal button This script manages the PayPal digital goods payments flow This flow appears in a lightbox overlaying your webpage 2 Place the Pay With PayPal button on the same webpage on which you add the dg js script 3 When the buyer clicks Pay With PayPal call the SetExpressCheckout API operation NOTE Make sure that your API version is 65 1 or greater for each PayPal API call that you make Pass details of the items purchased and other parameter fields required in digital goods transactions See Setting Up A Digital Goods Payment Transaction on page 22for details 4 A successful response returns a token to identify the digital goods transaction You pass the token in subsequent Express Checkout API operations related to this transaction 5 Redirect the buyer to the digital goods flow Append the token returned in the SetExpres
15. P Response Fields SetExpressCheckout Response Fields Token GetExpressCheckoutDetails SOAP Request Fields GetExpressCheckoutDetails Request Fields 58 Token January 2012 Digital Goods Integration Guide EC Edition GetExpressCheckoutDetails SOAP Response Fields GetExpressCheckoutDetails Response Fields Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods Token InvoiceID ContactPhone Note RedirectRequired CheckoutStatus PaymentDetails Payer Information Fields Payer PayerID PayerStatus PayerCountry PayerBusiness Payer Name Fields Salutation FirstName MiddleName LastName Suffix Payment Details Type Fields OrderTotal ItemTotal TaxTotal OrderDescription InvoiceID NotifyURL PaymentDetailsItem TransactionID PaymentRequest ID Payment Details Item Type Fields Name Digital Goods Integration Guide EC Edition January 2012 59 60 Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods e Description e Amount e Number e Quantity e Tax e ItemCategory DoExpressCheckoutPayment SOAP Request Fields DoExpressCheckoutPayment Request Fields e Token e PayerID e PaymentDetails e ReturnFMFDetails Payment Details Type Fields e OrderTotal e ItemTotal e TaxTotal e OrderDescription e InvoiceID e NotifyURL e PaymentAction e PaymentD
16. PAYMENTREQUEST_n_AMT e PAYMENTREQUEST_n_CURRENCYCODE e PAYMENTREQUEST_n_ITEMAMT e PAYMENTREQUEST_n_TAXAMT e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_INVNUM e PAYMENTREQUEST_n_NOTIFYURL e PAYMENTREQUEST_n_PAYMENTACTION e PAYMENTREQUEST_n_PAYMENTREQUESTID Payment Information Fields e PAYMENTINF O_n_TRANSACTIONID e PAYMENTINFO_n_TRANSACTIONTYPE e PAYMENTINF O_nN_ORDERTIME e PAYMENTINF O_n_CURRENCYCODE e PAYMENTREQUEST_n_FEEAMT e PAYMENTINF O_n_SETTLEAMT e PAYMENTINFO_n_TAXAMT e PAYMENTINF O_n_EXCHANGERATE e PAYMENTINF O_n_PAYMENTSTATUS e PAYMENTINFO_n_PENDINGREASON e PAYMENTINF O_n_REASONCODE e PAYMENTINFO_n_FMFfilterIDm e PAYMENTINFO_n_FMFfilte NAMEM Express Checkout SOAP API Fields Supported By Digital Goods SetExpressCheckout SOAP Request Fields SetExpressCheckout Request Fields e Token e ReturnURL e CancelURL Digital Goods Integration Guide EC Edition January 2012 57 Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods RegConfirmShipping NoShipping AllowNote LocaleCode PaymentDetails Payment Details Type Fields OrderTotal ItemTotal TaxTotal OrderDescription InvoiceID Not ifyURL PaymentDetailsItem PaymentAction Payment Details Item Type Fields Name Description Amount Number Quantity Tax ItemCategory SetExpressCheckout SOA
17. PayPal Digital Goods Integration Guide EC Edition Digital Goods Integration Guide Express Checkout Edition Document Number 10118 en_US 201201 2012 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or s
18. Regardless of the specified currency the format must have a decimal point There must be exactly 2 digits to the right of the decimal point There can be an optional thousands separator to the left The separator must be a comma For example specify EUR 2 000 00 as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00 regardless of the currency used ENTREQU EST_O_TAXAMT to the total 2 If you pass in a tax amount for each item set PAYM amount of tax January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout Poa Integrating Digital Goods Payments With Express Checkout 3 Specify the return URL to a page on your site RETURNURL https The return URL is the page to which PayPal redirects your buyer after the buyer approves the payment Typically this is a secure page hnttps on your site NOTE You can use the return URL to pass 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 If you do not require the buyer to explicitly review and confirm the payment on your review page the buyer can confirm payment on PayPal Add the token and the useraction value commit as a name value pair to the return URL https www
19. ating multiple recurring payments profiles you must call CreateRecurringPayment sProfile once for each profile you plan to create January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Recurring Payments With the Express Checkout API If the transaction includes a mixture of a one time purchase and recurring payments profiles call DoExpressCheckoutPayment to complete the one time purchase transaction Then call CreateRecurringPayment sProfile for each recurring payment profile you plan to create IMPORTANT PayPal does not create the recurring payments profile until you receive a success response from the CreateRecurringPaymentsProfile call To obtain the best rates for digital goods set values for the following required payment details item fields e LPAYMENTREQUEST_O_NAMEN e LPAYMENTREQUEST_O_AMTn e I PAYMENTREQUEST_O_QTYnN e L PAYMENTREQUEST_0_ITEMCATEGORYn you must set the value to Digital NOTE The payment details item fields are available with version 69 0 and later of the CreateRecurringPaymentsProfile API The CreateRecurringPayment sProfile response contains a Profile ID which is an encoded string that uniquely identifies the recurring payments profile The following is a Creat eRecurringPayment sProfile example that enables you to obtain the best rates for digital goods items Request Parameters requiredSecurityParameters amp MET
20. ations 2 4 3 3 4 4 4 oe he es ee A Wade TAT N we ede ed ed d Recurring Payments Terms 00 eee Options for Creating a Recurring Payments Profile Digital Goods Integration Guide EC Edition January 2012 a Contents Specifying the Regular Payment Period 0 0 000002 ee ae 35 Including an Optional Trial Period 2 a 36 Specifying an Initial Payment oaoa 36 Maximum Number of Failed Payments 2 00000 ee eee 37 Billing the Outstanding Amount 0 00 eee a 37 Identifying Items as Digital or PhysicalGoods 004 4 37 Recurring Payments With the Express Checkout API oaa aaa 38 Initiating the Processing Flow With SetExpressCheckout 41 Redirecting the Buyer to PayPal a 000200 eee eee 42 Getting Buyer Details Using GetExpressCheckoutDetails 42 Creating the Profiles With CreateRecurringPaymentsProfile 42 Recurring Payments Profile Status 2 2 a 44 Getting Recurring Payments Profile Information 00 000 2 ee 44 Modifying a Recurring Payments Profile 0 0020 eee eee 45 Updating Addresses o aoao a a 46 Updating the Billing Amount aoaaa a 46 Billing the Outstanding Amount of a Profile oaa aa 200008 46 Recurring Payments Notifications oaoa a aa ee 47 Appendix A Options For Closing the Lightbox or Mini browser 49 Reloading Parent Page to a Specific URL 1 49 Reloading Pare
21. ayment NVP SOAP INITAMT ScheduleDetails ActivationDetails InitialAmount FAILEDINITAMTACTION ScheduleDetails ActivationDetails FailedInitAmountAction By default PayPal does not activate the profile if the initial payment amount fails To override this default behavior set the FAILEDINITAMTACTION field to ContinueOnFailure If the initial payment amount fails Cont inueOnFailure instructs PayPal to add the failed payment amount to the outstanding balance due on this recurring payment profile If you do not set FAILEDINITAMTACTION or set it to CancelOnFailure PayPal creates the recurring payment profile However PayPal places the profile into a pending status until the initial payment completes If the initial payment clears PayPal notifies you by Instant Payment Notification IPN that it has activated the pending profile If the payment fails PayPal notifies you by IPN that it has canceled the pending profile If you created the profile using Express Checkout the buyer receives an email stating that PayPal cleared the initial payment or canceled the pending profile Maximum Number of Failed Payments By including the MAXFAITLEDPAYMENTS field in the CreateRecurringPaymentsProfile request you set the number of failed payments allowed before PayPal automatically suspends the profile PayPal sends you an IPN message when the number of failed payments reaches the maximum number spec
22. ayment It does not reduce the payment steps After successfully logging in the digital flow presents the You are about to pay page in a mini browser 12 January 2012 Digital Goods Integration Guide EC Edition Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments Jos Ramirez You are about to pay Receiver Rapid Action Towing Total My PayPal Balance View PayPal policies My PayPal Balance Memo of standard transaction Digital Goods EEANN cance PayPal protects your privacy and security Internet Site Feedback 5 00 USD 5 00 USD If the buyer chooses Cancel PayPal redirects the buyer s browser to the cancel URL specified in the SetExpressCheckout API operation s request message If the buyer chooses Pay the Thank you for using PayPal page appears in the mini browser Digital Goods Integration Guide EC Edition January 2012 13 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments Jos Ramirez Log out Thank you for using Pa yPal Receiver Rapid Action Towing 5 00 Total 5 00 USD PayPal protects your privacy and security Site Feedback 9 internet When the buyer clicks Close PayPal redirects the buyer s browser to the return URL specified in the SetExpressCheckout API operation s request message 2 The expType varible is set to instant and the buyer checked the
23. btain the digital goods discount rate Updated information for Version 69 0 Describes how to obtain the best rates for digital goods items for recurring payments and reference transactions First publication Digital Goods Integration Guide EC Edition January 2012 63 64 January 2012 Digital Goods Integration Guide EC Edition
24. ce type variable expType on your web page For details on setting expType see JavaScript Functions For Digital Goods Payments on page 28 2 Whether the buyer is remembered from a previous transaction Your buyers partially determine the digital goods flow by choosing whether to check the remember me box on the login page Checking the box creates a remember me cookie on the buyer s machine that lets them skip the login page on subsequent visits The following table describes the possible digital goods DG flows that the combination of expType and Remember Me Cookie present to a buyer expType Remember Me Cookie DG Flow Experience instant mini No The login page opens in a mini browser Yes The merchant review page opens in a lightbox and a mask is applied over the underlying web page No The login page opens in a mini browser and a mask is applied over the underlying web page January 2012 Digital Goods Integration Guide EC Edition Introducing Digital Goods for Express Checkout as Introducing Digital Goods Payments expType Remember Me Cookie DG Flow Experience Yes The merchant review page opens in a mini browser and a mask is applied over the underlying web page popup No The login page opens in a mini browser and a mask is not applied to the underlying web page Yes The merchant review page opens in a mini browser and a mask is not applied to the underlying web
25. d Contents 6 January 2012 Digital Goods Integration Guide EC Edition Preface About This Guide Digital Goods Integration Guide Express Checkout Edition describes how to implement PayPal for Digital Goods Intended Audience This document is intended for developers implementing PayPal for Digital Goods using the Express Checkout API Where to Go for More Information e Merchant Setup and Administration Guide Documentation Feedback Help us improve this guide by sending feedback to document at ionfeedback paypal com Digital Goods Integration Guide EC Edition January 2012 pe Documentation Feedback 8 January 2012 Digital Goods Integration Guide EC Edition Introducing Digital Goods for Express Checkout Digital Goods for Express Checkout streamlines the checkout process for buyers and keeps buyers on your website e Introducing Digital Goods Payments on page 9 Introducing Digital Goods Payments Digital goods payments combine JavaScript with the Express Checkout API to streamline the checkout process for buyers of digital goods Digital goods are items such as e books music files and digital images distributed in electronic format The buyer can conveniently purchase digital goods during checkout with a minimum of clicks without leaving your website or interrupting their online activities The following figure encapsulates digital goods payments PayPal for digital goods pay
26. dg new PAYPAL apps DGF low 1 HTML ID of form submit buttons that call setEC trigger submitBtn expType instant f lt script gt lt body gt lt html gt Digital Goods Integration Guide EC Edition January 2012 29 Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout 30 January 2012 Digital Goods Integration Guide EC Edition 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 pay
27. e Reloading Parent Page by Removing Frames on page 50 Reloading Parent Page to a Specific URL This procedure for closing the lightbox or mini browser reloads the parent page to a specific URL 1 Optionally to obtain details about the buyer to display to your web page call the GetExpressCheckoutDetails API operation 2 Call DoExpressCheckout to complete payment See Completing the Digital Goods Transaction on page 25 3 Include JavaScript code such as in the following example on the return URL and cancel URL pages lt Use result of DoEC to send the buyer to the correct page gt lt DOCTYPE html gt lt html gt lt head gt lt title gt lt title gt lt script gt top location href http example com path_to_fulfillment_page lt script gt lt head gt lt body gt If this page does not redirect lt a href page to deliver content to non JS customer gt Click Here lt a gt lt body gt lt html gt If the buyer cancels the order close the lightbox or mini browser without fulfilling the order The top window is the browser window This code replaces the top window content with the content of the page at the specified URL Digital Goods Integration Guide EC Edition January 2012 49 A Options For Closing the Lightbox or Mini browser Reloading Parent Page by Removing Frames Reloading Parent Page by Removing Frames This procedure for closing the lightbox or mini browser
28. e instant or mini expType instant f lt script gt NOTE Do not set a target for the redirect on button click 3 Include the following JavaScript code on the return URL and cancel URL pages The JavaScript closes the digital goods payment flow in the overlay window and sends the buyer to the correct page January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout Pol Integrating Digital Goods Payments With Express Checkout NOTE Make sure that you include content to be displayed in case the customer has JavaScript disabled on their browser You should include a link to deliver the content if the purchase completes successfully lt script gt if window opener window close else if top dg isOpen true top dg closeFlow lt script gt To update the page asynchronously without reloading you need to make some Ajax calls as in the following example This is the preferred method for closing the digital goods payments flow For other options see Integrating Digital Goods With Flash Third Party Merchant on page 51 lt Use result of DoEC to send the buyer to the correct pag gt lt DOCTYPE html gt lt html gt lt head gt lt title gt lt title gt lt script gt Sample AJAX code using jQuery any AJAX library works ajax url http example com path_to_fulfillment_content type GET error function
29. elds are not relevant to the digital goods flows and thus are not supported See Features Not Supported With Digital Goods on page 16 for details After Performing Digital Goods Transactions After performing digital goods payments transactions you can use PayPal API operations to perform the following back office tasks e Issue refunds e Get transaction details e Search transactions Features Not Supported With Digital Goods Digital goods does not support the following Express Checkout features described in the Express Checkout Advanced Features Guide e Physical goods Digital goods are digital media that the buyer downloads or accesses online e Shipping addresses Downloading electronic media only does not involve shipping addresses 16 January 2012 Digital Goods Integration Guide EC Edition Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments Instant Update API The PayPal server calls your callback server to instantly update the PayPal pages based on shipping options changes the buyer selects Parallel payments Parameter fields describe the details of up to 10 payments Digital goods supports passing a value for one payment only Immediate Payment Immediate Payment checks that you receive payment at the time the buyer commits to a purchase instant payment methods only Authorization and Capture API SetCustomerl Giropay Incentives BillingAgreement API S
30. ents events through IPN and email Typically however you can call Get TransactionDetails to obtain the information you need PayPal notifies you of certain events through IPN For recurring payments profiles created using Express Checkout PayPal also notifies buyers of specific events by email The following table indicates when PayPal generates IPN and emails Recurring payments IPN messages and email Event IPN Buyer Email Profile successfully created Yes Yes Profile creation failed Yes Yes Profile canceled from paypal com interface Yes Yes Profile status changed using API No Yes Profile updated using API No Yes Initial payment either succeeded or failed Yes Yes Payment either succeeded or failed during either trial Yes Yes period or regular payment period Outstanding payment either succeeded or failed Yes Yes Maximum number of failed payments reached Yes No NOTE API transactions such as ManangeRecurringPayment sProfileStatus do not trigger IPN notification The API response immediately provides the success or failure of the call Digital Goods Integration Guide EC Edition January 2012 47 az Handling Recurring Payments Recurring Payments Notifications 48 January 2012 Digital Goods Integration Guide EC Edition Options For Closing the Lightbox or Mini browser The following options for closing the lightbox or mini browser reload the parent page e Reloading Parent Page to a Specific URL on page 49
31. er 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 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 REFUNDTYPE Partial 3 For a partial refund specify the refund amount including the currency AMT amount CURRENCY CODE currencyID Digital Goods Integration Guide EC Edition January 2012 31 4 Issuing Refunds 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 32 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments Set up a recurring payment to handle subscription and other payments that occur on a fixed schedule e How Recurring Payments Work e Recurring Payments Terms e Options for Creating a Recurring Payments Profile e Recurring Payments With the Express Checkout API e Recurring Payments Profile Status e Getting Recurring Payments Profile Information e Modifying a Recurring Payments Profile e Billing the Outstanding Amount of a Profile e Recurring Payments Notifications
32. ervice described herein PayPal Inc reserves the right to make changes to any information herein without further notice Preface Chapter Contents About This Gude lt s s s sr ssas eee we a a we a R Intended Audience 0 0 Where to Go for More Information 2 a a a Documentation Feedback 2 00002 eee ee 1 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 0 00000 eee eee Express Checkout Buttons 2 2 ee Digital Goods Payments In More Detail 00004 Digital Goods Flows 2 0000 e a e ee ee Other Payments Features That Digital Goods Supports After Performing Digital Goods Transactions Features Not Supported With DigitalGoods Other Digital Goods Caveats 2 2 ee es Chapter 2 Integrating Digital Goods for Express Checkout Overview of Digital Goods Integration 022 00085 Integrating Digital Goods Payments With Express Checkout Setting Up A Digital Goods Payment Transaction Redirecting the Buyer to PayPal aa After PayPal Redirects the Buyer To Your Web Page aana aaa Completing the Digital Goods Transaction 24 Setting Up Web Pages To Invoke the Digital Goods Payments Flow Chapter 3 Issuing Refunds Chapter 4 Handling Recurring Payments How Recurring Payments Work 2 aa a Limit
33. etailsItem e PaymentRequestID Payment Details Item Type Fields e Name e Description e Amount e Number e Quantity e Tax e ItemCategory January 2012 Digital Goods Integration Guide EC Edition Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods DoExpressCheckoutPayment SOAP Response Fields DoExpressCheckoutPayment Response Fields e Token e Note e RedirectRequired Payment Information Fields e TransactionID e TransactionType e PaymentDate e GrossAmount e FeeAmount e SettleAmount e TaxAmount e ExchangeRate e PaymentStatus e PendingReason e ReasonCode Digital Goods Integration Guide EC Edition January 2012 61 Express Checkout API Fields Supported By Digital Goods Express Checkout SOAP API Fields Supported By Digital Goods 62 January 2012 Digital Goods Integration Guide EC Edition Revision History Revision history for PayPal Digital Goods Integration Guide Express Checkout Edition Date Published Description 01 30 12 03 15 11 03 08 11 01 26 11 Updated to describe the use of the expType variable to achieve different DG Flows Split Chapter 1 into 2 chapters in an effort to separate the bulk of the conceptual info from the procedural info Fixed doc bugs re formatted API field reference Updated to include a note on setting item detail variables in SetExpressCheckout and DoExpressCheckoutPayment to o
34. everal fields in the Recurring Payments API and in the Reference Transaction API are not relevant for digital goods transactions and thus are not supported Do not use the API fields in the following lists for digital goods operations Unsupported Fields in the Recurring Payments and Reference Transaction Name Value Pair NVP APIs SHIPTONAME HIPTOSTREE HIPTOCITY HIPTOSTATE HIPTOZIP HIPTOSTREET2 RY HIP TOCOUNT RYCODE HIPPINGAMT S S S S S SHIPTOCOUNTI S S S RI EGULARSHIP HIPTOPHONENUM INGAMT Unsupported Fields in the Recurring Payments and Reference Transaction SOAP APIs Name Street1 Street2 CityName StateOrProvince Digital Goods Integration Guide EC Edition January 2012 17 a Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments e PostalCode e Country e Phone e ShippingAmount Other Digital Goods Caveats Observe the following notes when integrating digital goods e Your website requires a P3P header if it is not directly integrating digital goods If your site uses a hosted cart embedded in another merchant s site you need a P3P header For details on P3P see the following link P3P documentation e Pass all the required Express Checkout API parameter fields in digital goods transactions For details see Integrating Digital Goods Payments With Express Checkout on pa
35. for Express Checkout Integrating Digital Goods Payments With Express Checkout 10 Execute the SetExpressCheckout API operation to set up the Express Checkout transaction 11 Test that the response to the SetExpressCheckout API operation was successful Upon success the SetExpressCheckout API operation returns a token PayPal uses the token to associate the execution of API operations and commands with a specific instance of the checkout experience 12 If calling the SetExpressCheckout API was successful redirect the buyer to the digital goods payments flow with the following redirect URL Append the token value returned in the SetExpressCheckout response to the URL SetExpressCheckout Example For Digital Goods The following is an example of SetExpressCheckout parameters and values for a digital goods payments transaction Request Parameters requiredSecurityParameters amp METHOD SetExpressCheckout amp RETURNURL http amp CANCELURL http amp PAYMENTREQUEST_0O_CURRENCYCODE USD amp PAYMENTREQUEST_0O_AMT 300 amp PAYMENTREQUEST_0O_ITEMAMT 200 amp PAYMENTREQUEST_0O_PAYMENTACTION Sale amp L_PAYMENTREQUEST_0O_ITEMCATEGORY0 Digital amp L_PAYMENTREQUEST_0O_ITEMCATEGORY1 Digital amp L_PAYMENTREQUEST_O_NAMEO0 Kitty Antics amp L_PAYMENTREQUEST_O_NAMF1 Al 1 About Cats amp
36. ge 22 18 January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout This chapter describes how to integrate Digital Goods for Express Checkout with your website e Overview of Digital Goods Integration on page 19 e Integrating Digital Goods Payments With Express Checkout on page 22 Overview of Digital Goods Integration There are two possible ways to integrate the digital goods flow with Express Checkout e Merchants using PHP can use the PHP Wizard located here https www paypal labs com integrationwizard e Merchants using other platforms must take the manual approach to integration Future releases will feature integration wizards for other platforms In either event when the integration is successfully completed you will have added the digital goods JavaScript to the page set up code to invoke the digital goods flow and specified URLs for return and cancel pages The following figure summarizes the manual integration steps for the digital goods payments flow Digital Goods Integration Guide EC Edition January 2012 19 i Integrating Digital Goods for Express Checkout Overview of Digital Goods Integration Legend WebFlow APicall Token f PayeriD Merchant Site PayPal Payment Pages PayFal Servers Gy Request y o Response Token API Server Add JavaScript to create iframe hoe HTTP Redirect mn D LCTO
37. he status of a recurring payments profile e Update the details of the recurring payments profile e Bill the outstanding amount of the recurring payments profile Limitations The current release of the Recurring Payments API has the following limitations e A profile can have at most one optional trial period and a single regular payment period e The profile start date may not be earlier than the profile creation date Recurring Payments with Express Checkout also has the following limitations e To be able to create a recurring payments profile for the buyer you must ensure that the buyer s PayPal account includes an active credit card e You can create a maximum of 10 recurring payments profiles during checkout e You can increase the profile amount by only 20 in each 180 day interval after you create the profile Recurring Payments Terms The following table lists and describes terms that are commonly used in the context of PayPal recurring payments Recurring Payments Terms Term Definition Recurring payments profile Your record of a recurring transaction for a single buyer The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval Billing cycle Make one payment per billing cycle Each billing cycle has 2 components e The billing period specifies the unit to calculate the billing cycle such as days or months e The billing frequency specifies
38. ified Billing the Outstanding Amount If a payment fails for any reason PayPal adds the billing amount including shipping and tax if applicable to the profile s outstanding balance Use the AUTOBILLOUTAMT field in the CreateRecurringPayment sProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle Whether or not you choose to include the outstanding amount with the payment for the next billing cycle you can also use the BillOutstandingAmount API to programmatically collect that amount at any time Identifying Items as Digital or Physical Goods Set all the payment details item fields in the following table in the CreateRecurringPayment sProfile request If all items are digital goods be sure to set the item category field to Digital to get the discount rate for digital goods Digital Goods Integration Guide EC Edition January 2012 37 az Handling Recurring Payments Recurring Payments With the Express Checkout API Required fields for specifying item details NVP SOAP Description L_PAYMENTREQUEST_O_ ItemCategory For digital goods this field must be set to ITEMCATEGORYN Digital e Digital e Physical L_PAYMENTREQUEST_0_ Name Item name NAMEN L_PAYMENTREQUEST_0O_ Amount Cost of item AMTN L_PAYMENTREQUEST_O_ Quantity Item quantity QTYN Recurring Payments With the Express Checkout API During the checkout flow you can
39. l payment and other options Specifying the Regular Payment Period Each recurring payments profile has a regular payment period that defines the amount and frequency of the payment The following table lists the required fields for specifying the regular payment period Required fields for specifying a regular payment period NVP SOAP Description PROF ILESTARTDATE RecurringPaymentsProfileDet The date when billing for this profile ails BillingStartDate begins NOTE The profile may take up to 24 hours for activation BILLINGPERIOD ScheduleDetails The unit of measure for the billing cycle PaymentPeriod BillingPeriod Must be one of the following e Day e Week e SemiMonth e e Month Year Digital Goods Integration Guide EC Edition January 2012 35 az Handling Recurring Payments Options for Creating a Recurring Payments Profile NVP SOAP Description BILLINGFREQUENCY ScheduleDetails The number of billing periods that make PaymentPeriod BillingFreque up one billing cycle The combination of ncy billing frequency and billing period must be less than or equal to one year NOTE If the billing period is SemiMonth the billing frequency must be 1 AMT ScheduleDetails Amount to bill for each billing cycle PaymentPeriod Amount You can optionally include a value for TOTALBILLINGCYCLES SOAP field ScheduleDetails PaymentPeriod TotalBillingCycles which specifies the total nu
40. laying your webpage Digital Goods only Places the Pay With PayPal button on your webpage Calls SetExpressCheckout setting up one or more billing agreements in the request Redirects buyer s browser to https www paypal com cgi bin webscr cmd _express checkout amp token lt token returned by SetExpressCheckout gt Calls GetExpressCheckoutDetails to get buyer information optional Displays merchant review page for buyer Calls DoExpressCheckoutPayment if the order includes one time purchases as well as a recurring payment Otherwise skip this step Calls CreateRecurringPayment sProfile one time for each recurring payment item included in the order If the order includes a one time digital goods purchase sets values for the required payment details item parameters Sets the item category to Digital Returns a token that identifies the transaction to the merchant Displays login page and allows user to select payment options and shipping address Redirects buyer s browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description Returns GetExpressCheckoutDetails response Returns Dol ExpressCheckoutPayment response Returns ProfileID in CreateRecurringPaymentsProfile response for each profile successfully created 40 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Recurring Payments With the
41. mber of billing cycles in the regular payment period If you either do not specify a value or specify the value 0 the payments continue until PayPal or the buyer cancels or suspends the profile If the value is greater than 0 the regular payment period continues for the specified number of billing cycles You can also specify an optional shipping amount or tax amount for the regular payment period 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 36 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Options for Creating a Recurring Payments Profile Required fields for specifying an initial p
42. ments teree m _ s GetEC DoEC To make a payment for a digital goods item the buyer 1 Clicks Pay With PayPal The button click triggers the call to the SetExpressCheckout API operation PayPal redirects the buyer to a lightbox overlaying your website 2 Clicks Pay to accept the order The button click triggers JavaScript code that closes the lightbox Digital Goods Integration Guide EC Edition January 2012 a Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 3 Confirms the order on your page after the lightbox closes 4 Resumes activity on your page Express Checkout Buttons The button you place on your web page to initiate PayPal digital goods transactions is available at the following URL https www paypal com en_US i btn btn_dg_pay_w_paypal gif Pay wary PayPal j NOTE Do not host copies of the PayPal images locally on your servers Outdated PayPal images reduce buyer confidence in your site Digital Goods Payments In More Detail To the buyer the digital goods payment process appears to be built into your website The digital goods payment process occurs in a lightbox that temporarily overlays your website Your buyer s digital goods payment experience depends upon two factors 1 The value you set for the experience type variable on your web page You determine how the digital goods flow appears to your buyers by setting or not setting the experien
43. nnection do anything required to get API response parameters into the response variable connect to game swf and call paymentComplete sendingLC send paymentConn paymentComplete response 52 January 2012 Digital Goods Integration Guide EC Edition Express Checkout API Fields Supported By Digital Goods A subset of the Express Checkout API parameter fields are relevant in digital goods integrations e Express Checkout NVP API Fields Supported By Digital Goods on page 53 e Express Checkout SOAP API Fields Supported By Digital Goods on page 57 Express Checkout NVP API Fields Supported By Digital Goods SetExpressCheckout NVP Request Fields SetExpressCheckout Request Fields e METHOD Must be set to SetExpressCheckout e TOKEN e RETURNURL e CANCELURL e REQCONFIRMSHIPPING e NOSHIPPING e ALLOWNOTE e LOCALECODE e PAYMENTDETAILS Payment Details Type Fields e PAYMENTREQUEST_n_AMT e PAYMENTREQUEST_n_CURRENCYCODE e PAYMENTREQUEST_n_ITEMAMT e PAYMENTREQUEST_n_TAXAMT e PAYMENTREQUEST_n_DESC e PAYMENTREQUEST_n_INVNUM e PAYMENTREQUEST_n_NOTIFYURL e PAYMENTREQUEST_n_PAYMENTACTION Digital Goods Integration Guide EC Edition January 2012 Express Checkout API Fields Supported By Digital Goods Express Checkout NVP API Fields Supported By Digital Goods Payment Details Item Type Fields e PAYMENTREQUEST_n_NAMEM e PAYMENTREQUEST_n_DESCm e PAYMENTREQUEST_n_AMTm
44. nt Page by Removing Frames aoao aaa a 50 Appendix B Methods For Integrating Digital Goods Into Flash 51 Integrating Digital Goods With Flash oaoa aaa a 51 Integrating Digital Goods With Flash Third Party Merchant 51 Appendix C Express Checkout API Fields Supported By Digital Goods 53 Express Checkout NVP API Fields Supported By Digital Goods 53 SetExpressCheckout NVP Request Fields 022 0002 53 SetExpressCheckout NVP Response Fields 0 000005 54 GetExpressCheckoutDetails NVP Request Fields oa oaao 54 GetExpressCheckoutDetails NVP Response Fields 4 54 DoExpressCheckoutPayment NVP Request Fields 4 56 DoExpressCheckoutPayment NVP Response Fields 4 56 Express Checkout SOAP API Fields Supported By Digital Goods 57 SetExpressCheckout SOAP Request Fields 0 2 50000 s 57 4 January 2012 Digital Goods Integration Guide EC Edition Contents a SetExpressCheckout SOAP Response Fields 00005 58 GetExpressCheckoutDetails SOAP Request Fields 4 58 GetExpressCheckoutDetails SOAP Response Fields 4 59 DoExpressCheckoutPayment SOAP Request Fields a aoa aaa a 60 DoExpressCheckoutPayment SOAP Response Fields oa oaa aaa 61 Revision History aoaaa a ce a a ee ee we ea BD Digital Goods Integration Guide EC Edition January 2012 5 ia
45. or fails A profile has a status of ExpiredProfile when PayPal completes the total billing cycles for the optional trial and the regular payment periods You can suspend or cancel a profile by using the ManageRecurringPaymentsProfileStatus API You can also reactivate a suspended profile If PayPal has already reached the maximum number of failed payments however you must increase the number of failed payments before reactivating the profile NOTE You can also suspend cancel or reactive a recurring payments profile through the PayPal website For recurring payments profiles created with the Express Checkout API the buyer receives an email about the change in status of their recurring payment Getting Recurring Payments Profile Information Use the GetRecurringPaymentsProfileDetails API to obtain information about a profile NOTE You can also get information about recurring payments profiles from the PayPal website Along with the information that you specified in the CreateRecurringPaymentsProfile request GetRecurringPaymentsProfileDetails 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 January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Modifying a Recurring Payments Profile e Number of billing cycles remaining in the active
46. ou increased the payment amount to 110 During the next 180 day interval starting September 7 you can only increase the amount of the payment to a maximum of 132 120 of 110 Billing the Outstanding Amount of a Profile Use the BillOutstandingAmount API to immediately bill the buyer for the current past due or outstanding amount for a recurring payments profile NOTE You can also bill the buyer for the current past due or outstanding amount for a recurring payments profile from the PayPal website To bill the outstanding amount e The profile status must be active or suspended NOTE The BillOutstandingAmount API does not reactivate a suspended profile You need to call ManageRecurringProfileStatus to do this e The profile must have a non zero outstanding balance e The amount of the payment cannot exceed the outstanding amount for the profile e The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile NOTE Anerror occurs when another outstanding balance payment is already queued PayPal informs you by IPN about the success or failure of the outstanding payment For profiles created using Express Checkout the buyer receives an email notification of the payment January 2012 Digital Goods Integration Guide EC Edition Handling Recurring Payments 4 Recurring Payments Notifications Recurring Payments Notifications PayPal notifies you of recurring paym
47. page not set No A launch page opens in a lightbox From here the buyer can log in the flow then proceeds to the login page in a mini browser or sign up with PayPal or pay as a guest Yes DG opens the merchant review page in a lightbox and a mask is applied over the underlying web page NOTE New DG Merchants Set expType to instant for the best performance Existing DG Merchants You can bypass the legacy flow s lightbox launch page by setting expType or leave your web page unchanged to maintain the current behavior Digital Goods Flows This section shows examples of different Digital Goods flows The first example shows the DG Instant flow expType set to instant for a new buyer or a buyer who didn t check the remember me box on the login page The second example shows the same DG Instant flow for a returning buyer who checked the remember me box The third example shows the legacy flow expType is unset for a new buyer The buyer initiates all DG flows by clicking Pay with PayPal Read the complete story instantly Story 200 000 Android devices sold each day 1 00 1 The expType variable is set to instant and the buyer is new The DG flow opens the Log in to your PayPal account page in a mini browser with a mask over the underlying page Digital Goods Integration Guide EC Edition January 2012 11 a Introducing Digital Goods for Express Checkout Introducing Digital Good
48. rease the number of billing cycles to 5 This provides the buyer with 4 additional trial payments If you call UpdateRecurringPaymentsProfile during the regular payment period the changes take effect with the buyer s next scheduled regular payment For complete details see the Name Value Pair Developer Guide and Reference or the SOAP API Reference Digital Goods Integration Guide EC Edition January 2012 45 46 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 To update the subscriber s street address for example specify all the address fields listed in the Name Value Pair Developer Guide and Reference or SOAP API Reference Do not specify only the street address field Updating the Billing Amount For profiles created using Express Checkout you can increase the recurring payment total amount by 20 maximum in a fixed 180 day interval after profile creation The 20 maximum is based on the total amount of the profile at the beginning of the 180 day interval including any shipping or tax amount If for example you create a profile on March 10 with a total amount of 100 during the 180 day interval from March 10 to September 6 you can increase the amount to a maximum of 120 120 of 100 Suppose that during the first 180 day interval y
49. reloads the parent page by removing frames 1 Optionally to obtain details about the buyer to display to your web page call the GetExpressCheckoutDetails API operation 2 Call DoExpressCheckout to complete payment See Completing the Digital Goods Transaction on page 25 NOTE You perform the previous 2 steps while you are still in control of the lightbox 3 Include JavaScript code such as in the following example on the return URL and cancel URL pages lt Use result of DoEC to send the buyer to the correct pag gt lt DOCTYPE html gt lt html gt lt head gt lt title gt lt title gt lt script gt if window top top location replace document location lt script gt lt head gt lt body gt lt Include non JavaScript content here gt If this page does not redirect lt a href page to deliver content to non JS customer gt Click Here lt a gt lt body gt lt html gt If the buyer cancels the order close the lightbox or mini browser without fulfilling the order The top window is the browser window This code replaces the top window content with the content of the page at the specified URL 50 January 2012 Digital Goods Integration Guide EC Edition Methods For Integrating Digital Goods Into Flash You can integrate digital goods into a Flash file e Integrating Digital Goods With Flash Third Party Merchant on page 51 e Integrating Digi
50. remember me box The digital goods flow skips the login screen and the flow proceeds directly to the payment page in a lightbox 14 January 2012 Digital Goods Integration Guide EC Edition Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments KENNETH PayPal n Not you Log out You are about to buy E c PayPal Digital Goods Merchant Qty Description 1 0 05 USD Total 0 05 USD PayPal will use Mastercard xxxx 9 View PayPal policies aay Cancel PayPal protects your privacy and security The rest of the flow proceeds as shown in the previous example but the pages are displayed in the lightbox instead of the mini browser 3 The expType variable is unset and the buyer is new The launcher page only appears if expType variable is not set and the buyer has not previously checked the remember me box on the login page Digital Goods Integration Guide EC Edition January 2012 15 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments PayPal Log in to your PayPal account to complete this purchase New to PayPal Sign up for a PayPal account and complete this purchase now Or check out with a debit or credit card no PayPal account required eB G E Other Payments Features That Digital Goods Supports You can use digital goods with the following payments features e Recurring payments Some Express Checkout fi
51. riggers the flow NOTE You are only required to explicitly start the flow when there is no triggering event for example when you want to associate digital goods payments with playing a Flash movie closeFlow function Closes the mini browser or lightbox associated with the flow Use this function after the buyer completes or cancels the payment isOpen function Determines whether the flow is still active 28 January 2012 Digital Goods Integration Guide EC Edition Integrating Digital Goods for Express Checkout em Integrating Digital Goods Payments With Express Checkout Example Merchant Page With Digital Goods JavaScript The following code presents an example of the HTML code on the merchant page lt html gt lt head gt lt meta charset utf 8 gt lt title gt lt title gt lt style type text css gt lt style gt lt head gt lt body gt lt Custom merchant code path to merchant app etc gt lt h1 gt El Jefe s Tours lt h1 gt lt form action path to setECURL method post gt lt p gt lt input id submitBtn type submit value Pay with PayPal gt lt input type hidden name success_url value path to successURL gt lt input type hidden name cancel_url value path to cancelURL gt lt p gt lt form gt lt End custom merchant code gt lt script src https paypalobjects com js external dg js gt lt script gt lt script gt var
52. s Payments DO OOO peg Aodraid coving S hainn Google believes that some 2 aut Lh e y sold each day leading to sig Log in to your PayPal account Windows Internet E N increased mobile search tra GO lel testi S RT x People are finally beginning is Schmidt said at the inau pointing to recent studies s operating system outpacing The number was about 100 Log in to your PayPal account Schmidt said It looks like A incredibly phenomenal in its Email address will continue PayPal PayPal password Read the complete story Forgot your email address or password Story 200 000 Android de l For faster checkout skip login for future purchases using this computer How it works Login Cancel New to PayPal Sign up and buy in a few easy steps Or buy as a quest visa TS G Ped PayPal protects your privacy and security internet Q10 From this page the buyer can log in optionally checking the remember me box for subsequent purchases if there is little risk of their account being misused or cancel the transaction IMPORTANT Opting in to the remember me behavior does not guarantee that the buyer will not be asked to provide log in credentials Buyers without a PayPal account can sign up for one or proceed as a guest and complete their purchase with a credit card NOTE Guest checkout provides only the visual benefits of a digital goods p
53. sCheckout response to the redirect URL If this is the first time the buyer is purchasing digital goods on your page a mini browser displays that lets the buyer log in to PayPal and initiate approval for the payment 6 After the buyer clicks Pay to approve or cancel PayPal redirects the buyer to the respective return or cancel URL page on your site PayPal passes the token and the buyer s Payer ID with the redirect 7 If the buyer approves payment you can optionally call GetExpressCheckoutDetails to obtain buyer details to display to your webpage 8 If the buyer approves payment call DokxpressCheckoutPayment to complete the payment including the details of the items purchased 9 Add JavaScript code to your return and cancel URL pages to close the digital goods lightbox 10 Fulfill the buyer s order from your webpage Download the digital goods and provide a purchase confirmation NoTE Make sure that you test your integration before taking your pages live Digital Goods Integration Guide EC Edition January 2012 21 22 Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout Integrating Digital Goods Payments With Express Checkout Integrating PayPal digital goods payments with the Express Checkout API requires implementing the following API operations SetExpressCheckout and DoExpressCheckoutPayment Optionally you can implement GetExpressCheckout
54. subscription period e Current outstanding balance e Total number of failed billing cycles e Date of the last successful payment received e Amount of the last successful payment received Modifying a Recurring Payments Profile Use the UpdateRecurringPaymentsProfile API to modify a recurring payments profile NOTE You can also modify recurring payments profiles from the PayPal website You can modify only the following specific information about an active or suspended profile e Subscriber name or address e Past due or outstanding amount e Whether to bill the outstanding amount with the next billing cycle e Maximum number of failed payments allowed e Profile description and reference e Number of additional billing cycles e Billing amount tax amount or shipping amount NOTE You cannot modify the billing frequency or billing period of a profile You can modify the number of billing cycles in the profile You can modify the following profile information during the trial period or regular payment period e Billing amount e Number of billing cycles NOTE For recurring payments with the Express Checkout API PayPal does not allow certain updates such as billing amount within 3 days of the scheduled billing date The profile changes take effect with the next payment after the call to update the profile Say for example the buyer has made 1 trial payment out of a total of 3 You call UpdateRecurringPayment sProfile to inc
55. t the buyer to display to your webpage 2 Call DoExpressCheckout to complete payment Completing the Digital Goods Transaction To complete the digital goods transaction after the buyer approves the order call the DoExpressCheckoutPayment API operation When calling DoExpressCheckout Payment do the following 1 Pass the token and Payer ID returned by PayPal when it redirected the buyer back to your site TOKEN token Value PAYERID payerld 2 Pass the total amount of the payment as the value of PAYMENTREQUEST_0_AMT include the currency if it is not in US dollars Specify the total amount of the transaction Regardless of the specified currency the format must have decimal point The decimal point must include exactly 2 digits to the right and an optional thousands separator to the left which must be a comma For example specify EUR 2 000 00 as 2000 00 or 2 000 00 The specified amount cannot exceed USD 10 000 00 regardless of the currency used PAYMENTREQUEST_0_AMT amount PAYMENTREQUEST_0_CURRENCYCODE currencylD 3 If you passed in a tax amount for each item set PAYMENTREQUEST_0O_TAXAMT to the total amount of tax Digital Goods Integration Guide EC Edition January 2012 25 26 Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout 4 If you pass a value for PAYMENTREQUEST_O_PAYMENTACTION
56. tal Goods With Flash on page 51 Integrating Digital Goods With Flash The following is an example of how a first party merchant can integrate digital goods with Flash To integrate digital goods with Flash 1 Include the digital goods JavaScript library in the HTML page game htm1 which also includes the Flash movie game swf 2 Include the following ActionScript in the Flash movie game swf to initialize the digital goods object dg_button addEventListener MouseEvent MOUSE_UP function evt MouseEvent void var payment_URL String lt Merchant URL to initiate API call gt use ExternalInterface to call the JavaScript method dg startFlow var result uint ExternaliInterface call dg startFlow payment_URL 1 function paymentComplete responseText void use responseText to do any customizations vegister the callback method so it can be called via JavaScript ExternaliInterface addCallback paymentCompleteExt paymentComplete Integrating Digital Goods With Flash Third Party Merchant The following is an example of how a third party merchant can integrate digital goods with Flash In the following example use ActionScript 3 0 s LocalConnection in the Flash movie game swf to respond to the payment Digital Goods Integration Guide EC Edition January 2012 51 B Methods For Integrating Digital Goods Into Flash Integrating Digital Goods With Flash Third Party Merchant
57. value in the range of 0 to 9 inclusive Set the value of each field to RecurringPayments L_BILLINGTYPEO RecurringPayments 2 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 3 If there is no associated purchase set PAYMENTREQUEST_0O_AMT to 0 PAYMENTREQUEST_O_AMT 0 Digital Goods Integration Guide EC Edition January 2012 41 42 Handling Recurring Payments Recurring Payments With the Express Checkout API 4 Optional Set MAXAMT to the average expected transaction amount PayPal uses the value you pass to validate the buyer s payment method for recurring payments If you do not specify a value the default is 25 00 The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls Redirecting the Buyer 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 to it https www paypal com cgi bin webscr cmd _express checkout amp token lt
58. you must pass the value Sale default 5 Set PAYMENTREQUEST_O_ITEMAMT to the total of all items in the order 6 Pass values for the following parameters for each item the buyer is purchasing NOTE Even though you passed values for these parameters in the call to SetExpressCheckout you must pass them again in the call to DoExpressCheckoutPayment Otherwise you do not receive the discount rate for digital goods L_PAYMENTREQUEST_0O_NAMEN L_PAYMENTREQUEST_O_AMTn L_PAYMENTREQUEST_O_OQTYnN L_PAYMENTREQUEST_0_ITEMCATEGORYn you must set the value to Digital 7 Examine the values returned if the transaction completes successfully Setting Up Web Pages To Invoke the Digital Goods Payments Flow To invoke the digital goods payments flow follow these steps to add JavaScript to your webpages 1 Add the JavaScript file dg js to your page using the path shown For example lt script src https www paypalobjects com js external dg js lt script gt For best performance place the path to the JavaScript file just before the closing lt body gt element in your page 2 Customize and include the following code after the JavaScript file Replace submitBtn with the ID of your HTML form button lt script gt var dg new PAYPAL apps DGFlow the HTML ID of the form submit button which calls setEC trigger submitBtn th xperience typ
Download Pdf Manuals
Related Search