Amazon Payments API Reference Guide

| Contents | 2

Contents

Overview of This Document.................................................................................... 4 Overview of Checkout by Amazon Inline Checkout API Reference Guide...................................................... 4

Who Should Read This Document.......................................................................................................... 4Prerequisites.............................................................................................................................................. 4Other Documentation................................................................................................................................4What's New in This Document................................................................................................................ 5Notice About Amazon Payments Services Functionality........................................................................ 6

API Overview............................................................................................................ 7WSDL and Schema Location...............................................................................................................................7API Versioning..................................................................................................................................................... 7

Specifying the API Version..................................................................................................................... 7Query Requests..................................................................................................................................................... 7

Structure of a GET Request..................................................................................................................... 8Structure of a POST Request................................................................................................................... 8

Responses.............................................................................................................................................................. 9Structure of a Successful Response......................................................................................................... 9Structure of an Error Response.............................................................................................................. 10API Endpoints in Production..................................................................................................................10API Endpoints in the Sandbox...............................................................................................................10

Signing Query Requests..................................................................................................................................... 11Signing Your Query Requests................................................................................................................11Create the Signature............................................................................................................................... 11Sample Signature Calculation for Query Requests................................................................................12Steps for Building a Signature............................................................................................................... 12

Amazon Payments Query API.............................................................................. 14Common Query Parameters................................................................................................................................14List of Query Operations....................................................................................................................................15CreatePurchaseContract...................................................................................................................................... 15

Description.............................................................................................................................................. 15Request Parameters.................................................................................................................................16Response Elements................................................................................................................................. 16Examples................................................................................................................................................. 17

GetPurchaseContract........................................................................................................................................... 18Description.............................................................................................................................................. 18Request Parameters.................................................................................................................................18Response Elements................................................................................................................................. 18Examples................................................................................................................................................. 18

SetPurchaseItems.................................................................................................................................................19Description.............................................................................................................................................. 19Request Parameters.................................................................................................................................19Response Elements................................................................................................................................. 23Examples................................................................................................................................................. 24

SetContractCharges............................................................................................................................................. 25Description.............................................................................................................................................. 25Request Parameters.................................................................................................................................25

| Contents | 3

Response Elements................................................................................................................................. 27Examples................................................................................................................................................. 27

CompletePurchaseContract................................................................................................................................. 27Description.............................................................................................................................................. 27Request Parameters.................................................................................................................................28Response Elements................................................................................................................................. 28Examples................................................................................................................................................. 29

Error Codes and Descriptions...............................................................................30HTML Error Codes and Descriptions................................................................................................................30Application Error Codes and Descriptions........................................................................................................ 30

| Overview of This Document | 4

Overview of This Document

Overview of Checkout by Amazon Inline Checkout API Reference Guide

Welcome to the Checkout by Amazon Inline Checkout API Reference Guide .

This section describes who should read this guide, how the guide is organized, and other resources related toCheckout by Amazon.

Who Should Read This Document

This document gives you the reference information for Inline Checkout APIs.

Prerequisites

This guide assumes you--or your development staff--are familiar with using HTML and XML in an applicationdevelopment environment.

• 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 Audience, Purpose, and Goals

Getting StartedGuide

For merchants who want to use a simple, step-by-step approach in setting up Checkout byAmazon 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 buttonon their websites.

StandardCheckout - ButtonCreation WizardImplementationGuide

StandardCheckout - HTMLImplementationGuide

Standard Checkout -XML ImplementationGuide

For merchants and developers who want a detailed list of ways to integrate their websitewith Checkout by Amazon. The Implementation Guide provides the information needed forprogramming 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 Buttonfeature in Seller Central, one for HTML-based code, and one for XML-based code.

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 ratesas well as promotional discounts and then send these results to Checkout by Amazon.

http://amazonpayments.s3.amazonaws.com/documents/Getting_Started_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Getting_Started_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideBTN.pdf





http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideHTML.pdf




http://amazonpayments.s3.amazonaws.com/documents/ImplementationGuideXML.pdf



http://amazonpayments.s3.amazonaws.com/documents/Using_Seller_Central.pdf

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_Guide.pdf


Standard Checkout- Callback APIDevelopers CheatSheet

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

Instant OrderProcessingNotifications Guide

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

Using Custom DataFields 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, settingup, and day-to-day operations.

Managing Orders A guide to assist you in the day-to-day operations for managing orders generated byCheckout by Amazon.

What's New in This Document

Release Date 2014-03-27

Global Changes

• Updated content to clarify Access Keys.


Global Changes

• New section Notice About Amazon Payments Services Functionality on page 6


Global Changes

• Revise links to other documentation


API Reference Guide

• Updated Request Parameters on page 19 to remove "Condition" as a parameter.


Global changes

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


API Reference Guide

• Updated Request Parameters on page 19 to document that only MERCHANT is acceptable as aFulfillmentNetwork value.


API Reference Guide

http://amazonpayments.s3.amazonaws.com/documents/Callback_API_DCS.pdf




http://amazonpayments.s3.amazonaws.com/documents/Instant_Order_Processing_Notification_API_Guide.pdf



http://amazonpayments.s3.amazonaws.com/documents/Using_Custom_Data_Fields.pdf

http://amazonpayments.s3.amazonaws.com/documents/Using_Custom_Data_Fields.pdf

http://amazonpayments.s3.amazonaws.com/documents/Best_Practices_Guide.pdf

http://amazonpayments.s3.amazonaws.com/documents/Checkout_by_Amazon_Managing_Orders_US.pdf


• Updated section on Request Parameters on page 28 to include updates to the use of MerchantURL andIntegratorURL


Global changes

• Added information to support Amazon Subsidiaries.


Changes to this document

Implementation Guide

• Added section on Checkout by Amazon on Mobile-Optimized Websites


Changes to this document

Implementation Guide

• Initial Release

Widget Reference Guide

• Initial Release

API Reference Guide

• Added section on SetContractCharges on page 25

Notice About Amazon Payments Services Functionality

