Google Checkout XML API for Political Organizations

Introduction to Google Checkout

Google Checkout allows visitors to your website to make contributions to your campaign quickly and securely using a Google username and password. Google will automatically charge contributors' credit cards for their contributions, and you can use Google Checkout's online Merchant Center or the Google Checkout APIs to track contributions.

Google Checkout can be used by federal candidates and political action committees (PACs) that are registered with the Federal Election Commission (FEC).

About this Document

This document provides an overview of the Google Checkout XML API and explains the basics of how to integrate your website with Google Checkout. Many sections of this document, in turn, link to additional documentation that explains a specific aspect of the XML API in greater detail.

This document contains the following sections:

• The Contributor Experience section explains how contributors complete contributions using Google Checkout and provides screenshots of the Google Checkout user interface for contributors.

• The Getting Started with Google Checkout section explains how to sign up with Google Checkout. This section also explains how to create Google Checkout buttons that contributors can click on to make a contribution.

• The Technical Overview explains the different components of the Google Checkout XML API and discusses different Checkout integration options. This section also contains a technical discussion that explains how you convey contribution information to Google and then track contributions made through Google Checkout. Finally, this section describes Google's policy for authorizing and charging contributors' credit cards.

• The API Reference section explains how to submit API requests to Google and also explains the responses that Google sends to an API request. This section also describes a Google Checkout diagnostic feature that lets you verify that an API request contains valid XML. Finally, this section explains how to use HTTP Basic Authentication to send certain types of API requests.

• The Checkout API, Notification API and Order Processing API sections provide specific details about the different Google Checkout APIs.

• The Using the Google Checkout Merchant Center section describes Google's online interface for managing contributions.

• The Testing and QA section discusses different resources that can help you to test your Google Checkout integration.

Note: The XML Element Reference for Political Organizations also defines all of the XML elements in the Google Checkout XML schema that would be used to process contributions in Google Checkout.

Contributor Experience

This section describes a contributor's experience in completing a contribution with Google Checkout. During this process, the contributor progresses through four different pages beginning with a page on your site that displays a Google Checkout button and culminating with the Google Checkout Contribution Confirmation page.

The following steps explain the contributor's experience on these pages.

1. The process of making a contribution through Google Checkout begins when a contributor visits your site and identifies the contribution she would like to make, which is added to a virtual shopping cart. When the contributor is ready to complete her contribution, she will click a Google Checkout button that displays on your web pages next to your other options for completing a contribution. The button will be contained within a form on your page.

2. When the contributor clicks the Google Checkout button, the contributor's browser will submit the virtual shopping cart information to Google. Google Checkout will then display the Sign In/Sign Up page, which shows the contribution. The page may show multiple contributions if the contributor has added more than one contribution to the virtual shopping cart. The Sign In/Sign Up page, which is shown below, also allows the contributor to create a new Google Account or log in to an existing account.

   

   If Google detects a cookie indicating that the contributor already has a Google Account and the account already contains credit card information, the right side of this page will display the email address for that account. In this case, the contributor will only need to enter the password for that account. If the contributor has recently shopped with Google Checkout and has a valid cookie, the Sign In/Sign Up page may not appear at all, in which case the contributor will proceed directly to the Place Order page. The interface will also change slightly for contributors who have a Google Account but do not have a credit card associated with their account.

3. After the contributor creates a new Google Account or signs in to an existing account, Google will display the Contribution Details page. This page, which is shown below, lists the items in the contribution. The Contribution Details page also lets the contributor choose the credit card to charge for the contribution and whether to share her email address with the organization or receive promotional email from the organization. Finally, the Place Order page displays Google's billing policy.

   

   Email Address Sharing and Forwarding

   When a transaction occurs, Google always provides you with an email address to contact the contributor. You can send correspondence to the contributor's email address for order processing issues and, if the contributor consented to receive promotional email, for marketing purposes (see Google Checkout Program Policies and Guidelines, section 1).

   As shown in the screenshot of the Contribution Details page shown above, Google does offer contributors the option of keeping their email address confidential. Depending on the contributor's preferences, Google will send you either the email address that the contributor used to register with Google or an email address that forwards through Google to the contributor's registered email address. If the contributor prefers to forward email through Google and decides that he or she no longer wants to receive email from a specific organization, the contributor can deactivate email forwarding from a specific organization at any time.

4. When the contributor clicks the Complete your contribution button on the Contribution Details page, Google starts to process the contribution and displays the Contribution Confirmation page. This page thanks the contributor for completing the contribution and also displays a link to your site so the contributor can learn more about your organization and then, hopefully, make some more contributions.

   

