Integrating Digital Goods for Express Checkout

Note: This integration method for digital goods is Deprecated. For all new integrations, see the Express Checkout Integration Guide.

Learn how to integrate Digital Goods with your website.

Overview of digital goods integration

The following figure summarizes the manual integration steps for the digital goods payments flow. In order to successfully complete the integration, add the digital goods JavaScript to your page, set up code to invoke the digital goods flow, and specify URLs on your site for the return and cancel pages.

The following steps correspond to the steps in the diagram:

  1. Add the dg.js JavaScript (provided by PayPal) to the web page 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 web page.

  2. Place the Pay With PayPal button on the same web page on which you add the dg.js script.

  3. When the buyer clicks Pay With PayPal, call the SetExpressCheckout call.

    Note: Make sure that your API version is 65.1 or later for each PayPal API call that you make. Pass details of the items purchased and other parameter fields required in digital goods transactions. See Set up a digital goods payment transaction for details.

  4. A successful response returns a token to identify the digital goods transaction. You pass the token in subsequent Express Checkout calls related to this transaction.

  5. Redirect the buyer to the digital goods flow. Append the token returned in the SetExpressCheckout 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 DoExpressCheckoutPayment 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.

Integrate digital goods payments

Integrating PayPal digital goods payments with the Express Checkout API requires implementing the following calls: SetExpressCheckout and DoExpressCheckoutPayment. Optionally, you can implement GetExpressCheckoutDetails.

Set 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 later 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: In the SetExpressCheckout call, 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 set-up procedure. To get the discount rate for digital goods, you also must pass these parameters and values in the DoExpressCheckoutPayment call.

To set up the transaction:

  1. Pass the total amount of the payment as PAYMENTREQUEST_0_AMT. If the currency is not in US dollars, you must include the currency. For example:

    PAYMENTREQUEST_0_AMT=amount
    PAYMENTREQUEST_0_CURRENCYCODE=currencyID
    

    Specify the total amount of the transaction. Regardless of the specified currency, the format must have a decimal point. There must be exactly two 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.

  2. If you pass in a tax amount for each item, set PAYMENTREQUEST_0_TAXAMT to the total amount of tax.

  3. Specify the return URL to a page on your site, as follows: 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.

    Note: You can use the return URL to pass parameters between pages on your site.

    For example, to set your return URL to specify additional parameters, use:

    https://www.yourcompany.com/page.html?param=value
    

    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, he or she can confirm payment on PayPal.

    Add the token and the useraction value commit as a name and value pair to the return URL:

    https://www.paypal.com/incontext?token=TOKENReturned&useraction=commit
    
  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.

    CANCELURL=cancel_url
    

    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.

  5. If you pass a value for PAYMENTREQUEST_0_PAYMENTACTION, you must pass the value Sale (default).

  6. Set PAYMENTREQUEST_0_ITEMAMT to the total number of items in the order.

  7. Pass values for the following parameters for each item the buyer is purchasing.

    • L_PAYMENTREQUEST_0_NAMEn
    • L_PAYMENTREQUEST_0_AMTn
    • L_PAYMENTREQUEST_0_QTYn
    • L_PAYMENTREQUEST_0_ITEMCATEGORYn You must set the value to Digital.

    Note: Set L_PAYMENTREQUEST_0_ITEMCATEGORY to Digital for every item in the DoExpressCheckoutPayment request and SetExpressCheckout request. Failing to do so will result in incorrect fee calculations.

  8. Set NOSHIPPING to 1.

  9. Execute the SetExpressCheckout call to set up the Express Checkout transaction.

  10. Test that the response to the SetExpressCheckout call was successful. Upon success, the SetExpressCheckout call returns a token. PayPal uses the token to associate the execution of calls and commands with a specific instance of the checkout experience.

  11. If the SetExpressCheckout call succeeds, 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

This example shows SetExpressCheckout parameters and values for a digital goods payments transaction.

Request parameters

[requiredSecurityParameters]
&METHOD=SetExpressCheckout
&VERSION=65.1
&RETURNURL=http://...
&CANCELURL=http://...
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&PAYMENTREQUEST_0_AMT=200
&PAYMENTREQUEST_0_ITEMAMT=200
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital
&L_PAYMENTREQUEST_0_ITEMCATEGORY1=Digital
&L_PAYMENTREQUEST_0_NAME0=Kitty Antics
&L_PAYMENTREQUEST_0_NAME1=All About Cats
&L_PAYMENTREQUEST_0_QTY0=1
&L_PAYMENTREQUEST_0_QTY1=1
&L_PAYMENTREQUEST_0_AMT0=100
&L_PAYMENTREQUEST_0_AMT1=100

Response parameters

[successResponseFields]
&TOKEN=EC-17C76533PL706494P

Redirect 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 call.

