Financial Commands in the Order Processing XML API

Overview

Each Google Checkout order has a financial order state and a fulfillment order state. The financial order state identifies the stage of the payment process where the order is located. Valid financial states include CHARGEABLE, CHARGED and PAYMENT_DECLINED.

The Order Processing API provides the following commands to enable you to change an order's financial state:

* The <cancel-order> command also changes an order's fulfillment state. As such, the <cancel-order> command is also described in the discussion of the API's order-level shipping commands.

This page describes the different financial states that can characterize a Google Checkout order. It also explains each of the API commands that let you change an order's financial state. In addition, this document provides a sample API request for each command as well as a list of errors that the API request may generate. Finally, this page defines the XML tags that the API commands use.

Financial Order States

The following table lists the possible financial states for an order. It also provides a description of the state and identifies the actions that place an order in that state.

Financial State	Valid Actions for an Order in this State	Description
REVIEWING	charge-order* * - See note in Description field for more information.	REVIEWING is the default financial state for all new orders. Upon receiving a new order, Google reviews the order to confirm that it is chargeable. After determining that the order is chargeable, Google will update the financial order state to CHARGEABLE. Note: You may issue a charge-order command while an order is still in the REVIEWING state. However, please be aware of the following processing rules for that request. Google will not actually charge the customer until Google has updated the order state to CHARGEABLE. If you issue a second charge-order command while the order is still in the REVIEWING state, you will receive an error indicating that you have requested an invalid state transition. You should not consider the order to be charged until you receive an order-state-change-notification indicating that the order's financial state has been changed to CHARGED.
CHARGEABLE	authorize-order cancel-order charge-order	The CHARGEABLE state indicates that you may charge the customer for an order by issuing a charge-order command. You may also cancel the order by issuing a cancel-order command.
CHARGING	None	The CHARGING state indicates that Google is in the process of charging the customer. Any actions taken on an order in this state will be invalid. Once the charge has been completed, Google will update the financial order state to CHARGED, even if you only charged the customer for part of the order. However, in the case of a partial charge, the remaining balance on the order will still be chargeable even though the financial order state is CHARGED rather than CHARGEABLE.
CHARGED	authorize-order charge-order refund-order	The CHARGED state indicates that you have fully or partially charged the customer for an order. If you have partially charged the customer, the order will still be chargeable until you have charged the customer for the full order amount. Note: If you partially charge an order, you may want to use the <send-buyer-message> command to inform the customer of the partial charge. For partially charged orders, the buyer's account page will display the amount that has been charged.
PAYMENT_DECLINED	cancel-order	The PAYMENT_DECLINED state indicates that Google's effort to authorize or charge the customer's credit card failed. If this happens, Google will email the customer to request a new credit card. The customer will have 72 hours to submit a new card. If the customer submits a new credit card for an order that previously failed authorization, Google will send you an order-state-change-notification indicating that the order's financial update status has been updated to CHARGEABLE. If the customer submits a new credit card for an order that previously failed to charge, Google will charge the credit card and send you an order-state-change-notification indicating that the order's financial update status has been updated to CHARGED.
CANCELLED	None	The CANCELLED state indicates that either the buyer or the merchant canceled the order. The buyer has two opportunities to cancel an order. First, if the buyer's credit card is declined, the buyer has the option of canceling the order rather than updating his credit card information. This opportunity only exists if the buyer's credit card is declined. Second, the buyer can cancel an order within 15 minutes of placing that order. After 15 minutes, the buyer can email you requesting to cancel the order, but you will need to send a cancel-order command to Google if you do actually cancel the order. You can cancel an order by issuing a cancel-order command. Once an order has been canceled, you can no longer update the order's financial order state. You can cancel an order that is in either the CHARGEABLE or the PAYMENT_DECLINED financial state. You can also cancel an order that has already been charged if you first issue a refund for the offer.
CANCELLED_BY_GOOGLE	None	The CANCELLED_BY_GOOGLE state indicates that Google canceled an order. Google may cancel an order if the credit card authorization fails and the customer does not provide a new credit card within 72 hours. Google will send an order-state-change-notification indicating that the order was canceled, and the reason tag in the notification will explain why Google canceled the order.

Order Processing API Commands

<charge-order>

The <charge-order> command instructs Google Checkout to charge the buyer for a particular order. After an order reaches the CHARGEABLE order state, you have seven days – 168 hours – to capture funds by issuing a <charge-order> command. You may issue a <charge-order> command for an order that is in any of the following financial order states:

Note: Even after you have issued a <charge-order> command, you should not assume that Google has charged your customer until you receive a charge-amount-notification confirming that the charge has been executed. In addition, if you charge an order that is in the REVIEWING financial order state, the charge will not take place until Google has updated the financial order state to CHARGEABLE.

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

<?xml version="1.0" encoding="UTF-8"?>
<charge-order xmlns="http://checkout.google.com/schema/2" google-order-number="6014423719">
    <amount currency="USD">335.55</amount>
