Digital Goods Integration Guide - EC Edition Last updated: January 2012
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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Specifying the Regular Payment Period . . . . . . . . . . . . . . . . . . . . . . . . . 35 Including an Optional Trial Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Specifying an Initial Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Maximum Number of Failed Payments . . . . . . . . . . . . . . . . . . . . . . . . . 37 Billing the Outstanding Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents SetExpressCheckout SOAP Response Fields . . . . . . . . . . . . . . . . . . . . . 58 GetExpressCheckoutDetails SOAP Request Fields . . . . . . . . . . . . . . . . . . 58 GetExpressCheckoutDetails SOAP Response Fields . . . . . . . . . . . . . . . . . 59 DoExpressCheckoutPayment SOAP Request Fields . . . . . . . . . . . . . . . . . . 60 DoExpressCheckoutPayment SOAP Response Fields . . . . . . . . . . . . . . . . . 61 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 Merchant Setup and Administration Guide Documentation Feedback Help us improve this guide by sending feedback to: documentationfeedback@paypal.
Documentation Feedback 8 January 2012 Digital Goods Integration Guide - EC Edition
1 Introducing Digital Goods for Express Checkout Digital Goods for Express Checkout streamlines the checkout process for buyers and keeps buyers on your website. “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.
1 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 NOT E : Do not host copies of the PayPal images locally on your servers.
Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments expType popup (not set) NOT E : 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. 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 page.
1 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 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. IM PORT AN T : Opting in to the remember me behavior does not guarantee that the buyer will not be asked to provide log-in credentials.
Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 1 If the buyer chooses Cancel, PayPal redirects the buyer’s browser to the cancel URL specified in the SetExpressCheckout API operation’s request message.
1 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 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.
Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 1 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.
1 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments Other Payments Features That Digital Goods Supports You can use digital goods with the following payments features: Recurring payments. Some Express Checkout fields 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.
Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments 1 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.
1 Introducing Digital Goods for Express Checkout Introducing Digital Goods Payments PostalCode Country Phone ShippingAmount Other Digital Goods Caveats Observe the following notes when integrating digital goods: 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.
2 Integrating Digital Goods for Express Checkout This chapter describes how to integrate Digital Goods for Express Checkout with your website. “Overview of Digital Goods Integration” on page 19 “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: Merchants using PHP can use the PHP Wizard, located here: https://www.paypallabs.com/integrationwizard/.
2 20 Integrating Digital Goods for Express Checkout Overview of Digital Goods Integration January 2012 Digital Goods Integration Guide - EC Edition
Integrating Digital Goods for Express Checkout Overview of Digital Goods Integration 2 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.
2 Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout I n t e g r a t i n g D i g i ta l G o o d s P a y m e n ts Wit h E x p r e s s Checkout Integrating PayPal digital goods payments with the Express Checkout API requires implementing the following API operations: SetExpressCheckout and DoExpressCheckoutPayment. Optionally, you can implement GetExpressCheckoutDetails.
Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout 2 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 (https://...) on your site. NOT E : You can use the return URL to pass parameters between pages on your site.
2 Integrating Digital Goods 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.
Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout 2 After the buyer approves the payment or cancels, PayPal redirects back to the return or cancel URL: Return URL—If 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).
2 Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout 4. If you pass a value for PAYMENTREQUEST_0_PAYMENTACTION, you must pass the value Sale (default). 5. Set PAYMENTREQUEST_0_ITEMAMT to the total of all items in the order. 6. Pass values for the following parameters for each item the buyer is purchasing.
Integrating Digital Goods for Express Checkout Integrating Digital Goods Payments With Express Checkout NOT E : 2 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.