Checkout by Amazon Widget Reference Guide - Inline Checkout

Transcription

1 Checkout by Amazon Widget Reference Guide - Inline Checkout

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

3 Overview of This Document 3 Overview of This Document Overview of Checkout by Amazon Inline Checkout Welcome to the Checkout by Amazon Inline Checkout Widgets Reference Guide. This section describes who should read this guide, how the guide is organized, 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 Checkout Widgets on your website. Prerequisites This guide assumes you--or your development staff--are familiar with using HTML and XML in an application development environment. Before you can use Checkout by Amazon Inline Checkout, your systems must meet the following prerequisites: You must be familiar with using web service APIs. You must be familiar with using JavaScript. (There are several required JavaScript code snippets that you must use in your carts to enable Inline Checkout and Express Checkout.) Other Documentation You can read our downloadable PDFs to understand more about Checkout by Amazon. More Resources for Checkout by Amazon Resource Getting Started Guide Standard Checkout - Button Creation Wizard Implementation Guide Audience, Purpose, and Goals For merchants who want to use a simple, step-by-step 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 XML-based code. Standard Checkout - HTML Implementation Guide Standard Checkout - XML Implementation Guide Using Seller Central Standard Checkout - Callback API Guide For merchants who want an overview of Seller Central. For developers who want to build their own applications to calculate shipping and tax rates as well as promotional discounts and then send these results to Checkout by Amazon.

4 Overview of This Document 4 Standard Checkout - Callback API Developers Cheat Sheet Instant Order Processing Notifications Guide Using Custom Data Fields Guide Best Practices Guide Managing Orders For developers who want a quick, 1-page summary of how to enable callbacks. For developers who want to automate order notifications with Amazon Payments. For merchants and developers who want to include custom data fields in their carts. Tips for setting up your website to use Amazon Payments, with advice for planning, setting up, and day-to-day operations. 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 Global Changes New section Notice About Amazon Payments Services Functionality on page 4 Release Date Global Changes Revise links to other documentation Release Date Global changes Modified the document to show the changes to the button use. Release Date Notice About Amazon Payments Services Functionality The Amazon Payments service has been designed and developed for use within a web browser only. Our service cannot be used within a native application (including, without limitation, ios, Android, RIM, or Windows operating systems). Amazon Payments reserves the right to suspend the Payment Account of any user of our services that has implemented our Services within a native application.

5 Widget Overview 5 Widget Overview Widget Setup To render a widget, copy and paste 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=" style="cursor: pointer;"/> </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 US is: Production Widget Please see this table for a list of URLs used for specific locales: Locale US URL PaymentWidgets.js Sandbox Widget To test your integration in the Sandbox environment, replace the JavaScript URL with one of these, depending on your locale:

6 Widget Overview 6 Locale US URL us/sandbox/paymentwidgets.js Common Widget Methods Each widget supports following methods: Name render(locationid) string getlocation() string getwidgettype() Description 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 Description required merchantid String Your merchant ID is a required parameter to each widget.

7 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 InlineCheckoutWidget 8 InlineCheckoutWidget Description 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 Description 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. 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() Description 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.

9 InlineCheckoutWidget 9 Example The widget below renders showing the label "Checkout with Amazon." 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=" &background=white&type=inlinecheckout" style="cursor: pointer;" /> </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 AddressWidget 10 AddressWidget Description 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 Description 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. optional design Object Amazon Payments will provide pre-defined set of designs. Each design identified by the name attribute has a choice

11 AddressWidget 11 Required Name Data Type Description 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 US-only 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 WalletWidget 12 WalletWidget Description 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 Description 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 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', size: {width: 'width in pixels', height: 'height in pixels'} }

13 WalletWidget 13 Required Name Data Type Description Please note that when you set width and height values, use digits only. Do not append unit measurements such as "px". optional onpaymentselect Callback function 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 ExpressCheckoutWidget 14 ExpressCheckoutWidget Description 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 Description 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 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 ID 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 inside the onauthorize callback.

15 ExpressCheckoutWidget 15 Widget Methods Table 6: Name getpurchasecontractid() submit() Description 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=" &background=white&type="expresscheckout" style="cursor: pointer;" /> </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 OrderDetailsWidget 16 OrderDetailsWidget Description 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 Description 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 Description 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.

17 OrderDetailsWidget 17 Note: You can also use the render() method (see Common Widget Methods in this documentcommon Widget Methods. 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> var orderdetailswidget = new CBA.Widgets.OrderDetailsWidget({ // Replace "AEIOU1234AEIOU" with your own merchantid value merchantid: "AEIOU1234AEIOU", 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>