After a contributor completes a contribution, Google will post a receipt for the contribution in the contributor's Google Checkout Order History. The screenshot below shows a contribution receipt:

Getting Started with Google Checkout

This section explains how to become a Google Checkout merchant and begin to integrate your online store.

1. Go to http://sandbox.google.com/checkout/sell/ to set up test accounts in the Google Checkout Sandbox service. The Sandbox is a development environment that is designed to help you test your Google Checkout implementation. The Sandbox offers the same functionality as the production Google Checkout system with the following exceptions:

   • The Sandbox requires you to use test credit card numbers.
   • The Sandbox does not actually execute debits and credits.
   • The Sandbox user interface displays an overlay that indicates you are working in the Sandbox environment.

   You need to create two test accounts in the Sandbox. One of these accounts will function as a contributor account and the other will function as your organization account. Please note that Google Checkout will not let you use your organization account to complete a contribution to your own organization. (In other words, the same account can not function as both the contributor and the organization for the same transaction.) In addition, you need to provide different information to create these two accounts.

   • Create your contributor account at http://sandbox.google.com/checkout.
   • Create your organization account at http://sandbox.google.com/checkout/sell/.

   The following guidelines explain how to set up your test accounts:

   • Skip any sections that ask for your bank account information. Since the Sandbox system does not process billing or payments, this information is not necessary when you are testing your implementation.

   • Enter any name and address as long as the State field contains a valid two-letter abbreviation for a U.S. state and the Zip Code field contains a five-digit or nine-digit zip code. (You do not need to enter the correct zip code for the address.)

   • Enter any 10-digit phone number for the Phone Number field.

   • Enter any value in either the Federal tax ID or Social Security number fields.

   • Use one of the credit card numbers in the following table:

     Card Type	Card Number	CVC	Expiration Date
     American Express	3782 8224 6310 005	any four digits	any future date
     Discover	6011 1111 1111 1117	any three digits	any future date
     MasterCard	5555 5555 5555 4444	any three digits	any future date
     VISA	4111 1111 1111 1111	any three digits	any future date

2. Go to http://checkout.google.com/sell/signup to sign up for a Google Checkout organization account. Complete the sign-up process and provide valid values for all fields. You will need the federal tax ID number for your organization or a credit card and your Social Security number.

3. Sign in to the accounts that you created in steps 1 and 2 to set your status as a political organization. After signing in to each account, click on the Settings tab. Then click on the Profile link on the left side of the page. Locate the Primary product type pulldown menu and select either Political Organization (federal candidate) or Political Organization (political action committee) from that menu. You may see a yellow box appear indicating that Google needs to verify your status as a political organization. If this box does appear, please follow the instructions and provide Google with the necessary materials to confirm your status. When you are finished, click the Save profile button at the bottom of the page.

4. Sign in to the accounts that you created in steps 1 and 2 to locate the Merchant ID and Merchant Key for each account. You will need these values to create Google Checkout buttons and to send API requests to Google Checkout. After signing in to each account, click on the Settings tab. Then click on the Integration link on the left side of the page. Your 10- or 15-digit Merchant ID and your Merchant Key will both be listed under the Account information header.

   You should never share your Merchant Key with anyone. Google uses your Merchant Key to authenticate your API requests, and no Google representative will ever ask you for your Merchant Key.

5. This step is optional. You can use curl (or a similar tool) to verify that your server communicates properly with Google Checkout. To complete this test, enter the following commands on one line each in your terminal window. Replace the MERCHANT_ID and MERCHANT_KEY strings with the Merchant ID and Merchant Key for your Sandbox account. Replace the same strings in command 2 with the Merchant ID and Merchant Key for your Google Checkout merchant account.

   Command 1:
   curl -d '<hello xmlns="http://checkout.google.com/schema/2"/>'
     https://MERCHANT_ID:MERCHANT_KEY@sandbox.google.com/checkout/api/checkout/v2/request/Political/MERCHANT_ID
   
   Command 2:
   curl -d '<hello xmlns="http://checkout.google.com/schema/2"/>'
     https://MERCHANT_ID:MERCHANT_KEY@checkout.google.com/api/checkout/v2/request/Political/MERCHANT_ID
   

   Google Checkout will respond to each command with the <bye> response. If you do not receive this type of response, then Google Checkout did not properly process your request. For example, if you receive an error response, that response should specify the reason that your request failed. If you do not receive a response at all, then your server may be unable to communicate with Google Checkout. The following XML excerpt shows a sample <bye> response:

   <?xml version="1.0" encoding="UTF-8"?>
   <bye xmlns="http://checkout.google.com/schema/2"
      serial-number="c567262a-dd13-4084-b8d3-6ccfbbc69d03" />
   

