Checkout by Amazon Widget Reference Guide - Inline Checkout

Transcription

1 Checkout by Amazon Widget Reference Guide - Inline Checkout

2 2 Checkout by Amazon TOC Contents Overview of Checkout by Amazon Inline Standard Checkout... 3 Who Should Read This Document...3 Prerequisites... 3 Code Samples...3 Other Documentation... 3 What's New in This Document...4 Widget Overview... 5 Widget Setup... 5 Common Widget Methods... 6 Common Widget Parameters... 6 Widgets...7 List of Widgets by Function...7 InlineCheckoutWidget Widget Parameters... 8 Widget Methods... 9 Example...9 AddressWidget Widget Parameters Example...11 WalletWidget Widget Parameters Example...13 ExpressCheckoutWidget Widget Parameters Widget Methods Example...15 OrderDetailsWidget Widget Parameters Widget Methods Example...17

3 Checkout by Amazon Overview of Checkout by Amazon Inline Standard Checkout 3 Overview of Checkout by Amazon Inline Standard Checkout Welcome to the Checkout by Amazon Inline 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 Inline Standard Checkout Widgets on your website. Prerequisites This guide assumes you--or your development staff--are familiar with using HTML and JavaScript in an application development environment. Before you can use Checkout by Amazon Inline Standard Checkout, your systems must meet the following prerequisites: You must be familiar with using web service APIs. 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 Inline and Express Checkout.) Standard Checkout.) For more information about using the Inline Standard Checkout Widgets, please see the following references: Inline Checkout API Reference Guide Inline Checkout Implementation Guide Inline Checkout Widget Reference Guide HTML Implementation Guide (PDF) XML Implementation Guide (PDF) Code Samples Checkout by Amazon provides code samples to assist you when implementing Inline Standard Checkout. Programming Language Java Download Location SDK Other Documentation You can read our downloadable PDFs to understand more about Checkout by Amazon. More Resources for Checkout by Amazon Resource Audience, Purpose, and Goals

4 4 Checkout by Amazon Overview of Checkout by Amazon Inline Standard Checkout Getting Started Guide Standard Checkout - Button Creation Wizard Implementation Guide Standard Checkout - HTML Implementation Guide Standard Checkout - XML Implementation Guide Inline Checkout - Implementation Guide Standard Checkout - Callback API Guide Instant Order Processing Notifications Guide Managing Orders For merchants who want to use a simple, step-bystep approach in setting up Checkout by Amazon on their websites. The Getting Started Guide walks merchants through the process, from gathering the required information for signing up for an account to setting up a button on their websites. For merchants and developers who want a detailed list of ways to integrate their website with Checkout by Amazon. The Implementation Guide provides the information needed for programming and code development. Note that there are three versions of this document: one for those who just want to paste the button code built using the Create Checkout Button feature in Seller Central, one for HTML-based code, and one for XMLbased code. For merchants and developers who want to integrate Checkout by Amazon seamlessly into their website. Inline Integration allows you to integrate Checkout by Amazon completely into your website using your layout. Your buyers can checkout using Checkout by Amazon without popups. For developers who want to build their own applications to calculate shipping rates as well as promotional discounts and then send these results to Checkout by Amazon. For developers who want to automate order notifications with Amazon Payments. A guide to assist you in the day-to-day operations for managing orders generated by Checkout by Amazon. What's New in This Document Release Date Revise links to other documentation Release Date Widget Reference Guide Small corrections to the content Release Date Widget Reference Guide Initial Release

