Checkout by Amazon Widget Reference Guide - Standard Checkout

Transcription

1 Checkout by Amazon Widget Reference Guide - Standard Checkout

2 2 TOC Contents Overview of Checkout by Amazon Standard Checkout... 3 Who Should Read This Document...3 Prerequisites... 3 Code Samples...3 What's New in This Document...3 Widget Overview...4 Widget Setup... 4 Common Widget Methods... 4 Common Widget Parameters... 5 Widgets...6 List of Widgets by Function...6 StandardCheckoutWidget Widget Parameters... 7 Widget Methods... 8 Example...8 OrderDetailsWidget Widget Parameters Widget Methods Example...11

3 Overview of Checkout by Amazon Standard Checkout 3 Overview of Checkout by Amazon Standard Checkout Welcome to the Checkout by Amazon Standard Checkout Widgets Reference Guide. This section describes who should read this guide, how the guide is organised, and other resources related to Checkout by Amazon. Who Should Read This Document This document gives you the information and steps you need to implement Standard Checkout Widgets on your website. Prerequisites This guide assumes you--or your development staff--are familiar with using HTML and JavaScript in a web application development environment. Before you can use Checkout by Amazon Standard Checkout, your systems must meet the following prerequisites: You must be familiar with using dynamic website programming. You must be familiar with using JavaScript. (There are several required JavaScript code snippets that you must use in your carts to enable Standard Checkout.) For more information about using the Standard Checkout Widgets, please see the following references: HTML Implementation Guide (PDF) XML Implementation Guide (PDF) Code Samples Checkout by Amazon provides code samples to assist you when implementing Standard Checkout. Java.NET PHP What's New in This Document Release Date Widget Reference Guide Small corrections to the content Release Date Widget Reference Guide Initial Release

4 4 Widget Overview Widget Overview Widget Setup We recommend you to use our Inline Integration Code Generator that can be found in Seller Central to generate the widgets. To render a widget, derive your code from the code snippet we provide (sample below) on every page where a widget needs to be rendered. Place the div block in the location where you want the widget to show up. script type='text/javascript' src=' <div id="amazonwidget"></div> new CBA.Widgets.XXXWidget ({ // Widget-specific parameters }).render("amazonwidget"); The widget setup involves 3 steps: 1. Include the PaymentWidgets.js file on your page. If you want to include multiple Checkout by Amazon widgets on the same page, load the external JavaScript file (for example, PaymentsWidget.js) just once. 2. Place a div HTML element where you want the widget to be rendered on your page. Give the div element a unique name. 3. Inside a script block, create an instance of the widget you want to display. URL Domains Used in This Guide Note: Creating an instance of the widget does not automatically make it visible. You must call the render() method of the widget instance when your page is ready to display the widget. The URL domain is specific for country to support internalization (i18n). That is, the JavaScript URL for UK is: Please see this table for a list of URLs used for specific locales: Locale UK Sandbox Widget To test your integration in the Sandbox environment, use this URL. URL PaymentWidgets.js Locale UK URL gb/sandbox/paymentwidgets.js Common Widget Methods Each widget supports following methods:

5 Widget Overview 5 Name render(locationid) string getlocation() string getwidgettype() Renders the widget inline. LocationId is a required input parameter that refers to the identifier of the HTML element (div or span) where the widget needs to be rendered. The locationid must be unique. This returns the associated locationid set by render method. This returns the widget type based on the widget. List of possible values: 'StandardCheckoutWidget', 'ExpressCheckoutWidget', 'InlineCheckoutWidget', 'AddressWidget', 'WalletWidget', 'OrderDetailsWidget' Common Widget Parameters The following parameters are applicable to every widget. The additional parameters applicable to each individual widget are discussed in the corresponding chapters. Required Name Type required merchantid String Your merchant ID is a required parameter to each widget.

6 6 Widgets Widgets List of Widgets by Function Initiating checkout StandardCheckoutWidget Accessing order details OrderDetailsWidget

