Implementing the Notification API for Political Organizations

Overview

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.

This document explains the process for receiving and processing notifications. This document also explains how you should respond to notifications to indicate whether you handled each notification successfully. This document proceeds to explain the different types of notifications that Google Checkout sends, including an XML example for each type. Finally, this document defines the XML tags used in all of the different types of notifications.

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.

Receiving and Processing Notifications

To implement the Notification API, you must establish a web service that receives and processes Google Checkout notifications. Your web service must be secured by SSL v3 or TLS and must use a valid SSL certificate. The API callback URL that you use for your production account must use port 443, which is the default port for HTTPS. The API callback URL that you use for your Sandbox account may use either port 443 or port 80.

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.

When your web service receives a request, the service should verify that the request is authenticated with your Merchant ID and Merchant Key. The notification itself will be an XML document that constitutes the body of the request. Your service should not process a notification unless your service can authenticate the notification.

After establishing your web service, log in to your Merchant Center account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. Enter the URL for your web service in the API callback URL field. (You need to enter your API callback URL in both your sandbox account and your production account.) You must also indicate whether you would like to receive notifications in XML format or HTML format. Please note that this document explains the XML notification format.

Responding to Notifications

When your web application receives a notification from Google, the application should attempt to parse and process the notification. Google allows you to choose one of the following processes for responding to notifications. Google recommends that you select the second method because it enables Google to more reliably confirm that you successfully processed a notification.

Using HTTP response codes to indicate successful or failed processing

The following list explains Google Checkout's default policy for notification responses:

• If your application parses and processes the notification successfully, the application needs to return an HTTP 200 response code, which indicates that the notification was received and processed successfully. Google will not resend a notification after receiving an HTTP 200 response code.

• If your application is unable to parse or process the notification, the application needs to return either a 4xx or 5xx HTTP response code (500, 501, etc.). These response codes indicate that your server has experienced an error or is incapable of performing the request. Your application must not return an HTTP 200 response code.

If you return an error response code, Google will try resending the notification, according to our retry policy, for up to 30 days. Your application should return an error response code even in cases when you know the notification will continue to fail. If Google is unable to successfully send a new order notification to your API callback URL, Google will send you an email to notify you of the new contribution.

Using a notification handshake to confirm successful processing

The following guidelines explain how to respond to notifications using a process that enables Google to more reliably confirm that you successfully processed a notification. This feature is only available on an opt-in basis because it may not be backward-compatible with Google Checkout integrations completed before October 2007. Instructions for opting in to this feature follow the guidelines below.

• If your application parses and processes a notification successfully, the application needs to return an HTTP 200 response code as well as the serial number of the notification. You can parse this value from the notification's serial-number attribute. Together, the response code and the serial number signify that you received the notification and processed it successfully. Google will not resend a notification after receiving this type of response.

  To return the serial number in your HTTP response, send a <notification-acknowledgment> response. In that response, set the value of the <notification-acknowledgment> tag's serial-number attribute to the serial number of the notification.

  The following examples demonstrate how to identify and return the serial number for a notification. Example 1 shows how the serial number would be conveyed in a new order notification. (All other types of notifications use the serial-number attribute in the same way.) Example 2 shows a <notification-acknowledgment> with the same serial number. In both examples, the serial number is shown in bold text.

  Example 1:
  <new-order-notification xmlns="http://checkout.google.com/schema/2" 
      serial-number="85f54628-538a-44fc-8605-ae62364f6c71">
      ...
  </new-order-notification>
  
  Example 2:
  <notification-acknowledgment xmlns="http://checkout.google.com/schema/2" 
      serial-number="85f54628-538a-44fc-8605-ae62364f6c71" />
  

• If your application is unable to parse or process the notification, the application should return either a 4xx or 5xx response code (500, 501, etc.). These response codes indicate that your server has experienced an error or is incapable of performing the request. Please note that your application should return an error response code even in cases when you know the notification will continue to fail.