5 Checkout by Amazon Widget Overview 5 Widget Overview Widget Setup We recommend you to use our Inline Integration Code Generator to generate the widgets that can be found in Seller Central. 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=' </script> <div id="amazonwidget"> // Replace "AEIOU1234AEIOU" with your own merchantid value <img src=" cartownerid=aeiou1234aeiou"/> </div> <script> new CBA.Widgets.XXXWidget ({ // Widget-specific parameters }).render("amazonwidget"); </script> The widget setup involves 4 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. Place the Checkout by Amazon button img source URL in the div defined as part of Step Inside a script block, create an instance of the widget you want to display. 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. URL Domains Used in This Guide The URL domain is specific for country to support internalization (i18n). That is, the JavaScript URL for DE is: Production Widget Please see this table for a list of URLs used for specific locales: Locale DE URL PaymentWidgets.js Sandbox Widget To test your integration in the Sandbox environment, use this URL.

6 6 Checkout by Amazon Widget Overview Locale DE URL de/sandbox/paymentwidgets.js Payment Buttons Use these links for the payment button images on your site. Stage Production Sandbox URL button?cartownerid=<merchant- ID>&color=<COLOR>&size=<SIZE> &background=<background>&type=<type> cba/button?cartownerid=<merchant- ID>&color=<COLOR>&size=<SIZE> &background=<background>&type=<type> Color, size, background, and type are optional parameters and can hold the values as defined in Widget Parameters on page 8C_StandardCheckoutWidgetWidgetParameters.dita_DE. The row labeled "buttonsettings" has information about color, size, and background The row labeled "buttontype" has information about type Common Widget Methods Each widget supports following methods: 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.

7 Checkout by Amazon Widgets 7 Widgets List of Widgets by Function Initiating checkout InlineCheckoutWidget ExpressCheckoutWidget StandardCheckoutWidget Note: Please read the corresponding Checkout by Amazon Implementation Guides for details of how checkout can be initiated from your website using any of the above widgets. Accessing account information AddressWidget WalletWidget Accessing order details OrderDetailsWidget

8 8 Checkout by Amazon InlineCheckoutWidget InlineCheckoutWidget The Inline Checkout widget renders the Checkout with Amazon button that allows your buyers to indicate that they'd like to access their Amazon account information and pay with Amazon Payments during the checkout process. When the Inline Checkout widget is coupled with the Address Book widget and the Wallet widget, you can allow your buyers to complete their checkout on your site. 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 required onauthorize Callback function The JavaScript function to perform when the buyer clicks the Checkout by Amazon button and authenticates himself. Upon successful authentication, this JavaScript function is performed. The widget object is passed as an input parameter to the function. optional purchasecontractid String The unique identifier for the purchase contract created by createpurchasecontract API. If you do not use APIs to create the contract (that is, if you leave this blank), the widget will create a contract. You can access the purchase contract inside the onauthorize callback. optional buttonsettings Object The following is an example button settings: {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 buttontype String The value of this parameter determines what type of button to display. Possible values are "checkout" or "addressbook". The default value is "checkout".

9 Checkout by Amazon InlineCheckoutWidget 9 Required Name Type If the value is set to "checkout", the button label displays the text "Checkout with Amazon". If the value is set to "addressbook", the button label displays the text "Use Amazon Address Book". 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 getpurchasecontractid() Returns the purchasecontractid if one exists. If called inside the onauthorize callback, it returns the purchase contract ID that is created after buyer clicks the button and authenticates himself. Example The widget below renders showing the label "Use Amazon Address Book." In this example, after the buyer clicks the button and authenticates the purchase, the widget calls the function associated with the onauthorize parameter. The function then redirects the browser to the next page. <div id="amazoninlinewidget"> // Replace "AEIOU1234AEIOU" with your own merchantid value <img src=" cartownerid=aeiou1234aeiou &color=orange&size=large&background=white&type=inlinecheckout"/> </div> <script> new CBA.Widgets.InlineCheckoutWidget({ // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", onauthorize: function(widget) { window.location = ' + widget.getpurchasecontractid() ; } }).render("amazoninlinewidget") ; </script>