</charge-order>

Requests to charge an order could generate the following errors:

• Invalid Argument Errors

  • The requested charge amount is greater than the remaining chargeable amount. (You are trying to charge the customer for more than the total order amount.)
  • The requested charge amount is zero or negative.

• Invalid State Errors

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

<refund-order>

The <refund-order> command instructs Google Checkout to refund the buyer for a particular order. 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 your customer 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 an order 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 customer has spent.)
  • The requested refund amount is zero or negative.

• Invalid State Errors

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

<cancel-order>

The <cancel-order> command instructs Google Checkout to cancel a particular order. If the customer has already been charged, you must refund the customer's money before you can cancel the order. You may issue a <cancel-order> command for an order that is in either of the following financial order states:

The <cancel-order> command effectively marks all of the items in an order as canceled. An order 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 an order have been canceled. When you cancel specific items in an order, that order will not transition to the CANCELLED state unless you actually cancel all of the items in the order.

Note: Even after you have issued a <cancel-order> command, you should not assume that Google has canceled the order 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>Buyer cancelled the order.</reason>
    <comment>Buyer ordered another item.</comment>
</cancel-order>

Requests to cancel an order could generate the following errors:

• Invalid State Errors

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

<authorize-order>

The <authorize-order> command instructs Google Checkout to explicitly reauthorize a customer's credit card for the uncharged balance of an order to verify that funds for the order are available. You may issue an <authorize-order> command for an order that is in either of the following financial order states:

This feature allows you to wait until items are available before charging customers for those items, providing a better experience for customers who preorder items or order out-of-stock items. Explicit reauthorizations also benefit merchants that have a policy of shipping an item before charging the customer for that item. By explicitly reauthorizing the customer's credit card, the merchant can ship an order with confidence that the ensuing credit card charge will be successful.

• If Google successfully reauthorizes the customer's credit card, you will receive an <authorization-amount-notification> that provides details about the authorization. (You will not receive an <order-state-change-notification> or a <risk-information-notification> in response to a successful reauthorization request.)

• If Google fails to reauthorize the customer's credit card, you will receive an <order-state-change-notification> indicating that Google has updated the order's financial order state to PAYMENT_DECLINED. Google will then email the customer to request updated billing information, and the customer will have 72 hours to submit that information.

  If the customer submits updated credit card information for the order, Google will send you an <order-state-change-notification> indicating that the order's financial status has changed. If the order had never been charged before the customer updated his credit card information, the order's financial status will be updated to CHARGEABLE. If the order had been partially charged before the customer updated his credit card information, the order's financial status will be updated to CHARGED, though the order will still be chargeable. Google will also send a <risk-information-notification> if the customer updates his credit card information. Finally, Google will send an <authorization-amount-notification> if you requested one in the original shopping cart (using the <order-processing-support> and <request-initial-auth-details> tags).

• If the customer's credit card is already authorized and the authorization has not yet expired, Google will return a synchronous Invalid double authorization error that identifies the date when the existing authorization will expire.

Note: You will be charged $0.20 for each explicit reauthorization request. This fee will show up with the other refundable fees that you incur when you charge an order. (Learn more about Google Checkout fees.)

The XML below shows a sample <authorize-order> request:

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

Requests to reauthorize an order could generate the following errors:

• Invalid State Errors

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

• Invalid double authorization

  • This error indicates that the order has already been authorized and that the existing authorization has not yet expired. The error message will specify the amount for which the customer's credit card is authorized as well as the date and time when the authorization expires. Note that your code should not require the error message to only contain the text Invalid double authorization since the message may also contain other text.

    The following example shows a sample invalid double authorization error response:

    <?xml version="1.0" encoding="UTF-8"?>
    <error xmlns="http://checkout.google.com/schema/2"
        serial-number="2b3579ef-7f2c-4731-8ec2-4bba1026789d">
      <error-message>Invalid double authorization. The order is currently 
          authorized for USD 6.15, valid until Aug 31, 2007 4:04:13 PM EDT.</error-message>
    </error>
    

XML Tag Definitions

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

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>

authorize-order
Definition	The <authorize-order> tag contains a request to reauthorize an order. There are several possible consequences of the request: If the reauthorization is successful, and the customer has not been partially charged for the order, the order's financial-order-state will update to CHARGEABLE. If the reauthorization is successful, but the customer has already been partially charged for the order, the order's financial-order-state will update to (or remain at) CHARGED. If the reauthorization is unsuccessful, the order's financial-order-state will update to PAYMENT_DECLINED. In this case, the customer will have 72 hours to submit a new card.
Attributes	Name Format Description google-order-number String The google-order-number attribute contains an ID that uniquely identifies an order.
Content Format	Container
Example	<authorize-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">

charge-order
Definition	The <charge-order> tag identifies an order for which Google should charge the customer. The <charge-order> tag may specify whether the buyer should be charged the full amount 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?
Content Format	Container
Example	<charge-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>

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">