6. Add a Google Checkout button to the pages on your website where people can make contributions. The button needs to be embedded in a form in the HTML for your pages. The button should appear next to your existing contribution buttons. Note: You may add more than one Google Checkout button to your page.

7. Modify the code for your website so that the form containing the Google Checkout button also submits information about the contributor's gift.

   Your code needs to create an XML document containing information about the contribution. Your code will need to encrypt the XML document and embed the encrypted value in the form that contains the Google Checkout button.

   The Checkout API section provides instructions for creating the XML. In addition, the Sending Contribution Information to Google Checkout section explains how to encrypt your XML document and include it in the form on your checkout page.

• In your development environment, your form needs to submit contributions to the following URL. You must replace the text MERCHANT_ID with the Merchant ID from your Sandbox account.

  <form method="POST"
      action="https://sandbox.google.com/checkout/api/checkout/v2/checkout/Political/MERCHANT_ID">

  Note: Your production account will have a different Merchant ID and Merchant Key than your Sandbox account. Your code should use the values from the Sandbox account when communicating with the Google Checkout Sandbox service. Similarly, your code should use the values from your production account when communicating with the Google Checkout production service.

• Your production system will submit contributions to the following URL. You must replace the text MERCHANT_ID with the Merchant ID from your production account.

  <form method="POST"
      action="https://checkout.google.com/api/checkout/v2/checkout/Political/MERCHANT_ID">

8. This step is optional. Create a web service that receives and processes new order notifications from Google Checkout. The Notification API and Order Processing API sections explain the ways that you can integrate your internal order processing systems with Google Checkout.

9. To ensure a positive, consistent experience for your contributors, please ensure that your site complies with the Google Checkout API integration checklist. The checklist provides guidelines for Google Checkout button placement, the checkout order flow and branding.

10. After you have thoroughly tested your Google Checkout implementation with the Sandbox service, release your code to your production system to begin accepting contributions through Google Checkout. Please remember that you must use a different Merchant ID and Merchant Key in your production environment than you use in your test environment. Your Google Checkout buttons will also have different URLs in your test and production environments. You will receive an error if you try to process orders using the wrong Merchant ID or Merchant Key.

Google Checkout Buttons

The Google Checkout Program Policies and Guidelines (section 4b) state that you must place a Google Checkout button immediately beside, above or below every existing checkout button or link on your website.

Google hosts the image for the Google Checkout buttons that you place on your pages. The base URL for the image is http://checkout.google.com/buttons/contribution.gif.

To display an image, you must add several parameters to the base URL as name=value pairs. The following table lists the parameters that you need to add to the Google Checkout button image. All parameters are required unless otherwise noted.

Parameter	Description
merchant_id	This parameter identifies your Merchant ID. Note: You need to use different Merchant IDs for buttons in your test and production environments. Please see the Getting Started with Google Checkout section for more details.
w	This parameter specifies the width of the button in pixels. You must use one of the sizes in the following list. Valid values for the w parameter are shown in bold text. large: 180 by 46 medium: 168 by 44 small: 160 by 42
h	This parameter specifies the height of the button in pixels. You must use one of the sizes in the following list. Valid values for the h parameter are shown in bold text. large: 180 by 46 medium: 168 by 44 small: 160 by 42
style	This parameter specifies the background color for the button. Use the parameter value white to indicate that you are placing the button on a white background and the value trans to indicate that you are placing the button on a colored background.
variant	This value indicates whether the button is clickable or disabled. Use the parameter value text to indicate that the button is clickable.
loc	Optional. This parameter identifies a locale associated with the transaction. The only valid value for this parameter is en_US.

For example, the following form contains a large Google Checkout button on a white background. The <input> tag for the button is shown in bold text.

<form method="POST"
    action="https://sandbox.google.com/checkout/api/checkout/v2/checkout/Political/1234567890">

    <input type="hidden" name="cart"
        value="PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxjaGVja291dC1zaG9wcGlu">
    <input type="hidden" name="signature"
        value="kdjsf590GFDGK23l2kgit259fjSDKET0592jalkfwe3539Gjekwu">

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

The button in the form displays the following image:

Contribution Buttons

Google provides Contribution buttons as a simple way to allow visitors to your site to make one-time contributions. If you use Contribution buttons, you do not need to implement the Checkout API as described in this document. The Contribution button will contain all of the information that you need to send to Google for that contribution.

To create Contribution buttons, go to the Merchant Center, click the Settings tab and then click the Contribution buttons link. After you generate the button, copy the code for the button and then paste that code in an appropriate location on your website.