https://www.paypal.com/incontext?token=TOKENReturned

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 payer ID.

  • Cancel URL — If 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 call to obtain details about the buyer to display to your web page.

  2. Call DoExpressCheckout to complete payment.

Complete the digital goods transaction

To complete the digital goods transaction after the buyer approves the order, call the DoExpressCheckoutPayment call. When calling DoExpressCheckoutPayment, do the following:

  1. Pass the token and Payer ID returned by PayPal when it redirected the buyer back to your site.

    TOKEN=tokenValue
    PAYERID=payerId
    
  2. Pass the total amount of the payment as PAYMENTREQUEST_0_AMT. If the currency is not in US dollars, include the currency. Specify the total amount of the transaction. Regardless of the specified currency, the format must have a decimal point. The decimal point must include exactly two 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=currencyID
    
  3. If you passed in a tax amount for each item, set PAYMENTREQUEST_0_TAXAMT to the total amount of tax.

  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.

    • L_PAYMENTREQUEST_0_NAMEn

    • L_PAYMENTREQUEST_0_AMTn

    • L_PAYMENTREQUEST_0_QTYn

    • L_PAYMENTREQUEST_0_ITEMCATEGORYn

      You must set the value to Digital.

    Note: Even though you passed values for these parameters in the SetExpressCheckout call, you must pass them again in the DoExpressCheckoutPayment call. Otherwise, you do not receive the discount rate for digital goods.

  7. Examine the values returned if the transaction completes successfully.

Add JavaScript to your web pages

To invoke the digital goods payments flow, follow these steps to add JavaScript to your web pages:

  1. Add the JavaScript file dg.js to your page, using the path shown. For example:

    <script src="https://www.paypalobjects.com/js/external/dg.js">
    </script>
    

    For best performance, place the path to the JavaScript file just before the closing </body> element in your page.

  2. Customize and include the following code after the JavaScript file. Replace submitBtnID with the ID of your HTML form button.

    <script>
    var dg = new PAYPAL.apps.DGFlow({
      // the HTML ID of the form submit button which calls setEC
      trigger: '<submitBtnID>'
      // the experience type: instant or mini
      expType: 'instant'
    });
    </script>
    

    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.

    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.

    <script>
    if (window.opener){
      window.close();
    }
    else if (top.dg.isOpen() == true){
      top.dg.closeFlow();
    }
    </script>
    

    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 Options For Closing the Lightbox or Mini-browser.

    <!-- Use result of DoEC to send the buyer to the correct page -->
    <!DOCTYPE html>
    <html>
      <head>
        <title></title>
        <script>
        // Sample AJAX code using jQuery (any AJAX
        // library works)
        $.ajax({
          url: '<http://example.com/path_to_fulfillment_content>',
          type: 'GET',
          error: function () {
            // Handle error cases
          },
          success: function (response){
            // Replace content on page, initiate
            // download, etc.
          }
        });
        </script>
      </head>
      <body>
        <!-- Include non-JavaScript content here -->
        If this page does not redirect <a href="[page to deliver content
        to non-JS customer]">Click Here</a>
      </body>
    </html>
    

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.

The following list shows the signatures for the JavaScript functions:

  • PAYPAL.apps.DGFlow = function ({trigger: HTML_id_of_event_triggering_flow expType: experience_type})

    Configures the digital goods payment flow.

    Set the experience type variable, expType, to:

    • instant–DG flow in lightbox, with overlay mask
    • mini–DG flow in mini-browser with overlay mask
    • popup–DG flow in mini-browser

    Note: Leave expType unset for the legacy DG flow.

  • setTrigger: function (id)

    Adds a trigger for the flow, where id is the HTML ID of the event that triggers the flow. To set up the flow, first call PAYPAL.apps.DGFlow.

  • startFlow: function (url)

    Explicitly starts the digital goods flow, where url is the URL that triggers 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.

Example merchant page with digital goods JavaScript

The following example shows the HTML code on the merchant page:

<html>
  <head>
    <meta charset="utf-8" />
    <title></title>
    <style type="text/css"></style>
  </head>
  <body>
    <!-- Custom merchant code (path to merchant app, etc.) -->
    <h1>El Jefe's Tours</h1>
    <!--  This example uses the Sandbox (testing) NVP endpoint -->
    <form action="https://api-3t.sandbox.paypal.com/nvp" method="post">
    <p>
    <input id="submitBtn" type="submit" value="Pay with PayPal" />
    <input type="hidden" name="success_url" value="<path to successURL>" />
    <input type="hidden" name="cancel_url" value="<path to cancelURL>">
    </p>
    </form>
    <!-- End custom merchant code -->
    <script
      src="https://paypalobjects.com/js/external/dg.js">
    </script>
    <script>
      var dg = new PAYPAL.apps.DGFlow({
      // HTML ID of form submit buttons that call setEC
      trigger:'submitBtn',
      expType:'instant'
      });
    </script>
  </body>
</html>