The Amazon Payments service has been designed and developed for use within a web browser only. Our servicecannot be used within a native application (including, without limitation, iOS, Android, RIM, or Windows operatingsystems). Amazon Payments reserves the right to suspend the Payment Account of any user of our services that hasimplemented our Services within a native application.

| API Overview | 7

API Overview

WSDL and Schema Location

File URL

WSDL http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/CheckoutByAmazonService.wsdl

Schema http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/CheckoutByAmazonService.xsd

API VersioningBecause features and changes can introduce incompatible API changes, all Amazon Payments API updates areversioned. By including a version in the request, clients receive responses they can process.

Each API revision is assigned a version in date form (the current API version is 2010-08-31). This version is includedas a Version parameter when using our Query API. The response that Amazon Payments returns honors the versionincluded in the request.

The WSDL for each supported API version is available from the following URI:

http://amazonpayments.s3.amazonaws.com/documents/api/<api-version-date>/CheckoutByAmazonService.wsdl

The WSDL for latest version of our API is available from the following URI:

http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/CheckoutByAmazonService.wsdl

Specifying the API Version

For all requests, you must explicitly request the API version you want to use. Specifying the version makes sure thatthe service does not return response that your application is not designed to handle.

In Query requests, you include the Version parameter (highlighted).

http://payments.amazon.com/cba/api/purchasecontract/?Action=CreatePurchaseContract&AWSAccessKeyId=0GS7573JW74RZM612K0AEXAMPLE&Expires=2010-09-10T12:00:00Z&SignatureMethod=HmacSHA256&SignatureVersion=2&Version=2010-08-31&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE

Query RequestsAmazon Payments supports Query requests for calling service actions. Query requests are simple HTTPS requests,using the GET or POST method. Query requests must contain an Action parameter to indicate the action to beperformed. The response is an XML document that conforms to a schema.



http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/CheckoutByAmazonService.xsd

http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/CheckoutByAmazonService.xsd

| API Overview | 8

Structure of a GET Request

This guide presents the Amazon Payments GET requests as URLs, which can be used directly in a browser. The URLconsists of the following elements:

• Endpoint—The resource the request is acting on• Action—The action you want to perform on the endpoint; for example: sending a message• Parameters—Any request parameters

The following is an example GET request to create a Purchase Contract.

https://payments.amazon.com/cba/api/purchasecontract/?Action=CreatePurchaseContract&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Version=2010-08-31&Expires=2010-10-10T12%30A00%30A00Z&SignatureVersion=2&SignatureMethod=HmacSHA256&Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE

Note:

Because the GET requests are URLs, you must URL-encode the parameter values. To make the GETexamples even easier to read, this guide presents them in the following parsed format.

In the example Query requests we present in this guide, we use a false Access Key ID and false signature,each with EXAMPLE appended. We do this to indicate that you shouldn't expect the signature in the exampleto be accurate based on the request parameters presented in the example.

The first line represents the endpoint of the request. After the endpoint is a question mark (?), which separates theendpoint from the parameters. Each parameter is separated by an ampersand (&).

The Action parameter indicates the action to perform (for a list of the actions, see List of Query Operations on page15 List of Query Operations). For a list of the other parameters that are common to all Query requests, seeCommon Query Parameters#CommonQueryParameters.

Structure of a POST Request

Amazon Payments also accepts POST requests. With a POST request, you send the query parameters as a form in theHTTP request body as described in the following procedure.

To create a POST request

1. Assemble the query parameter names and values into a form. This means you put the parameters and valuestogether like you would for a GET request (with an ampersand separating each name-value pair). The followingexample shows a sample request with the line breaks we use in this guide to make the information easier to read.

Action=SomeOperation&SomeTextInput=Your Message Text&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Version=2010-08-31&Expires=2010-10-10T12%30A00%30A00Z&SignatureVersion=2&SignatureMethod=HmacSHA256

2. Form-URL-encode the form according to the Form Submission section of the HTML specification (for moreinformation, please see http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1).

Action=SomeOperation&SomeTextInput=Your%20Message%20Text&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Version=2010-08-31&Expires=2010-10-10T12%30A00%30A00Z&SignatureVersion=2

http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1

| API Overview | 9

&SignatureMethod=HmacSHA256

3. Add the request signature to the end of the form. For more information about creating signatures, please see"Signing Query Requests," in the Inline Checkout Implementation GuideSigning Your Query Requests.

Action=SomeOperation&SomeTextInput=Your%20Message%20Text&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Version=2010-08-31&Expires=2010-10-10T12%30A00%30A00Z&SignatureVersion=2&SignatureMethod=HmacSHA256&Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE

4. Provide the resulting form as the body of the POST request.5. Include the Content-Type HTTP header with the value set to application/x-www-form-urlencoded.

Important: Do not use multi-part forms in your POST request as the post will fail.

The following example shows the final POST request.

POST / HTTP/1.1 Host: payments.amazon.com Content-Type: application/x-www-form-urlencoded

Action=SomeOperation &SomeTextInput=Your%20Message%20Text &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE

Amazon Payments requires no other HTTP headers in the request besides Content-Type.

Note: Your HTTP client typically adds other items to the HTTP request as required by the version of HTTPthe client uses. We don't include those additional items in the examples listed in this guide.

ResponsesIn response to an action request, Amazon Payments returns an XML data structure that contains the results of therequest. This data conforms to the Amazon Payments schema.

The XSD file defines the response messages, and users can access the XSD file directly. For more information, seeWSDL and Schema Location on page 7 #WSDLAndSchemaLocation .

Structure of a Successful Response

If the request succeeded, the main response element is named after the action, but with "Response"appended. For example, CreatePurchaseContractResponse is the response element returned for a successfulCreatePurchaseContract request. This element contains the following child elements:

• An optional element containing action-specific results; for example, the CreatePurchaseContractResponse elementincludes an element called CreatePurchaseContractResult

• ResponseMetadata, which contains the RequestId child element

The XML schema describes the XML response message for each Amazon Payments action.

http://amazonpayments.s3.amazonaws.com/documents/Inline_Checkout_Implementation_Guide.pdf

| API Overview | 10

The following is an example of a successful response.

