| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
This page explains how to include digital items in Google Checkout orders and then deliver those items to your customers. Checkout orders can combine digital and physical items. Please note that orders that contain digitally delivered items are not covered by Google Checkout's payment guarantee.
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 base64-decoding the shopping cart data on your web page.
Description-based delivery 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 a digitally signed cart 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.)
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 XML tags that enable you to embed digital content in Checkout API requests. The following list identifies these tags. In addition, the XML Tag Definitions section provides complete definitions for each tag in the list.
The <digital-content> tag is a subtag of <item> that contains information relating to digital delivery of an item. If you are using the embedded delivery option, then this tag is required for the item that will be digitally delivered.
The <display-disposition> tag specifies when the buyer will be able to access the digital content.
If the value of the <display-disposition> tag 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> tag 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> tag contains instructions for downloading a digital content item. Note: Please use the <item-description> tag to provide the description of the item that is being purchased. As shown in the example below, the <description> tag's value may contain XML-escaped HTML tags.
The <email-delivery> tag 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> tag contains a key needed to download or unlock a digital content item. You must provide a non-empty value for either the <key> tag or the <url> tag. This tag is only used for key/URL delivery.
The <url> tag 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> tag or the <url> tag. This tag is only used for key/URL delivery.
The following XML excerpts demonstrate how these tags are used. Tags used for digital delivery are shown in bold text.
|
<?xml version="1.0" encoding="UTF-8"?>
<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
<shopping-cart>
<items>
<item>
<item-name>Super Software 5000</item-name>
<item-description>Super Software 5000 improves download speeds.</item-description>
<unit-price currency="USD">1.00</unit-price>
<quantity>1</quantity>
<digital-content>
<display-disposition>OPTIMISTIC</display-disposition>
<email-delivery>true</email-delivery>
</digital-content>
</item>
</items>
</shopping-cart>
<checkout-flow-support>
<merchant-checkout-flow-support/>
</checkout-flow-support>
</checkout-shopping-cart>
<?xml version="1.0" encoding="UTF-8"?>
<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
<shopping-cart>
<items>
<item>
<item-name>Super Software 5000</item-name>
<item-description>Super Software 5000 improves download speeds.</item-description>
<unit-price currency="USD">1.00</unit-price>
<quantity>1</quantity>
<digital-content>
<display-disposition>OPTIMISTIC</display-disposition>
<description>
Please go to &lt;a href="http://supersoft.example.com"&gt;our website&lt;/a&gt;,
and enter your access key so that you can download our software.
</description>
<key>1456-1514-3657-2198</key>
<url>http://supersoft.example.com</url>
</digital-content>
</item>
</items>
</shopping-cart>
<checkout-flow-support>
<merchant-checkout-flow-support/>
</checkout-flow-support>
</checkout-shopping-cart>
<?xml version="1.0" encoding="UTF-8"?>
<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
<shopping-cart>
<items>
<item>
<item-name>Super Software 5000</item-name>
<item-description>Super Software 5000 improves download speeds.</item-description>
<unit-price currency="USD">1.00</unit-price>
<quantity>1</quantity>
<digital-content>
<display-disposition>OPTIMISTIC</display-disposition>
<description>
It may take up to 24 hours to process your new storage. You will
be able to see your increased storage on your
&lt;a href="http://login.example.com"&gt;account page&lt;/a&gt;.
</description>
</digital-content>
</item>
</items>
</shopping-cart>
<checkout-flow-support>
<merchant-checkout-flow-support/>
</checkout-flow-support>
</checkout-shopping-cart>
The following screenshots illustrate the buyer's experience in completing an order for digitally delivered goods.
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.
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.
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.
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:
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.
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.
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.
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 <quantity> tag 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.
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 specifies <email-delivery>true</email-delivery> for each digital item.
Verify that the Checkout API request does not provide values for the <key> or <url> tags. Please note that an XML request that includes either of those tags in addition to the <email-delivery> tag is valid according to the XML schema. However, combining these tags with the <email-delivery> tag 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> tag, verify that the value of that tag is a non-NULL value. The Order Confirmation page will display text indicating that there is a key even if the <key> tag contains a NULL value.
If you are providing a value for the <url> tag, confirm that the tag value is a valid URL.
Confirm that any HTML tags in the <description> tag 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> tag 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> tag 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> tag 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.
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| description | |
| Definition | As a subtag of <digital-content>, the <description> tag contains instructions for downloading a digital content item. Please use the <item-description> tag to provide the description of the item being purchased. Note: This field has a maximum length of 1024 characters and may contain HTML tags. (HTML tags must be XML-escaped as described in the Google Checkout Developer's Guide.) As a subtag of <promotion>, the <description> tag contains information about a promotion that Google applied to an order. |
| Subtag of | digital-content, promotion |
| Content Format | String |
| Example | <description>To download this item, link to the URL below and follow the instructions there. When prompted, enter the software key provided below.</description> |
| digital-content | |
| Definition | The <digital-content> tag contains information relating to digital delivery of an item. |
| Subtag of | item |
| Subtags | description?, email-delivery?, key?, url?, display-disposition? |
| Content Format | Container |
| Example | <digital-content> |
| display-disposition | |
| Definition | The <display-disposition> tag specifies when the buyer will be able to access purchased digital content. The only valid values for this tag are OPTIMISTIC and PESSIMISTIC.
The default value for this tag is PESSIMISTIC. |
| Subtag of | digital-content |
| Content Format | String |
| Example | <display-disposition>OPTIMISTIC</display-disposition> |
| email-delivery | |
| Definition | The <email-delivery> tag indicates that the merchant will send email to the buyer explaining how to access the digital content. Email delivery allows the merchant to charge the buyer for an order before allowing the buyer to access the digital content. |
| Subtag of | digital-content |
| Content Format | Boolean |
| Example | <email-delivery>true</email-delivery> |
| key | |
| Definition | The <key> tag contains a key needed to download or unlock a digital content item. |
| Subtag of | digital-content |
| Content Format | String |
| Example | <key>ad8x-15ss-gs9x-as91</key> |
| url | |
| Definition | The <url> tag contains a URI from which the customer can download the purchased content. |
| Subtag of | digital-content |
| Content Format | String |
| Example | <url>http://download.example.com/key/124194</url> |