10 10 Checkout by Amazon AddressWidget AddressWidget The Address Book Widget allows your buyers to access their Amazon address book from within your checkout pipeline and select a shipping address. Widget Parameters Table 3: Required Name Data Type optional purchasecontractid String Purchase Contract ID generated by either InlineCheckoutWidget or ExpressCheckoutWidget. If not provided, the widget will assume the one stored in the cookie. optional destinationname String Uniquely identifies each address selected by the buyer. The seller provides the identifier to make sure that it's unique if the seller wants to collect more than one address from the buyer. If no name is supplied, the system uses the name "#default". When using the getpurchasecontract API, you find the selected address associated with this destination name or with "#default" name if none is provided here. optional displaymode String Indicates whether the widget is intended for display only purposes or not. displaymode:read renders the widget and displays the shipping address associated with the purchase contract. This mode requires that the shipping address is already selected and is associated with the purchase contract. This mode is best for use after the buyer selects an address using the Express Checkout widget. displaymode:edit renders the widget with the option to select or change shipping address. This mode does not require that a shipping address is selected and associated with the purchase contract. Possible values are "Read" and "Edit". Default mode is "Edit." optional onaddressselect Callback function JavaScript function to perform after buyer selects an address. The widget object is passed as an input parameter to the function. You can retrieve the selected address using the getpurchasecontract API on the server side.

11 Checkout by Amazon AddressWidget 11 Required Name Data Type optional design Object 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". Note: In the current release, there is only one design and color theme. Therefore, you do not need to specify these attributes. However, you can still customize the width and height of the wallet widget. Below are the allowed width and height values for this widget. Please note that the size restrictions depend on the displaymode value. The default values are used if no width or height is provided. Mode Width (pixels) Height (pixels) Default (pixels) Min Max Min Max displaymode:read (w) x 180 (h) displaymode:edit (w) x 230 (h) Example The widget below allows buyers to see their addresses and select one of them. The selected address is then associated with the destination name "GIFT1". <div id="amazonaddresswidget"></div> <script> new CBA.Widgets.AddressWidget({ // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", destinationname: "GIFT1", displaymode: "Edit", onaddressselect: function(widget) { alert("address selected for " + widget.getpurchasecontractid()); } }).render("amazonaddresswidget"); </script>

12 12 Checkout by Amazon WalletWidget WalletWidget The Wallet Widget (also called the Payment Method Widget) allows your buyers to access the payment methods in their Amazon account from within your checkout pipeline and select a payment method for the order. Widget Parameters Table 4: Required Name Data Type optional purchasecontractid String Purchase Contract ID generated by either InlineCheckoutWidget or ExpressCheckoutWidget. If not provided, the widget will assume the one stored in the browser cookie. optional displaymode String Indicates whether the widget is intended for display-only purposes or not. displaymode:read renders the Wallet widget and displays the payment method already associated with the purchase contract. This mode requires that a payment method is selected and is associated with the purchase contract. This mode is best for use after the buyer selects payment using the Express Checkout widget. displaymode:edit renders the Wallet widget with the option to select or change the payment method. This mode does not require that a payment method is selected and associated with the purchase contract. Possible values are "Read" and "Edit". Default mode is "Edit." optional design Object 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',

13 Checkout by Amazon WalletWidget 13 Required Name Data Type optional onpaymentselect Callback function 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". JavaScript function to perform after buyer selects a payment method. The widget object is passed as an input parameter to the function. Amazon Payments uses the selected payment method to authorize and charge the buyer. Please note that Amazon Payments does not share the selected payment method with you. Note: In the current release, there is only one design and color theme. Therefore, you do not need to specify these attributes. However, you can still customize the width and height of the wallet widget. Below are the allowed width and height values for this widget. Please note that the size restrictions depend on the displaymode value. The default values are used if no width or height is provided. Mode Width (pixels) Height (pixels) Default (pixels) Min Max Min Max displaymode:read (w) x 180 (h) displaymode:edit (w) x 230 (h) Example In the example below, the Wallet widget renders in the read mode and displays the payment method already associated with the purchase contract. The widget size is 200 pixels wide and 300 pixels high. <div id="amazonwalletwidget"></div> <script> new CBA.Widgets.WalletWidget({ // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", purchasecontractid: "abcdefg", displaymode: "Read", design: {size: {width: '200', height: '300'}} } ).render("amazonwalletwidget"); </script>