HTTP/1.1 200<CreatePurchaseContractResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <CreatePurchaseContractResult> <PurchaseContractId>amzn1.contract.1.1.2.816c4711dabbc070c2feefe2afc82420</PurchaseContractId> </CreatePurchaseContractResult> <ResponseMetadata> <RequestId>5f89b701-a92c-11df-a44c-9b7a8313f6cb</RequestId> </ResponseMetadata></CreatePurchaseContractResponse>

Structure of an Error Response

If a request is unsuccessful, the main response element is called ErrorResponse regardless of the action that wascalled. This element contains at least one Error element and a RequestId element. Each Error includes:

• A Type element that identifies whether the error was a receiver or sender error• A Code element that identifies the type of error that occurred• A Message element that describes the error condition in a human-readable form

The following is an example of an error response.

<ErrorResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <Error> <Type> Sender </Type> <Code> InvalidParameterValue </Code> <Message> Value for parameter PurchaseContractID is invalid. </Message> </Error> <RequestId> 42d59b56-7407-4c4a-be0f-4c88daeea257 </RequestId></ErrorResponse>

API Endpoints in Production

The following table lists the API endpoint URLs used for specific locales:

Locale URL

US https://payments.amazon.com/cba/api/purchasecontract/

API Endpoints in the Sandbox

To test your integration in the Sandbox environment, please use these API endpoint URLs (depending on yourlocale):

Locale URL

US https://payments-sandbox.amazon.com/cba/api/purchasecontract/

| API Overview | 11

Signing Query Requests

Signing Your Query Requests

You must include a signature in every query request. This section describes how to create the signature. The methoddescribed in the following procedure is known as signature version 2.

Caution: If you are currently using signature version 1: Because signature version 1 is deprecated, you mustbe using signature version 2. For information about the differences between signature version 2 and version 1,please see Making Secure Requests to Amazon Web Services.

Checkout by Amazon provides code samples to assist you in signing your requests.

Programming Language Download Location

Java SDK

Create the Signature

Context for the current task

1. Create the canonicalized query string that you need later in this procedure:a) Sort the UTF-8 query string components by parameter name with natural byte ordering.

The parameters can come from the GET URI or from the POST body (when Content-Type isapplication/x-www-form-urlencoded.

b) URL-encode the parameter name and values according to the following rules:

• Do not URL-encode any of the unreserved characters that RFC 3986 defines. These unreserved charactersare A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).

• Percent-encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F.• Percent-encode extended UTF-8 characters in the form %XY%ZA....• Percent-encode the space character as %20 (and not +, as common encoding schemes do).

c) Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character61), even if the parameter value is empty.

d) Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).2. Create the string to sign according to the following pseudo-grammar (the "\n" represents an ASCII newline):

StringToSign = HTTPVerb + "\n" +ValueOfHostHeaderInLowercase + "\n" +HTTPRequestURI + "\n" +CanonicalizedQueryString <from the preceding step>

The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including, thequery string. If the HTTPRequestURI is empty, use a forward slash ( / ).

3. Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, andSHA256 or SHA1 as the hash algorithm.For more information, go to http://www.ietf.org/rfc/rfc2104.txt.

4. Convert the resulting value to base64.5. Use the resulting value as the value of the Signature request parameter.

Important: The final signature you send in the request must be URL-encoded as specified in RFC 3986 (formore information, go to http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL-encodes your final request,then it handles the required URL encoding of the signature. If your toolkit doesn't URL-encode the finalrequest, then make sure to URL-encode the signature before you include it in the request. Most importantly,make sure the signature is URL-encoded only once. A common mistake is to URL-encode it manually duringsignature formation, and then again when the toolkit URL-encodes the entire request.

http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1928

https://amazonpayments.s3.amazonaws.com/documents/checkoutbyamazon-service-2010-08-31-java-library.zip

http://www.ietf.org/rfc/rfc2104.txt

http://www.ietf.org/rfc/rfc3986.txt

| API Overview | 12

Sample Signature Calculation for Query Requests

Action=GetPurchaseContract SignatureMethod=HmacSHA256 PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 AWSAccessKeyId=AKIAJV6MUTXRDBNVXLJA SignatureVersion=2 Version=2010-08-31 Timestamp=2010-08-31T11:45:50.582Z

Steps for Building a Signature

1. Create the canonicalized query stringa) Sort the UTF-8 query string components by parameter name with natural byte ordering. The parameters

can come from the GET URI or from the POST body (when Content-Type is application/x-www-form-urlencoded).

AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE Action=GetPurchaseContract PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 SignatureMethod=HmacSHA256 SignatureVersion=2 Timestamp=2010-08-31T11:45:50.582ZVersion=2010-08-31

b) URL-encode the parameter name and values.c) Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character

61), even if the parameter value is empty.

AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE Action=GetPurchaseContract PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 SignatureMethod=HmacSHA256 SignatureVersion=2 Timestamp=2010-08-31T11%3A45%3A50.582ZVersion=2010-08-31

d) Concatenate the parameters and separate the name-value pairs with an ampersand ( & ) (ASCII code 38). Thiswill give you the Canonicalized Query String.

AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Action=GetPurchaseContract&PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2010-08-31T11%3A45%3A50.582Z&Version=2010-08-31

2. Create the string to sign according to the following grammar (the "\n" represents an ASCII newline character).Literal values are in plain text; values you replace are in italics:

Code Explanation

HTTP Verb Use an HTTP verb such as "GET" or "POST"

+ "\n" + New line

Value of host header inlowercase

For example, "payments-sandbox.amazon.com"

Notice it is all lowercase and does not have port as it uses standard port 443

+ "\n" + New line

HTTP Request URI For example, "/cba/api/purchasecontract/"

| API Overview | 13

Code Explanation

+ "\n" + New line

Canonicalized QueryString

Get this from the previous step

For example

POSTpayments-sandbox.amazon.com/cba/api/purchasecontract/AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Action=GetPurchaseContract&PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2010-08-31T11%3A45%3A50.582Z&Version=2010-08-31

3. Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, andSHA256 or SHA1 as the hash algorithm.

4. Convert the resulting value to base64.For example, 5nB7nu7PFbCiDg+vYyWMj1JzEH3S+IzFoVgwHGjG5Ms=

| Amazon Payments Query API | 14

Amazon Payments Query API

Common Query ParametersAll Query operations share a set of common parameters that must be present in each call.

Name Description Required

Action Indicates the action to perform.

Example: CreatePurchaseContract

Yes

Version The API version to use, as specifiedin the WSDL.

Example: 2010-08-31

Yes

AWSAccessKeyId The Access Key ID for the requestsender. You can find your AccessKey ID in Seller Central. Clickthe Integration tab and then clickAccess Key.

Example:AKIADQKE4SARGYLEXAMPLE

Yes

Timestamp The date and time at which therequest is signed, in the formatYYYY-MM-DDThh:mm:ssZ. Formore information, please see ISO8601.

Condition: Either Timestamp orExpires must be present in therequest, but not both.

Example: 2006-07-07T15:04:56Z

Note that the "Z" offset is notrequired.

Conditional

Expires The date and time at which thesignature included in the requestexpires, in the format YYYY-MM-DDThh:mm:ssZ.

Condition: Either Expires orTimestamp must be present in therequest, but not both.

Example: 2006-07-07T15:04:56Z

Note that the "Z" offset is notrequired.

Conditional

Signature The request signature. For moreinformation, please see "Signing

Yes

http://www.w3.org/TR/NOTE-datetime

http://www.w3.org/TR/NOTE-datetime


Name Description RequiredQuery Requests," in the InlineCheckout Implementation Guide.

Example:Qnpl4Qk/7tINHzfXCiT7VbBatDA=

SignatureMethod The hash algorithm you use to createthe request signature. For moreinformation, please see "SigningQuery Requests," in the InlineCheckout Implementation Guide.

Valid values: HmacSHA256 |HmacSHA1.

Example: HmacSHA256

Yes

SignatureVersion The signature version you use tosign the request. Set this value to2. For more information, please see"Signing Query Requests," in theInline Checkout ImplementationGuide.

Example: 2

Yes

Note: Parameter values must be URL-encoded. This is true for any Query parameter passed to the service,and is typically necessary in the Signature parameter. Some clients do this automatically, but this is notalways the case.

List of Query Operations• CreatePurchaseContract• GetPurchaseContract• SetPurchaseItems• SetContractCharges• CompletePurchaseContract

CreatePurchaseContract

Description

CreatePurchaseContract API lets you create a new Purchase Contract ID. Please note that this ID will not beactive unless it is used along with the Inline Checkout Widget and a buyer authorizes the checkout session within thewidget.API lets you create a new Purchase Contract ID.

Note:

Unused Purchase Contract IDs will expire three hours from the creation time.

If you use this API, you must pass the Purchase Contract ID as input to the InlineCheckoutWidget. If noPurchase Contract ID is passed to the InlineCheckoutWidget, the widget will always create and return a newPurchase Contract ID.








For most cases, you don't need to use this API. A Purchase Contract ID will be returned to you from theInlineCheckoutWidget, which you can then use with the other APIs described in this document.

Request Parameters

The following table lists the special request parameters the CreatePurchaseContract action uses in addition to thecommon parameters all actions use.


PurchaseContractMetadata Base64-encoded private data that canbe stored with the purchase contract.You can access this data using theGetPurchaseContract action.

Type: String

Constraints: Maximum 1024 bytes;base64-encoded

Default: None

No

DirectedId The unique identifier for the Amazoncustomer, generated for yourmerchant site by Amazon Identity.

Type: String

Default: None

Yes

AuthorizationToken The token returned by AmazonIdentity, authorizing the buyer toinitiate a purchase on your merchantsite.

Type: String

Default: None

Yes

Note that if both the DirectedId and the AuthorizationToken are provided and valid, the buyer will be consideredsigned-in, and will not be prompted to sign in again once he initiates checkout.

If you provide neither parameter, the buyer will get the traditional checkout experience, with the popup asking him tosign in. This is not recommended, as it will result in a suboptimal user experience.

If only one or the other of the parameters is present, or one or both are invalid (for example, the AuthorizationTokenhas expired), then the result will be a 400 Bad Request error. (See "Application Error Codes and Descriptions"below.)

Response Elements

The following table lists the elements the CreatePurchaseContract response includes in addition to the elementsreturned in all successful responses.

Name Description

PurchaseContractId The unique identifier for the purchase contract created bythe API or widget.

Type: String

Ancestor: CreatePurchaseContractResult


Examples

Sample Request

https://payments.amazon.com/cba/api/purchasecontract/?Action=CreatePurchaseContract&PurchaseContractMetadata=Test%20Data&SignatureMethod=HmacSHA256&AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&SignatureVersion=2&Timestamp=2010-08-16T04%3A45%3A30.692-07%3A00&Signature=BA7CnhukT60ysRrQ8PNwlNw5M3EXAMPLE&Version=2010-08-31

https://payments.amazon.com/cba/api/purchasecontract/?Action=CreatePurchaseContract&PurchaseContractMetadata=Test%20Data&SignatureMethod=HmacSHA256&AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&DirectedId=amzn1.account.CQ62MEXAMPLE5JG8L2EXAMPLE&AuthenticationToken=%7BAcws1%7DEXAMPLE-ItIsAVeryLongTokenMuchLongerThanThis-EXAMPLE&SignatureVersion=2&Timestamp=2010-08-16T04%3A45%3A30.692-07%3A00&Signature=BA7CnhukT60ysRrQ8PNwlNw5M3EXAMPLE&Version=2010-08-31

Sample Response

HTTP Status 200 OK

<CreatePurchaseContractResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <CreatePurchaseContractResult> <PurchaseContractId> amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 </PurchaseContractId> </CreatePurchaseContractResult> <ResponseMetadata> <RequestId> 5cd3ec4f-8047-11df-8d5c-bf56a38ef3b4 </RequestId> </ResponseMetadata></CreatePurchaseContractResponse>

HTTP Status 200 OK<CreatePurchaseContractResponsexmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"><CreatePurchaseContractResult><PurchaseContractId>amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080</PurchaseContractId></CreatePurchaseContractResult><ResponseMetadata><RequestId>5cd3ec4f-8047-11df-8d5c-bf56a38ef3b4</RequestId></ResponseMetadata></CreatePurchaseContractResponse>


