Financial Commands in the Order Processing HTML 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 HTML parameters 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.

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 parameters show a sample charge-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=charge-order
  &google-order-number=6014423719
  &amount=69.99
  &amount.currency=USD

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 parameters show a sample refund-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=refund-order
  &google-order-number=6014423719
  &amount=69.99
  &amount.currency=USD
  &comment=Discount%20for%20inconvenience.%20Ship%20replacement%20item.
  &reason=Damaged%20merchandise.

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. 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 parameters show a sample cancel-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=cancel-order
  &google-order-number=6014423719
  &reason=Buyer%20canceled%20the%20order.
  &comment=Buyer%20ordered%20another%20item.

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 following parameters show a sample authorize-order request:

POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
_type=authorize-order
  &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:

    _type=error
      &serial-number=2b3579ef-7f2c-4731-8ec2-4bba1026789d
      &error-message=Invalid%20double%20authorization.%20The%20order%20is%20currently%20authorized%20for%20USD%206.15%2C%20valid%20until%20Aug%2031%2C%202007%204%3A04%3A13%20PM
    

HTML Parameter Definitions