| Note: This is the latest documentation. The previous version of this page is identical—only the left nav differs. |
This document describes the Polling API, which provides a data-pull model for retrieving batches of Google Checkout notifications. The Polling API is one of three methods that Google Checkout offers for retrieving notifications. Depending on your needs, you might implement one, two or all three of these methods.
The Notification API lets Google send you information about new orders or updates to existing orders. To implement the Notification API, you must build and operate a callback service that listens for Google Checkout notifications and then communicates the details of those notifications to your internal order processing systems.
The Polling API enables you to retrieve batches of notifications using a scheduled process. The actual notifications are identical to the ones that you could receive via the Notification API. However, instead of Google sending notifications automatically, the Polling API lets you set the schedule for retrieving notifications. Using the Polling API, you can retrieve all notifications that are less than 180 days old and that are at least 30 minutes old. The Polling API is designed to simplify your efforts to integrate the Notification API in the following ways:
You do not need your own SSL certificate to implement the Polling API.
You do not need to open your firewall to support or test notifications in a development environment.
You do not need to operate a web service that is always available to receive and process notifications. With the Notification API, you might miss notifications if your callback server goes offline for a few minutes. But since the Polling API doesn't use a callback server, it virtually eliminates the possibility of those missed notifications.
The Notification History API lets you retrieve a list of previously sent notifications. Using the Notification History API, you can retrieve notifications for a particular order or date range. Compared to the Notification API, the Notification History API offers the same advantages as the Polling API.
This document contains the following information:
The Using the Polling API section explains the technical requirements and security guidelines for implementing the Polling API. This section also describes the steps for retrieving notifications from the Polling API server.
The Polling API Commands section describes the two types of requests and responses that you will send in the process of retrieving notifications from the Polling API server. This section also provides sample XML for each request and response.
The XML Tag Definitions section defines the XML elements that will be added to the Google Checkout XML schema to support Polling API functionality.
The XML Schema Changes section identifies the changes made that will be made to the Google Checkout XML schema for this feature.
If you have feedback or questions about this feature, please visit the Google Checkout Beta APIs section of the Google Checkout Merchants Forum
To obtain notifications using the Polling API, you will need to write new code that periodically sends a request to Google for the most recent set of notifications. For example, to schedule the polling process, you might use Scheduled Tasks in Windows or cron in Linux. Upon receiving the API response from Google, your code will then process the notifications and upload their information to your database. The guidelines below explain how to ensure the security of Polling API requests and responses:
All Polling API requests use HTTP Basic Authentication to securely transmit information. The XML Developer's Guide explains how to format HTTP request headers to use HTTP Basic Authentication.
All Polling API responses are secured with SSL. Even though you do not need your own SSL certificate to implement the Polling API, we still recommend that you verify the authenticity of the server certificate that is presented to you when you make the HTTPS connection with Google. Please verify the items in the checklist below before processing any information in an API response:
The following subsections explain how to retrieve notifications from the Polling API server. The first section, Fetching a continue-token for the First Time, explains how to retrieve your first continue-token, a preliminary step to fetching notifications. The second section, Retrieving Notifications from the Polling API Server, explains how to use the continue-token to request notifications.
The following pseudo-code illustrates the Polling API process:
|
1 if (!exists (continue-token in database)) {
2 send notification-data-token-request
3 parse continue-token from notification-data-token-response and store value in database
4 }
5
6 while (exists (continue-token in database)) {
7 extract continue-token from database
8 send notification-data-request that specifies continue-token
9 receive notification-data-response
10 foreach (notification in notification-data-response) {
11 process notification
12 }
13 parse continue-token from notification-data-response and store value in database
14 if (notification-data-response.has-more-notifications == false) {
15 sleep 10 minutes;
16 }
17 }
Before your application can fetch notifications from the Polling API server, it will need to retrieve a token that tells the server which notifications to return. The token serves as a pointer into a chronological listing of the notifications for your account. Your application will need to complete the following steps one time in your development environment and one time in your production environment.
Set a timestamp to the date and time from which you would like to receive notifications.
Submit a notification-data-token-request that specifies the timestamp from step 1 as the start time.
Extract the continue-token from the notification-data-token-response and record the token in your database. The continue-token serves as a pointer
Note: Your application should not complete these steps each time it fetches notifications. Your application will retrieve an updated token value each time it fetches notifications from the Polling API server.
The following steps explain how to retrieve notifications from the Polling API server:
Query your database to retrieve the continue-token that your application most recently received from the Polling API server.
Submit a notification-data-request that specifies this token value.
Process the notifications in the notification-data-response.
Extract the continue-token from the notification-data-response and record the token in your database. Your application will submit this token value in its next request to retrieve notifications.
If the <has-more-notifications> tag in the notification-data-response has a value of true, proceed immediately back to step 1.
If the <has-more-notifications> tag in the notification-data-response has a value of false, wait 10 minutes before returning to step 1.
A notification-data-token-request requests a token that can subsequently be used to retrieve notifications via the Polling API. This request specifies the most recent time that can be associated with the notifications that the Polling API will return in any notification-data-response stemming from the initial token request.
To submit a notification-data-token-request send an HTTP request that uses HTTP Basic Authentication to one of the following URLs:
Sandbox environment: https://sandbox.google.com/checkout/api/checkout/v2/reports/Merchant/MERCHANT_ID Production environment: https://checkout.google.com/api/checkout/v2/reports/Merchant/MERCHANT_ID
The following XML shows a sample notification-data-token-request. The <start-time> tag indicates that the application will be receiving any notifications submitted after December 12, 2007 at 2 p.m. UTC.
<notification-data-token-request xmlns="http://checkout.google.com/schema/2">
<start-time>2007-12-10T14:00:00</start-time>
</notification-data-token-request>
A notification-data-token-response contains a token that your application can then use in a notification-data-request to retrieve the first set of notifications in the result set. The result set includes all notifications that Google Checkout would have sent after the start time specified in the notification-data-token-request. Note that the notification-data-token-response does not contain notifications.
The following XML shows a sample notification-data-token-response:
<?xml version="1.0" encoding="UTF-8"?>
<notification-data-token-response xmlns="http://checkout.google.com/schema/2" serial-number="a6483f0e-6df2-42ae-b97f-a0e5d71da82a"> <continue-token>CIDO66LsIhAAGAA</continue-token>
</notification-data-token-response>
A notification-data-request requests a list of notifications from the Polling API server. The continue-token specified in the request identifies the set of notifications that should be included in the notification-data-response.
To submit a notification-data-request send an HTTP request that uses HTTP Basic Authentication to the following URL as with a notification-data-token-request:
Sandbox environment:
https://sandbox.google.com/checkout/api/checkout/v2/reports/Merchant/MERCHANT_ID
Production environment:
https://checkout.google.com/api/checkout/v2/reports/Merchant/MERCHANT_ID
The following XML shows a sample notification-data-request:
<notification-data-request xmlns="http://checkout.google.com/schema/2">
<continue-token>CPeFhvuBIxDxwp6Jn4w6GAI</continue-token>
</notification-data-request>
A notification-data-response contains the following information:
A list of notifications returned by the Polling API server. Your application should process each notification in the order that it appears in the XML response.
A has-more-notifications flag, which indicates whether there are additional notifications waiting to be processed.
A new continue-token, which can be used to retrieve additional notifications generated after the start time associated with the initial notification-data-token-request. As described in the
The following XML shows a sample notification-data-response. Please note that the bodies of the new-order-notification and the charge-amount-notification have been omitted in the sample. The various types of notifications that can appear in the notification-data-response are documented in the Notification API documentation for the XML API.
<?xml version="1.0" encoding="UTF-8"?>
<notification-data-response xmlns="http://checkout.google.com/schema/2"
serial-number="6047a845-aec0-41fd-b920-fbe840c5e8c7">
<continue-token>CPeFhvuBIxDxwp6Jn4w6GAI</continue-token>
<notifications>
<new-order-notification serial-number="6215c415-bda0-97cb-b920-dac840a5e8a7">
...
</new-order-notification>
<charge-amount-notification serial-number="4514a988-aff1-55ab-c814-feb418f5e8a7">
...
</charge-amount-notification>
</notifications>
<has-more-notifications>false</has-more-notifications>
</notification-data-response>
Note: Since the value of the <has-more-notifications> tag is false, the application that receives this response should wait 10 minutes before submitting another notification-data-request.
Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:
| continue-token | |
| Definition |
As a subtag of <notification-data-request>, the <continue-token> tag contains a value that identifies the set of results that should be included in the API response. For example, the <continue-token> tag might indicate to the Polling API server that your application had already received the first 50 notifications queued up since the start time. As a subtag of <notification-data-token-response> or <notification-data-response>, the <continue-token> tag contains a value that you must submit in a notification-data-request to retrieve a list of notifications. Note: The token can be up to 511 characters long and does not have a fixed length. As such, the length of the token may vary from one request to another. |
| Content Format | String |
| Example | <continue-token>CPeFhvuBIxDxwp6Jn4w6GAI</continue-token> |
| has-more-notifications | |
| Definition |
The <has-more-notifications> tag indicates whether there are more pending notifications generated since the start time associated with the original notification-data-token-request that preceded a notification-data-response.
|
| Content Format | Boolean |
| Example | <has-more-notifications>true</has-more-notifications> |
| notification-data-request | |
| Definition |
The <notification-data-request> tag requests a list of notifications from the Polling API server. The continue-token specified in the request identifies the set of notifications that should be included in the notification-data-response. |
| Subtags | continue-token |
| Content Format | Complex |
| notification-data-response | |||||||
| Definition |
The <notification-data-response> tag encapsulates a list of notifications returned in response to a notification-data-request as well as other information that can be used to request additional notifications. |
||||||
| Attributes |
|
||||||
| Subtags | continue-token, notifications?, has-more-notifications | ||||||
| Content Format | Complex | ||||||
| notification-data-token-request | |
| Definition |
The <notification-data-token-request> tag requests a token that can subsequently be used to retrieve notifications via the Polling API. This request specifies the most recent time that can be associated with the notifications that the Polling API will return in any notification-data-response stemming from the initial token request. |
| Subtags | start-time |
| Content Format | Complex |
| notification-data-token-response | |||||||
| Definition |
The <notification-data-token-response> tag encapsulates the token that your application will use to retrieve the first set of notifications in the result set. The result set includes all notifications that Google Checkout would have sent after the start time specified in the corresponding notification-data-token-request. |
||||||
| Attributes |
|
||||||
| Subtags | continue-token | ||||||
| Content Format | Complex | ||||||
| notifications | |
| Definition |
The <notifications> tag encapsulates the list of notifications returned in response to a notification-data-request. |
| Subtags | authorization-amount-notification*, charge-amount-notification*, chargeback-amount-notification*, new-order-notification*, order-state-change-notification*, refund-amount-notification*, risk-information-notification* |
| Content Format | Container |
| Example | <notifications> |
| start-time | |
| Definition |
Optional. The <start-time> tag identifies the earliest time that a notification could have been sent to be included in the API response. The time may not be within one hour of the time that the API request is submitted or more than 180 days earlier than the time that the API request is submitted. |
| Content Format | Date formatted as YYYY-MM-DDThh:mm:ss or YYYY-MM-DDThh:mm:ssTZD. |
| Example | <start-time>2008-05-10T15:06:26</start-time> <start-time>2008-05-10T17:06:26-02:00</start-time> |
This following elements will be added to the Google Checkout XML schema to support Polling API functionality. Note that the elements shown in italics have data types that are already defined in the schema.
<xs:element name="notification-data-request"
type="tns:NotificationDataRequest" />
<xs:element name="notification-data-response"
type="tns:NotificationDataResponse" />
<xs:element name="notification-data-token-request"
type="tns:NotificationDataTokenRequest" />
<xs:element name="notification-data-token-response"
type="tns:NotificationDataTokenResponse" />
<xs:complexType name="NotificationDataTokenRequest">
<xs:all>
<xs:element name="start-time" type="xs:dateTime" />
</xs:all>
</xs:complexType>
<xs:complexType name="NotificationDataTokenResponse">
<xs:all>
<xs:element name="continue-token" type="xs:string" />
</xs:all>
<xs:attribute name="serial-number" type="xs:string" use="required" />
</xs:complexType>
<xs:complexType name="NotificationDataRequest">
<xs:all>
<xs:element name="continue-token" type="xs:string" />
</xs:all>
</xs:complexType>
<xs:complexType name="NotificationDataResponse">
<xs:all>
<xs:element name="continue-token" type="xs:string" />
<xs:element name="has-more-notifications" type="xs:boolean" minOccurs="0"/>
<xs:element name="notifications">
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="authorization-amount-notification"
type="tns:AuthorizationAmountNotification" />
<xs:element name="charge-amount-notification"
type="tns:ChargeAmountNotification" />
<xs:element name="chargeback-amount-notification"
type="tns:ChargebackAmountNotification" />
<xs:element name="new-order-notification"
type="tns:NewOrderNotification" />
<xs:element name="order-state-change-notification"
type="tns:OrderStateChangeNotification" />
<xs:element name="refund-amount-notification"
type="tns:RefundAmountNotification" />
<xs:element name="risk-information-notification"
type="tns:RiskInformationNotification" />
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
<xs:attribute name="serial-number" type="xs:string" use="required" />
</xs:complexType>