GetPurchaseContract

Description

GetPurchaseContract API returns the current state of the Purchase Contract. It returns the Destination informationif the buyer selected an address, and also returns the Purchase Item information if you call the SetPurchaseItems APIprior to calling this API.

Request Parameters

The following table lists the special request parameters the GetPurchaseContract action uses in addition to thecommon parameters all actions use.


PurchaseContractId The unique identifier of the purchasecontract.

Type: String

Constraints: ID returned to accountholder after creating the purchasecontract.

Default: None

Yes

Response Elements

The following table lists the elements the response includes in addition to the elements returned in all successfulresponses.

Name Description

PurchaseContract The XML document that describes the purchase contractcreated by the API or widget.

Type: PurchaseContractType (see schema)

Ancestor: GetPurchaseContractResult

Note: The response will contain a Destination only if the buyer selected an address for this purchaseusing the AddressWidget. The response will contain Purchase Items only if you previously called theSetPurchaseItems API.

Examples

Sample Request

https://payments.amazon.com/cba/api/purchasecontract/?Action=GetPurchaseContract&SignatureMethod=HmacSHA256&PurchaseContractId=amzn1.contract.1.1.2.23bc485cc4c6b0dc63cd7f8c0d3d8900&AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE&SignatureVersion=2&Timestamp=2010-08-16T05%3A20%3A14.780-07%3A00&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE&Version=2010-08-31


Sample Response

HTTP Status 200 OK

<GetPurchaseContractResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <GetPurchaseContractResult> <PurchaseContract> <Id>amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080</Id> <ExpirationTimeStamp>2010-10-01T01:01:01.000Z</ExpirationTimeStamp> <MerchantId>AEIOU1234AEIOU</MerchantId> <MarketplaceId>AZ4B0753LGLX</MarketplaceId> <State>OPEN</State> <Destinations> <Destination> <DestinationName>#default</DestinationName> <DestinationType>PHYSICAL</DestinationType> <PhysicalDestinationAttributes> <ShippingAddress> <City>NY</City> <StateOrProvinceCode>NY</StateOrProvinceCode> <PostalCode>10101-9876</PostalCode> <CountryCode>US</CountryCode> </ShippingAddress> </PhysicalDestinationAttributes> </Destination> </Destinations> </PurchaseContract> </GetPurchaseContractResult> <ResponseMetadata> <RequestId>5f20169b-7ab2-11df-bcef-d35615e2b044</RequestId> </ResponseMetadata></GetPurchaseContractResponse>

SetPurchaseItems

Description

When the buyer confirms the order on your order review page, you must invoke the SetPurchaseItems API followedby CompletePurchaseContract API operation so Checkout by Amazon can authorize the payment of the order.

The SetPurchaseItems API will take the list of order items as input. You can specify the order total (that is, theamount the buyer will be charged for the entire order) broken down to each item as part of this API call.

Note: Subsequent calls of this action replace the entire list of items bound to the purchase contract. If youcall this action multiple times, you must pass the complete list of items and for each item all required andoptional attributes again.

Request Parameters

The following tables list the special request parameters the SetPurchaseItems action uses in addition to the commonparameters all actions use.


PurchaseContractId The unique identifier of the purchasecontract.

Type: String

Yes


Name Description RequiredConstraints: ID returned to accountholder after creating the purchasecontract.

Default: None

Following the PurchaseContractId, you can pass a list of items as request parameters. The maximum number ofdifferent items supported in a purchase contract is 50. Purchase item parameter names must meet the following style:

"PurchaseItems.PurchaseItem" followed by an index value; then followed by item attribute name.

For instance, to pass the title of the second purchase item, the request parameter name will be as follows:

PurchaseItems.PurchaseItem.2.Title

Note: Indexes are integers (sequences of 1 or more digits) with a non-zero first digit. The index of the firstpurchase item is 1.


MerchantItemId The unique identifier of the purchase item.

Type: String

Constraints: Each item within a purchase contractmust have a unique alphanumeric-only ID.

Default: None

Yes

SKU The SKU of the item.

Type: String

Default: None

No

MerchantId The ID of the merchant selling the item.

Type: String

Constraints: You must use the Access Key of thismerchant to make the API calls.

Default: None

Yes

Title The title of the item.

Type: String

Default: None

Yes

Description The description of the item.

Type: String

Default: None

No

UnitPrice.Amount The per-quantity price of the item.

Type: Non-negative Double

Constraints: The amount must be 0 or more.

Default: None

Yes



UnitPrice.CurrencyCode The currency of the item's unit price.

Type: String; 3-letter ISO code for the currency.

Yes

Quantity The quantity of the item.

Type: Positive Integer

Constraints: The quantity must be 1 or more, up toa limit of 999.

Default: 1 (if no Quantity is specified)

No

URL The URL of the product's detail page.

Type: URL

Default: None

No

Category Type: String

Default: None

No

FulfillmentNetwork Type: String

Constraints: The only accepted value isMERCHANT

Default: MERCHANT

No

ItemCustomData Base64-encoded private data that can be storedwith the purchase item. This data is available toyou by means of your order notifications (such asyour IOPN).

Type: String

Constraints: Maximum 1024 bytes; base64-encoded

Default: None

No

ProductType Type: String

Default: PHYSICAL

No

Below are attributes applicable to physical items only. If you pass any of these attributes, you also must make surethat the ProductType is set to "PHYSICAL." Otherwise, the action will return an error.

Note:

Physical item attribute names must be preceded by the PhysicalProductAttributes keyword.

Example:

PurchaseItems.PurchaseItem.2.PhysicalProductAttributes.Condition


Weight.Value Type: Non-negative Double

Constraints: The amount must be 0 ormore.

Conditional


Name Description RequiredConditions: Must be used if weight unitspecified.

Weight.Unit Type: String.

Conditions: Must be used if weight amountis specified.

Conditional

DeliveryMethod.ServiceLevel Predefined shipping speed category.

Type: String

Constraints: The only accepted values areStandard, OneDay, TwoDay, or Expedited

Default: None

Yes

DeliveryMethod.DisplayableShippingLabel Custom name for the shipping method.

Type: String

Default:None.

No

DeliveryMethod.DestinationName The destination this item will be shippedto. The name corresponds to the valueof the destinationName input parameterspecified in the Address Widget.

Type: String

Default: "#default"

No

DeliveryMethod.ShippingCustomData Base64-encoded private data related tothe delivery that can be stored with thepurchase item. This data is available to youthrough order notifications (that is, IOPN).

Type: String

Constraints: Maximum 1024 bytes;base64-encoded

Default: None

No

Below are attributes applicable to charges calculated by you for the given physical item. Each charge below has 2subcomponents (with the exception of PromotionId and Description): Amount and CurrencyCode. If you set one, youalso must set the other. The data types are Non-negative Double and String, respectively. The Amount must be 0 ormore.


Shipping.Amount

Shipping.CurrencyCode

If no Shipping is provided, itis assumed that the item has noShipping charge. CurrencyCode mustuse the 3-letter ISO code.

No

Promotions.Promotion.1.PromotionId The ID of the promotion applied tothis item.

Conditions: If any promotionattribute is specified, the other 3

Conditional


Name Description Requiredpromotion attributes also must bespecified.

Promotions.Promotion.1.Description The description of the promotionapplied to this item.

Conditions: If any promotionattribute is specified, the other 3promotion attributes also must bespecified.

Conditional

Promotions.Promotion.1.Discount.AmountThe promotion amount subtractedfrom the item amount.


Conditional

Promotions.Promotion.1.Discount.CurrencyCodeThe currency of the promotionapplied to this item. It must be a 3-letter ISO code for the currency.


Conditional

Note:

Internationally, various characters are used to represent a decimal separator. For example, in the US, 10.49USD represents 10 dollars and 49 cents. The US uses a period (.) as the default separator. Other locationsmight use a comma (,) instead, and represent the amount as 10,49 USD.

Checkout by Amazon accepts only a period (.) as the decimal separator. If you perform calculations forinternational transactions, you might need to modify your code to convert the decimal separator from thecomma to a period.

The following code represents a method you might use:

parameters["Charges.Shipping.Amount"] = charges.Shipping.Amount.ToString(); to parameters["Charges.Shipping.Amount"] = Replace(charges.Shipping.Amount.ToString(), ",", ".");

The current release of the APIs do not support more than one promotion applied to the same item. You canspecify at most one promotion per item.

Response Elements

There is no additional element in the SetPurchaseItems response in addition to the elements already returned in allsuccessful responses.


Examples

Sample Request

https://payments.amazon.com/cba/api/purchasecontract/ ?PurchaseContractId= amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080&Action=SetPurchaseItems&PurchaseItems.PurchaseItem.1.MerchantItemId=1&PurchaseItems.PurchaseItem.1.SKU=Item1SKU&PurchaseItems.PurchaseItem.1.MerchantId=A32EMVWCF1111H&PurchaseItems.PurchaseItem.1.Title=Item1Title&PurchaseItems.PurchaseItem.1.Description=ItemDescription&PurchaseItems.PurchaseItem.1.UnitPrice.Amount=3.14159&PurchaseItems.PurchaseItem.1.UnitPrice.CurrencyCode=USD&PurchaseItems.PurchaseItem.1.Quantity=1&PurchaseItems.PurchaseItem.1.URL=http%3A%2F%2Fmydomain.com%2Fproduct&PurchaseItems.PurchaseItem.1.Category=books&PurchaseItems.PurchaseItem.1.FulfillmentNetwork=MERCHANT&PurchaseItems.PurchaseItem.1.ItemCustomData=MHhkZWFkYmVlZg%3D%3D&PurchaseItems.PurchaseItem.1.ProductType=PHYSICAL&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Weight.Value=3.25&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Weight.Unit=LB&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Condition=new&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.ServiceLevel=Standard&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.DisplayableShippingLabel= One%20Day%20Super%20Saver%20Shipping&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.DestinationName=Item1Destination&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.ShippingCustomData=MHhkZWFkYmVlZg%3D%3D&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Tax.Amount=3.14&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Tax.CurrencyCode=USD&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes.ItemCharges.Shipping.Amount=3.14&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Shipping.CurrencyCode=USD&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.PromotionId=EXAMPLE&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Description=EXAMPLE&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Discount.Amount=3.14&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Discount.CurrencyCode=USD&SignatureMethod=HmacSHA256&Expires=2010-10-18T12:00:00-07:00&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd61jTUA9Uf6SGtEExwUQEXAMPLE&Version=2010-08-31

Sample Response

HTTP Status 200 OK

<SetPurchaseItemsResponse


xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <ResponseMetadata> <RequestId>f42df4b1-8047-11df-8d5c-bf56a38ef3b4</RequestId> </ResponseMetadata></SetPurchaseItemsResponse>

SetContractCharges

Description

You can use this API to set shipping, tax, or promotion amounts for the entire purchase contract. After calling thisAPI, the GetPurchaseContract API response returns purchase level charges inside the Charges XML element, whichis an immediate child of the PurchaseContract XML element. Please refer to the XSD for the full schema details.

After the purchase contract is completed (that is, the order is placed), the contract charges are distributed to each itemproportional to the item's cost (that is, the item's unit price multiplied by the quantity). However, the sum of chargeamounts distributed to each item will be equal to the contract charge amount you set with this API.

There are certain rules that apply to the charges set by this API, especially when used along with theSetPurchaseItems API.

Charges consolidation behavior

• Subsequent calls of this action replace the entire list of Contract charges bound to the purchase contract. If you callthis action multiple times, you must pass the complete list of Contract charges.

• There can be following valid sets of input charge elements to this API –

• [Shipping + Tax] + Promotion• [Shipping + Tax] + No Promotion• [No Shipping + No Tax] + Promotion

• Shipping and Tax are BOTH picked either from Item level or from Contract level depending upon which of thetwo APIs (SetContractCharges and SetPurchaseItems) was called later.

• If only Shipping and Tax are provided at the Contract level, then Promotions at item level, if present, will beapplicable.

• Similarly, if only Promotions are specified at the Contract level, the Shipping and Tax at item level, if present, willbe applicable.

• If Promotions are specified at both Contract and Item levels then Contract level promotions take precedence,irrespective of the order in which they were specified.

• GetPurchaseContract API returns a final consolidated view of charges specified at the Item and Contract levels, asper the above rules.

• Complete API performs additional check to make sure the total of all item prices isn’t greater than the Promotionamount specified at the contract level, if any.

Request Parameters

The following tables list the special request parameters the SetContractCharges action uses in addition to the commonparameters all actions use.

Note: Please note only one promotion can be applied per order at the cart level.


Tax.Amount

Tax.CurrencyCode

If no Tax is provided, it is assumedthat the item has no Tax charge.CurrencyCode must use the 3-letterISO code.

Conditional


Name Description RequiredConditions: If a tax attribute isspecified, the shipping attribute mustalso be specified, even if it is zero.

Shipping.Amount

Shipping.CurrencyCode

If no Shipping is provided, itis assumed that the item has noShipping charge. CurrencyCode mustuse the 3-letter ISO code.

Conditions: If a shipping attribute isspecified, the tax attribute must alsobe specified, even if it is zero.

Conditional

Promotions.Promotion.1.PromotionId The ID of promotion applied to thiscontract.

Conditions: If any promotionattributed is specified, the other 3attributes must also be specified.

Conditional

Promotions.Promotion.1.Description The description of the promotionapplied to this contract.


Conditional

Promotions.Promotion.1.Discount.AmountThe promotion amount subtractedfrom the contract.


Conditional

Promotions.Promotion.1.Discount.CurrencyCodeThe currency of promotion amountsubtracted from the contract. It mustbe 3-letter ISO code for the currency.


Conditional

PurchaseContractId The unique identifier of this purchasecontract.

Type: String

Conditions: ID returned to accountholder after creating the purchasecontract.

Default: None

Yes

Note:


Internationally, various characters are used to represent a decimal separator. For example, in the US, 10.49USD represents 10 dollars and 49 cents. The US uses a period (.) as the default separator. Other locationsmight use a comma (,) instead, and represent the amount as 10,49 USD.

Checkout by Amazon accepts only a period (.) as the decimal separator. If you perform calculations forinternational transactions, you might need to modify your code to convert the decimal separator from thecomma to a period.

The following code represents a method you might use:

parameters["Charges.Shipping.Amount"] = charges.Shipping.Amount.ToString(); to parameters["Charges.Shipping.Amount"] = Replace(charges.Shipping.Amount.ToString(), ",", ".");

Response Elements

There is no additional element in the SetContractCharges response in addition to the elements already returned in allsuccessful responses.

Examples

Sample Request

https://payments.amazon.com/cba/api/purchasecontract/ ?PurchaseContractId=amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 &Action=SetContractCharges&Charges.Tax.Amount=3&Charges.Tax.CurrencyCode=USD&Charges.Shipping.Amount=3&Charges.Shipping.CurrencyCode=USD&Charges.Promotions.Promotion.1.PromotionId=EXAMPLE&Charges.Promotions.Promotion.1.Description=EXAMPLE&Charges.Promotions.Promotion.1.Discount.Amount=3&Charges.Promotions.Promotion.1.Discount.CurrencyCode=USD&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&SignatureMethod=HmacSHA1&Timestamp=2010-09-10T14%3A47%3A13.000Z&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE

Sample Response

HTTP Status 200 OK

<SetContractChargesResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <ResponseMetadata> <RequestId>f42df4b1-8047-11df-8d5c-bf56a38ef3b4</RequestId> </ResponseMetadata> </SetContractChargesResponse>

CompletePurchaseContract

Description

Once you set the items to the purchase contract, you should call the CompletePurchaseContract API which accepts thepurchase contract ID as input. This API transforms the purchase contract into Checkout by Amazon orders and returnsyou a list of Checkout by Amazon Order IDs. You then use these Order IDs to manage the orders.


Request Parameters

The following table lists the special request parameters the CompletePurchaseContract action uses in addition to thecommon parameters all actions use.


PurchaseContractId The unique identifier of thepurchase contract.

Type: String

Constraints: ID returnedto the account holder aftercreating the purchasecontract.

Default: None

Yes

IntegratorId Conditions: Must be used ifintegrator name is specified.

Conditional

IntegratorName Conditions: Must be used ifintegrator ID is specified.

Conditional

InstantOrderProcessingNotificationURLs.MerchantURL Type: URL

Default: None

Note: If the MerchantURLis not specified in the APIthe values specified in SellerCentral (Settings > CheckoutPipeline Settings > InstantOrder Processing NotificationSettings > Merchant URL)will be used.

Yes

InstantOrderProcessingNotificationURLs.IntegratorURL Type: URL

Default: None

Note: If the IntegratorURLis not specified in the APIthe values specified in SellerCentral (Settings > CheckoutPipeline Settings > InstantOrder Processing NotificationSettings > Integrator URL)will be used.

Yes

Note: For InstantOrderProcessingNotificationURL requirements, please see the Instant Order ProcessingNotification Guide.

Response Elements

The following table lists the elements the CompletePurchaseContract response includes in addition to the elementsreturned in all successful responses.

https://amazonpayments.s3.amazonaws.com/documents/Instant_Order_Processing_Notification_API_Guide.pdf

https://amazonpayments.s3.amazonaws.com/documents/Instant_Order_Processing_Notification_API_Guide.pdf


Name Description

OrderIds The XML document that describes the order IDcollection which identifies the orders created when thepurchase contract is completed.

Type: OrderIdListType (see schema)

Ancestor: CompletePurchaseContractResult

Examples

Sample Request