Note: If you implement the Notification API, you will receive notifications for contributions that were made by contributors who clicked on Contribution buttons. Similarly, you can send updated information about these contributions to Google using the Order Processing API.

Technical Overview

Google provides a suite a APIs that enable you to integrate your website with Google Checkout. Please note that you must at least implement the Checkout API to integrate with Google Checkout; the remaining APIs are optional.

• The Checkout API allows you to send Google the list of contributions that a contributor wants to make.

• The Notification API lets you integrate Google Checkout with your internal contribution processing systems by allowing those systems to automatically receive contribution information from Google. Google sends notifications to inform you of new contributions or to send updates for existing contributions. To implement this API, you must create a web service that receives notifications from Google and then relays the information in those requests to your internal systems.

• The Order Processing API lets you integrate Google Checkout with your internal contribution processing systems by allowing those systems to automatically refund, cancel or archive contributions.

Integration Options

As noted above, you must implement the Checkout API to integrate with Google Checkout. Once you have implemented the Checkout API, Google will send you an email notification when a contributor completes a contribution. You can also use the Google Checkout Merchant Center, an online interface where you can manage contributions placed through Google Checkout, to track contributions and, if necessary, process refunds or cancellations.

After completing your shopping cart integration, you also have the option of implementing the Notification and Order Processing APIs to further integrate Google Checkout with your website and internal contribution processing systems. Typically, organizations that integrate the Notification API and the Order Processing API will implement both APIs at the same time.

Sending Contribution Information to Google Checkout

When a contributor clicks a Google Checkout button to complete a contribution, your site will send a Checkout API request containing information about the contribution.

The following XML sample shows a Checkout API request for a contribution. The example contains a single contribution to a general election fund in the amount of $100.00. The XML request also identifies a URL where the contributor can modify the contribution and another URL that links back to the political organization's website. Google Checkout will display a link to the second URL after the contributor completes the contribution.

<?xml version="1.0" encoding="UTF-8"?>

<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
  <shopping-cart>
    <items>
      <item>
        <item-name>General Election Fund</item-name>
        <item-description>Help Joe Candidate get elected!</item-description>
        <unit-price currency="USD">100.00</unit-price>
        <quantity>1</quantity>
      </item>
    </items>
    <merchant-private-data >In response to email campaign to past contributors.</merchant-private-data>
  </shopping-cart>
  <checkout-flow-support>
    <merchant-checkout-flow-support>
      <continue-shopping-url >http://political.example.com</continue-shopping-url>
      <edit-cart-url >http://political.example.com/contributions</edit-cart-url>
    </merchant-checkout-flow-support>
  </checkout-flow-support>
</checkout-shopping-cart>

You can use either of the two methods described below to send Checkout API requests to Google so that a contributor can complete a contribution. The Google Checkout Sample Code page provides ASP, Java, .NET, PHP and Perl code samples to help you with your integration.

Please note that your Checkout integration must allow the contributor to use the browser's Back button during the Google Checkout process, which is a requirement of the Google Checkout program (see Google Checkout Program Policies and Guidelines, section 4e).

Managing and Processing Contributions with Google Checkout

Receiving new order notifications

When a contributor completes a contribution, Google will notify you that the new contribution has been submitted using one, or both, of the following mechanisms:

• Google automatically sends email notifications for new contributions to all organizations who have not implemented the Notification API.

• If you have implemented the Notification API, Google will send a new-order-notification to inform you of the new contribution. The notification will list the contributions that the contributor has made. For example, a contributor could make two separate contributions in a single transaction. In addition, the notification will provide the contributor's billing address and contact information.

  Even if you implement the Notification API, you can still receive email notifications by setting a preference in your Merchant Center account. To set this preference, log in to your account and click the Settings tab. Then click the Preferences link on the left side of the page and check the preference that says, "Email my customer support contact each time I receive an order, cancellation or other transaction."

  

Charging contributors

After a contributor submits a contribution, Google performs a risk assessment in an effort to avoid fraudulent charges. Google also authorizes the contributor's credit card to ensure that it can be charged for the full amount of the contribution. Google will charge the contributor's credit card as soon as the risk assessment is complete and the credit card has been authorized. You do not need to instruct Google to charge the contributor. Google will also update the contributor's purchase history page to indicate that the charge was executed.

If you have implemented the Notification API, Google will also send you a charge-amount-notification so that your internal processing systems can record the charge.

Archiving contributions

You can archive a contribution to remove it from the list of active contributions that appears in the Merchant Center. (This step is optional; you do not need to archive contributions.) There are two ways to archive a contribution:

• Log in to your Merchant Center account and click the Archive button for the contribution.

• If you have implemented the Order Processing API, you can send an archive-order command to Google.

Credit Card Authorization and Capture

Google automatically charges contributors as soon as their contributions become chargeable. Google will continue to automatically charge contributions even if you try to deactivate this feature in the Merchant Center.

Contributor Refund Request

Contributors can ask for a refund or cancellation by clicking the Questions about this order link on their order history page. If the contributor requests a refund, Google will send you an email to notify you of the request. Note that this email does not start the refund or cancellation process. The link merely enables the contributor to inform you that he would like to cancel a contribution or receive a refund for a contribution.

API Reference

The following sections provide general details about the XML messages that you will exchange with Google Checkout. These sections discuss guidelines for posting XML messages to Google, ensuring the security of your transactions and handling Google's responses to your API requests.

Posting API Requests to Google

When you sign up with Google Checkout, Google assigns you a unique identifier called a Merchant ID. The Getting Started with Google Checkout (step 3) explains how to locate this value. Your Merchant ID is included in the URLs to which you send Google Checkout API requests.

If you configure your Google Checkout button to submit directly to Google, you will send Checkout API requests to the following URLs. (Please note that these URLs are not used for server-to-server Checkout API requests.) The first URL is for requests from your test environment and the second URL is for requests from your production site. In the first URL, you must replace the MERCHANT_ID string with the Merchant ID for your Sandbox account. You must replace the same string in the second URL with the Merchant ID for your Google Checkout merchant account.

https://sandbox.google.com/checkout/api/checkout/v2/checkout/Political/MERCHANT_ID
https://checkout.google.com/api/checkout/v2/checkout/Political/MERCHANT_ID

The following URLs are used for server-to-server Checkout API requests. Again, you must replace the MERCHANT_ID string with the appropriate value as described in the previous paragraph.

https://sandbox.google.com/checkout/api/checkout/v2/merchantCheckout/Political/MERCHANT_ID
https://checkout.google.com/api/checkout/v2/merchantCheckout/Political/MERCHANT_ID

Finally, the following URLs are used for Order Processing API requests. Again, you must replace the MERCHANT_ID string with the appropriate value.

https://sandbox.google.com/checkout/api/checkout/v2/request/Political/MERCHANT_ID
https://checkout.google.com/api/checkout/v2/request/Political/MERCHANT_ID

Guidelines for XML API Requests

The following guidelines explain how to format XML documents that you send in Google Checkout API requests. Some of these guidelines apply specifically to XML elements that contain text strings, including URLs.

• All XML messages between you and Google Checkout must use UTF-8 (Unicode) encoding. Specify UTF-8 encoding by including the following line at the start of each XML API request:

  <?xml version="1.0" encoding="UTF-8"?>

• To include the XML reserved characters &, <, and > in an XML element value, you must encode the characters as hexadecimal numeric character references. Note: This guideline also applies to URL parameters that are included in XML values.

  The following table shows the numeric character references for these characters:

  Character	Hexadecimal character reference
  &	&
  <	&#x3c;
  >	&#x3e;

  You can use all other UTF-8 characters directly.

• Google will not render HTML tags that you include in XML element values. If you pass HTML tags, such as in the <item-name> and <item-description> elements, Google will remove the HTML tags and display the text without formatting.

• Unless otherwise noted, string elements in Google Checkout are not limited to any particular length.

• Time/date values use the ISO 8601 standard, which specifies time as an offset from UTC.

• All money elements must have a currency attribute.

Sending API Requests with HTTP Basic Authentication

The following instructions explain how to format HTTP request headers to use HTTP Basic Authentication. You will need to follow these steps to send server-to-server requests to Google, including server-to-server Checkout API requests and Order Processing API requests.

Please note that Google also uses HTTP Basic Authentication to send Notification API requests to you. As such, when you receive a notification from Google, you can base64-decode the authorization header to confirm that the notification is valid.

1. Create a properly formatted XML file for the command being executed. The Google Checkout XML schema defines an XML structure for each type of API request.

2. Follow these steps to create the HTTPS header for your request:

   • Create the Authorization header for your request.

     1. Append a colon to your Google Checkout Merchant ID. Then append your Google Checkout Merchant Key to this value. (The value has the format MERCHANT_ID:MERCHANT_KEY.)

     2. Base64-encode the value you produced in the previous step to generate your authorization key.

     3. Provide the Authorization header for your request using the following format. Replace the text Authorization_Key in this header with your authorization key:

        Authorization: Basic Authorization_Key
        

   • Include the Content-Type header with the value application/xml; charset=UTF-8

   • Include the Accept header with the value application/xml; charset=UTF-8

   For example, if your Merchant ID is 1234567890 and your Merchant Key is HsYXFoZfHAqyLcCRYeH8qQ, you would base64-encode the value 1234567890:HsYXFoZfHAqyLcCRYeH8qQ. The example below shows how the base64-encoded value would appear in your request header:

   Authorization: Basic MTIzNDU2Nzg5MDpIc1lYRm9aZkhBcXlMY0NSWWVIOHFR
   Content-Type: application/xml;charset=UTF-8
   Accept: application/xml;charset=UTF-8

3. Post the XML structure created in step 1 to Google Checkout. This URL is constructed using your Google-assigned Merchant ID.

   https://checkout.google.com/api/checkout/v2/request/Political/MERCHANT_ID

   Note: You must replace the string MERCHANT_ID with your Google Checkout Merchant ID.

You must also secure Notification and Order Processing API requests with an SSL certificate.

Validating XML Messages to Google Checkout

Google Checkout provides a diagnostic feature that lets you verify that Checkout and Order Processing API requests contain valid XML without actually submitting those requests. To use this feature, construct the XML for the API request and then submit it to Google Checkout's validator by appending /diagnose to the submission URL.

• Use the following URLs to validate Checkout API requests that do not use the server-to-server posting method. You must replace the MERCHANT_ID string in each URL with your Merchant ID. The first URL will contain the Merchant ID for your Sandbox account; the second URL will contain the Merchant ID for your Google Checkout merchant account.

  https://sandbox.google.com/checkout/api/checkout/v2/checkout/Political/MERCHANT_ID/diagnose
  https://checkout.google.com/api/checkout/v2/checkout/Political/MERCHANT_ID/diagnose
  

• For server-to-server Checkout API requests, use the following URLs:

  https://sandbox.google.com/checkout/api/checkout/v2/merchantCheckout/Political/MERCHANT_ID/diagnose
  https://checkout.google.com/api/checkout/v2/merchantCheckout/Political/MERCHANT_ID/diagnose
  

• For Order Processing API commands, use the following URLs:

  https://sandbox.google.com/checkout/api/checkout/v2/request/Political/MERCHANT_ID/diagnose
  https://checkout.google.com/api/checkout/v2/request/Political/MERCHANT_ID/diagnose
  

When you post a diagnostic message, Google parses the request and returns a <diagnosis> response, which indicates whether the API response contained any errors.

You can use curl to send diagnostic requests to Google. For example, you could save the API request in a file and then send it to Google using HTTP Basic Authentication with the following command. Please note that you must use the appropriate URL from the list above for your request. You must also replace the FILENAME, MERCHANT_ID and MERCHANT_KEY strings with the proper values.

curl -d '@FILENAME'
    https://MERCHANT_ID:MERCHANT_KEY@checkout.google.com/api/checkout/v2/request/Political/MERCHANT_ID/diagnose

Immediate (Synchronous) Responses to Posts

Google Checkout returns an immediate response to server-to-server API requests that you post to Google, including server-to-server Checkout API requests, Order Processing API requests and diagnostic requests. The immediate response indicates whether your XML request is valid. A valid request must conform with the Google Checkout XML schema and must also request a legitimate action. For example, a <refund-order> request that instructs Google to refund the contributor for more than the total amount of a contribution would be invalid even if it conformed to the Google Checkout XML schema.

• If your request is valid, Google returns one of three types of responses:

  • If you sent a valid server-to-server Checkout API request, Google will return a <checkout-redirect> response. This response is described in step iv of the section that explains server-to-server Checkout API requests.

  • If you sent a valid Order Processing API request, Google will return a <request-received> response. Please note that this message only indicates that your request is valid. It does not indicate that your request has been successfully processed. The following XML shows a sample <request-received> response:

    <?xml version="1.0" encoding="UTF-8"?>
    <request-received xmlns="http://checkout.google.com/schema/2"
        serial-number="58ea39d3-025b-4d52-a697-418f0be74bf9"/>
    

  • If you sent a valid diagnostic request, Google will return a <diagnosis> response. This response indicates that the API request contained valid XML and that the request was sent to the proper diagnostic URL. For example, the URL would have to contain the correct Merchant ID. The following XML shows the format of a <diagnosis> response. Please note that the <input-xml> tag will contain the complete XML document that you sent to Google in your diagnostic request.

    <?xml version="1.0" encoding="UTF-8"?>
    <diagnosis xmlns="http://checkout.google.com/schema/2"
      serial-number="49ba18e3-016b-4c52-a697-159a3lk38bf9">
        <input-xml>
          <refund-order google-order-number="552406916759246">
            <amount currency="USD">5.51</amount>
          </refund-order>
        </input-xml>
    </diagnosis>
    

• If your request is not properly formed or requests an invalid status change, Google Checkout will return an <error> response to your request.

  There are two types of reasons that a properly formed XML request would return an error:

  • Invalid argument errors occur when a value in a request is not in the range of valid values. For example, requesting a refund for more than the total amount of a contribution would trigger an invalid argument error.

  • Invalid state change errors occur when an order processing command cannot be executed on the contribution in its current state. For example, if you are canceling a contribution, you must issue a <refund-order> request before you can issue a <cancel-order> request.

  The following XML shows a sample <error> response:

  <?xml version="1.0" encoding="UTF-8"?>
  <error xmlns="http://checkout.google.com/schema/2"
      serial-number="3c394432-8270-411b-9239-98c2c499f87f">
      <error-message>Bad username and/or password for API Access.</error-message>
  </error>
  

To help you monitor and debug your Google Checkout implementation, the Merchant Center displays a list of error messages that Google Checkout returned in response to your API requests. To see this list, log in to your Merchant Center account and click on the Settings tab. Then click on the Integration link in the menu on the left side of the page. The error log displays at the bottom of the Integration page. Learn more about the Integration Issues Console.

Checkout API

A Checkout API request sends contribution information from your website to Google, thereby enabling a contributor to complete a contribution using Google Checkout. The following XML shows a simple Checkout API request:

<?xml version="1.0" encoding="UTF-8"?>

<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
  <shopping-cart>
    <items>
      <item>
        <item-name>General Election Fund</item-name>
        <item-description>Help Joe Candidate get elected!</item-description>
        <unit-price currency="USD">100.00</unit-price>
        <quantity>1</quantity>
      </item>
    </items>
    <merchant-private-data >In response to email campaign to past contributors.</merchant-private-data>
  </shopping-cart>
  <checkout-flow-support>
    <merchant-checkout-flow-support>
      <continue-shopping-url >http://political.example.com</continue-shopping-url>
      <edit-cart-url >http://political.example.com/contributions</edit-cart-url>
    </merchant-checkout-flow-support>
  </checkout-flow-support>
</checkout-shopping-cart>

A Checkout API request contains two main sections:

• The <shopping-cart> element contains the list of contributions that the contributor wants to make. You can specify the following information for each contribution:

  • The name of the contribution.

  • A description of the contribution.

  • The amount of the contribution.

  • A value, such as a campaign fund name, that you use to uniquely identify the contribution.

  • You can also provide additional, private information that you would like associated with the contribution. This information will not be displayed to the contributor but will be included in subsequent API exchanges that include information about the contribution. For example, you could specify that a contributor visited your website in response to an email campaign.

• The <checkout-flow-support> element contains additional information that is needed during the checkout process, such as a URL where the contributor can modify a contribution or a URL for the contributor to return to your site after completing a contribution. The XML elements used for these features are shown in the sample Checkout API request above.

Notification API

Note: The Notification API and Order Processing API sections of this document are only relevant for organizations that are completing order processing integrations. Order processing integrations allow organizations to integrate Google Checkout with internal contribution processing systems. If you are not implementing these APIs, please skip ahead to the Using the Google Checkout Merchant Center section.

Google Checkout uses the Notification API to inform you of a new contribution or to send you information about an existing contribution. The Notification API lets you integrate Google Checkout with your internal contribution processing systems by allowing those systems to receive contribution information from Google. Typically, organizations choose to simultaneously integrate the Notification API and the Order Processing API, which allows you to send Google updated information about a contribution.

Each Google Checkout notification is an XML document that constitutes the body of an HTTP POST request. To implement the Notification API, you must build and operate a web service that receives Google Checkout notifications and then communicates the details of those notifications to your internal contribution processing systems.

The following list identifies the different types of notifications that the API supports. Each item in the list links to a section that describes the notification and provides sample XML for that notification.

• New Order Notifications inform you of new contributions that have been submitted through Google Checkout.

• Order State Change Notifications signal an update to a contribution's financial status.

• Amount Notifications inform you that a charge or refund has been processed for a contribution. These notifications also identify the amount of the transaction.

The Notification API is described in full detail in a separate document titled Implementing the Notification API. That document explains how to authenticate API requests so that you can ensure those requests are valid before you process them. It also explains how Google will interpret your HTTP response to each notification to determine whether you handled the notification successfully. That document proceeds to describe each of the different types of notifications and includes a sample for each notification type.

Order Processing API

Note: This section is only relevant for organizations that are integrating Google Checkout with their internal contribution processing systems. If you are not implementing the Notification API or the Order Processing API, please skip ahead to the Using the Google Checkout Merchant Center section.

