PayPal Digital Goods User Guide
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. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained 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 f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1 Introducing Digital Goods for Express Checkout . . . . . . 9
Introducing Digital Goods Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Express Checkout Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Digital Goods Payments In More Detail . . . . . . . . . . . . . . . . . . . . . . . . . 10
Digital Goods Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Other Payments Features That Digital Goods Supports. . . . . . . . . . . . . . . . . 16
After Performing Digital Goods Transactions . . . . . . . . . . . . . . . . . . . . . . 16
Features Not Supported With Digital Goods. . . . . . . . . . . . . . . . . . . . . . . 16
Other Digital Goods Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 2 Integrating Digital Goods for Express Checkout . . . . . .19
Overview of Digital Goods Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Integrating Digital Goods Payments With Express Checkout . . . . . . . . . . . . . . . . 22
Setting Up A Digital Goods Payment Transaction. . . . . . . . . . . . . . . . . . . . 22
Redirecting the Buyer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
After PayPal Redirects the Buyer To Your Web Page . . . . . . . . . . . . . . . . . . 25
Completing the Digital Goods Transaction. . . . . . . . . . . . . . . . . . . . . . . . 25
Setting Up Web Pages To Invoke the Digital Goods Payments Flow . . . . . . . . . . 26
Chapter 3 Issuing Refunds . . . . . . . . . . . . . . . . . . . . . . .31
Chapter 4 Handling Recurring Payments . . . . . . . . . . . . . . . .33
How Recurring Payments Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Recurring Payments Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Options for Creating a Recurring Payments Profile . . . . . . . . . . . . . . . . . . . . . 35
Digital Goods Integration Guide - EC Edition January 2012 3
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Identifying Items as Digital or Physical Goods. . . . . . . . . . . . . . . . . . . . . . 37
Recurring Payments With the Express Checkout API . . . . . . . . . . . . . . . . . . . . 38
Initiating the Processing Flow With SetExpressCheckout . . . . . . . . . . . . . . . 41
Redirecting the Buyer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Getting Buyer Details Using GetExpressCheckoutDetails. . . . . . . . . . . . . . . . 42
Creating the Profiles With CreateRecurringPaymentsProfile . . . . . . . . . . . . . . 42
Recurring Payments Profile Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Getting Recurring Payments Profile Information. . . . . . . . . . . . . . . . . . . . . . . 44
Modifying a Recurring Payments Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Updating Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Updating the Billing Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Billing the Outstanding Amount of a Profile . . . . . . . . . . . . . . . . . . . . . . . . . 46
Recurring Payments Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Appendix A Options For Closing the Lightbox or Mini-browser . . . . . 49
Reloading Parent Page to a Specific URL . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Reloading Parent Page by Removing Frames. . . . . . . . . . . . . . . . . . . . . . . . 50
Appendix B Methods For Integrating Digital Goods Into Flash . . . . .51
Integrating Digital Goods With Flash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . 53
SetExpressCheckout NVP Response Fields . . . . . . . . . . . . . . . . . . . . . . 54
GetExpressCheckoutDetails NVP Request Fields . . . . . . . . . . . . . . . . . . . 54
GetExpressCheckoutDetails NVP Response Fields . . . . . . . . . . . . . . . . . . 54
DoExpressCheckoutPayment NVP Request Fields . . . . . . . . . . . . . . . . . . . 56
DoExpressCheckoutPayment NVP Response Fields . . . . . . . . . . . . . . . . . . 56
Express Checkout SOAP API Fields Supported By Digital Goods . . . . . . . . . . . . . 57
SetExpressCheckout SOAP Request Fields . . . . . . . . . . . . . . . . . . . . . . 57
4 January 2012 Digital Goods Integration Guide - EC Edition
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Digital Goods Integration Guide - EC Edition January 2012 5
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.com
Digital Goods Integration Guide - EC Edition January 2012 7
Documentation Feedback
8 January 2012 Digital Goods Integration Guide - EC Edition
Introducing Digital Goods for
1
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. 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 payments
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 9
Introducing Digital Goods for Express Checkout
1
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
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 experience 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 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.
mini No The login page opens in a mini-browser, and a mask is applied
over the underlying web page.
10 January 2012 Digital Goods Integration Guide - EC Edition
Introducing Digital Goods for Express Checkout
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 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 minibrowser) 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 expTyp e 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.
1
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:
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
Introducing Digital Goods for Express Checkout
1
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.
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 payment. 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
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. 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
1
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. The expType varible is set to ‘instant’ and the buyer checked the “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
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. 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
1
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.
After Performing Digital Goods Transactions
After performing digital goods payments transactions, you can use PayPal API operations to
perform the following back-office tasks:
Issue refunds.
Get transaction details.
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.
Physical goods
Digital goods are digital media that the buyer downloads or accesses online.
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
SetCustomerBillingAgreement API
Giropay
Incentives
Several 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.
1
Unsupported Fields in the Recurring Payments and Reference Transaction Name/Value
Pair (NVP) APIs:
SHIPTONAME
SHIPTOSTREET
SHIPTOSTREET2
SHIPTOCITY
SHIPTOSTATE
SHIPTOZIP
SHIPTOCOUNTRY
SHIPTOCOUNTRYCODE
SHIPTOPHONENUM
SHIPPINGAMT
REGULARSHIPINGAMT
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
Introducing Digital Goods for Express Checkout
1
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.
For details on P3P, see the following link:
P3P documentation
Pass all the required Express Checkout API parameter fields in digital goods transactions.
For details, see “Integrating Digital Goods Payments With Express Checkout” on page 22.
18 January 2012 Digital Goods Integration Guide - EC Edition
Integrating Digital Goods for
2
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.paypal-
labs.com/integrationwizard/.
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
Integrating Digital Goods for Express Checkout
2
Overview of Digital Goods Integration
20 January 2012 Digital Goods Integration Guide - EC Edition
Loading...