14 14 Checkout by Amazon ExpressCheckoutWidget ExpressCheckoutWidget The Express Checkout Widget provides an alternate way for your buyers to initiate their checkout with Amazon. With the Express Checkout Widget, the buyer can select an address and payment within a pop-up window hosted by Amazon Payments before entering your checkout pipeline. By contrast, with Inline Checkout Widget the buyer gets a chance to select an address only inside your checkout pipeline using the Address Book Widget. Both the Inline Checkout Widget and the Express Checkout Widget allow your buyers to complete checkout on your website. Both leverage the Address Book Widget and Wallet widget integrated within your checkout pipeline. The key difference is the buyer experience. Widget Parameters Table 5: Required Name Type required onauthorize Callback function optional onopen Callback function The JavaScript function to perform when the buyer authorizes a shipping address and payment. After the buyer clicks the Checkout by Amazon button, he is prompted to select an address and payment. Upon confirming the selection, this JavaScript function is performed. The widget object is passed as an input parameter to the function. JavaScript function to perform when the Express Checkout window opens after buyer clicks the Checkout with Amazon button. The code is performed before buyer is prompted for an address and payment inside the pop-up window. The widget object is passed as an input parameter to the function. You are expected to invoke a submit method on the widget object whenever you choose to add such a callback function. Only after you invoke the submit method will the buyer be able to select an address and a payment method. optional buttonsettings Object The following is an example button settings: {size:'large', color:'orange', background:'white'} Below are possible values for each button setting property: Size: medium large x-large. Default is large.

15 Checkout by Amazon ExpressCheckoutWidget 15 Required Name Type Color: orange tan. Default is orange. Background: white light dark. Default is white. optional purchasecontractid String The unique identifier for the purchase contract created by the V2 API (see the Inline Checkout API Reference Guide for more information). If the purchase contract ID provided here, then the widget updates that purchase contract when the buyer selects an address and payment method. If you leave this blank, the widget creates a contract. You can access the purchase contract ID inside the onauthorize callback. Widget Methods Table 6: Name getpurchasecontractid() submit() Returns the purchasecontractid if one exists. If the function is called inside the onauthorize callback, the function returns the purchase contract ID created after buyer confirms the address and payment in the pop-up window. If you associate a function with the onopen parameter, the buyer can select an address and payment only after you call the submit() method. Example Simple use case; after selecting an address and payment method, the buyer is redirected to the location set in the onauthorize callback function: <div id="amazonexpresswidget"> // Replace "AEIOU1234AEIOU" with your own merchantid value <img src=" cartownerid=aeiou1234aeiou&color=orange&size=large&background=white"/> </div> <script> new CBA.Widgets.ExpressCheckoutWidget({ // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", onauthorize: function(widget) { window.location = ' + widget.getpurchasecontractid();} }).render("amazonexpresswidget"); </script>

16 16 Checkout by Amazon 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 7: 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 8: 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

17 Checkout by Amazon OrderDetailsWidget 17 Name Data Type a percentage relative to the browser window. Both the top and left parameters are required. 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: <p>your Amazon Payments Order ID is <a href="#" onclick="orderdetailswidget.open('230px', '554px');"> </a>.</p> <script> // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", var orderdetailswidget = new CBA.Widgets.OrderDetailsWidget({ orderid: ' ' }); </script> 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> <script> new CBA.Widgets.OrderDetailsWidget ({ // Replace "AEIOU9999AEIOU" with your own merchantid value merchantid: "AEIOU9999AEIOU", orderid: " " }).render ("amazonorderdetail"); </script>