Order Processing API Commands for Political Organizations

Overview

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. The Order Processing API Commands section defines and provides an XML example for each of these requests. The XML Tag Definitions section also defines the XML elements used in any of these commands.

• 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.

Sending Secure Order Processing API Transactions

Order Processing API requests must meet the following requirements:

• Order processing requests must use an HTTPS connection secured by 128-bit SSL v3 or TLS connection using a valid certificate from a major certifying authority. (SSL v2 is not allowed.)
• Order processing requests must use HTTP Basic Authentication, using your Merchant ID and Merchant Key as the username and password.

We also strongly 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 sending any data or doing HTTP Basic Authentication.

• The server certificate belongs to checkout.google.com or sandbox.google.com.
• The server certificate was signed by the appropriate Certifying Authority.
• The certificate has not expired.

Order Processing API Commands

<refund-order>

The <refund-order> command instructs Google Checkout to refund the contributor for a particular contribution. You may issue a <refund-order> command after an order has been charged and is in the CHARGED financial order state.

Note: Even after you have issued a <refund-order> command, you should not assume that Google has refunded the contributor until you receive a refund-amount-notification confirming that the refund has been processed.

The following XML shows a sample <refund-order> command:

<?xml version="1.0" encoding="UTF-8"?>
<refund-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">
    <amount currency="USD">15.00</amount>
    <comment>Discount for inconvenience; ship replacement item</comment>
    <reason>Damaged Merchandise</reason>
</refund-order>

Requests to refund a contribution could generate the following errors:

• Invalid Argument Errors

  • The requested refund amount is greater than the amount charged. (You are trying to refund more money than the original contribution.)
  • The requested refund amount is zero or negative.

• Invalid State Errors

  • The contribution can not be refunded in its current financial order state.

<cancel-order>

The <cancel-order> command instructs Google Checkout to cancel a particular contribution. You must fully refund a contribution before you can cancel that contribution. You may issue a <cancel-order> command for a contribution that is in either of the following financial order states:

The <cancel-order> command effectively marks an entire contribution as canceled. A contribution cannot be removed from the CANCELLED state. However, you can use the <cancel-items> command for line-item shipping to specify that only specific items in a contribution have been canceled. When you cancel specific items in a contribution, that contribution will not transition to the CANCELLED state unless you actually cancel all of the items in the contribution.

Note: Even after you have issued a <cancel-order> command, you should not assume that Google has canceled the contribution until you receive an order-state-change-notification confirming that the financial order state was updated to CANCELLED.

The following XML shows a sample <cancel-order> command:

<?xml version="1.0" encoding="UTF-8"?>
<cancel-order xmlns="http://checkout.google.com/schema/2" google-order-number="841171949013218">
    <reason>Contributor canceled the contribution.</reason>
    <comment>Contributor inadvertently submitted the contribution twice.</comment>
</cancel-order>

Requests to cancel a contribution could generate the following errors:

• Invalid State Errors

  • The contribution can not be canceled in its current financial order state.

<archive-order>

The <archive-order> command instructs Google Checkout to remove a contribution from your Merchant Center Inbox.

<?xml version="1.0" encoding="UTF-8"?>
<archive-order xmlns="http://checkout.google.com/schema/2"
    google-order-number="841171949013218" />

<unarchive-order>

The <unarchive-order> command instructs Google Checkout to return a previously archived contribution to your Merchant Center Inbox.

The following XML shows a sample <unarchive-order> request:

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

<unarchive-order xmlns="http://checkout.google.com/schema/2"
    google-order-number="841171949013218" />

<add-merchant-order-number>

The <add-merchant-order-number> command instructs Google Checkout to associate an order number or other unique value that you have assigned to identify a contribution.

The following XML shows a sample <add-merchant-order-number> request:

<?xml version="1.0" encoding="UTF-8"?>
<add-merchant-order-number xmlns="http://checkout.google.com/schema/2"
    google-order-number="841171949013218">
    <merchant-order-number>P6502-53-7861SBJD</merchant-order-number>
</add-merchant-order-number>

<send-buyer-message>

The <send-buyer-message> command instructs Google Checkout to place a message in the buyer's Google Checkout account. It may also include an optional argument instructing Google Checkout to also email the message to the buyer. This command does not impact the order's fulfillment state.

The following XML shows a sample <send-buyer-message> request. In this request, the optional <send-email> element indicates that Google should email the contributor in addition to displaying the message in the contributor's Google Checkout account.

<?xml version="1.0" encoding="UTF-8"?>
<send-buyer-message xmlns="http://checkout.google.com/schema/2"
    google-order-number="841171949013218">
    <message>Thank you for your generous contribution!</message>
    <send-email>true</send-email>
</send-buyer-message>

XML Tag Definitions

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

add-merchant-order-number
Definition	The <add-merchant-order-number> tag instructs Google Checkout to attach a merchant-assigned order number to an order.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	merchant-order-number
Content Format	Container
Example	<add-merchant-order-number xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

amount
Definition	The <amount> tag identifies the amount of money to charge or refund for an order. The tag's value may either be the full amount of the order or a partial amount. If this tag is omitted and as a part of a charge-order command, Google will charge the customer for the full amount of the order. If this tag is omitted as a part of a refund-order command, Google will refund the full order amount to the customer. This tag has one required attribute, which identifies the currency of the amount to be charged or refunded.
Attributes	Name Format Description currency String The currency attribute identifies the unit of currency associated with the tag's value. The value of the currency attribute must be a three-letter ISO 4217 currency code.
Subtag of	charge-order, refund-order
Content Format	Decimal
Example	<amount currency="USD">129.43</amount>

archive-order
Definition	The <archive-order> tag indicates a request to archive a particular order. You would archive an order to remove it from your Merchant Center Inbox, indicating that the order has been delivered.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Content Format	Empty
Example	<archive-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"/>

cancel-order
Definition	The <cancel-order> tag identifies an order that should be canceled. A <cancel-order> command sets the financial-order-state and the fulfillment-order-state to canceled.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	comment?, reason
Content Format	Container
Example	<cancel-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

comment
Definition	The <comment> tag contains a comment related to a refunded or canceled order. Note: The maximum accepted length for the tag value is 140 characters.
Subtag of	refund-order, cancel-order, cancel-items
Content Format	String
Example	<comment>Refund processed by Bob Smith</comment>

error
Definition	The <error> tag contains information about an invalid API request. This information is intended to help you debug the problem causing the error.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Subtags	error-message, warning-messages?
Content Format	Container
Example	<error xmlns="http://checkout.google.com/schema/2" serial-number="3c394432-8270-411b-9239-98c2c499f87f">

error-message
Definition	The <error-message> tag contains a message that describes why an API request caused an error.
Subtag of	error
Content Format	Container
Example	<error-message>Error: Illegal Argument</error-message>

merchant-order-number
Definition	The <merchant-order-number> tag contains the order number that you have assigned to an order. This number appears in the reconciliation report available in the Merchant Center.
Subtag of	add-merchant-order-number
Content Format	String (Limit 255 characters)
Example	<merchant-order-number>1234abcd</merchant-order-number>

message
Definition	The <message> tag contains a message associated with a coupon or gift certificate or, when used in a <send-buyer-message> request, a message that you want to communicate to a buyer about a specific order. The maximum accepted length for the tag value is 255 characters.
Subtag of	coupon-adjustment, gift-certificate-adjustment, coupon-result, gift-certificate-result, send-buyer-message
Content Format	String
Example	<message>You saved $10.00 with this gift certificate.</message>

reason
Definition	As a subtag of <cancel-order> or <refund-order>, the <reason> tag contains the reason that you are canceling or refunding an order. As a subtag of <order-state-change-notification>, the <reason> tag, if provided, will contain a description of the reason that Google canceled a particular order. For example, Google would cancel an order if the buyer's credit card authorization failed and the buyer did not provide updated credit card information within 72 hours. This element may be included in an order-state-change notification when an order's financial state is changed to CANCELLED_BY_GOOGLE. Note: The maximum accepted length for the tag value is 140 characters.
Subtag of	cancel-order, cancel-items, order-state-change-notification, refund-order
Content Format	String
Example	<reason>Failed risk check</reason>

refund-order
Definition	The <refund-order> tag identifies an order that should be refunded. The <refund-order> tag may specify whether the buyer should be refunded the full amount of the order or a partial amount.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	amount?, comment?, reason
Content Format	Container
Example	<refund-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

request-received
Definition	The <request-received> tag confirms that Google received a properly formed request to change an order's status and that the merchant requested a valid status change. Note: This tag does not indicate that your request was successfully completed.
Attributes	Name Format Description serial-number String The serial-number attribute contains an ID that uniquely identifies a Google Checkout notification.
Content Format	Empty
Example	<request-received xmlns="http://checkout.google.com/schema/2" serial-number="dc66f8c7"/>

send-buyer-message
Definition	The <send-buyer-message> command instructs Google to send a message to a customer about a particular order.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Subtags	send-email?, message
Content Format	Container
Example	<send-buyer-message xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">

send-email
Definition	The <send-email> tag indicates whether Google Checkout should email the buyer with updated information about the shipping status of the items in an order. Google's default behavior is to send an email. To prevent Google Checkout from sending this email, your command must include this element with a value of false.
Subtag of	deliver-order, send-buyer-message, backorder-items, cancel-items, reset-items-shipping-information, return-items, ship-items
Content Format	Boolean
Example	<send-email>true</send-email>

string
Definition	The <string> tag contains a description of a warning generated by an API request.
Subtag of	warnings, warning-messages
Content Format	String
Example	<string>Sample warning message here</string>

unarchive-order
Definition	The <unarchive-order> tag indicates a request to unarchive a particular order. You would use this command to return an order to your Merchant Center Inbox after the order had previously been archived.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Content Format	Complex
Example	<unarchive-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719"/>