If you opt to use this feature, then you must return an HTTP 200 response code and the serial number for a successfully processed notification. Otherwise, Google will try to resend the notification, in accordance with our retry policy, for up to 30 days. Specifically, Google will resend a notification if you send any of the following responses to a notification:

• An HTTP 4xx or 5xx response code. (Google recommends this response for a notification that is not handled successfully.)

• An HTTP 200 response code that does not include the serial number of the processed notification. Please note that this policy represents a significant change from option 1, which describes Google's original policy for notification responses. Under that policy, Google will interpret any HTTP 200 response code as an indication that a notification was successfully processed.

• Any other HTTP 2xx or 3xx response code.

The following instructions explain how to enable this feature for your account. Please note that you must complete these steps for your sandbox and production accounts:

1. Log in to your merchant account.
2. Click on the Settings tab.
3. Click the Integration link on the left side of the page.
4. Expand the list of advanced settings and check the box next to the setting that says, "Require notification acknowledgments to specify the serial number of the notification."

   

5. Click the Save button to update your settings.

Types of Notifications

New Order Notifications

Google sends a new order notification when a contributor makes a contribution through Google Checkout. This notification contains the following information:

• The <shopping-cart> element appears exactly as you sent it to Google in the Checkout API request for the order. The shopping cart contains the list of items in the contribution.

• The <buyer-billing-address> and <buyer-shipping-address> elements encapsulate the billing and shipping addresses for the contribution, respectively. These addresses will be the same for contributions.

• The <demographic-data> element contains employment information – the employer and occupation – for the contributor.

• The <order-total> element specifies the amount of the contribution.

• The <buyer-id> element contains an ID that Google uses to uniquely identify a user. The <buyer-marketing-preferences> tag indicates whether the contributor would like to receive marketing emails from your organization.

The following XML shows a sample new order notification. Please note that you must modify the settings in your merchant account if you want to receive the buyer's billing phone number or parsed first and last name. Please see the definitions of the <phone> and <structured-name> tags for more information about enabling these features.

<?xml version="1.0" encoding="UTF-8"?>
<new-order-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="85f54628-538a-44fc-8605-ae62364f6c71">
    <google-order-number>841171949013218</google-order-number>
    <buyer-shipping-address>
        <contact-name>Bill Hu</contact-name>
        <email>billhu@example.com</email>
        <address1>99 Credit Lane</address1>
        <city>Mountain View</city>
        <region>CA</region>
        <postal-code>94043</postal-code>
        <country-code>US</country-code>
        <phone>5555557890</phone>
        <structured-name>
          <first-name>Bill</first-name>
          <last-name>Hu</last-name>
        </structured-name>
    </buyer-shipping-address>
    <buyer-billing-address>
        <contact-name>Bill Hu</contact-name>
        <email>billhu@example.com</email>
        <address1>99 Credit Lane</address1>
        <city>Mountain View</city>
        <region>CA</region>
        <postal-code>94043</postal-code>
        <country-code>US</country-code>
        <phone>5555557890</phone>
        <structured-name>
          <first-name>Bill</first-name>
          <last-name>Hu</last-name>
        </structured-name>
    </buyer-billing-address>
    <buyer-id>294873009217523</buyer-id>
    <demographic-data>
      <employment-information>
        <employer>Company XYZ</employer>
        <occupation>Fundraiser</occupation>
      </employment-information>
    </demographic-data>
    <fulfillment-order-state>NEW</fulfillment-order-state>
    <financial-order-state>REVIEWING</financial-order-state>

    <shopping-cart>
        <items>
            <item>
                <item-name>Contribution to Joe Candidate's Election Fund</item-name>
                <item-description>Support Joe Candidate's election!</item-description>
                <unit-price currency="USD">250.00</unit-price>
            </item>
        </items>
    </shopping-cart>
    <order-total currency="USD">250.00</order-total>
    <buyer-marketing-preferences>
        <email-allowed>false</email-allowed>
    </buyer-marketing-preferences>
    <timestamp>2007-03-19T15:06:26.051Z</timestamp>