7 StandardCheckoutWidget 7 StandardCheckoutWidget The Standard Checkout widget renders the Checkout with Amazon button which allows your buyers to place instant orders from a pop-up window hosted by Amazon Payments. Please refer to the XML and HTML Implementation Guides for details on integrating the standard Checkout by Amazon product on your website. Widget Parameters The following are additional parameters supported by this widget. Please refer to the first chapter for common parameters not listed here explicitly. Table 1: Required Name Type conditional orderinput Object orderinput has 2 properties: {format: "HTML", value: "formid"} The format field must have one of two values, "HTML" or "XML". The format identifies how order input is supplied. If the format field is set to "HTML," then the value field must have the ID of the form element which contains the HTML cart. Please refer to the HTML Implementation Guide on how to create the form element. If the format field is set to "XML," then the value field must have the base64-encoded cart XML string (signed or unsigned). Please refer to the XML Implementation Guide for instructions on encoding strings. The orderinput parameter can be set after the widget is initialized and rendered. However, it must be available before the buyer can see the cart details. optional onopen Callback function JavaScript function to perform when the Standard Checkout window opens after buyer clicks the Checkout with Amazon button. The code is performed before buyer sees checkout details within the pop-up window. The widget object is passed as an input parameter to the function. You can set the orderinput inside this function so the buyer sees the latest order details after the pop-up window appears. Only after you invoke the submit method will the buyer see the checkout details. optional buttonsettings Object The following is an example button settings:

8 8 StandardCheckoutWidget Required Name Type {size:'large', color:'orange', background:'white'} Below are possible values for each button setting property: Size: medium large x-large. Default is large. Color: orange tan. Default is orange. Background: white light dark. Default is white. optional cartorigin String The default value is "CartPage". Possible values are CartPage and DetailPage. Widget Methods The following are additional methods supported by this widget. Please refer to the first chapter for common methods not listed here explicitly. Table 2: Name updateorderinput(orderinput) submit() Use this method to update the orderinput parameter after you initialize the widget. This method is used mostly when a JavaScript function is associated with the onopen parameter. If you associated a function with the onopen parameter, the buyer can select an address and payment only after you call the submit() method. Example Below is a simple use of the widget with an XML cart. The button will use these default settings: {size:'large',color:'orange',background:'white'}. <div id="cbabutton"></div> new CBA.Widgets.StandardCheckoutWidget({ merchantid: "AEIOU1234AEIOU", orderinput: {format: "XML", value: "type:merchant-signed-order/awsaccess-key/1; order:pd94bwwgdmvyc2lvbj0nms4wjyblbmnvzgluzz0nvvrgl TgnPz48T3JkZXIgeG1sbnM9J2h0dHA6Ly9wYXltZW50cy5hbWF6 b24uy29tl2nozwnrb3v0lziwmdgtmtetmzavjz48q2fydd48sxr lbxm+pel0zw0+pfnlvt5bqkmxmjm8l1nlvt48twvyy2hhbnrjzd 5BMUVKTjJKSUcxMEs2NzwvTWVyY2hhbnRJZD48VGl0bGU+UmVkI EZpc2g8L1RpdGxlPjxQcmljZT48QW1vdW50PjE5Ljk5PC9BbW91 bnq+pen1cnjlbmn5q29kzt5vu0q8l0n1cnjlbmn5q29kzt48l1b yawnlpjxrdwfudgl0et4xpc9rdwfudgl0et48rnvszmlsbg1lbn ROZXR3b3JrPk1FUkNIQU5UPC9GdWxmaWxsbWVudE5ldHdvcms+P C9JdGVtPjwvSXRlbXM+PC9DYXJ0PjwvT3JkZXI+;

9 StandardCheckoutWidget 9 signature:0nppbxtktfov80kh41gk7ruuhq8=; aws-access-keyid:19g7e7x2qe2v45letx2e"} }).render("cbabutton"); Below is another simple use of the widget with an HTML cart. Notice how the ID of the form element is used inside the orderinput parameter. The button will be x-large, tan, with a dark background. <!-- Form fields that describe Cart --> <form id="cbacartformid"> <input name="item_merchant_id_1" value="aeiou1234aeiou" type="hidden" /> <input name="item_sku_1" value="abc123" type="hidden" /> <input name="item_title_1" value="red Fish" type="hidden" /> <input name="item_price_1" value="19.99"type="hidden" /> <input name="item_quantity_1" value="1" type="hidden" /> <input name="currency_code" value="gbp" type="hidden" /> <input name="merchant_signature" value="c2lnbmf0dxjligzvcibdagvja291dcbiesbbbwf6b24" type="hidden" /> <input name="aws_access_key_id" value="19g7e7x2qe2v45letx2e" type="hidden" / > </form> <div id="cbabutton"></div> new CBA.Widgets.StandardCheckoutWidget({ merchantid: "AEIOU1234AEIOU", buttonsettings: {size:'x-large',color:'tan',background:'dark'}, orderinput: {format: "HTML", value: "CBACartFormId"} }).render("cbabutton"); Below is an advanced example where orderinput is set using an AJAX handler. Notice how the submit() method is called after an AJAX response is received. The example below uses JQuery to implement the AJAX call. <div id="cbabutton"></div> new CBA.Widgets.StandardCheckoutWidget({ merchantid: ABCDEFG, buttonsettings: {background:'light'}, onopen: function() { $.ajax({ url: 'ajax/test.html', complete: function(data) { // Initialize cartxml variable with the encoded cart xml string // extracted from the AJAX response. // Then set the orderinput parameter and call submit() method // to signal the widget to display order details this.updateorderinput({format: "XML", value: cartxml}); this.submit(); } }); } }).render("cbabutton");

10 10 OrderDetailsWidget OrderDetailsWidget The Order Details Widget allows Amazon customers to see the details of a given Checkout by Amazon order on the merchant's site. Widget Parameters Table 3: Required Name Data Type required orderid String Amazon Payments Order ID. optional design Object This input parameter is applicable only when render() method is called. When the open() method is used, this parameter input is ignored. Amazon Payments will provide pre-defined set of designs. Each design identified by the name attribute has a choice of color themes and valid sizes. Name attribute is optional, and if omitted, the default design corresponding to this widget is used. However, you can still specify a color theme and size applicable to the default design. {name: 'pre-defined name', colortheme: 'pre-defined color theme', size: {width: 'width in pixels', height: 'height in pixels'} } Please note that when you set width and height values, use digits only. Do not append unit measurements such as "px". Widget Methods The following table lists the special methods supported by the OrderDetailsWidget in addition to the common methods supported by all widgets. Table 4: Name Data Type open(top, left) function Opens widget inside a light box at the specified position. Seller can use this method instead of the render method to display order details in a modal dialog window when the buyer clicks a link or button. The top and left positions can be specified in pixels or as a percentage relative to the browser window. Both the top and left parameters are required.

11 OrderDetailsWidget 11 Note: You can also use the render() method (see Common Widget Methods in this document. Size Specification If you use the open() method of the OrderDetailsWidget, the pop-up window will be 422 pixels wide and 340 pixels high. Please note that if you decide to use the open() method, you cannot configure the size of the pop-up window. If you use the render() method of the OrderDetailsWidget, you can also specify the width and height of the box that will display the order summary. You can configure the size as part of the design input parameter. The table below lists the available ranges and the default size. Width (pixels) Height (pixels) Default (pixels) Min Max Min Max (w) x 310 (h) Example To display the order details on clicking a link, use this example. The widget will open at pos-x = 554px and pos-y = 230px: <-- Dynamically replace "AMAZON ORDER ID" ' ' with the correct Amazon Order ID --> <p>your Amazon Payments Order ID is <a href="#" onclick="orderdetailswidget.open('230px', '554px');"> </ a>.</p> // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", var orderdetailswidget = new CBA.Widgets.OrderDetailsWidget({ // Dynamically replace "AMAZON ORDER ID" ' ' with the correct Amazon Order ID orderid: ' ' }); To display the order detail on part of the page layout, use this example. Note that in this example, the OrderDetailsWidget, when rendered, will display the details of this order when the page loads. <div id="amazonorderdetail"></div> new CBA.Widgets.OrderDetailsWidget ({ // Replace "AEIOU9999AEIOU" with your own merchantid value merchantid: "AEIOU9999AEIOU", // Dynamically replace "AMAZON ORDER ID" ' ' with the correct Amazon Order ID orderid: " " }).render ("amazonorderdetail");