The MerchantCalculationsAPIFunctions.php library contains a set of functions that are used to create Merchant Calculations API XML responses.
This document includes an explanation of each function in the MerchantCalculationsAPIFunctions.php 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.php library.
Please refer to the ResponseHandler.php implementation to see sample usages of these functions.
Definition:
The ProcessMerchantCalculationCallback function handles a <merchant-calculation-callback> request and returns a <merchant-calculation-results> XML response. This function calls the CreateMerchantCalculationResults function, which constructs the <merchant-calculation-results> response. This function then prints the <merchant-calculation-results> response to return the <merchant-calculation-results> information to Google Checkout and logs the response as well.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
Functions that call ProcessMerchantCalculationCallback:
Code:
/*
* Process <merchant-calculation-callback> and create
* <merchant-calculation-results>
*/
$xml_mc_results = CreateMerchantCalculationResults($dom_mc_callback_obj);
// Respond with <merchant-calculation-results> XML
echo $xml_mc_results;
// Log <merchant-calculation-results>
LogMessage($GLOBALS["logfile"], $xml_mc_results);
}
Definition:
The CreateMerchantCalculationResults function creates the XML DOM for a <merchant-calculation-results> XML response. This function receives the <merchant-calculation-callback> from the ProcessMerchantCalculationCallback function.
This function calls the CreateMerchantCodeResults, GetShippingRate and GetTaxRate functions to calculate shipping costs, taxes and discounts that should be applied to the order total.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
Functions that call CreateMerchantCalculationResults:
Code:
// Create an empty XMLDOM
$dom_mc_results_obj = domxml_new_doc("1.0");
// Create root tag for <merchant-calculation-results> response
$dom_mc_results = $dom_mc_results_obj->append_child(
$dom_mc_results_obj->
create_element("merchant-calculation-results"));
$dom_mc_results->set_attribute("xmlns", $GLOBALS["schema_url"]);
// Create child element <results>
$dom_results =
$dom_mc_results->append_child(
$dom_mc_results_obj->create_element("results"));
$dom_data = $dom_mc_callback_obj->document_element();
/*
* Retrieve Boolean value indicating whether merchant calculates
* tax for the order.
* e.g. <tax>true</tax>
* If you do not use custom calculations to calculate tax, you
* may ignore the next two lines of code.
*/
$dom_tax_list = $dom_data->get_elements_by_tagname("tax");
$calc_tax = $dom_tax_list[0]->get_content();
/*
* Retrieve the names of the shipping methods available for the
* order. These shipping methods will have been communicated to Google
* Checkout in a CheckoutAPIRequest. Note: The
* <merchant-calculated-callback> will only contain
* <merchant-calculated-shipping> options from the Checkout API request.
*/
$dom_method_list = $dom_data->get_elements_by_tagname("method");
/*
* Retrieve shipping addresses from the <merchant-calculated-callback>
* response. These shipping addresses are anonymous, meaning they
* only include the city, region (state), postal code and country
* code for the address
*/
$dom_anonymous_address_list =
$dom_data->get_elements_by_tagname("anonymous-address");
/*
* Retrieve a list of coupon and gift certificate codes that
* should be applied to the order total. Note: The
* <merchant-calculated-callback> can only contain these codes if
* the <accept-merchant-coupons> or <accept-gift-certificates> tag
* in the corresponding Checkout API request has a value of "true".
*/
$dom_merchant_code_list =
$dom_data->get_elements_by_tagname("merchant-code-string");
// Loop through address IDs to build <result> elements
foreach ($dom_anonymous_address_list as $dom_anonymous_address) {
// Retrieve the address ID
$address_id = $dom_anonymous_address->get_attribute("id");
/*
* If there are merchant-calculated shipping methods, build
* a <result> element for each shipping method-address ID
* combination. If there are no shipping methods, build a
* <result> element that contains calculations for each address ID.
*/
if (sizeof($dom_method_list) > 0) {
// Loop for each merchant-calulated shipping method
foreach ($dom_method_list as $dom_method) {
// Retrieve the name of the shipping method
$shipping_name = $dom_method->get_attribute("name");
/*
* Create a <result> element in the response with
* shipping-name and address-id attributes
*/
$dom_result = $dom_results->append_child(
$dom_mc_results_obj->create_element("result"));
$dom_result->set_attribute("shipping-name", $shipping_name);
$dom_result->set_attribute("address-id", $address_id);
/*
* If the <tax> tag in the <merchant-calculation-callback>
* has a value of "true", call the GetTaxRate function
* to calculate taxes for the order.
*/
if ($calc_tax == "true") {
$dom_total_tax = $dom_result->append_child(
$dom_mc_results_obj->create_element("total-tax"));
$dom_total_tax->set_attribute(
"currency", $GLOBALS["currency"]);
$total_tax = GetTaxRate($dom_mc_callback_obj, $address_id);
$dom_total_tax->append_child(
$dom_mc_results_obj->create_text_node($total_tax));
}
/*
* If there are coupon or gift certificate codes, call
* the CreateMerchantCodeResults function to verify those
* codes and to create <coupon-result> or
* <gift-certificate-result> elements to be included in
* the <merchant-calculation-response>.
*/
if (sizeof($dom_merchant_code_list) > 0) {
$dom_merchant_code_results =
CreateMerchantCodeResults($dom_mc_callback_obj,
$dom_merchant_code_list, $address_id);
$dom_merchant_code_results_root =
$dom_merchant_code_results->document_element();
$dom_result->append_child(
$dom_merchant_code_results_root->clone_node(true));
}
/*
* Call the GetShippingRate function to calculate the
* shipping cost for the shipping method-address ID
* combination.
*/
$dom_shipping_rate = $dom_result->append_child(
$dom_mc_results_obj->create_element("shipping-rate"));
$dom_shipping_rate->set_attribute(
"currency", $GLOBALS["currency"]);
$shipping_rate =
GetShippingRate($dom_mc_callback_obj, $address_id, $shipping_name);
$dom_shipping_rate->append_child(
$dom_mc_results_obj->create_text_node($shipping_rate));
// Verify that the order can be shipped to the address
$shippable =
VerifyShippable($dom_mc_callback_obj, $address_id, $shipping_name);
$dom_shippable = $dom_result->append_child(
$dom_mc_results_obj->create_element("shippable"));
$dom_shippable->append_child(
$dom_mc_results_obj->create_text_node($shippable));
}
// This block executes if no shipping methods are specified
} else {
/*
* Create a <result> element in the response with
* address-id attribute
*/
$dom_result = $dom_results->append_child(
$dom_mc_results_obj->create_element("result"));
$dom_result->set_attribute("address-id", $address_id);
/*
* If the <tax> tag in the <merchant-calculation-callback>
* has a value of "true", call the GetTaxRate function
* to calculate taxes for the order.
*/
if ($calc_tax == "true") {
$dom_total_tax = $dom_result->append_child(
$dom_mc_results_obj->create_element("total-tax"));
$dom_total_tax->set_attribute(
"currency", $GLOBALS["currency"]);
$total_tax = GetTaxRate($dom_mc_callback_obj, $address_id);
$dom_total_tax->append_child(
$dom_mc_results_obj->create_text_node($total_tax));
}
/*
* If there are coupon or gift certificate codes, call
* the CreateMerchantCodeResults function to verify those
* codes and to create <coupon-result> or
* <gift-certificate-result> elements to be included in
* the <merchant-calculation-response>.
*/
if (sizeof($dom_merchant_code_list) > 0) {
$dom_merchant_code_results =
CreateMerchantCodeResults($dom_mc_callback_obj,
$dom_merchant_code_list, $address_id);
$dom_merchant_code_results_root =
$dom_merchant_code_results->document_element();
$dom_result->append_child(
$dom_merchant_code_results_root->clone_node(true));
}
}
}
// Return <merchant-calculation-results> XML
return $dom_mc_results_obj->dump_mem();
}
Definition:
The CreateMerchantCodeResults function creates the <merchant-code-results> tag, which encapsulates the calculated amounts for a list of coupon or gift certificate codes. It then calls the GetMerchantCodeInfo function, which you will need to modify, to retrieve information about each coupon or gift certificate code.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
| $dom_merchant_code_list | Required. This parameter contains the list of coupon and gift certificate codes that a customer wants to apply to an order. |
| $address_id | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
Functions that call CreateMerchantCodeResults:
Code:
$dom_merchant_code_list, $address_id) {
// Create an empty XMLDOM
$dom_code_results_obj = domxml_new_doc("1.0");
$dom_merchant_code_results = $dom_code_results_obj->append_child(
$dom_code_results_obj->create_element("merchant-code-results"));
foreach ($dom_merchant_code_list as $dom_merchant_code) {
$code = $dom_merchant_code->get_attribute("code");
$dom_merchant_code_result_obj =
GetMerchantCodeInfo($dom_mc_callback_obj, $code, $address_id);
$dom_merchant_code_result_root =
$dom_merchant_code_result_obj->document_element();
$dom_merchant_code_results->append_child(
$dom_merchant_code_result_root->clone_node(true));
}
return $dom_code_results_obj;
}
Definition:
The GetMerchantCodeInfo function retrieves information about a coupon or gift certificate code provided by the customer. You will need to modify this function to retrieve information about the code. The changes you will need to make are discussed in the comments in the function. After retrieving this information, this function calls and returns the value of the CreateMerchantCodeResult function.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
| $code | Required. This parameter contains a coupon or gift certificate code. |
| $address_id | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
Functions that call GetMerchantCodeInfo:
Code:
/*
* +++ CHANGE ME +++
* You need to modify this function to retrieve information about
* a coupon or gift certificate code provided by the customer. This
* function needs to retrieve the following information about the code:
* 1. The code's type. The code type may be either "coupon" or
* "gift-certificate".
* 2. A flag that indicates whether the code is valid. The value
* of this flag must be either "true" or "false".
* 3. The calculated amount of the code. If the code is valid,
* you need to quantify the amount of the code discount.
* This data is optional.
* 4. A message that should be displayed with the code. This
* data is optional.
* This function returns the result from the CreateMerchantCodeResult
* function, which is a <coupon-result> or a <gift-certificate-result>,
* to the CreateMerchantCodeResults function, which adds the XML
* block to the response.
*/
$code_type = "coupon";
$valid = "true";
$calculated_amount = "10.00";
$message = "You saved \$" . $calculated_amount;
return CreateMerchantCodeResult($code_type, $valid, $code,
$calculated_amount, $message);
}
Definition:
The CreateMerchantCodeResult function creates the XML DOM for a <coupon-result> or a <gift-certificate-result> for a Merchant Calculations API response.
Parameters:
| Parameter Name | Definition |
|---|---|
| $code_type | Required. This parameter indicates whether a <merchant-code-string> in a Merchant Calculations API request contains a coupon code or a gift certificate code. Valid values are coupon and gift-certificate. |
| $valid | Required. This parameter indicates whether a coupon or gift certificate code is valid. This parameter should have a Boolean (true/false) value. |
| $code | Required. This parameter contains a coupon or gift certificate code. |
| $calculated_amount | Optional. This parameter contains the amount that should be deducted from an order total for a particular coupon or gift certificate code. |
| $message | Required. This parameter contains the message to be logged. |
Functions that call CreateMerchantCodeResult:
Code:
$calculated_amount="", $message="") {
// Create an empty XMLDOM
$dom_code_result_obj = domxml_new_doc("1.0");
// Create root tag for <coupon-result> or <gift-certificate-result>
$dom_merchant_code_result = $dom_code_result_obj->append_child(
$dom_code_result_obj->create_element($code_type . "-result"));
// Create <valid> tag, which will indicate whether the code is valid
$dom_valid = $dom_merchant_code_result->append_child(
$dom_code_result_obj->create_element("valid"));
// Add value for <valid> tag
$dom_valid->append_child($dom_code_result_obj->create_text_node($valid));
// Add the coupon or gift certificate code in a <code> tag
$dom_code = $dom_merchant_code_result->append_child(
$dom_code_result_obj->create_element("code"));
$dom_code->append_child($dom_code_result_obj->create_text_node($code));
/*
* Add the <calculated-amount> tag if there is a value for the
* $calculated_amount parameter. You could omit this tag if the
* code is invalid.
*/
if ($calculated_amount) {
$dom_calculated_amount = $dom_merchant_code_result->append_child(
$dom_code_result_obj->create_element("calculated-amount"));
$dom_calculated_amount->set_attribute(
"currency", $GLOBALS["currency"]);
$dom_calculated_amount->append_child(
$dom_code_result_obj->create_text_node($calculated_amount));
}
// Add a <message> tag if the $message parameter has a value
if ($message) {
$dom_message = $dom_merchant_code_result->append_child(
$dom_code_result_obj->create_element("message"));
$dom_message->append_child(
$dom_code_result_obj->create_text_node($message));
}
return $dom_code_result_obj;
}
Definition:
The VerifyShippable function determines whether an order can be shipped to the specified address using the specified shipping method. You will need to modify this function to return a Boolean value indicating whether the order is shippable using the given shipping method.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
| $address_id | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
| $shipping_method | Required. This parameter identifies the name of the shipping method for which you must calculate shipping costs. |
Functions that call VerifyShippable:
Code:
/*
* +++ CHANGE ME +++
* You need to modify this function to return a Boolean (true/false)
* value that indicates whether the order can be shipped to the
* specified address ($address_id) using the specified shipping
* method ($shipping_method).
*/
return "true";
}
Definition:
The GetShippingRate function determines the cost of shipping the order to the specified address using the specified shipping method. You will need to modify this function to calculate and return this cost.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
| $address_id | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
| $shipping_method | Required. This parameter identifies the name of the shipping method for which you must calculate shipping costs. |
Functions that call GetShippingRate:
Code:
/*
* +++ CHANGE ME +++
* You need to modify this function to return the cost of
* shipping an order to the specified address using the specified
* shipping method.
*/
return "8.76";
}
Definition:
The GetTaxRate function returns the total tax that should be applied to the order if it is shipped to the specified address. You will need to modify this function to return the calculated tax amount.
Parameters:
| Parameter Name | Definition |
|---|---|
| $dom_mc_callback_obj | Required. This parameter contains a DOM object representation of an XML document. |
| $address_id | Required. This parameter contains the value of the id parameter for an address in a <merchant-calculation-callback>. |
Functions that call GetTaxRate:
Code:
/*
* +++ CHANGE ME +++
* You need to modify this function to return the total tax for
* an order based on the specified address.
*/
return "17.55";
}
?>