| Note: This is the latest documentation. The previous version of this page is identical — only the left nav differs. |
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.
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 |
* - 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.
|
| 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 168 hours (7 days) to submit a new card.
|
| 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 168 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. |
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
Invalid State Errors
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
Invalid State Errors
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 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 168 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
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
| amount |
The <amount> parameter identifies the amount of money to charge or refund for an order. The parameter's value may either be the full amount of the order or a partial amount. If this parameter 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 parameter is omitted as a part of a refund-order command, Google will refund the full order amount to the customer. API commands Content format for parameter value Decimal
Sample use(s)
<input type="hidden" name="amount" value="19.99"/>
|
| comment |
The <comment> parameter contains a comment related to a refunded or canceled order. Note: The maximum accepted length for the parameter value is 140 characters. API commands Content format for parameter value String
Sample use(s) comment=Refund+processed+by+Bob+Smith
|
| currency |
| The currency parameter identifies the unit of currency associated with a price, shipping cost or other monetary value. Every monetary value in a Google Checkout API request must specify the currency associated with that value. The value of the currency parameter must be a three-letter ISO 4217 currency code.
Associated recurring elements The currency parameter includes recurring elements any time the monetary value associated with the currency also contains a recurring element. For example, in a Checkout API request, the unit-price parameter identifies the price of an item and contains the recurring item element. As such, the currency associated with the unit-price parameter value will also contain the repeating price parameter.
API commands Checkout, Charge Order, Refund Order, New Order Notification, Charge Amount Notification, Refund Amount Notification, Chargeback Amount Notification, Authorization Amount Notification
Content format for parameter value String
Sample use(s) In a Checkout API request:
<item type="hidden" name="shopping-cart.items.item-1.unit-price" value="12.99"> <item type="hidden" name="shopping-cart.items.item-1.unit-price.currency" value="USD"> In a new order notification: order-adjustment.total-tax=1.38&order-adjustment.total-tax.currency=USD In a refund order request: amount=12.99&amount.currency=USD |
| google-order-number |
The <google-order-number> parameter contains an ID, which Google generates, that uniquely identifies an order. API commands New Order Notification, Risk Information Notification, Order State Change Notification, Charge Amount Notification, Refund Amount Notification, Chargeback Amount Notification, Authorization Amount Notification, Charge Order, Refund Order, Cancel Order, Authorize Order, Process Order, Deliver Order, Add Tracking Data, Send Buyer Message, Archive Order, Unarchive Order, Add Merchant Order Number, Ship Items, Reset Items Shipping Information, Cancel Items, Return Items, Backorder Items
Content format for parameter value String
Sample use(s) google-order-number=6014423719
|
| reason |
As a subtag of <cancel-order> or <refund-order>, the <reason> parameter contains the reason that you are canceling or refunding an order. As a subtag of <order-state-change-notification>, the <reason> parameter, 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 168 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 parameter value is 140 characters. API commands Content format for parameter value String
Sample use(s) reason=Failed%20risk%20check
|