</new-order-notification>

Order State Change Notifications

Google sends an order state change notification to notify you that a contribution's financial status or its fulfillment status has changed. The notification identifies the new financial and fulfillment statuses for the contribution as well as the previous statuses for that contribution. You can disregard the fulfillment status for contributions. Typically, the fulfillment status indicates whether an order placed through Google Checkout has been shipped.

These status changes can be triggered by Order Processing API commands that you send to Google Checkout. For example, if you send Google Checkout a <cancel-order> request, Google will respond through the Notification API to inform you that it changed the contribution's status to CANCELLED.

The following XML shows a sample order state change notification:

<?xml version="1.0" encoding="UTF-8"?>
<order-state-change-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="c821426e-7caa-4d51-9b2e-48ef7ecd6423">
    <google-order-number>841171949013218</google-order-number>
    <new-financial-order-state>CHARGING</new-financial-order-state>
    <new-fulfillment-order-state>NEW</new-fulfillment-order-state>
    <previous-financial-order-state>CHARGEABLE</previous-financial-order-state>
    <previous-fulfillment-order-state>NEW</previous-fulfillment-order-state>
    <timestamp>2007-03-19T15:06:29.051Z</timestamp>
</order-state-change-notification>

Amount Notifications

Google defines a set of notifications that report information about financial transactions for a contribution. These notifications inform you when a contribution is charged, refunded or charged back. The following subsections contain information about each of these notifications:

• Charge Amount Notifications
• Refund Amount Notifications
• Chargeback Amount Notifications

Charge Amount Notifications

Google Checkout sends a <charge-amount-notification> after successfully charging a contributor for a contribution. Google automatically charges contributors for contributions made through Google Checkout. You should not assume that Google has charged the contributor until you have received the <charge-amount-notification>.

The following XML shows a sample charge amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<charge-amount-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="95d44287-12b1-4722-bc56-cfaa73f4c0d1">
    <google-order-number>841171949013218</google-order-number>
    <latest-charge-amount currency="USD">226.06</latest-charge-amount>
    <total-charge-amount currency="USD">226.06</total-charge-amount>
    <timestamp>2007-03-19T15:12:26.051Z</timestamp>
</charge-amount-notification>

Refund Amount Notifications

Google Checkout sends a <refund-amount-notification> after successfully executing a <refund-order> order processing command. You should not assume that Google has granted a refund until you receive this notification. Typically, this notification is sent within seconds of the corresponding <refund-order> request.

The following XML shows a sample refund amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<refund-amount-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="d669f8c7-6d75-4ad6-9278-d2fc997d15f2">
    <google-order-number>841171949013218</google-order-number>
    <latest-refund-amount currency="USD">226.06</latest-refund-amount>
    <total-refund-amount currency="USD">226.06</total-refund-amount>
    <timestamp>2007-03-29T15:06:26.051Z</timestamp>
</refund-amount-notification>

Chargeback Amount Notifications

Google Checkout sends a <chargeback-amount-notification> when a contributor initiates a chargeback against a contribution and Google approves the chargeback.

The following XML shows a sample chargeback amount notification:

<?xml version="1.0" encoding="UTF-8"?>
<chargeback-amount-notification xmlns="http://checkout.google.com/schema/2"
    serial-number="bea6bc1b-e1e2-44fe-80ff-0180e33a2614">
    <google-order-number>841171949013218</google-order-number>
    <latest-chargeback-amount currency="USD">226.06</latest-chargeback-amount>
    <total-chargeback-amount currency="USD">226.06</total-chargeback-amount>
    <timestamp>2007-04-19T15:06:26.051Z</timestamp>
</chargeback-amount-notification>

XML Tag Definitions

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are: