Checkout by Amazon Widget Reference Guide - Standard Checkout

Checkout by Amazon Widget Reference Guide - Standard Checkout

| TOC | 2

Contents Overview of This Document........................................................................................................... 3 Overview of Checkout by Amazon Standard Checkout....................................................................................... 3 Who Should Read This Document............................................................................................................3 Prerequisites.............................................................................................................................................. 3 Code Samples............................................................................................................................................ 3 Other Documentation................................................................................................................................ 3 What's New in This Document..................................................................................................................4 Notice About Amazon Payments Services Functionality......................................................................... 5

Widget Overview............................................................................................................................. 6 Widget Setup......................................................................................................................................................... 6 Common Widget Methods.................................................................................................................................... 7 Common Widget Parameters.................................................................................................................................8

Widgets............................................................................................................................................. 9 List of Widgets by Function..................................................................................................................................9

StandardCheckoutWidget............................................................................................................ 10 Description.......................................................................................................................................................... 10 Widget Parameters.............................................................................................................................................. 10 Widget Methods.................................................................................................................................................. 11 Example...............................................................................................................................................................11

OrderDetailsWidget...................................................................................................................... 14 Description.......................................................................................................................................................... 14 Widget Parameters.............................................................................................................................................. 14 Widget Methods.................................................................................................................................................. 14 Example...............................................................................................................................................................15

| Overview of This Document | 3

Overview of This Document Overview of Checkout by Amazon Standard Checkout Welcome to the Checkout by Amazon Inline Checkout API Reference Guide. Welcome to the Checkout by Amazon Inline Checkout Guide. Welcome to the Checkout by Amazon Standard Checkout Widgets Reference Guide. 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 Standard Checkout using Checkout by Amazon 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: Before you can use Checkout by Amazon Standard 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.)

For more information about using the Inline Checkout Widgets, please see the following references: • • •

Inline Checkout API Reference Guide Inline Checkout Implementation Guide Inline Checkout Widget Reference Guide

• • •

Inline Checkout API Reference Guide for Subsidiaries Inline Checkout Implementation Guide for Subsidiaries Inline Checkout Widget Reference Guide for Subsidiaries

Code Samples Checkout by Amazon provides code samples to assist you when implementing Inline or Standard Checkout. Programming Language

Download Location

Java

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


Getting Started Guide

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.

Standard Checkout - Button Creation Wizard Implementation Guide

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

For merchants who want an overview of Seller Central.

Standard Checkout Callback API Guide

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.

Standard Checkout - Callback API Developers Cheat Sheet

For developers who want a quick, 1-page summary of how to enable callbacks.

Instant Order Processing Notifications Guide

For developers who want to automate order notifications with Amazon Payments.

Using Custom Data Fields Guide

For merchants and developers who want to include custom data fields in their carts.

Best Practices Guide

Tips for setting up your website to use Amazon Payments, with advice for planning, setting up, and day-to-day operations.

Managing Orders

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 2013-11-20 Global Changes •

New section Notice About Amazon Payments Services Functionality on page 5

Release Date 2013-04-13 Global Changes •

Revise links to other documentation

Release Date 2013-02-05 API Reference Guide


•

Updated Request Parameters to remove "Condition" as a parameter.

Release Date 2012-04-13 Global changes •

Modified the document to show the changes to the button use.

Release Date 2012-06-27 API Reference Guide •

Updated Request Parameters to document that only MERCHANT is acceptable as a FulfillmentNetwork value.

Release Date 2011-04-07 API Reference Guide •

Updated section on Request Parameters to include updates to the use of MerchantURL and IntegratorURL

Release Date 2010-12-15 Global changes •

Added information to support Amazon Subsidiaries.

Release Date 2010-10-22 Changes to this document Implementation Guide •

Added section on Checkout by Amazon on Mobile-Optimized Websites

Release Date 2010-09-15 Changes to this document Implementation Guide •

Initial Release

Widget Reference Guide •

Initial Release

API Reference Guide •

Added section on SetContractCharges

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.

| Widget Overview | 6

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.
// Replace "AEIOU1234AEIOU" with your own merchantId value
new CBA.Widgets.XXXWidget ({ // Widget-specific parameters }).render("AmazonWidget"); 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 2. 4. 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: https://static-na.payments-amazon.com/cba/js/us/PaymentWidgets.js Production Widget Please see this table for a list of URLs used for specific locales: Locale

URL

US

https://static-na.payments-amazon.com/cba/js/us/ PaymentWidgets.js

Sandbox Widget To test your integration in the Sandbox environment, replace the JavaScript URL with one of these, depending on your locale:


Locale

URL

US

https://static-na.payments-amazon.com/cba/js/ us/sandbox/PaymentWidgets.js

Payment Buttons Use these links for the payment button images on your site. Stage

URL

Production

https://payments.amazon.com/gp/cba/ button?cartOwnerId=&color=&size= &background=&type=

Sandbox

https://payments-sandbox.amazon.com/gp/ cba/button?cartOwnerId=&color=&size= &background=&type=

Color, size, background, and type are optional parameters and can hold the values as defined the table below: Table 1: Parameter Name

Required

Description

cartOwnerid

Required

The merchant ID is to be used to show the button

color

Optional

Defines the color of the button. Options: orange | tan. Default is orange.

size

Optional

Defines the size of the button. Options: medium | large | x-large Default is large

background

Optional

Defines the background color where the button will be used on your website. Options: white | light | dark Default is white.

type

Optional

The value of this parameter determines what type of button to display. Possible values are "inlineCheckout", "addressBook", or "expressCheckout". The default value is "inlineCheckout". If the value is set to "inlineCheckout", 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". if the value is set to "expressCheckout", the button label displays the text "Checkout with Amazon".

Common Widget Methods Each widget supports following methods:


Name

Description

render(locationId)

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.

string getLocation()

This returns the associated locationId set by render method.

string getWidgetType()

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.

required

purchaseContractId

String

The unique identifier for the purchase contract created by CreatePurchaseContract API. This is a required parameter to each widget.

| Widgets | 9

Widgets List of Widgets by Function Initiating checkout • • •

InlineCheckoutWidgetInlineCheckoutWidget ExpressCheckoutWidgetExpressCheckoutWidget StandardCheckoutWidgetStandardCheckoutWidget 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 • •

AddressWidgetAddressWidget WalletWidgetWalletWidget

Accessing order details •

OrderDetailsWidgetOrderDetailsWidget

| StandardCheckoutWidget | 10

StandardCheckoutWidget Description 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 2: Required

Name

Type

Description

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 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.


Required

Name

Type

Description

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

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 3: Name

Description

updateOrderInput(orderInput)

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.

submit()

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'}.

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+; 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.

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 dynamically when buyer clicks the button. In this example, the order input string is not readily available when page loads. Instead, you use AJAX to communicate with your backend process to receive the encoded and signed order input string on demand after page loads. Notice how the submit() method is called after an AJAX response is received. The example below uses JQuery to implement the AJAX call.

new CBA.Widgets.StandardCheckoutWidget({ merchantId: AEIOU1234AEIOU, buttonSettings: {background:'light'}, onOpen: function() { $.ajax({


url: 'ajax/test.html', complete: function(data) { // Initialize orderInputString variable with a string that represents // the encoded cart xml with the signature appended to it. // You will extract that string from the AJAX response before // initializing orderInputString variable. // (see XML Implementation Guide for steps to construct the string) // Then set the orderInput parameter and call submit() method // to signal the widget to display order details // Notice that the input to the updateOrderInput() method is same as // the widget parameter: orderInput. this.updateOrderInput({format: "XML", value: orderInputString}); this.submit(); } }); } }).render("cbaButton");

| OrderDetailsWidget | 14

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 4: 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 5: 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.

| OrderDetailsWidget | 15

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

392

600

310

400

392 (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:
Your Amazon Payments Order ID is 902-3317348-8724505.
var orderDetailsWidget = new CBA.Widgets.OrderDetailsWidget({ // Replace "AEIOU1234AEIOU" with your own merchantId value merchantId: "AEIOU1234AEIOU", orderID: '902-3317348-8724505' }); 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.
new CBA.Widgets.OrderDetailsWidget ({ // Replace "AEIOU9999AEIOU" with your own merchantId value merchantId: "AEIOU9999AEIOU", orderID: "902-3317348-8724505" }).render ("amazonOrderDetail");