Google Checkout ASP Sample Code - OrderProcessingAPIFunctions.asp

The OrderProcessingAPIFunctions.asp library contains a set of functions that are used to create Order Processing API XML requests. Order Processing API requests can be used to update the financial-order-state or the fulfillment-order-state for an order. For example, the charge-order command charges the customer for an order and updates the order's financial-order-state to charged. These XML requests are also used to update customers about the status of their orders. For example, the add-tracking-data request enables merchants to add shipment tracking information to an order.

This document includes an explanation of each function in the OrderProcessingAPIFunctions.asp file. Each explanation includes a list of the parameters that are passed to the function, links to other functions that call the function, and links to the sample API implementations that call the function.

Note: To use these functions in your web application, you will need to update the return values of the GetMerchantID and GetMerchantKey functions in the GlobalAPIFunctions.asp library.

Please refer to the OrderProcessingDemo.asp implementation to see sample usages of these functions.

Order Processing API Functions

createArchiveOrder

createChargeOrder

createCancelOrder

createProcessOrder

createRefundOrder

createUnarchiveOrder

createDeliverOrder

createAddTrackingData

changeOrderState

changeShippingInfo

createAddMerchantOrderNumber

createSendBuyerMessage

createArchiveOrder

Definition:

The createArchiveOrder function is a wrapper function that calls the changeOrderState function and returns an <archive-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.

See Sample Usage:

OrderProcessingDemo

Code:

Function createArchiveOrder(attrGoogleOrderNumber)
createArchiveOrder = changeOrderState(attrGoogleOrderNumber, _
"archive", "", "", "")
End Function

createChargeOrder

Definition:

The createChargeOrder function is a wrapper function that calls the changeOrderState function and returns a <charge-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemAmount	Required. The elemAmount parameter identifies the amount that should be charged when a <charge-order> command is executed.

See Sample Usage:

OrderProcessingDemo

Code:

Function createChargeOrder(attrGoogleOrderNumber, elemAmount)
createChargeOrder = changeOrderState(attrGoogleOrderNumber, _
"charge", "", elemAmount, "")
End Function

createCancelOrder

Definition:

The createCancelOrder function is a wrapper function that calls the changeOrderState function and returns a <cancel-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemReason	Required. The elemReason parameter provides the reason that an order is being canceled.
elemComment	Optional. The elemComment parameter provides a comment relevant to a <cancel-order> command.

See Sample Usage:

OrderProcessingDemo

Code:

Function createCancelOrder(attrGoogleOrderNumber, elemReason, elemComment)
createCancelOrder = changeOrderState(attrGoogleOrderNumber, _
"cancel", elemReason, "", elemComment)
End Function

createProcessOrder

Definition:

The createProcessOrder function is a wrapper function that calls the changeOrderState function and returns a <process-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.

See Sample Usage:

OrderProcessingDemo

Code:

Function createProcessOrder(attrGoogleOrderNumber)
createProcessOrder = changeOrderState(attrGoogleOrderNumber, _
"process", "", "", "")
End Function

createRefundOrder

Definition:

The createRefundOrder function is a wrapper function that calls the changeOrderState function and returns a <refund-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemReason	Required. The elemReason parameter provides the reason that an order is being refunded.
elemAmount	Required. The elemAmount parameter identifies the amount that should be refunded when a <refund-order> command is executed.
elemComment	Optional. The elemComment parameter provides a comment relevant to a <refund-order> command.

See Sample Usage:

OrderProcessingDemo

Code:

Function createRefundOrder(attrGoogleOrderNumber, elemReason, elemAmount, _
    elemComment)

    createRefundOrder = changeOrderState(attrGoogleOrderNumber, _
        "refund", elemReason, elemAmount, elemComment)

End Function

createUnarchiveOrder

Definition:

The createUnarchiveOrder function is a wrapper function that calls the changeOrderState function and returns an <unarchive-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.

See Sample Usage:

OrderProcessingDemo

Code:

Function createUnarchiveOrder(attrGoogleOrderNumber)
createUnarchiveOrder = changeOrderState(attrGoogleOrderNumber, _
"unarchive", "", "", "")
End Function

createDeliverOrder

Definition:

The createDeliverOrder function is a wrapper function that calls the changeShippingInfo function and returns a <deliver-order> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemCarrier	Required. The elemCarrier parameter identifies the company that is handling an order shipment.
elemTrackingNumber	Optional. The elemTrackingNumber parameter identifies the tracking number that the carrier has assigned to a shipment associated with an order.
elemSendEmail	Optional. The elemSendEmail parameter indicates whether Google Checkout should email the buyer when the <deliver-order> command is processed.

See Sample Usage:

OrderProcessingDemo

Code:

Function createDeliverOrder(attrGoogleOrderNumber, elemCarrier, _
    elemTrackingNumber, elemSendEmail)

    createDeliverOrder = changeShippingInfo(attrGoogleOrderNumber, _
        "deliver-order", elemCarrier, elemTrackingNumber, elemSendEmail)

End Function

createAddTrackingData

Definition:

The createAddTrackingData function is a wrapper function that calls the changeShippingInfo function and returns an <add-tracking-data> XML block.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemCarrier	Required. The elemCarrier parameter identifies the company that is handling an order shipment.
elemTrackingNumber	Required. The elemTrackingNumber parameter identifies the tracking number that the carrier has assigned to a shipment associated with an order.

See Sample Usage:

OrderProcessingDemo

Code:

Function createAddTrackingData(attrGoogleOrderNumber, elemCarrier, _
    elemTrackingNumber)

    createAddTrackingData = changeShippingInfo(attrGoogleOrderNumber, _
        "add-tracking-data", elemCarrier, elemTrackingNumber, "")

End Function

changeOrderState

Definition:

The changeOrderState function creates XML documents used to send order processing commands to Google Checkout. This function creates XML for the following commands:

<archive-order>
<cancel-order>
<charge-order>
<refund-order>
<process-order>
<unarchive-order>

Note: This function is called by one of several wrapper functions in the OrderProcessingAPIFunctions.asp file. For example, to create the XML for a <process-order> command, you would call the createProcessOrder function. That function passes its parameters through to the changeOrderState function and returns the changeOrderState function's result.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
functionName	Required. The functionName parameter identifies the type of order processing command that you want to perform. Valid values for this parameter are process, charge, cancel, refund, archive and unarchive.
elemReason	Required. The elemReason parameter provides the reason that an order is being canceled or refunded.
elemAmount	Required. The elemAmount parameter identifies the amount that should be charged or refunded when a <charge-order> or <refund-order> command is executed.
elemComment	Optional. The elemComment parameter provides a comment relevant to a <cancel-order> or <refund-order> command.

Functions that call changeOrderState:

createArchiveOrder
createCancelOrder
createChargeOrder
createProcessOrder
createRefundOrder
createUnarchiveOrder

Code:

Function changeOrderState(attrGoogleOrderNumber, functionName, elemReason, _
    elemAmount, elemComment)

    ' Check for errors
    Dim strFunctionName
    Dim errorType

    strFunctionName = "changeOrderState(" & functionName & ")"

    ' Verify that the necessary parameter values have been provided.
    ' The attrGoogleOrderNumber and functionName parameters are
    ' required for all commands. The elemReason parameter is required
    ' for <cancel-order> and <refund-order> commands. In addition,
    ' if an elemAmount is provided for either the <charge-order> or
    ' <refund-order> commands, then the attrCurrency variable, which
    ' is defined in GlobalAPIFunctions.asp, must also have a value.
    errorType = "MISSING_PARAM"
    checkForError errorType, strFunctionName, "attrGoogleOrderNumber", _
        attrGoogleOrderNumber

    If functionName = "cancel" Or functionName = "refund" Then
        checkForError errorType, strFunctionName, "elemReason", elemReason
    End If

    ' Check for missing currency when amount is set
    If functionName = "charge" Or functionName = "refund" Then
        errorType = "MISSING_CURRENCY"
        If (elemAmount <> "") And (attrCurrency = "") Then
            errorHandler errorType, strFunctionName, "elemAmount", elemAmount
        End If
    End If

    ' Define the objects used to create the Order Processing API request
    Dim domOrderObj
    Dim domOrder
    Dim domReason
    Dim domAmount
    Dim domComment

    Set domOrderObj = Server.CreateObject(strMsxmlDomDocument)
    domOrderObj.async = False
    domOrderObj.appendChild(_
        domOrderObj.createProcessingInstruction("xml", strXmlVersionEncoding))

    ' Create the root tag for the Order Processing API command.
    ' Also set the "xmlns" and "google-order-number" attributes
    ' on that element.
    Set domOrder = domOrderObj.appendChild(_
        domOrderObj.createElement(functionName & "-order"))
    domOrder.setAttribute "xmlns", strXmlns
    domOrder.setAttribute "google-order-number", attrGoogleOrderNumber

    ' Add <reason> element to <cancel-order> and <refund-order> commands
    If functionName = "cancel" Or functionName = "refund" Then
        Set domReason = _
            domOrder.appendChild(domOrderObj.createElement("reason"))
        domReason.Text = elemReason
    End If

    ' Add <amount> element to <charge-order> and <refund-order> commands
    If functionName = "charge" Or functionName = "refund" Then
        If elemAmount <> "" Then
            Set domAmount = _
                domOrder.appendChild(domOrderObj.createElement("amount"))
            domAmount.setAttribute "currency", attrCurrency
            domAmount.Text = elemAmount
        End If
    End If

    ' Add <comment> element
    If elemComment <> "" Then
        Set domComment = _
            domOrder.appendChild(domOrderObj.createElement("comment"))
        domComment.Text = elemComment
    End If

    changeOrderState = domOrderObj.xml

    ' Release the objects used to create the Order Processing API request
    Set domOrderObj = Nothing
    Set domOrder = Nothing
    Set domReason = Nothing
    Set domAmount = Nothing
    Set domComment = Nothing

End Function

changeShippingInfo

Definition:

The ChangeShippingInfo function creates XML documents used to send order processing commands to Google Checkout. This function creates XML for the following commands:

<deliver-order>
<add-tracking-data>

This function is called by one of several wrapper functions in the OrderProcessingAPIFunctions.asp file. For example, to create the XML for a <deliver-order> command, you would call the createDeliverOrder function. That function passes its parameters through to the ChangeShippingInfo function and returns the ChangeShippingInfo function's result.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
functionName	Required. The functionName parameter identifies the type of order processing command that you want to perform. Valid values for this parameter are deliver-order and add-tracking-data.
elemCarrier	Optional for <deliver-order> commands; required for <add-tracking-data> commands. The elemCarrier parameter identifies the company that is handling an order shipment.
elemTrackingNumber	Optional for <deliver-order> commands; required for <add-tracking-data> commands. The elemTrackingNumber parameter identifies the tracking number that the carrier has assigned to a shipment associated with an order.
elemSendEmail	Optional. The elemSendEmail parameter indicates whether Google Checkout should email the buyer when the <deliver-order> command is processed.

Functions that call changeShippingInfo:

createAddTrackingData
createDeliverOrder

Code:

Function changeShippingInfo(attrGoogleOrderNumber, functionName, _
    elemCarrier, elemTrackingNumber, elemSendEmail)

    ' Check for errors
    Dim strFunctionName
    Dim errorType

    strFunctionName = "changeShippingInfo(" & functionName & ")"

    ' Check for missing parameters
    errorType = "MISSING_PARAM"
    checkForError errorType, strFunctionName, "attrGoogleOrderNumber", _
        attrGoogleOrderNumber

    ' Check for missing tracking number when carrier is set
    ' Verify that the necessary parameter values have been provided.
    ' The attrGoogleOrderNumber and functionName parameters are
    ' required for all commands. For the <deliver-order> command, the
    ' elemCarrier and elemTrackingNumber parameters are optional; however,
    ' if the elemCarrier is provided, then a elemTrackingNumber must also
    ' be provided. For the <add-tracking-data> command, the elemCarrier
    ' and elemTrackingNumber parameters are both required.
    If functionName = "deliver-order" Then
        errorType = "MISSING_TRACKING"
        If (elemCarrier <> "") And (elemTrackingNumber) = "" Then
            errorHandler errorType, strFunctionName, "elemCarrier", elemCarrier
        End If
    ElseIf functionName = "add-tracking-data" Then
        checkForError errorType, strFunctionName, "elemCarrier", elemCarrier
        checkForError errorType, strFunctionName, "elemTrackingNumber", _
            elemTrackingNumber
    End If

    ' Define the objects used to create the Order Processing API request
    Dim domShippingObj
    Dim domShipping
    Dim domTrackingData
    Dim domCarrier
    Dim domComment
    Dim domSendEmail

    Set domShippingObj = Server.CreateObject(strMsxmlDomDocument)
    domShippingObj.async = False
    domShippingObj.appendChild( _
        domShippingObj.createProcessingInstruction("xml", _
            strXmlVersionEncoding))

    ' Create the root tag for the Order Processing API command.
    ' Also set the "xmlns" and "google-order-number" attributes
    ' on that element.
    Set domShipping = _
        domShippingObj.appendChild(domShippingObj.createElement(functionName))
    domShipping.setAttribute "xmlns", strXmlns
    domShipping.setAttribute "google-order-number", attrGoogleOrderNumber

    ' Add the <carrier> and <tracking-number> elements
    If elemCarrier <> "" Then

        Set domTrackingData = _
            domShipping.appendChild( _
                domShippingObj.createElement("tracking-data"))

        Set domCarrier = _
            domTrackingData.appendChild( _
                domShippingObj.createElement("carrier"))
        domCarrier.Text = elemCarrier

        Set domComment = _
            domTrackingData.appendChild( _
                domShippingObj.createElement("tracking-number"))
        domComment.Text = elemTrackingNumber

    End If

    ' Add the <send-email> element to the command
    If elemSendEmail <> "" Then
        Set domSendEmail = _
            domShipping.appendChild(domShippingObj.createElement("send-email"))
        domSendEmail.Text = elemSendEmail
    End If

    changeShippingInfo = domShippingObj.xml

    ' Release the objects used to create the Order Processing API request
    Set domShippingObj = Nothing
    Set domShipping = Nothing
    Set domTrackingData = Nothing
    Set domCarrier = Nothing
    Set domComment = Nothing
    Set domSendEmail = Nothing

End Function

createAddMerchantOrderNumber

Definition:

The createAddMerchantOrderNumber function creates the XML for the Order Processing API command. This command is used to associate the Google order number with the ID that the merchant assigns to the same order.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemMerchantOrderNumber	Required. This parameter identifies a string that you use to uniquely identify a particular order.

See Sample Usage:

OrderProcessingDemo

Code:

Function createAddMerchantOrderNumber(attrGoogleOrderNumber, _
    elemMerchantOrderNumber)

    ' Check for errors
    Dim strFunctionName
    Dim errorType

    strFunctionName = "createAddMerchantOrderNumber()"

    ' Check for missing parameters
    errorType = "MISSING_PARAM"
    checkForError errorType, strFunctionName, "attrGoogleOrderNumber", _
        attrGoogleOrderNumber
    checkForError errorType, strFunctionName, "elemMerchantOrderNumber", _
        elemMerchantOrderNumber

    ' Define the objects used to create the <add-merchant-order-number> command
    Dim domAddMerchantOrderNumberObj
    Dim domAddMerchantOrderNumber
    Dim domMerchantOrderNumber

    Set domAddMerchantOrderNumberObj = Server.CreateObject(strMsxmlDomDocument)
    domAddMerchantOrderNumberObj.async = False
    domAddMerchantOrderNumberObj.appendChild( _
        domAddMerchantOrderNumberObj.createProcessingInstruction("xml", _
            strXmlVersionEncoding))

    ' Create the root tag for the Order Processing API command.
    ' Also set the "xmlns" and "google-order-number" attributes
    ' on that element.
    Set domAddMerchantOrderNumber = domAddMerchantOrderNumberObj.appendChild( _
        domAddMerchantOrderNumberObj.createElement("add-merchant-order-number"))

    domAddMerchantOrderNumber.setAttribute "xmlns", strXmlns

    domAddMerchantOrderNumber.setAttribute "google-order-number", _
        attrGoogleOrderNumber

    ' Add the <merchant-order-number> element
    Set domMerchantOrderNumber = domAddMerchantOrderNumber.appendChild( _
        domAddMerchantOrderNumberObj.createElement("merchant-order-number"))

    domMerchantOrderNumber.Text = elemMerchantOrderNumber

    createAddMerchantOrderNumber = domAddMerchantOrderNumberObj.xml
End Function

createSendBuyerMessage

Definition:

The createSendBuyerMessage function creates the XML for the <send-buyer-message> command, which is defined in the Order Processing API.

Parameters:

Parameter Name	Definition
attrGoogleOrderNumber	Required. This parameter identifies the order number that Google Checkout assigned to a particular order. This parameter is required for all order processing commands.
elemMessage	Required. The elemMessage parameter contains the text of the message you wish to send to the buyer.
elemSendEmail	Optional. The elemSendEmail parameter indicates whether Google Checkout should email the buyer when the <deliver-order> command is processed.

See Sample Usage:

OrderProcessingDemo

Code:

Function createSendBuyerMessage(attrGoogleOrderNumber, elemMessage, _
    elemSendEmail)

    ' Check for errors
    Dim strFunctionName
    Dim errorType

    strFunctionName = "createSendBuyerMessage()"

    ' The attrGoogleOrderNumber and elemMessage parameters must both have values
    errorType = "MISSING_PARAM"
    checkForError errorType, strFunctionName, "attrGoogleOrderNumber", _
        attrGoogleOrderNumber
    checkForError errorType, strFunctionName, "elemMessage", elemMessage

    ' Define the objects used to create the <send-buyer-message> command
    Dim domSendBuyerMessageObj
    Dim domSendBuyerMessage
    Dim domMessage
    Dim domSendEmail

    ' Create the root element for the <send-buyer-message> command
    ' Also set the "xmlns" and "google-order-number" attributes
    ' on that element.
    Set domSendBuyerMessageObj = Server.CreateObject(strMsxmlDomDocument)
    domSendBuyerMessageObj.async = False
    domSendBuyerMessageObj.appendChild( _
        domSendBuyerMessageObj.createProcessingInstruction("xml", _
            strXmlVersionEncoding))

    Set domSendBuyerMessage = _
        domSendBuyerMessageObj.appendChild( _
            domSendBuyerMessageObj.createElement("send-buyer-message"))
    domSendBuyerMessage.setAttribute "xmlns", strXmlns
    domSendBuyerMessage.setAttribute "google-order-number", _
        attrGoogleOrderNumber

    ' Add the <message> element to the command
    Set domMessage = _
        domSendBuyerMessage.appendChild( _
            domSendBuyerMessageObj.createElement("message"))
    domMessage.Text = elemMessage

    ' Add the <send-email> element to the command
    If elemSendEmail <> "" Then
        Set domSendEmail = _
            domSendBuyerMessage.appendChild( _
                domSendBuyerMessageObj.createElement("send-email"))
        domSendEmail.Text = elemSendEmail
    End If

    createSendBuyerMessage = domSendBuyerMessageObj.xml

    ' Release the objects used to create the <send-buyer-message> command
    Set domSendBuyerMessageObj = Nothing
    Set domSendBuyerMessage = Nothing
    Set domMessage = Nothing
    Set domSendEmail = Nothing

End Function