https://payments.amazon.com/cba/api/purchasecontract/&Action=CompletePurchaseContract?PurchaseContractId= amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080&IntegratorId=MNOPQ1234MNOPQ&IntegratorName=Integrator%20Inc&InstantOrderProcessingNotificationURLs. IntegratorURL=http%3A%2F%2Fintegrator.com%2Fiopn&InstantOrderProcessingNotificationURLs. MerchantURL=http%3A%2F%2Fmydomain.com%2Fiopn &SignatureMethod=HmacSHA256&Expires=2010-10-18T12:00:00-07:00&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&SignatureVersion=2&Signature=Dqlp3Sd61jTUA9Uf6SGtEExwUQEXAMPLE&Version=2010-08-31

Sample Response

HTTP Status 200 OK

<CompletePurchaseContractResponse xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/"> <CompletePurchaseContractResult> <OrderIds> <OrderId>102-2432725-669014</OrderId> <OrderId>101-7821075-313967</OrderId> </OrderIds> </CompletePurchaseContractResult> <ResponseMetadata> <RequestId>02055a12-8048-11df-8d5c-bf56a38ef3b4</RequestId> </ResponseMetadata></CompletePurchaseContractResponse>

| Error Codes and Descriptions | 30

Error Codes and Descriptions

HTML Error Codes and Descriptions

Table 1: HTML Error Codes and Descriptions

HTTP Code HTTP Status Description

200 OK The request succeeded.

400 Bad Request The request sent by client is malformed or violates constraints/business rules followed by the service. The client should not retrywithout modifying the request. Most of the errors will not occurif the client integration is proper. For remaining errors, clients canappropriately design their checkout workflow and overcome them.Please see Application Error Codes and Descriptions on page30Error Codes and Descriptions for details on application errorcodes.

403 Forbidden The request requires authentication and the client did not provideauthentication or the provided signature was not valid. Please seeApplication Error Codes and Descriptions on page 30ErrorCodes and Descriptions for details on application error codes.

500 Internal Server Error There was an unexpected problem on server side and retrying fromclient would not be helpful. If this error occurs, the merchant shouldcontact the Checkout by Amazon team.

502 Bad Gateway There was an unexpected problem on server side. The client shouldretry the request.

503 Service Unavailable There was an unexpected problem on server side. The client shouldretry the request.

Application Error Codes and Descriptions

Table 2: HTML Error Codes and Descriptions

API Name HTTPError Code

Application Error Code Description

CreatePurchaseContract

400 InvalidParameterValue This error can be generated by several conditions:

PurchaseContractMetadata is missing, is providedin an invalid format, or exceeds the maximumsize allowed by server.

The DirectedId is improperly formatted.

The AuthorizationToken is improperly formattedor has expired.




403 MissingAuthenticationToken The request sent to the server does not haveAWSAccessKeyId or Signature.

403 InvalidClientTokenId The request sent to the server does not have avalid AWSAccessKeyId for verification or theAWSAccessKeyId is missing.

403 SignatureDoesNotMatch The request was signed using an invalid signaturemethod or the computed signature is invalid

403 InvalidMerchant The merchant has not yet completed registrationwith Checkout by Amazon.

SetPurchaseItems

400 ValidationError The request does not follow the constraintsspecified in the WSDL. The error message willindicate the invalid parameter(s) and the issuewith the parameter(s). The request can be re-sent only after correcting the problem. For moredetails, the client should consult the WSDL.

400 InvalidParameterValue ServerSide validation of request failed. The errormessage will indicate the invalid parameter andthe problem with the parameter in a descriptiveformat. The request can be re-sent only aftercorrecting the problem.

Some of the additional rules that clients shouldadhere to are listed below. For more details pleaserefer the appropriate section of ImplementationGuide.

• The contractId is invalid or the contract is notActive (other possible states are Expired orCompleted)

• The MerchantId provided at an item leveldoes not match with MerchantId derived fromthe AWSAccessKeyId sent with request

• Number of items sent in the request exceededthe maximum allowed limit of 40

• Each item does not have a unique Item ID• Weight Value specified is invalid or is not

supported in the marketplace• The amounts specified for UnitPrice or

ItemCharges is invalid• The currency code for the amounts is invalid

or is not supported in the marketplace• Either shipping or tax is provided at item level

but not both• Promotion discounts exceed the subtotal

amounts• Length of a parameter exceeded the maximum

allowed limit




• An unsupported feature is used (please see theImplementation Guide for more details)





SetContractCharges



The reason may be as listed below:


• Only Shipping or Tax was provided, whenthey must always be present together.

• The currency code specified for any ofthe Charge components (Shipping/Tax/Promotions) is unsupported.

• More than one Promotion is provided in thePromotions list.





GetPurchaseContract







• Length of a parameter exceeded the maximumallowed limit

• URLs provided are formatted incorrectly





CompletePurchaseContract


400 InvalidParameterValue ServerSide validation of request failed. Therequest can be re-sent only after correcting theproblem.



• The MerchantId provided at an item leveldoes not match with MerchantId derived fromthe AWSAccessKeyId sent with request

• Number of items sent in the request exceededthe maximum allowed limit of 40




• Each item does not have a unique Item ID• Weight Value specified is invalid or is not

supported in the marketplace• The amounts specified for UnitPrice or

ItemCharges is invalid• The currency code for the amounts is invalid

or is not supported in the marketplace• Either shipping or tax is provided at item level

but not both• Promotion discounts exceed the subtotal

amounts• Length of a parameter exceeded the maximum

allowed limit• An unsupported feature is used (please see the

Implementation Guide for more details)

400 BuyerNotRecognized There are no buyer details for the contract, mostlikely because the buyer has not signed in andselected the destination and payment detailsClients can redirect to a page where the buyercan sign in and provide destination and paymentdetails.

400 InvalidDestination One of the destinations selected for the itemsis invalid. The issue might be that a wrongdestination name was provided or the destinationis invalid or expired. Clients can choose toredirect to a page where the buyer can re-select anew destination.

400 InvalidPaymentDetails The payment details presented were invalidor expired. Clients can choose to redirect to apage where the buyer can re-select the paymentinstruments.

400 NoItemsInContract There are no items present in the purchasecontract. Client needs to call SetPurchaseItemsfirst before calling Complete.





Amazon Payments API Reference Guide - Amazon Web...

Documents

Transcript of Amazon Payments API Reference Guide - Amazon Web...