The Order Processing API lets you integrate Google Checkout with your contribution processing systems by allowing those systems to send information about a contribution to Google Checkout. The following list identifies the functions that this API provides for managing contributions made through Google Checkout. For more information about these functions, including sample XML requests, please see the separate document titled Order Processing API Commands for Political Organizations.

• The <refund-order> command enables you to refund a contributor for a contribution. For example, this command could be useful in cases where a contributor inadvertently submitted the wrong contribution amount or submitted a contribution twice.

• The <cancel-order> command enables you to mark a contribution as canceled. Please note that you must completely refund a contributor before canceling a contribution.

• The <archive-order> and <unarchive-order> commands enable you to manage the list of contributions in your Merchant Center inbox. Archiving commands do not affect a contribution's status or the information that is communicated to the contributor about the contribution.

• The <add-merchant-order-number> command lets you associate a value that you use to uniquely identify a contribution with its associated Google Checkout order.

• The <send-buyer-message> command instructs Google to place a message in the contributor's Google Checkout account and may also instruct Google to email the message to the contributor.

Organizations that use the Order Processing API can also still use the Merchant Center to refund, cancel or archive contributions.

Using the Google Checkout Merchant Center

The Merchant Center is an online interface that allows you to view and manage contributions placed through Google Checkout. The screenshot below shows the Inbox page in the Merchant Center, which displays active – nonarchived – contributions for your organization.

Note: The Merchant Center in the Google Checkout Sandbox displays a background image to indicate that you are working in the Sandbox environment.

Debugging Errors with the Integration Issues Console

The Merchant Center includes an Integration Issues console that identifies the errors and warnings from the API requests that you have sent to Google Checkout. Errors and warnings appear in the console as they occur, enabling you to debug errors as they occur. The console will display error and warning messages from the previous seven-day period. If there are more than 1000 errors and warnings from the previous seven days, only the most recent 1000 messages will be accessible.

We recommend you check the console frequently while you are integrating Google Checkout into your website. After launching your Google Checkout integration, you should check the console periodically to ensure that your integration is working as you expect.

To locate the Integration Issues console, log in to your Merchant Center account and click the Tools tab. The console, which is shown in the diagram below, displays in the center of the page.

You can use the console to debug errors in your test environment or your production environment. To view errors in your test environment, log in to your Sandbox account. To view errors in your production environment, log in to your Google Checkout account.

Note: Google Checkout will only log errors for API requests that you send to a valid URL for posting API requests.

If you click on the description for an error or warning, you will be directed to a page that displays more information about the issue. That page will display the date and time that the issue occurred, the error or warning message that Google returned, the request that Google received and the response that Google returned. The screenshot below shows a sample Integration Issue Detail page:

Testing and QA

This section describes several techniques that you can use to test your integration and to troubleshoot problems that you encounter. This section reviews Google Checkout tools discussed earlier in this document and also introduces other tools that you can use for testing and troubleshooting.

• The Integration Issues console in the Merchant Center identifies the errors and warnings generated by API requests that you have sent to Google Checkout. Errors and warnings appear in the console as they occur, enabling you to debug errors as they occur.

• Google Checkout provides a diagnostic feature that lets you validate Checkout and Order Processing API requests without actually submitting them. The Validating XML Messages to Google Checkout section explains how to use this feature.

• You can perform basic experiments with the Google Checkout API using curl, an open-source tool for communicating with servers that use HTTP and other protocols. The Getting Started with Google Checkout section – see step 4 – explains how to use curl to ensure that your server can communicate with Google Checkout.

  You can also use curl to test other API requests. The Validating XML Messages to Google Checkout section explains how to save an API request in a file and then use the @ option in curl to post the contents of that file to Google. When you submit a request, you will see Google Checkout's immediate response to that request. If you test server-to-server Checkout API requests, the response will contain a redirect URL that you can follow to see the order in your browser.

  For more information about curl, see http://curl.haxx.se/.

• The <demo-failure> request enables you to test your application's ability to handle error messages from Google Checkout. Google returns an <error> response for any <demo-failure> request. The response's <error-message> element contains the string "Failed as expected with:" followed by the text you provided in the message attribute of the <demo-failure> tag.

  The following XML shows a sample <demo-failure> request:

  <?xml version="1.0" encoding="UTF-8"?>
  <demo-failure xmlns="http://checkout.google.com/schema/2" message="test error handling">
  </demo-failure>
  

  This request yields the following <error> response:

  <?xml version="1.0" encoding="UTF-8"?>
  <error xmlns="http://checkout.google.com/schema/2"
   serial-number="6dcd58ae-3411-4383-a4ee-9a38d7d4f0a8">
    <error-message>Failed as expected with: test error handling</error-message>
  </error>