Google Checkout HTML API - Digital Delivery

Overview

This page explains how to include digital items in Google Checkout orders and then deliver those items to your customers. Please note that Checkout orders can combine digital and physical items.

Digital Delivery Options

Google Checkout provides several options for you to digitally deliver goods for an order. You can determine when the buyer will be able to access the digital content as well as how to communicate instructions for accessing the content. The following list describes these delivery options:

• Delivery schedule – you can specify when the buyer will receive instructions for accessing the purchased digital content. Google defines two delivery schedule options:

  • Pessimistic delivery occurs when the buyer cannot access purchased digital content until his credit card has been authorized to be charged for the amount of the order. By default, Google Checkout uses pessimistic delivery when processing orders.

    Typically, pessimistic delivery introduces a delay of several seconds between the time that a buyer confirms the order and the time that the buyer receives instructions for accessing the digital content. The Understanding the Buyer Experience for Digital Delivery section of this document describes this process in further detail.

  • Optimistic delivery occurs when the buyer receives instructions for accessing the digital content even if Google cannot obtain a valid credit card authorization within 20 seconds. We recommend that you only use optimistic delivery if you can easily revoke access to the digital content if Google cannot authorize the customer's credit card.

• Delivery method – you can specify how instructions for accessing the digital content will be communicated to the buyer. Google supports three delivery methods:

  • Email delivery occurs when you email the buyer instructions for accessing the digital content. You can send the email any time after the customer completes the order. Since you are responsible for sending the buyer instructions for accessing the digital content, the delivery schedule is not necessarily relevant for orders that use email delivery. You can send instructions for accessing the digital content as soon as you receive the order or you can wait until the order becomes chargeable.

    Please note that this delivery option may offer a poor customer experience since the customer may not know when he will be able to access the purchased digital content.

    You should choose email delivery for digital content if you meet either of the following criteria:

    • You submit orders to Google Checkout using the HTML API.

    • You submit XML shopping carts by digitally signing the shopping cart and then including the base64-encoded cart and the digital signature in a form on the web page displayed to the buyer.

  • Key/URL delivery occurs when you embed information for accessing the digital content in your Checkout API request. For key/URL delivery, you must provide either a URL where the buyer can access the digital content or a key needed to download or unlock the content. (You may provide a key and a URL.) You may also provide additional instructions for the buyer. Google Checkout will display the key, URL and additional instructions after the buyer completes the order. (If you are using pessimistic delivery, Google will wait until the buyer's credit card is authorized before displaying this information.)

    Key/URL delivery will work best for you if you meet both of the following criteria:

    • To access your content, someone needs to have an access key or URL that authorizes access to your content.

    • You use the server-to-server method for posting Checkout API requests to Google. Key/URL delivery requires you to include instructions for accessing digital content directly in the Checkout API request. The server-to-server method ensures that unscrupulous customers cannot obtain the information needed to access your digital content just by looking at the hidden <input> parameters on your web page.

  • Description-based delivery also occurs when you embed information for accessing the digital content in your Checkout API request. You should consider using description-based delivery in either of the following circumstances:

    • You need to provide multiple keys or access URLs per item. (Key/URL delivery allows you to provide a maximum of one key and one URL.)

    • You do not require users to have a special key or URL to access digital content but still want to deliver instructions for accessing purchased content in the Google Checkout order flow. For example, you might use description-based delivery to sell additional storage for an online photo-sharing account.

      In this use case, description-based delivery offers a slightly better buyer experience than email delivery since the buyer receives information about accessing the digital content on the Order Confirmation page.

    The following guidelines may help you to implement description-based delivery:

    • If your description includes instructions for accessing the purchased digital content, then you should use the server-to-server method for posting Checkout API requests to Google. For example, if you sell special abilities for characters in a video game, you might provide instructions for entering a password into the game. In this case, you would want to prevent the buyer from accessing the password until the buyer had completed his order. The server-to-server method of submitting API requests would ensure that the buyer could not obtain the password without completing the order.

    • If you do not need to be concerned that the buyer might obtain the information in the description even if the purchase is not completed, then you can use hidden <input> fields to include your Checkout API request directly on your web page. In this use case, the buyer could only access the digital content after you had processed the buyer's order. For example, if you are selling additional account storage, your instructions might indicate that the storage will be available within 24 hours. (This description might reflect the time that you would normally need to process a completed order for additional storage.)

Identifying Digital Goods in Checkout API Requests

This section explains how to embed digital content within a Checkout API request.

Note: If you embed digital content in your Checkout API request, Google recommends that you use the server-to-server method of posting order information to Google. For more information about server-to-server posts, please see the instructions for Submitting Server-to-Server Checkout API Requests in the Google Checkout XML API Developer's Guide.

This section explains several HTML parameters that enable you to embed digital content in Checkout API requests. The following list identifies these parameters. In addition, Appendix B provides complete definitions for each parameter in the list.

• The display-disposition parameter specifies when the buyer will be able to access the digital content.

  • If the value of the display-disposition parameter is PESSIMISTIC, the buyer will only see the information needed to download the content on the Thank You page if Google is able to authorize the buyer's credit card for the full order amount within 20 seconds. After the buyer's credit card has been authorized, the information needed to access the digital content will also display on the buyer's Order History page.

  • If the value of the display-disposition parameter is OPTIMISTIC, Google Checkout will display the information that the buyer needs to download the content on the Thank You page, which displays after the customer places an order. Before displaying the Thank You page, Google will attempt to authorize the buyer's credit card. However, Google will display instructions for downloading the digital content even if Google cannot obtain a valid credit card authorization within 20 seconds. The information needed to access the digital content will also display on the buyer's Order History page.

• The description parameter contains instructions for downloading a digital content item. Note: Please use the <item-description> parameter to provide the description of the item that is being purchased. As shown in the example below, the description tag's value may contain escaped HTML tags.

• The email-delivery parameter indicates that you will email the customer instructions for accessing your digital content. This tag is only used for email delivery. You should email the buyer after Google successfully authorizes the customer's credit card. If you have implemented the Notification API, you should email the customer after you receive the new order notification for the order and the order state change notification informing you that the order's financial state has been updated to CHARGEABLE.

• The key parameter contains a key needed to download or unlock a digital content item. You must provide a non-empty value for either the key parameter or the url parameter. This parameter is only used for key/URL delivery.

• The url parameter specifies a URL from which the customer can download or access the purchased content. You must provide a non-empty value for either the key parameter or the url parameter. This parameter is only used for key/URL delivery.

The following HTML excerpts demonstrate how these parameters are used. Parameters used for digital delivery are shown in bold text.

Email Delivery

<form method="POST"
    action="https://sandbox.google.com/checkout/api/checkout/v2/checkoutForm/Merchant/1234567890"
    accept-charset="utf-8">

  <input type="hidden" name="item_name_1" value="Super Software 5000"/>
  <input type="hidden" name="item_description_1" value="Improves download speeds!"/>
  <input type="hidden" name="item_price_1" value="1.00"/>
  <input type="hidden" name="item_currency_1" value="USD"/>
  <input type="hidden" name="item_quantity_1" value="1"/>

  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.display-disposition"
    value="OPTIMISTIC"/>
  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.email-delivery" value="true"/>

  <input type="hidden" name="_charset_"/>
  <input type="image" name="Google Checkout"
    src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=MERCHANT_ID&w=180&h=46&style=white&variant=text&loc=en_US"
    height="46" width="180"/>
</form>

Key/URL Delivery

<form method="POST"
    action="https://sandbox.google.com/checkout/api/checkout/v2/checkoutForm/Merchant/1234567890"
    accept-charset="utf-8">

  <input type="hidden" name="item_name_1" value="Super Software 5000"/>
  <input type="hidden" name="item_description_1" value="Improves download speeds!"/>
  <input type="hidden" name="item_price_1" value="1.00"/>
  <input type="hidden" name="item_currency_1" value="USD"/>
  <input type="hidden" name="item_quantity_1" value="1"/>

  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.display-disposition"
    value="OPTIMISTIC"/>
  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.description"
    value="Please go to &amp;lt;a href="http://supersoft.example.com"&amp;gt;our website&amp;lt;/a&amp;gt;,
      and enter your access key so that you can download our software."/>
  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.key"
    value="1456-1514-3657-2198"/>
  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.url"
    value="http://supersoft.example.com"/>

  <input type="hidden" name="_charset_"/>
  <input type="image" name="Google Checkout"
    src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=MERCHANT_ID&w=180&h=46&style=white&variant=text&loc=en_US"
    height="46" width="180"/>
</form>

Description-based Delivery

<form method="POST"
    action="https://sandbox.google.com/checkout/api/checkout/v2/checkoutForm/Merchant/1234567890"
    accept-charset="utf-8">

  <input type="hidden" name="item_name_1" value="Super Software 5000"/>
  <input type="hidden" name="item_description_1" value="Improves download speeds!"/>
  <input type="hidden" name="item_price_1" value="1.00"/>
  <input type="hidden" name="item_currency_1" value="USD"/>
  <input type="hidden" name="item_quantity_1" value="1"/>

  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.display-disposition"
    value="OPTIMISTIC"/>
  <input type="hidden"
    name="shopping-cart.items.item-1.digital-content.description"
    value="It may take up to 24 hours to process your new storage. You will
      be able to see your increased storage on your
      &amp;lt;a href="http://login.example.com"&amp;gt;account page&amp;lt;/a&amp;gt;."/>

  <input type="hidden" name="_charset_"/>
  <input type="image" name="Google Checkout"
    src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=MERCHANT_ID&w=180&h=46&style=white&variant=text&loc=en_US"
    height="46" width="180"/>
</form>

Understanding the Buyer Experience for Digital Delivery

The following screenshots illustrate the buyer's experience in completing an order for digitally delivered goods.

• Place Order page for digital delivery
• Interstitial page for authorizing the buyer's credit card
• Order Confirmation page for email delivery
• Order Confirmation page for key/URL delivery
• Order Confirmation page for description-based delivery
• Order History page

Place Order page for digital delivery

The image below shows the Place Order page, where your customer selects the credit card to use for the order. If the buyer only orders digital goods, your Checkout API request does not need to specify shipping methods. In the image, the Place Order page does not list shipping methods or the customer's shipping address.

Interstitial page for authorizing the buyer's credit card

Google Checkout tries to authorize the buyer's credit card before displaying instructions that explain how to access the purchased content. The following screenshot illustrates the page that the buyer will see while Google completes the credit card authorization. Typically, it takes several seconds for Google to obtain a credit card authorization.

In rare cases, Google may not be able to authorize the buyer's credit card within 20 seconds.

• If you are using optimistic delivery, the buyer will progress to one of the Order Confirmation pages described below.

• If you are using pessimistic delivery, Google Checkout will display a page indicating that the buyer should check the Order History page, which is shown below, for up-to-date order status information. Once the buyer's credit card has been authorized, any information that would normally have displayed on the Order Confirmation page – including a key, URL, description or notification that the buyer will receive access instructions via email – will display on the Order History page.

  

Order Confirmation page for email delivery

The image below shows the Order Confirmation page for an order in which the merchant uses email delivery to send access instructions to the buyer. The text in the yellow box indicates that the merchant will email the customer with instructions for accessing the purchased digital content.

Order Confirmation page for key/URL delivery

The image below shows the Order Confirmation page for an order in which the merchant uses key/URL delivery to provide access instructions to the buyer. The yellow box in the image displays three lines of text:

• The first line represents the value of the description parameter.
• In the second line of text, the value "1234-5678" represents the value of the key parameter. Google Checkout automatically inserts the text, "Your license key is" prior to the actual key value.
• In the third line of text, the url parameter's value is the target of the link. Google Checkout provides the anchor text – "Click here to retrieve your purchase."

Please note that the description is optional and that, since the description may include HTML, it may include links. In addition, you do not need to provide both a key and a URL, though you must provide at least one of those two values for key/URL delivery.

Order Confirmation page for description-based delivery

The image below shows the Order Confirmation page for an order in which the merchant uses description-based delivery to provide access instructions to the buyer. Please note that since the description may include HTML, it may include links as shown in the image.

Order History page

The image below shows the Order History page, which displays information about a completed order. If you are using key/URL delivery or description-based delivery, the buyer's Order History page will display any access instructions that you communicated in the Checkout API request for the order. The image below shows the Order History page for the order shown in the order confirmation page for key/URL delivery.

Selling Multiple Quantities of the Same Item

We recommend that you use email delivery if you sell multiple licenses for the same digital item in a single order. The multiple licenses could be bundled as an individual item, such as a five-user license to a software application, or the licenses could be combined in a single line item by adjusting the value of the item_quantity_# parameter for the item.

The Checkout XML schema allows you to provide a maximum of one license key and one URL with each digital item. As such, the Order Confirmation page will not display multiple license keys or URLs for a single item. Email delivery enables you to ensure that access instructions for multiple licenses are clearly communicated to the buyer.

Checklist for Launching this Feature

The following checklists will help you to ensure that you have implemented digital delivery correctly. The checklist is divided into different sections for merchants doing email delivery, key/URL delivery and description-based delivery, respectively.

• Email Delivery

  • Confirm that your Checkout API request contains the email-delivery parameter for each digital item.

  • Verify that the Checkout API request does not provide values for the key or url parameters. Please note that an HTML request that includes either of those parameters in addition to the email-delivery parameter is valid according to the XML schema. However, combining these parameters with the email-delivery parameter may create a confusing experience for your customer.

  • Confirm that your order handling process supports emailing the customer after Google successfully authorizes the customer's credit card. If you have implemented the Notification API, you should email the customer with instructions for accessing the customer after you receive the new order notification for the order and the order state change notification informing you that the order's financial state has been updated to CHARGEABLE.

  • Confirm that your Checkout API request specifies shipping methods if the customer's order contains both digital and physical goods. Please note that Google Checkout will not display shipping options to the buyer if the order only contains digital items.

• Key/URL Delivery

  • Confirm that you are posting Checkout API requests using the server-to-server posting method. For Key/URL delivery, this posting method ensures that customers cannot steal the information needed to access your digital content directly off of your web pages.

  • If your Checkout API request includes the key parameter, verify that the value of that parameter is a non-NULL value. The Order Confirmation page will display text indicating that there is a key even if the key parameter contains a NULL value.

  • If you are providing a value for the url parameter, confirm that the parameter value is a valid URL.

  • Confirm that any HTML tags in the description parameter value are XML-escaped properly.

  • Confirm that your Checkout API request specifies shipping methods if the customer's order contains both digital and physical goods. Please note that Google Checkout will not display shipping options to the buyer if the order only contains digital items.

  • If you want to use optimistic delivery, verify that the display-disposition parameter is set to OPTIMISTIC. Google Checkout's default behavior is to use pessimistic delivery, which means that Google does not display information that explains how to access purchased digital content until the buyer's credit card has been authorized.

• Description-based Delivery

  • Confirm that your Checkout API request specifies a value for the description parameter for each digital item.

  • Confirm that any HTML tags in the description value are XML-escaped properly.

  • Confirm that your Checkout API request specifies shipping methods if the customer's order contains both digital and physical goods. Please note that Google Checkout will not display shipping options to the buyer if the order only contains digital items.

  • If you want to use optimistic delivery, verify that the display-disposition parameter is set to OPTIMISTIC. Google Checkout's default behavior is to use pessimistic delivery, which means that Google does not display information that explains how to access purchased digital content until the buyer's credit card has been authorized.

HTML Parameter Definitions