ASP Advanced Users Guide...Amazon Simple Pay Getting Started Guide details the processes and procedures involved to make use of Amazon Simple Pay's standard features without needing

Amazon Simple Pay Advanced Users Guide API Version 2010-08-28

Amazon Simple Pay Advanced Users Guide

i

Amazon Web Services

Copyright © 2012 - 2013 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, Cloudfront, Amazon DevPay, DynamoDB, Elasticache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon.

All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.


ii

Table of Contents

Welcome .................................................................................................................................... 1

How Do I...?............................................................................................................................ 1

Introduction to Amazon Simple Pay ........................................................................................... 3

Overview of Amazon Simple Pay ............................................................................................ 3

Amazon Simple Pay Concepts ............................................................................................... 3

Simplified Button Creation and Customization .................................................................... 3

Amazon Simple Pay Implementation Process ................................................................. 3

Five Commonly Used Buttons ............................................................................................. 4

Co-Branding with Amazon Simple Pay ................................................................................ 5

Settling Later Versus Paying Now ....................................................................................... 5

Amazon Flexible Payments Service Actions ....................................................................... 5

Amazon Payments Developer Account ............................................................................... 6

Developer Sandbox ............................................................................................................ 6

Keeping Payments Secure .................................................................................................. 7

About Signature Version 2 ............................................................................................... 7

Using Access Identifiers ...................................................................................................... 8

To view your Access Key ID and Secret Access Key: ...................................................... 8

Access Key Rotation ........................................................................................................... 8

Working with Amazon Simple Pay Buttons ................................................................................10

Common Amazon Simple Pay Tasks.....................................................................................10

Creating Button Forms Dynamically ......................................................................................11

Creating a Single Button Dynamically ................................................................................11

Creating a Single Button Form Dynamically ...................................................................11

Creating Multiple Buttons Dynamically ...............................................................................12

Preload your button html in your product database .........................................................12

Collect runtime input .......................................................................................................13

Complete the transaction using your script .....................................................................13

How to Add Your AWS Access Key to the Form ................................................................13

To Add Your Access Key ID to the Form ........................................................................13

How to Generate a Signature .............................................................................................14


iii

How to Sign your Button Form Correctly ............................................................................16

To add your signature to the form ...................................................................................16

Amazon Simple Pay Button Input Reference .........................................................................16

Standard Button Input Reference .......................................................................................17

Standard Button Well-formed HTML ...............................................................................18

Donation Button Input Reference .......................................................................................19

Donation Button Well-Formed HTML ..............................................................................20

Accept Marketplace Fee Button Input Reference ...............................................................21

Accept Marketplace Fee Button Well-Formed HTML ......................................................22

Marketplace Payment Button Input Reference ...................................................................23

Marketplace Payment Button Well-Formed HTML ..........................................................24

Donation Button with Marketplace Fee Input Reference .....................................................26

Donation Button with Marketplace Fee Well-Formed HTML ...........................................27

Subscription Button Input Reference ..................................................................................28

Subscription Button Well-Formed HTML .........................................................................30

Handling Return Content .......................................................................................................32

Handling Button Response Data ........................................................................................32

Handling Instant Payment Notification Responses .............................................................32

Handling Flexible Payments Service Responses ...............................................................32

Verifying the ReturnURL and IPN Notifications. .....................................................................33

Including Amazon Simple Pay as an Additional Payment Method .........................................34

Accepting Payments from Mobile Devices .............................................................................34

Working with Subscription Button Advanced Features ...........................................................35

Getting Subscription Information ........................................................................................35

Getting Subscription Transaction Information .....................................................................35

Canceling Subscriptions .....................................................................................................35

Canceling a subscription on your own web page ............................................................36

How to Limit Subscription Cancellation to Your Website ....................................................36

Modifying Subscriptions .....................................................................................................37

Modifying a Subscription using CancelSubscriptionAndRefund ......................................37

What Happens When Subscription Payments Fail .............................................................37

Subscription Payment Error Process ..............................................................................37

Payment Failure Notifications .........................................................................................38


iv

Settling and Refunding Transactions Programmatically .........................................................38

How to Settle Transactions Programmatically ....................................................................39

To settle a transaction ....................................................................................................39

How to Refund Transactions Programmatically ..................................................................39

To refund a transaction ...................................................................................................40

Using Instant Payment Notification ........................................................................................40

Enabling Instant Payment Notification ................................................................................41

Using Instant Payment Notification Data ............................................................................41

How To Verify the IPN Signature ....................................................................................41

Testing Your Applications in the Amazon Payments Sandbox ...............................................42

Amazon Payments Sandbox ..............................................................................................42

Simulating a Mobile Client ..................................................................................................42

Testing Button Signatures ..................................................................................................43

Creating a Test Account Balance .......................................................................................43

To create a test account balance ....................................................................................43

Forcing Error Conditions ....................................................................................................44

Configuring Default Button Values .........................................................................................44

Email Notification Templates .................................................................................................46

Amazon Simple Pay WSDL and Schema ..............................................................................48

Simple Pay FPS Actions API Reference ...................................................................................50

Flexible Payments Service Actions Available with Amazon Simple Pay .................................50

Cancel ...............................................................................................................................51

Description .....................................................................................................................51

Request Parameters.......................................................................................................51

Response Elements .......................................................................................................51

Errors .............................................................................................................................52

Examples .......................................................................................................................52

Sample REST Request ..................................................................................................52

Sample Response to REST Request ..............................................................................52

Sample IPN Success Notification to Rest Request .........................................................53

CancelSubscriptionAndRefund ..........................................................................................54

Description .....................................................................................................................54



v


Errors .............................................................................................................................55

Examples .......................................................................................................................55




GetSubscriptionDetails .......................................................................................................57

Description .....................................................................................................................57



Errors .............................................................................................................................57

Examples .......................................................................................................................57



GetTransactionsForSubscription ........................................................................................59

Description .....................................................................................................................59



Errors .............................................................................................................................59

Examples .......................................................................................................................59



GetTransactionStatus ........................................................................................................61

Description .....................................................................................................................61



Status Codes ..................................................................................................................62

Errors .............................................................................................................................62

Examples .......................................................................................................................63



Refund ...............................................................................................................................64

Description .....................................................................................................................64


vi



Errors .............................................................................................................................65

Examples .......................................................................................................................65




Settle .................................................................................................................................67

Description .....................................................................................................................67



Errors .............................................................................................................................68

Examples .......................................................................................................................68




VerifySignature ..................................................................................................................70

Description .....................................................................................................................70



Errors .............................................................................................................................71

Examples .......................................................................................................................71



Common Request Parameters ..............................................................................................73

Common Response Elements ...............................................................................................75

Common Errors .....................................................................................................................75

Error Response Elements ..............................................................................................75

Errors .............................................................................................................................76

Data Types ............................................................................................................................80

Amount Data Types ...........................................................................................................80

SubscriptionDetails Type ...................................................................................................80

SubscriptionStatus Type ....................................................................................................81


vii

SubscriptionTransaction Type ............................................................................................81

MarketplaceRefundPolicy Data Types ...............................................................................81

API TransactionStatus Data Types ....................................................................................82

Appendix: Sample Code ...........................................................................................................83

Understanding the Amazon Simple Pay Button Samples ......................................................83

Understanding the IPNAndReturnURLValidation Sample ......................................................85

Understanding the VerifySignature Sample ...........................................................................87

Using the VerifySignature Action Sample ...........................................................................87

Adding Amazon as an Additional Payment Option .................................................................90

Getting the Samples ..............................................................................................................91

Appendix: Return Values ..........................................................................................................92

API Return Values .................................................................................................................92

Additional Return Values for Marketplace Fee Requests .......................................................94

Additional Return Values for Subscription Requests ..............................................................95

Return URL Status Codes .....................................................................................................95

Appendix: IPN Response Elements for Transactions ................................................................97

Common IPN Response Elements ........................................................................................97

IPN Response Elements for Subscriptions .......................................................................... 100

IPN Responses for Marketplace Transactions ..................................................................... 102

IPN Status Codes ................................................................................................................ 103

Amazon Simple Pay Related Resources ................................................................................. 105

Glossary.................................................................................................................................. 106

Document History ................................................................................................................... 108

Welcome

1

Welcome

The Amazon Simple Pay Advanced User Guide shows you how to add fully featured payment processing to your applications by providing an in-depth guide on how to use all the Amazon Simple Pay buttons.

Amazon Simple Pay is an Amazon Payments service that enables you to quickly add payment features to your website. Your customers can make one-time payments, subscriptions, marketplace payments or a combination of these using the payment information stored in their Amazon.com accounts. To implement Amazon Simple Pay, you simply copy and paste a small amount of HTML code to the web pages where you want the buttons to appear.

Note

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

How Do I...? How do I? See These Sections Decide whether Amazon FPS is right for my needs

Amazon Simple Pay detail page.

Get started with Amazon FPS quickly Amazon Simple Pay Getting Started Guide Learn about the advanced Amazon Simple Pay features

Overview of Amazon Simple Pay Amazon Simple Pay Concepts

Modify the sample code to create a specific button

Creating Button Forms Dynamically

Learn about the HTML components of a well-formed Amazon Simple Pay buttons

Amazon Simple Pay Button Input Reference

Make use of the response and transaction content returned by your buttons and by Amazon Payments

Handling Return Content

Cancel and modify subscriptions Working with Subscription Buttons Validate responses Using Instant Payment Notification

How to Verify the IPN Signature Refund or settle a payment Settling and Refunding Transactions

Programmatically Use the Flexible Payments Service actions available with Amazon Simple

Simple Pay FPS Actions API Reference

https://payments.amazon.com/sdui/sdui/business?sn=paynow/o

https://amazonpayments.s3.amazonaws.com/FPS_ASP_Guides/ASP_Getting_Started_Guide.pdf

Welcome

2

How do I? See These Sections Pay Work with Instant Payment Notification Using Instant Payment Notification Use the sandbox for testing and error simulation

Testing your Applications in the Amazon Payments Sandbox

Set defaults for a cancel subscription URL, an IPN URL, and the signing of buttons created using Amazon Payments online forms

Configuring Default Button Values

Learn about Amazon Simple Pay WSDL and Schema

Amazon Simple Pay WSDL and Schema

Find sample Code for signing buttons, verifying return data, or generating a button request

Appendix: Sample Code

Introduction to Amazon Simple Pay

3


This section introduces Amazon Simple Pay and gives an overview of how the system operates.

Overview of Amazon Simple Pay Amazon Simple Pay is a set of basic payment-only products. Using online Amazon Simple Pay forms you can create fully-functional payment buttons, which you then add to your web page. These buttons allow your customers to use their Amazon.com accounts as a payment method for purchasing products and services from you. When customers click one of your Amazon Simple Pay buttons, they begin making a secure payment.

The Amazon Simple Pay Getting Started Guide details the processes and procedures involved to make use of Amazon Simple Pay's standard features without needing to write any code. In contrast, the Amazon Simple Pay Advanced User Guide concentrates on the advanced features available to you when you decide that your application calls for custom code. If you don't need to write code, but do want to make use of the basic features of Amazon Simple Pay, you should refer to the Amazon Simple Pay Getting Started Guide.

Amazon Simple Pay Concepts In order to understand Amazon Simple Pay and to use it most easily, you should be familiar with the terminology and concepts found in this section.

Simplified Button Creation and Customization Implementing the advanced features of Amazon Simple Pay does not require a high level of programming expertise. Developers create the HTML for one or many buttons dynamically, making small per-product adjustment as needed.

Amazon Simple Pay Implementation Process 1. You need an Amazon Payments business account to use the most basic Amazon

Simple Pay features. You use a business sandbox account to test the buttons you create. How to get both accounts is described in “Before you Begin" in the Amazon Simple Pay Getting Started Guide. To work with the Amazon Flexible Payments Service APIs detailed in this guide you need an Amazon Web Services developer account. For more information on getting a






4

developer account, see the “Amazon Payments Developer Account” section of this guide.

2. Create an HTML button form dynamically or use the Amazon Simple Pay user interface. As a developer you have flexibility to adjust the button functionality, its content, and whether to sign it for security. If you do choose to sign the button, you also can set the signature strength to either SHA256 or SHA1.

3. The button form provides the exact functionality and features required by your chosen button. Insert the HTML form element into your web page, again either manually or dynamically, to make it available to users.

4. Submit the form on the user's behalf if you need to control the flow between your website and Amazon Payments.

5. Add the code to your website to handle form responses when someone clicks the Amazon Simple Pay button. You can capture button responses, Instant Payment Notification (IPN) responses, and certain Amazon Flexible Payments Service action returns. You can also ensure that the responses returned to your application have originated with Amazon by programmatically validating the signature using the VerifySignature action.

6. Test the button. With a developer account, you can simulate error conditions such as denied payments.

Five Commonly Used Buttons Amazon Simple Pay enables you to create five different payment buttons that online shoppers can use to purchase items. Each button performs a different task:

Standard—You use standard buttons to offer Amazon Simple Pay as a standalone payment method for one-time purchases.

Marketplace—The marketplace button lets you display and sell the goods of other sellers, optionally charging them a fee for the service.

The marketplace button is similar to the standard button in appearance. However, it is functionally different, because it involves three parties instead of only two.

Donation—Donation buttons are an easy-to-use and secure way for US-based, IRS-certified 501(c)3 non-profit organizations to solicit donations.

Marketplace-Enabled Donation Button—A special donation button which enables third parties to collect donation funds on behalf of a 501(c)3 non-profit organization.

Subscription—Subscription buttons enable an easy way to charge your customers a recurring fee.


5

Co-Branding with Amazon Simple Pay Co-branding is simply adding your merchant logo to each of the payment authorization web pages.

When your buyers click one of your Amazon Simple Pay buttons, the browser navigates to the Amazon Simple Pay payment authorization web pages (hosted by Amazon). These web pages require the buyer to sign in, specify a payment method such as a credit card, and authorize the payment. If you have ever purchased something on Amazon.com, you're familiar with the checkout process.

Clicking an Amazon Simple Pay button directs buyers away from the merchant's website. However, by including your merchant branding on the payment authorization web pages, buyers don't feel as if they've completely left your website to pay. Jumping from your website to Amazon's without co-branding could confuse buyers. Co-branding provides continuity between the shopping and purchasing experience.

For more information about setting up co-branding, see “Configuring Default Button Values.”

Settling Later Versus Paying Now A buyer's payment instrument is not necessarily charged immediately for a product when he or she clicks an Amazon Simple Pay button. Amazon Simple Pay standard, marketplace, and donation buttons give the developer the option of either charging the buyer immediately or settling later. If you choose to settle later, Amazon Payments reserves the purchase price against the buyer's payment instrument.

When you create a standard, marketplace, on donation button and you decide to settle later, use the Amazon Flexible Payments Service Settle action to implement the settle functionality. For more information on using the Amazon Flexible Payments Service API to settle a transaction see “Settling and Refunding Transactions Programmatically.”

Amazon Flexible Payments Service Actions Amazon Simple Pay handles many tasks for you so that you do not need to write code for your web page. However, there are some tasks that Amazon Simple Pay does not handle. Sometimes, you can use Amazon Flexible Payments Service (Amazon FPS) actions to add some functionality to Amazon Simple Pay, and some of those actions are described in this guide.

The actions that are described in this guide are:

• Cancel • CancelSubscriptionAndRefund • Refund

• GetTransactionStatus • Refund • Settle


6

• GetSubscriptionDetails • GetTransactionsForSubscription

• VerifySignature

Note In order to execute FPS actions, you must have an AWS developer account as described below.

Amazon Payments Developer Account If you plan to work with Amazon Flexible Payments Service actions such as CancelSubscriptionandRefund, Refund, or Settle, you must upgrade your Amazon Payments business account to an Amazon Payments developer account. In addition, because the developer account is separate from the business account, you must get a developer sandbox account to test your FPS actions.

To upgrade to an Amazon Payments developer account and get a developer sandbox account:

1. Go to http://payments.amazon.com. Click the Developer tab. 2. On the Developers tab, click Sign up for Amazon FPS. The What You Need to Sign

up for Amazon Flexible Payments Service displays. 3. Click Sign Up and follow the instructions on the web pages.

We recommend that before you put your solution into production, you test it in the sandbox. The developer sandbox is not the same as the business sandbox, so you must get an account in the developer sandbox to test the Cancel, Refund, or Settle actions. This allows you to test your actions without real money exchange.

4. Go to https://payments-sandbox.amazon.com/sdui/sdui/index.htm. 5. Click Create Account or Sign In and follow the instructions on the subsequent pages.

Developer Sandbox We recommend that you test all of the buttons you create before putting them on your website. The Amazon Simple Pay Getting Started Guide, has instructions on setting up an Amazon Payment business account and an Amazon Payments business sandbox account. However, in order to execute Amazon Flexible Payments Service (Amazon FPS) actions, you must also have an AWS developer account and its corresponding developer sandbox account. You cannot test Amazon FPS actions using your business account sandbox. To get your Amazon Payments developer account, see “Amazon Payments Developer Account.”

In the developer sandbox you can operate the advanced features of Amazon Simple Pay buttons without incurring charges or making purchases. For more information about using the developer sandbox, see “Testing Your Applications in the Amazon Payments Sandbox.”

http://payments.amazon.com/

https://payments-sandbox.amazon.com/sdui/sdui/index.htm



7

Keeping Payments Secure Payments between buyers and merchants using Amazon Simple Pay are handled through web service requests. To make these requests more secure, Amazon Simple Pay uses the following means of securing requests:

SSL —All requests communicate over Secure Sockets Layer using HTTPS

Signed Buttons —If you choose, you can opt to sign your buttons with a signature based on the button parameters and your AWS access identifiers, which provides a way for Amazon to verify that a button action originated from your application. The method of signing is based on signature version 2, which supports the SHA1 and SHA256 encryption algorithms. For more information on signature version 2, see “About Signature Version 2.”

The instructions in this guide have you create signed buttons. For complete information on creating a signed button, see “Creating Button Forms Dynamically.” Amazon Payments uses the signature to validate the requests it receives. A signed button's signature is based on the parameter values contained in the form.

Signed and Verifiable Responses —Both the Return URL and IPN responses are also signed, using the signature version 2 method. The FPS Action “VerifySignature” enables you to easily check that the content in the response has not been modified after sending.

About Signature Version 2 For inbound requests, signature version 2 signing uses the entire HTML button form as the basis for the signature, and encryption is based on the unique security credentials for your account.

For outbound notifications, signature version 2 provides the Amazon FPS action, VerifySignature, which enables you to securely check a response using a server-side call.

Important The original implementation of signature version 2 supported client-side signature validation using PKI. Client-side signature validation was deprecated on November 3rd, 2009, and as of 10 February, 2011 it is no longer supported. If you have been using client-side signature validation, you must switch to server-side validation using the FPS action VerifySignature.

Signature version 2 supports AWS access key rotation, further enhancing the security of your button content. For more information, see “Access Key Rotation.”

Important The previous method for signing (signature version 1) was deprecated on November 3rd, 2009, and as of 10 February, 2011 it is no longer supported. Whenever you sign a request with your access keys, you must now use signature version 2.


8

Using Access Identifiers When you have your AWS developer account, download your access identifiers. You will need them for sending REST requests and for signing buttons.

AWS Access Key ID --You use this to identify yourself when you send requests to the co-branded service or when you send REST requests to Amazon FPS.

AWS Secret Access Key - Each Access Key ID has a Secret Access Key associated with it. This key is just a long string of characters (and not a file) that you use to calculate the digital signature that you include in the request. Your Secret Access Key is a secret, and only you and AWS should have it. Don't e-mail it to anyone, include it any AWS requests, or post it on the AWS Discussion Forums. No authorized person from AWS will ever ask for your Secret Access Key.

When you create a request, you create a digital signature with your secret key and include it in the request along with your Access Key ID. When we get the request, we use your Access Key ID to look up the corresponding Secret Access Key. We use the key to validate the signature and confirm that you're the request sender.

Important You can use these access identifiers in both the sandbox and the production environment.

Your Access Key ID and Secret Access Key display when you create your AWS account. They are not emailed to you. If you need to see them again, you can view them at any time from your AWS account.

To view your Access Key ID and Secret Access Key: 1. Go to the Amazon Security Credentials page at http://aws.amazon.com/security-

credentials. If you are not logged in, you will be prompted for your user name and password.

2. Your Access Key ID is displayed on the resulting Security Credentials page in the Access Credentials area. Your Secret Access Key remains hidden as a further precaution.

3. To display your Secret Access Key, on the Access Keys tab, under Secret Access Key, click Show.

Access Key Rotation If you decide that it is necessary to change your access keys, the security credentials page (available from your account page at the Amazon Web Services website at

http://aws.amazon.com/security-credentials

http://aws.amazon.com/security-credentials


9

http://aws.amazon.com) enables you to create a second set, and allows you to activate and deactivate the sets independently.

With both sets active, you can propagate the new set to your applications over time, maintaining the high security that signing provides. Since both sets are valid, you don't have to take your entire application down to incorporate the new keys. When the distribution is complete you can deactivate the old set.

Note You can have two sets of keys only. Both, one, or neither of them can be active.

http://aws.amazon.com/

Working with Amazon Simple Pay Buttons

10


This section provides task-oriented descriptions of how to create Amazon Simple Pay buttons, and how to use and implement Amazon Flexible Payments Service (FPS) actions. For a description of Amazon FPS actions that are appropriate to use with Amazon Simple Pay, see the API Reference.

Common Amazon Simple Pay Tasks The following table explains how you can find the information you need in this guide.

If you want to … Relevant sections Learn the basics of Amazon Simple Pay

Overview Key concepts Amazon Simple Pay Getting Started Guide

Learn how to create a signed button of any type

Creating Button Forms Dynamically

Modify the sample code to create a standard, donation, marketplace, or subscription button

Understanding the Amazon Simple Pay Button Samples

Use the response and transaction content returned by your buttons and by Amazon Payments

Handling Return Content

Validate responses for the Return URL and Instant Payment Notification

Verifying the ReturnURL and IPN Notifications

Understand subscription button particulars

Working with Subscription Buttons

Use Amazon Flexible Payments Service actions available with Amazon Simple Pay

API Reference

Use Instant Payment Notification (IPN)

Using Instant Payment Notification, How to Verify the IPN Signature and Verifying the IPN

Settle or refund money How to Settle and Refund Transactions Programmatically

Work with signatures Creating Button Forms Dynamically, How to Generate a Signature, and About Signature Version 2.

Get sample code for signing buttons, verifying return data, and generating a button request




11

Creating Button Forms Dynamically The Amazon Simple Pay Getting Started Guide describes how to create Amazon Simple Pay buttons using the online forms Amazon has prepared for you. This works well when you only have a few buttons to create. If you have many buttons, you can create them programmatically.

Creating a Single Button Dynamically The following process outlines creating a single button dynamically.

Creating a Single Button Form Dynamically 1. Create the HTML for type of button you want to build. An example structure of each

button is available in the “Amazon Simple Pay Button Input Reference” section. 2. Set the product-specific parameters required by the HTML form. A button-specific

parameter reference is also available in “Amazon Simple Pay Button Input Reference.” 3. Set the values of the accessKey and secretKey parameters with your security

credentials. For more information, see “Using Access Identifiers” and “How to Add Your AWS Access Key to the Form.”

4. Create a string to sign using the form parameters. The parameters and values must be arranged in particular order. See “How to Generate a Signature” for the proper way to form the URL string.

5. Calculate the signature and set it as the value for the signature parameter. For more information on generating a signature, see “How to Generate a Signature.”

6. Generate the final button HTML, and add it to your web page. 7. Repeat steps 1-6 for each button you plan to use.

Important The preceding process includes steps 4-6 for signing the button because button parameters are sent in clear text and subject to tampering. You are not required to sign your button, but when you do, you are protecting the integrity of the data.

If you choose to not sign your parameters, you should verify the accuracy of the parameters manually in the Amazon Payments website or the Instant Payment Notification data.

Amazon has published a set of samples in C#, Java, Perl and PHP that demonstrates how to do this in detail for each button type. For information on downloading the code, see the Amazon Flexible Payments Service Getting Started Guide.


https://amazonpayments.s3.amazonaws.com/FPS_ASP_Guides/FPS_Getting_Started_Guide.pdf

https://amazonpayments.s3.amazonaws.com/FPS_ASP_Guides/FPS_Getting_Started_Guide.pdf


12

Creating Multiple Buttons Dynamically If you have a larger product line, you application probably makes use of a dynamic catalog with a backend database for product information and transaction records. If so, you will want to use the referenceId parameter as a key to the transaction. This changes the process you use to support a large number of items.

While you can prepopulate button forms with many of the parameter values, some of them may only be determined at runtime. This is true not only of referenceId, but amount, subscriptionPeriod, and others which are set by the customer. Because you cannot calculate the signature until all the parameter values are known, for large applications the signature parameter must be done at runtime as well. Additionally, to create the most secure button, we strongly recommend that you use server-side code to calculate the signature.

The following three-part process outlines one way to create multiple button forms dynamically.

First, build as much of the button as you can:

Preload your button html in your product database 1. Create the HTML for each button instance you want. An example structure of each

button is available in “Amazon Simple Pay Button Input Reference.” Instead of the payments.amazon.com (or payments-sandbox.amazon.com) endpoint, specify your own client-side page or asynchronous script. This script's role is described below.

2. Set the known product-specific parameters required by each HTML form. A button-specific parameter reference is also available in “Amazon Simple Pay Button Input Reference.”

3. Set the values of the accessKey and secretKey parameters using your security credentials. Also, set the signatureMethod and signatureVersion parameters with the values which represent your signing algorithm.

Important Do not expose your AWS Secret Key to the client-side of your application. Calculate your signature on the server-side.

4. Store each button html in a database field, and key it to the product it is configured to sell.

5. Using the HTML created in step 4, create a string to sign using the form parameters. The parameters and values must be arranged in particular order. Include all parameters, even those for which you don't have values yet. See “How to Generate a Signature” for the proper way to form the URL string.

6. Store the string to sign you created in step 5 in a database field, and key it to the product it is configured to sell.


13

Then, at runtime, you display the products to the user and collect any runtime input:

Collect runtime input 1. Populate your catalog page with your incomplete buttons. 2. Collect any information required from the user, setting appropriate button parameters. 3. When the user submits the form, generate the unique value for the referenceId. 4. The script you specified as the form action does the rest.

Finally, your custom client-side page or asynchronous script finishes the button and submits it:

Complete the transaction using your script 1. Retrieve the string to sign for the product purchased from the database, and insert the

runtime values, including the referenceId. Now you are ready to sign it. 2. Calculate the signature and set it as the value for the signature parameter. For more

information on generating a signature, see “How to Generate a Signature.” 3. Retrieve the HTML for the product purchased, and insert the runtime values, including

the referenceId. Also insert the signature, and set the payments.amazon.com (or payments-sandbox.amazon.com) endpoint as the form action.

4. Store the HTML in your database, and key it to the referenceId. 5. Without displaying it again, submit the button. The user begins the Amazon payments

pipeline.

How to Add Your AWS Access Key to the Form The buttons you create using the form generator at http://payments.amazon.com do not have your Access Key ID as the value for the accessKey parameter. If you decide to sign your buttons yourself, you must set this value in the form before you create the button signature.

To Add Your Access Key ID to the Form 1. Retrieve your AWS Access Key Id as detailed in “Using Access Identifiers.”

Important Your access key is the only credential you add to your HTML button form. Though you need your secret key to create the signature, it is never part of the form.

2. Paste your access key in the value attribute that corresponds to the accessKey. It should be similar to the following:

<input type="hidden" name="accessKey" value="AKIAIOSFODNN7EXAMPLE" >

For information on the high-level process for creating a button, see “Creating Button Forms Dynamically.”



14

How to Generate a Signature To create the signature

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 is application/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 characters are 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).

Note Currently all AWS service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use.

c. Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), 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, the query 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, and SHA256 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.

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


15

Important The final signature you send in the request must be URL encoded as specified in RFC 3986 (for more 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 final request, 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 during signature formation, and then again when the toolkit URL encodes the entire request.


In the following examples, new lines have been inserted to make the examples easier to read. Explicit '\n' is used wherever new line is required.

The following is an example Amazon Simple Pay request using POST.

<form action="https://authorize.payments- sandbox.amazon.com/pba/paypipeline" method="POST"> <input type="image" src="https://authorize.payments- sandbox.amazon.com/pba/im ages/payNowButton.png" border="0"> <input type="hidden" name="SignatureVersion" value="2" > <input type="hidden" name="immediateReturn" value="0" > <input type="hidden" name="Signature" value="Base64Encode(HmacSHA256(String ToSign))" > <input type="hidden" name="amount" value="USD 1.1" > <input type="hidden" name="SignatureMethod" value="HmacSHA256" > <input type="hidden" name="description" value="Test Widget" > <input type="hidden" name="ipnUrl" value="http://yourwebsite.com/ipn" > <input type="hidden" name="accessKey" value="YourCallerKey" > <input type="hidden" name="cobrandingStyle" value="logo" > <input type="hidden" name="processImmediate" value="1" > <input type="hidden" name="returnUrl" value="http://yourwebsite.com/return.html" > <input type="hidden" name="referenceId" value="YourReferenceId" > </form>

The following is an example of a string to use for StringToSign in the preceding example.

POST\n authorize.payments-sandbox.amazon.com\n /pba/paypipeline\n SignatureMethod=HmacSHA256 &SignatureVersion=2 &accessKey=YourCallerKey &amount=USD%201.1 &cobrandingStyle=logo &description=Test%20Widget

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


16

&immediateReturn=0 &ipnUrl=http%3A%2F%2Fyourwebsite.com%2Fipn &processImmediate=1 &referenceId=YourReferenceId &returnUrl=http%3A%2F%2Fyourwebsite.com%2Freturn.html

For more examples of generating a signature, see “Appendix: Sample Code.”

For information on signing your button form correctly, see “How to Sign your Button Form Correctly.”

How to Sign your Button Form Correctly The signature parameter contains the calculated signature. The SignatureVersion and SignatureMethod parameters describe the characteristics of the signature you plan to provide. All three parameters must be present in your button form for it to be correctly signed.

To add your signature to the form 1. Paste your calculated signature into the value attribute that corresponds to the signature.

To create a signature, see “How to Generate a Signature.” 2. Paste the name of your signing algorithm in the value attribute that corresponds to the

signatureMethod, either HmacSHA256 or HmacSHA1. 3. Paste your signing version number into the value attribute that corresponds to the

signatureVersion field. This value must be 2.

The signature portion of the button should be similar to the following:

<input type="hidden" name="signature" value="rtnUZPP50DxgzmYOcUaFBvbhLqY=" > <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" >


Amazon Simple Pay Button Input Reference Each Amazon Simple Pay button is comprised of a mix of required and optional parameters. This section lists and describes the parameters available for each button, and notes whether the parameter is required.

When you generate your Amazon Simple Pay buttons, they must be valid HTML. This section also provides well-formed examples of all the Amazon Simple Pay buttons, including the marketplace fee button.


17

Note The values for the signature parameter in all of the following examples assume YourAccessKeyId as the value for accessKey, and YourSecretKeyId as the value for the secret key.

Standard Button Input Reference The input parameters for the standard button are a mix of required parameters, as listed in the following table.

Parameter Description Required abandonUrl Optionally enter the URL where

senders should be redirected if they cancel their transaction

No

accessKey Your AWS Access Key Yes amazonPaymentsAccountId Your Amazon Payments account

ID. This parameter is not used and should not be present if you sign the button using your secret key. For more information, see “Using Access Identifiers.”

Yes

amount Enter the amount you want to collect for the item

Yes

cobrandingStyle Optionally, set to a cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred)

No

collectShippingAddress Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information

No

description Enter a description of the item Yes immediateReturn Optionally set to 1 to skip the final

status page in Amazon Payments. Default is 0.

No

ipnUrl Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction information

No

processImmediate Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0. Default value is 1

No

referenceId Optionally provide a unique identifies of this transaction for your records

No

returnUrl Optionally enter the URL where No


18

Parameter Description Required buyers should be redirected after they complete the transaction

signature A value calculated using the form parameters.

Yes

signatureMethod The signing algorithm, either HmacSHA1 or HmacSHA256.

Yes

signatureVersion A value that specifies the signature format. Currently, the only valid value is 2.

Yes

For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Samples.”

Standard Button Well-formed HTML Example HTML for a standard Pay Now button, signed using the signature version 2 method.

<form action ="https://authorize.payments.amazon.com/pba/paypipeline" method ="POST"> <input type ="hidden" name ="immediateReturn" value ="1"> <input type ="hidden" name ="collectShippingAddress" value ="0"> <input type ="hidden" name ="accessKey" value ="YourAccessKeyId"> <input type ="hidden" name ="referenceId" value ="MyTransaction-001"> <input type ="hidden" name ="amount" value ="USD 10"> <input type ="hidden" name ="signature" value ="K2ryWe7s/0AHI0/PbuAveuUPksTefhmNCzDTold2VYA="> <input type ="hidden" name ="description" value ="pay for dinner"> <input type ="hidden" name ="ipnUrl" value ="http://yourwebsite.com/instantpaymentnotification"> <input type ="hidden" name ="returnUrl" value ="http://yourwebsite.com/success"> <input type ="hidden" name ="processImmediate" value ="1"> <input type ="hidden" name ="cobrandingStyle" value ="logo"> <input type ="hidden" name ="abandonUrl" value ="http://yourwebsite.com/abandon"> <input type ="image" src ="https://authorize.payments.amazon.com/pba/images/SLPayNowWithLogo.png" border ="0"> <input type ="hidden" name ="signatureVersion"


19

value ="2"> <input type ="hidden" name ="signatureMethod" value ="HmacSHA256"> </form>

Donation Button Input Reference The input parameters are a mix of required parameters, as listed in the following table.

Parameter Description Required abandonUrl Optionally enter the URL

where senders should be redirected if they cancel their transaction

No

accessKey Your AWS Access Key Yes amazonPaymentsAccountId Your Amazon Payments

account ID. This parameter is not used and should not be present if you sign the button using your secret key. For more information, see “Using Access Identifiers.”

Yes


Yes


No


No

description Enter a description of the item Yes donationType Optionally set to the type of

donation. Valid values are fixedAmount, minimumAmount and anyAmount. Default value is anyAmount.

No

immediateReturn Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0.

No

ipnUrl Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction

No


20

Parameter Description Required information

isDonationWidget Always 1 for a donation button.

Yes

minimumDonationAmount The minimal payment allowed or the donation.

Yes, if the value for donationType is minimumAmount


No

referenceId Optionally provide a unique identifies of this transaction for your records.

No

returnUrl Optionally enter the URL where buyers should be redirected after they complete the transaction

No


Yes


Yes


Yes


Donation Button Well-Formed HTML Example HTML for a basic donation button with no added fee, signed using the signature version 2 method.

<form action="https://authorize.payments.amazon.com/pba/paypipeline" method="POST"> <input type="image" src= "https://authorize.payments.amazon.com/pba/images/GSDonationWithLogo.png" border="0"> <input type="hidden" name="immediateReturn" value="1" > <input type="hidden" name="collectShippingAddress" value="1" > <input type="hidden" name="accessKey" value="YourAccessKeyId" >


21

<input type="hidden" name="minimumDonationAmount" value="USD 50" > <input type="hidden" name="referenceId" value="MyTransaction-001" > <input type="text" name="amount" size="8" value="50" > <input type="hidden" name="isDonationWidget" value="1" > <input type="hidden" name="fixedMarketplaceFee" value="" > <input type="hidden" name="description" value="City Mission" > <input type="hidden" name="ipnUrl" value="http://yourwebsite.com/instantpaymentnotification" > <input type="hidden" name="returnUrl" value="http://yourwebsite.com/success" > <input type="hidden" name="processImmediate" value="1" > <input type="hidden" name="cobrandingStyle" value="logo" > <input type="hidden" name="abandonUrl" value="http://yourwebsite.com/abandon"> <input type="hidden" name="signature" value="JL9k2iY4H2IQ0A+2zvFi31zLnPmOFEfMwzpLYG0Rao8=" > <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" > </form>

Accept Marketplace Fee Button Input Reference This button may be use to set terms for either the Marketplace button or the Marketplace-enabled donation button. The input parameters are a mix of required parameters, as listed in the following table.

Parameter Description Required accessKey Your access key from your account security

credentials Yes

callerReference Optionally, a value to uniquely identifies this transaction

No

collectEmailAddress Set to 1 if you want Amazon Payments to return the buyer's email address as part of the transaction information

No


22

Parameter Description Required maxFixedFee If you assess a fixed charge per transaction, set

maxFixedFee to that value. You may have a value in both this parameter and maxVariableFee, and you must have a value for at least one of them.

No

maxVariableFee If you assess a percentage charge per transaction, set maxVariableFee to that value.You may have a value in both this parameter and maxFixedFee, and you must have a value for at least one of them.

No

pipelineName The kind of token you are creating. For Amazon Simple Pay, this value is always Recipient.

Yes

recipientPaysFee Set this value to True if the recipient agrees to pay the fees, otherwise set this value to False.

Yes

returnURL Optionally enter the URL where buyers should be redirected after they complete the transaction

No

signature A value calculated using the form parameters. Yes signatureMethod The signing algorithm, either HmacSHA1 or

HmacSHA256 Yes


Yes

For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Sample.”

Accept Marketplace Fee Button Well-Formed HTML Example HTML for a marketplace fee button, signed using the signature version 2 method.

<form =https://authorize.payments.amazon.com/cobranded- ui/actions/start method="get"> <input type="hidden" name="signature" value="8UVrm+bK/O8I92e6RKlWKg76els=" > <input type="hidden" name="accessKey" value="AKIAIOSFODNN7EXAMPLE" > <input type="hidden" name="callerReference" value="983fab72-6695-4b53-a69f-5bf5fb47c25e" > <input type="hidden" name="collectEmailAddress" value="true" > <input type="hidden" name="maxFixedFee" value="0.2" > <input type="hidden" name="maxVariableFee" value="4.00" > <input type="hidden" name="pipelineName" value="Recipient" > <input type="hidden" name="recipientPaysFee" value="true" > <input type="hidden" name="returnURL"

https://authorize.payments.amazon.com/cobranded-%20%20%20%20%20%20%20ui/actions/start

https://authorize.payments.amazon.com/cobranded-%20%20%20%20%20%20%20ui/actions/start


23

value="http://yourwebsite.com/returnurl" > <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" > <input type="image" src= "http://g-ecx.images- amazon.com/images/G/01/asp/MarketPlaceFeeWithLogo.gif" border="0"> </form>

Marketplace Payment Button Input Reference The input parameters are a mix of required parameters, as listed in the following table.



No

accessKey Your AWS Access Key Yes amount Enter the amount you want to

collect for the item Yes

cobrandingStyle Optionally, set to a cobranding style.Valid values are "logo" or banner.” ("logo" is preferred)

No


No

description Enter a description of the item Yes fixedMarketplaceFee If you assess a fixed charge

per transaction, set fixedMarketplaceFee to that value. You may have a value in both this parameter and variableMarketplaceFee, and you must have a value for at least one of them.

No


No

ipnUrl Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction

No


24

Parameter Description Required information


No

recipientEmail The email address of the seller

Yes


No


No

secretKey Your AWS secret key Yes signature A value calculated using the

form parameters Yes


Yes


Yes

variableMarketplaceFee If you assess a percentage charge per transaction, set variableMarketplaceFee to that value.You may have a value in both this parameter and fixedMarketplaceFee, and you must have a value for at least one of them.

No


Marketplace Payment Button Well-Formed HTML Example HTML for a marketplace button, signed using the signature version 2 method.

<form action="https://authorize.payments.amazon.com/pba/paypipeline" method="POST"> <input type="hidden" name="immediateReturn" value="1" > <input type="hidden" name="collectShippingAddress" value="1" > <input type="hidden" name="accessKey" value="YourAccessKeyId" > <input type="hidden" name="referenceId"


25

value="MyTransaction-001" > <input type="hidden" name="recipientEmail" value="email domain.com" > <input type="hidden" name="amount" value="USD 10" > <input type="hidden" name="variableMarketplaceFee" value="4" > <input type="hidden" name="signature" value="dXZgCQ8fLsPjNkbHswghORXd34tTVZWEjyetpzYG1ok=" > <input type="hidden" name="fixedMarketplaceFee" value="USD 0.20" > <input type="hidden" name="description" value="Pay for Purple Vase (Walter store)" > <input type="hidden" name="ipnUrl" value="http://yourwebsite.com/instantpaymentnotification" > <input type="hidden" name="returnUrl" value="http://yourwebsite.com/success" > <input type="hidden" name="processImmediate" value="1" > <input type="hidden" name="cobrandingStyle" value="logo" > <input type="hidden" name="abandonUrl" value="http://yourwebsite.com/cancel" > <input type="image" src= "https://authorize.payments.amazon.com/pba/images/SMPayNowWithAmazon.png" border="0"> <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" > </form>


26

Donation Button with Marketplace Fee Input Reference The input parameters are a mix of required parameters, as listed in the following table.

Parameter Description Required abandonUrl Optionally enter the URL where senders

should be redirected if they cancel their transaction

No

accessKey Your AWS Access Key Yes amazonPaymentsAccountId Your Amazon Payments account ID. This

parameter is not used and should not be present if you sign the button using your secret key. For more information, see “Using Access Identifiers.”

Yes


Yes


No


No

description Enter a description of the item Yes donationType Optionally set to the type of donation.

Valid values are fixedAmount, minimumAmount and anyAmount. Default value is anyAmount.

No

fixedMarketPlaceFee If you want to assess a fixed charge per transaction, set fixedMarketplaceFee to that value.You may have a value in both this parameter and variableMarketplaceFee.

No


No


No

isDonationWidget Always 1 for a donation button. Yes minimumDonationAmount The minimal payment allowed or the

donation. Yes, if the value for donationType is minimumAmount

processImmediate Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0.

No


27

Parameter Description Required Default value is 1


No

recipientEmail E-mail address of the merchant who will receive the payment.

Yes


No

variableMarketplaceFee If you plan to assess a percentage charge per transaction, set variableMarketplaceFee to that value.You may have a value in both this parameter and fixedMarketplaceFee.

No


Yes


Yes


Yes


Donation Button with Marketplace Fee Well-Formed HTML Example HTML for a basic donation button with an added fee, signed using the signature version 2 method.

<form action="https://authorize.payments.amazon.com/pba/paypipeline" method="post"> <input type="hidden" name="immediateReturn" value="1" > <input type="hidden" name="collectShippingAddress" value="1" > <input type="hidden" name="accessKey" value="AKIAIOSFODNN7EXAMPLE" > <input type="hidden" name="minimumDonationAmount" value="USD 50" > <input type="hidden" name="referenceId" value="MyTransaction-001" > <input type="hidden" name="recipientEmail" value="email domain.com" > <input type="hidden" name="variableMarketplaceFee" value="3" > <input type="hidden" name="signature" value="nVPwhhP9VqTJGUEilNlBcGVVTOs=" > <input type="hidden" name="fixedMarketplaceFee"


28

value="USD 0.20" > <input type="hidden" name="isDonationWidget" value="1" > <input type="hidden" name="description" value="City Mission" > <input type="hidden" name="amazonPaymentsAccountId" value="WFQISAVAYLSB2VZ1LVCDJ2KLJ8H1BVUEXAMPLE" > <input type="hidden" name="ipnUrl" value="http://yourwebsite.com/instantpaymentnotification" > <input type="hidden" name="returnUrl" value="http://yourwebsite.com/success" > <input type="hidden" name="processImmediate" value="1" > <input type="hidden" name="cobrandingStyle" value="logo" > <input type="hidden" name="abandonUrl" value="http://yourwebsite.com/abandon" > <input type="image" src= "https://authorize.payments.amazon.com/pba/images/GSDonationWithLogo.png" border="0"> <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" > </form>

Subscription Button Input Reference The input parameters are a mix of required parameters, as listed in the following table.



No

accessKey Your AWS Access Key Yes amount Enter the amount you want to

collect for the item Yes

amazonPaymentsAccountId Your Amazon Payments account ID. This parameter is not used and should not be present if you sign the button using your secret key. For more information, see “Using Access Identifiers.”

Yes

cobrandingStyle Optionally, set to a No


29

Parameter Description Required cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred)


No

description Enter a description of the item Yes immediateReturn Optionally set to 1 to skip the

final status page in Amazon Payments. Default is 0.

No


No

noOfPromotion Transactions

Optionally set to the number of transactions in the promotion period.

Yes, if promotionAmount is not null or zero.


No

promotionAmount The optional amount you are providing for a promotional price.

No

recurringFrequency The billing period (how often Amazon bills the subscriber) The format is x tag, where tag is either day, week, month, and year, and x is a number that makes sense for tag. For example, 1 month is valid, but 31 month is not.

Yes

recurringStartDate Optionally enter the start date for the subscription. By default, the subscription will be processed as soon as subscription is created

No


No


No


30

Parameter Description Required signature A value calculated using the

form parameters. Yes


Yes


Yes

subscriptionPeriod Optionally enter the subscription duration. The format is x tag, where tag is either day, week, month, and year, and x is a number that makes sense for tag. For example, 1 month is valid, but 31 month is not. Note If this parameter is not provided, or the value is forever, the subscription will be for an unlimited period.

No

Subscription buttons have special features to consider. See “Working with Subscription Button Advanced Features.”


Subscription Button Well-Formed HTML Example HTML for a subscription button, signed using the signature version 2 method.

<form action="https://authorize.payments.amazon.com/pba/paypipeline" method="POST"> <input type="hidden" name="immediateReturn" value="1" > <input type="hidden" name="noOfPromotionTransactions" value="2" > <input type="hidden" name="recurringStartDate" value="1250161950" > <input type="hidden" name="collectShippingAddress" value="1" > <input type="hidden" name="promotionAmount" value="USD 1" > <input type="hidden" name="accessKey" value="YourAccessKeyId" > <input type="hidden" name="referenceId" value="MyTransaction-001" >


31

<input type="hidden" name="recurringFrequency" value="1 month" > <input type="hidden" name="amount" value="USD 10.05" > <input type="hidden" name="signature" value="L8I/R5inJ3RtGIz/uYvyYlIu1ibDcSlaSn3/IwK6ciA=" > <input type="hidden" name="isAutoRenewal" value="0" > <input type="hidden" name="description" value="Daily NYT Delivery" > <input type="hidden" name="ipnUrl" value="http://yourwebsite.com/instantpaymentnotification" > <input type="hidden" name="returnUrl" value="http://yourwebsite.com/success" > <input type="hidden" name="processImmediate" value="0" > <input type="hidden" name="cobrandingStyle" value="logo" > <input type="hidden" name="abandonUrl" value="http://yourwebsite.com/cancel" > <input type="image" src="https://authorize.payments-sandbox.amazon.com/pba/images/GMSubscribeWithLogo.png" border="0"> <input type="hidden" name="signatureVersion" value="2" > <input type="hidden" name="signatureMethod" value="HmacSHA256" > </form>


32

Handling Return Content Amazon Simple Pay sends transaction information to your Return URL, your IPN URL, and Amazon Flexible Payments Service API calls. If you application demands it, you can capture the transaction data in the pages you specify when you create the button form.

Handling Button Response Data Amazon Payments sends transaction data to the URL you specify as your Return URL as HTTP GET data. You simply capture the response elements as you would with any other form post.

All the common response parameters are listed in API Return Values.

Important You should validate Amazon's signature in the button response. For more information, see “Verifying the ReturnURL and IPN Notifications.”

Handling Instant Payment Notification Responses Amazon Payments sends transaction data to the URL you specify as your IPN URL as HTTP POST data. You simply capture the response elements as you would with any other form post.

All the IPN response parameters are listed in “Appendix: IPN Response Elements for Transactions.”

Important You should validate Amazon's signature of each IPN post. For more information, see “Verifying the ReturnURL and IPN Notifications.”

Handling Flexible Payments Service Responses In response to an FPS action request the Amazon FPS returns an XML document fragment that contains the results of the request in an XML data structure. Use your preferred method for parsing an XML document fragment to manipulate the FPS transaction data elements.


33

As an example, the following XML fragment shows a simplified response to a REST request for a Settle action.

<SettleResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <SettleResult> <TransactionId> 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22 </TransactionId> <TransactionStatus>Pending</TransactionStatus> </SettleResult> <ResponseMetadata> <RequestId>9ed2008b-b230-4ed0-9210-095f77fc2359:0</RequestId> </ResponseMetadata> </SettleResponse>

The response contains all the data you need to validate and process the transaction.

For a complete listing of the values returned for all FPS actions, see “Simple Pay FPS Actions API Reference.”

Verifying the ReturnURL and IPN Notifications. Amazon Simple Pay sends you outbound notifications for both the ReturnURL and IPN notification. For the ReturnURL, it is in the form of GET data, and for IPN notification, it is POST data. When you handle these notifications, we recommend you validate the signature to ensure the notification originated from Amazon Payments.

Signature version 2 security enables you to verify the signature of the response using a server-side call to the VerifySignature FPS Action. To use it, modify your returnUrl and ipnUrlpages to parse the notification. From those components, you assemble the relevant parameters for VerifySignature and sign it like any other request. The result of the call is either Success, meaning the response is valid, or Failure, indicating the response is suspect.

For more information on VerifySignature, see “VerifySignature.” In addition, you can use the validation samples to assist creating your own validation pages. For more information, see “Understanding the IPNAndReturnURLValidation Sample.”

Important The original implementation of signature version 2 supported client-side signature validation using PKI. Client-side signature validation was deprecated on November 3rd, 2009, and as of 10 February, 2011 it is no longer supported. If you have been using client-side signature validation, you must switch to server-side validation using the FPS action VerifySignature.


34

Including Amazon Simple Pay as an Additional Payment Method Along with creating the HTML for Amazon Simple Pay buttons manually, you can build the HTML form request dynamically using code. This enables you to set the amount to charge the customer dynamically as well, and generate the button request for the user.

This technique enables you to manipulate the transaction between the time the user clicks your button and when the Amazon Payments portion of the transaction begins.

Generating a Button Request For the User

1. Add an option to your web page, such as a radio button, that enables a buyer to select Amazon Payments as a payment instrument. Use one of the logos from our logo guidelines document to implement the radio button.

2. Use the procedure presented in previous sections to generate the complete HTML form

for the button (including product parameters and signing information). For more information, see “Creating Button Forms Dynamically.” Do not render this HTML until the user clicks the button you created in step 1.

3. When the buyer selects Amazon Payments as a payment instrument, render the form and submit it immediately. There are a variety of ways to do this. For example, you could submit the form in the body.onload event:

<body onload="document.getElementByName('TheForm').submit()">

Since the form's ACTION attribute is to Amazon Payments, the buyer completes the purchase as with an Amazon Simple Pay static button.

For a complete example, see “Adding Amazon as an Additional Payment Option.”

Accepting Payments from Mobile Devices Amazon FPS provides a seamless integration with web sites optimized for mobile devices. No special Amazon FPS coding is required. The software detects the client browser HTTP_USER_AGENT and routes the request along the appropriate CBUI pipeline. A separate pipeline is optimized for the mobile device experience.

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

https://payments.amazon.com/sdui/sdui/business?sn=cba/usage


35

Note For optimal security, your mobile application should make use of a full browser instance (not a browser embedded within an application). It should display the browser address bar to enable customers to confirm the URL.

The user CBUI experience is managed for you. You handle all Amazon FPS requests, return URLs, and IPN notifications regardless of which client browser the customer is using.

Amazon Simple Pay makes it easy to test your mobile client experience. For more information, see “Simulating a Mobile Client.”

Working with Subscription Button Advanced Features Amazon Simple Pay enables you to get the details of a subscription, and retrieve the transaction that have occurred against it. In addition, you can cancel and modify subscription payments.

Getting Subscription Information You can use the GetSubscriptionDetails action to retrieve the details about a subscription. You simply pass in the SubscriptionId of interest. Amazon Simple Pay returns a SubscriptionDetails Type object with the details of the subscription.

Getting Subscription Transaction Information You can use the GetTransactionsForSubscription action to retrieve the details for all transactions about a subscription. You pass in the SubscriptionId of interest, and Amazon Simple Pay returns a SubscriptionTransaction Type object with the details of all known transactions for the subscription.

You can also use Instant Payment Notification (IPN) to retrieve information on subscriptions. For more information, see “Using Instant Payment Notification Data.”

Canceling Subscriptions A subscriber may want to cancel a subscription. Subscribers can cancel an active subscription either by using their account on Amazon Payments or by using a user interface that you create on your website.

https://payments.amazon.com/


36

Note A subscription can be canceled by Amazon as well. For more information, see “What Happens When Subscription Payments Fail.”

When a subscriber uses Amazon Payments to cancel a subscription, Amazon sends the subscriber and seller notice of the cancellation. If the cancellation happens only on your website, you need to implement the subscription cancellation programmatically.

If you decide to provide a user interface on your own website for canceling subscriptions, be aware that Amazon Simple Pay does not provide a cancel subscription button among its generated buttons. But you can use the Amazon Flexible Payments Service CancelSubscriptionAndRefund API to cancel subscriptions.

Canceling a subscription on your own web page 1. Create a graphical user interface button that sends a CancelSubscriptionAndRefund

request when it is clicked. The refundAmount parameter of the CancelSubscriptionAndRefund action specifies the exact amount of the refund returned to your customer. This amount can be zero. For more information, see “CancelSubscriptionAndRefund.”

2. Send a cancellation notification email to the subscriber.

How to Limit Subscription Cancellation to Your Website If you plan to allow subscription cancellation only on your own website, you need to prevent subscription cancellation on the Amazon Payments website. When you first create the subscription button, you can set this up.

To prevent cancellations through the Amazon Payments website

1. Go to http://payments.amazon.com. and sign in to your account. 2. Go to the Developer and Seller Preferences page at

https://payments.amazon.com/sdui/sdui/managecobranding.

Note To set your Developer and Seller Preferences in the Amazon FPS Sandbox, go to https://payments-sandbox.amazon.com/sdui/sdui/managecobranding instead. The settings for the sandbox and production environments are separate.

3. In the Cancel Subscription URL field, enter the URL on your website where subscribers should be redirected when they try to cancel their subscriptions. The user will be redirected to your URL rather than to Amazon Payments.

https://payments.amazon.com/


https://payments.amazon.com/sdui/sdui/managecobranding

https://payments-sandbox.amazon.com/sdui/sdui/managecobranding


37

Modifying Subscriptions If you offer a variety of subscriptions, subscribers might want to upgrade or downgrade them. For example, if your service offers stock market reports, a subscriber might like to upgrade to a subscription that offers more reports.

The Amazon Simple Pay system does not directly support the modification of an active subscription, but there is a way to offer this functionality. You can create a new subscription using Amazon Simple Pay and then use the Amazon Flexible Payments Service CancelSubscriptionAndRefund API to cancel the current subscription.

Modifying a Subscription using CancelSubscriptionAndRefund 1. Create a modify subscription button that sends the same request that the subscription

button sends. All your buttons should have a unique value for the referenceID parameter. The response to your subscription request contains this value. Pairing the value for referenceID with the ID of the subscriber enables you to detect a subscription modification.

2. Parse the subscription modification response. If Amazon Payments returns success, and if it represented a modification, send a CancelsubscriptionandRefund request to cancel the old subscription. In the CancelsubscriptionandRefund request, you also have the option of including a refund using the refundAmount parameter.This parameter can equal zero, and in the case of a modification, it likely will. For more information, see “CancelSubscriptionAndRefund.”

3. Amazon Payments sends email messages for the creation of the new subscription as well as the cancellation of the older subscription to both the subscriber and seller.

What Happens When Subscription Payments Fail Amazon processes each subscription payment according to the subscription interval and billing period set when the subscription is created. Within a subscription, each payment is assigned its own payment serial number which distinguishes it from all other payments. Amazon uses the payment serial number any time that payment is attempted.

When Amazon attempts a subscription payment, the attempt either succeeds or fails. If it fails, it may be due to a payment method failure or from some other error. What happens afterwords depends on how many times we have attempted the payment, and whether a payment method error is involved.

Amazon uses the following rules when processing payment errors.

Subscription Payment Error Process 1. When payment attempts fail, Amazon waits 6 days before trying again. 2. Amazon makes at most 3 attempts to collect a subscription payment.


38

3. If a payment method error happens twice in a row, regardless of subscriber action, the subscription is canceled. Amazon stops trying to collect payments against the subscription.

4. If a payment fails twice for reasons other than a payment method failure, Amazon stops trying to collect that payment. The rest of the payments are attempted on schedule.

5. If a payment fails first for some other reason, and then for two payment method errors, the subscription is canceled. Amazon stops trying to collect payments against the subscription.

6. Finally, if a payment fails first for some other reason, then for a payment method error, and finally for some other reason, Amazon stops trying to collect that payment. The rest of the payments are attempted on schedule.

There are two special cases of involving subscription cancellation.

• For a payment method failure, Amazon sends an email to the subscriber requesting a payment method update. If the subscriber makes no updates to the payment method before the next retry (6 days later), Amazon cancels the subscription.

• If a payment method error happens for a subscription that has a billing period of 15 days or less, Amazon cancels the subscription immediately (even if the failure was on the first attempt). Amazon stops trying to collect payments against the subscription.

Payment Failure Notifications Whenever Amazon fails to collect a payment, we notify both the merchant and the subscriber of the problem.

• For payment method failures, Amazon sends an email message to the subscriber advising them to update the payment method. The merchant is sent an IPN response of PendingSubscriberAction.

• For failures due to other reasons, Amazon sends an email message to the subscriber about the irregularity. If Amazon plans to retry the collection, the merchant is sent a PaymentRescheduledcode in the IPN response.

• If Amazon decides to stop trying to collect the payment, but is not canceling the subscription, Amazon sends an email message to the subscriber about the irregularity. The merchant is sent a PaymentCancelled code in the IPN response.

• If for any reason Amazon has decided to cancel the subscription, Amazon sends an email message to both the subscriber and the merchant about the cancellation. The merchant is sent a SubscriptionCancelled code in the IPN response.

Settling and Refunding Transactions Programmatically When you do not select the Do you want to settle immediately? check box in the co-branded user interface (see “Configuring Default Button Values”), the buyer is not charged for the


39

purchase. Instead, the purchase price is reserved against the chosen payment instrument. To charge the buyer for the purchase, you must settle the charge. A reserve authorization is valid only for seven days. After that, Amazon Simple Pay automatically cancels the transaction and notifies both you and the buyer.

You can settle the charge using the user interface on http://payments.amazon.com or you can send a Settle request to Amazon Flexible Payments Service. The one you choose typically depends upon the number of refunds or settlements you need to do and how automated you want to make your system. The greater the number of refunds or settlements, the more likely you are to complete these tasks programmatically. Settling and refunding using the online forms is described in the Amazon Simple Pay Getting Started Guide.

How to Settle Transactions Programmatically This section describes how to send a Settle request to the Amazon Flexible Payments Service. For more information about settling charges using the Amazon Payments user interface, see the Amazon Simple Pay Getting Started Guide.

To settle a transaction Send a request to the Amazon Flexible Payment service similar to the following.

https://fps.amazonaws.com/? Action=Settle &AWSAccessKeyId=[Your access key Id] &TransactionId=208sg0849sfwers082 &Timestamp=2007-05-10T05%3A11%3A41Z &Version=[WSDL version in the YYYY-MM-DD format] &Signature=[calculated signature] &SignatureVersion=2 &SignatureMethod=HmacSHA256

The request includes the TransactionId, which identifies the transaction to be settled. If a value for the optional parameter, SettleAmount is not included, the entire purchase price is settled.

Among other values, Amazon Flexible Payments Service returns TransactionStatus, which specifies whether the request completed successfully or not.

For more information about the action, its parameters, and return values, see “Settle.”

How to Refund Transactions Programmatically Amazon Simple Pay enables you to refund money using the Amazon Payments user interface (see the Amazon Simple Pay Getting Started Guide), or you can send a Refund request to Amazon Flexible Payments Service. The one you choose typically depends upon the number of refunds you need to do. The more refunds you need to make, the more likely you'll prefer to do so programmatically.






40

This section describes how to send a Refund request to Amazon Flexible Payments Service. For more information about settling charges using the Amazon Payments user interface, see Amazon Simple Pay Getting Started Guide.

Use the following procedure to refund charges programmatically.

To refund a transaction 1. If the transaction was reserved, settle it now (see “How to Settle Transactions

Programmatically.” For more information, see “Settle.” 2. Send a Refund request similar to the following.

https://fps.amazonaws.com/? &Action=Refund &AWSAccessKeyId=[Your access key Id] &TransactionId=208sg0849sfwers082 &RefundTransactionReference=w908dnwf092987 &Timestamp=2007-05-10T05%3A11%3A41Z &Version=[WSDL version in the YYYY-MM-DD format] &Signature=[calculated signature] &SignatureVersion=2 &SignatureMethod=HmacSHA256

The Refund request includes the TransactionId, which identifies the transaction to be refunded. The request also includes a value you create for RefundTransactionReference, which must be a unique value in your namespace.

Within the return, Amazon Flexible Payments Service returns TransactionStatus, which specifies whether the request completed successfully or not. The parameter, RefundTransactionReference, is also returned so that you can associate the information on your end with the refund status Amazon Payments returns. For more information about the Refund action, its parameters, and return values, see “Refund.”

Using Instant Payment Notification Instant Payment Notification (IPN) is an HTTP POST notification that Amazon sends whenever a transaction is completed successfully or a transaction fails. You must host a script to handle the IPN notifications. You can specify the default URL for IPN in your Amazon Payments account settings as described in Enabling Instant Payment Notification. You can override the default value for Instant Payment Notification URL by passing your URL value in as an input parameter.



41

Enabling Instant Payment Notification You can set a default URL for Instant Payment Notification in your Amazon Payments Business account. Or, you can set this value in the user interface when you create an Amazon Simple Pay button. You can accomplish the same thing by setting the ipnurl parameter in the Amazon Simple Pay button form.

Tip You should periodically test your URL for Instant Payment Notification. Check that the processing script is running on the server and that you can reach the server from the Internet using the fully-qualified domain name in the URL. If you do not receive notifications from IPN, contact Amazon Payments for assistance.

For information on the Amazon Payments business account, see the Amazon Simple Pay Getting Started Guide. For information on creating buttons, see “Creating Button Forms Dynamically.”

Using Instant Payment Notification Data Amazon Simple Pay returns IPN transaction information as an HTTP post. For more information, see “Handling Instant Payment Notification Responses.” You are notified of the following:

• a payment succeeds or fails • a refund succeeds or fails • a reserved payment succeeds or fails to settle • a subscription request succeeds • a subscription cancels successfully • a subscription completes (runs to term)

See “Appendix: IPN Response Elements for Transactions for the HTTP” post parameters which can be included in an IPN post.

How To Verify the IPN Signature The Amazon Simple Pay Getting Started Guide describes accessing the Amazon Payments business account sandbox and provides an overview of its features. For more information about the sandbox, go to https://payments-sandbox.amazon.com.




https://payments-sandbox.amazon.com/


42

Testing Your Applications in the Amazon Payments Sandbox The Amazon Simple Pay Getting Started Guide describes accessing the Amazon Payments business account sandbox and provides an overview of its features. For more information about the sandbox, go to https://payments-sandbox.amazon.com.

Amazon Payments Sandbox With the Amazon Payments developer sandbox you can test the more advanced features of your button applications.

Note You cannot port the code for the buttons you create in the sandbox to the production environment. When you are satisfied that your button works correctly in the sandbox, make careful notes and recreate it in the production environment. For best results, test the button again in the production environment.

The Amazon Payments developer sandbox enables you to try the following:

• Use credit cards and bank accounts in your test transactions without any prior verification and without incurring charges.

• Simulate certain errors, such as temporary declines, that could appear in a real transaction. This simulation can help you test the error handling capabilities in your application.

You can test the following user experiences in the sandbox:

• View changes to the test account balance from test button operations you generate • Track the effects on your account balance of a series of transactions over time (you

cannot, however adjust the sandbox dates, but you can track cumulative changes in your Account Activity Center).

• View the transaction activity updates from test button operations you generate

The Amazon Simple Pay Getting Started Guide has instructions on testing basic button features using the Amazon Payments business sandbox.

Simulating a Mobile Client You can easily test the CBUI pipeline that your customers experience when they use their mobile devices. Amazon Payments uses the value of the client browser's HTTP_USER_AGENT to route the request along the appropriate pipeline. If you set your development environment to





43

report a value for HTTP_USER_AGENT reported by a mobile device, Amazon Payments will invoke the mobile pipeline.

For example, the following value simulates an Apple iPhone 3G version 2.1, with Safari 3.1.1:

Mozilla/5.0 (iPhone; U; CPU iPhone OS 2_1 like Mac OS X; en-us) AppleWebKit/525.18.1 (KHTML, like Gecko) Version/3.1.1.1 Mobile/5F136 Safari/525.20

Testing Button Signatures You can easily test your signature creation code using any of the examples in Amazon Simple Pay Button Input Reference. Each example contains a signature calculated from the values in the rest of the example.

To test a signature

1. Copy any one of the HTML examples in Amazon Simple Pay Button Input Reference. 2. Remove the enclosing FORM element from your copy. 3. Remove the Signature field and the HTML comments from your copy. 4. Create a signature using the instructions in How to Generate a Signature. 5. Compare the output from your signature creation code with the value you removed from

the HTML example. They should be identical.

Creating a Test Account Balance When using the Amazon Payments developer sandbox, you can use a test account for payment simulations.

To create a test account balance 1. Log in to http://payments-sandbox.amazon.com with your username and password. 2. On the Your Account tab, click Add a Bank Account in the Enhance your account

area. 3. Provide following test information

• Routing#: 123456789 • Account#: 111122223333 • Driver license: 123; WA

4. Add the bank account 5. On the Deposit tab, use the deposit form to add money to your account. 6. Click the Your Account tab. Your balance will be displayed.

http://payments-sandbox.amazon.com/


44

Forcing Error Conditions In the Amazon Payments developer sandbox, you can force an error by placing certain decimal values in the amount. The following table details the values.

Force Condition Error Forced Simulation The amount includes a decimal value between .60 and .69

Temporary Decline

Occurs when a downstream process is not available.

The amount includes a decimal value between .70 and .89.

Payment Error

Insufficient funds

Note If you want your test transaction to be a success, avoid using amount values which contain decimal values between .60 and .89. For example, the following amounts all force errors: 0.61, 123.6522, 1.79. The following amounts do not force an error: 0.16, 123.56, 8.97.

Configuring Default Button Values The user interfaces that help you create Amazon Simple Pay buttons ask you to enter a variety of information. Many of the buttons ask for the same information, such as a URL to redirect buyers to once they successfully authorize a payment. Amazon Simple Pay enables you to set default values for many of the button parameter values. Even though you set default values, you can still specify different values when generating the buttons. The values you enter in the user interfaces that create the buttons override the default values.

To configure the default values for your buttons

1. Go to http://payments.amazon.com. 2. Click the Your Account tab and log in if prompted. 3. Go to the Developer and Seller Preferences page at

https://payments.amazon.com/sdui/sdui/managecobranding.

Note To set your Developer and Seller Preferences in the Amazon FPS Sandbox, go to https://payments-sandbox.amazon.com/sdui/sdui/managecobranding instead. The settings for the sandbox and production environments are separate.

4. Use the following table to help you fill in the text fields or make choices.

Field Description Header and Footer To add your company logo to the upper left corner on all of

the Amazon Payment order pipeline pages, select Co-


https://payments.amazon.com/sdui/sdui/managecobranding

https://payments-sandbox.amazon.com/sdui/sdui/managecobranding


45

branded header image and enter the URL for the logo image. Adding your logo helps your customers know that while they're paying for their purchases using Amazon Payments, they're still connected to your website. Your logo is placed on a white background. The image can be no greater than 215 pixels wide by 40 pixels high and the URL must always be available. If there is no logo available when your customers check out (either because there was no logo specified or because the logo URL is not available), the name of your company is displayed. By default, no co-branding is selected.

Return URL Optionally, enter the URL where you want the system to redirect buyers after they authorize the payment, for example, http://yourweb_site/return.htm. You might want to return your customers to your home page or you might have a special Thank You page set up. If you do not specify a return URL, the default Thank You page from Amazon Payments appears. This means that your customers might not navigate back to your website. We recommend that you always specify a return URL, even if it's just your home page.

User Abandon URL Optionally, enter the URL where you want the system to direct buyers after they choose not to complete the CBUI web pages, for example, http://yourweb_site/cancel.htm. If you do not supply a value, Amazon Simple Pay directs the buyer to the Return URL. This URL is used when the buyer decides not to authorize the purchase and clicks the Cancel button.

Subscription Cancellation URL

Enter the URL to your website where subscribers can be directed when they try to cancel their subscription on payments.amazon.com. If you do not include a URL, subscribers will only be able to cancel their subscription through the Amazon Payments website.

URL for Instant Payment Notification

Optionally, enter the URL where you host a script to handle Instant Payment Notifications. Instant Payment Notification (IPN) is an HTML POST notification that is sent whenever a payment, refund, or reserved payment completes successfully or fails. You must host your own script to handle IPN notifications.

Sign the buttons? Select this check box if you want the signature parameter that is included in the HTML form element to be checked for each request. For more information, see “Keeping Payments Secure.”

5. Click Confirm.


46

Email Notification Templates Many transactions generate email messages from Amazon Payments, sent to either the buyer, seller, or web site owner in the case of a marketplace transaction. Transaction details are listed in the body of the email message. The content of the email message sent out depends on the transaction and its status.

The table here defines the templates that are used, and provides a link to an example message for each.

Email Template Name Description ASPPayFailureEmailToRecipient Donation Button

An Amazon Simple Pay donation button payment has failed to complete. The recipient has not received the intended funds.

ASPPayFailureEmailToRecipient Marketplace Button

An Amazon Simple Pay marketplace button payment has failed to complete. The recipient has not received the intended funds.

ASPPayFailureEmailToRecipient Standard Button

An Amazon Simple Pay standard button payment has failed to complete. The recipient has not received the intended funds.

ASPPaySuccessEmailToRecipient Donation Button

An Amazon Simple Pay donation button payment has succeeded.

ASPPaySuccessEmailToRecipient Marketplace Button

An Amazon Simple Pay marketplace button payment has succeeded.

ASPPaySuccessEmailToRecipient Standard Button

An Amazon Simple Pay standard button payment has succeeded.

ASPRefundFailedEmailToRecipient An Amazon Simple Pay button refund has failed to complete. The recipient has not received the intended funds.

ASPRefundSuccessEmailToRecipient Donation Button

An Amazon Simple Pay donation button refund has succeeded.

ASPRefundSuccessEmailToRecipient Marketplace Button

An Amazon Simple Pay marketplace button refund has succeeded.

ASPRefundSuccessEmailToRecipient Standard Button

An Amazon Simple Pay standard button refund has succeeded.

ASPReserveFailureEmailToMerchant Marketplace Button

An Amazon Simple Pay marketplace button reserve request has failed.

ASPReserveFailureEmailToMerchant Standard Button

An Amazon Simple Pay standard button reserve request has failed.

ASPReserveSuccessEmailToMerchant Marketplace Button

An Amazon Simple Pay marketplace button reserve request has succeeded.

ASPReserveSuccessEmailToMerchant Standard Button

An Amazon Simple Pay standard button reserve request has succeeded.

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPayFailureEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPPaySuccessEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundFailedEmailToRecipient.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPRefundSuccessEmailToRecipient-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveFailureEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveFailureEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveFailureEmailToMerchant-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveFailureEmailToMerchant-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveSuccessEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveSuccessEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveSuccessEmailToMerchant-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPReserveSuccessEmailToMerchant-Std.html


47

Email Template Name Description ASPSettleFailureEmailToMerchant An Amazon Simple Pay button settle

request has failed. ASPSettleSuccessEmailToMerchant Marketplace Button

An Amazon Simple Pay marketplace button settle request has succeeded.

ASPSettleSuccessEmailToMerchant Standard Button

An Amazon Simple Pay marketplace button settle request has succeeded.

BAVerifFailed Bank account verification failed BAVerifStartedForPersonalBusiness Bank account verification started for

personal and business account BAVerifStartedForDeveloper Bank account verification started for

developer account BAVerifSuccess Bank account verification successful CCVerifFailedBusiness Credit card verification failed for business

Account ConfirmEmailPersonal Email confirmation sent to confirm the email

address for the personal account. ConfirmEmailBusiness Email confirmation sent to confirm the email

address for a business account. DailySummary Daily summary of transactions DepositFailure Deposit failed DepositFundsInitiated Request to deposit funds initiated DepositSuccess Deposit successful MonthlyNotif Notification for monthly statement MPFeeRegistrationCallerPaysFee MarketPlace registration email, fee paid by

Caller MPFeeRegistrationRecipientPaysFee MarketPlace registration email, fee paid by

Recipient MultiPaymentFailure Payment failure from a multi use token

(payment authorizations) MultiPaymentSuccess Payment success from a multi use token

(payment authorizations) OnetimePaymentACHInit One-time payment (ACH) initiated OnetimePaymentFailure Donation Button One-time donation button payment failed OnetimePaymentFailure Marketplace Button One-time marketplace button payment failed OnetimePaymentFailure Standard Button One-time payment failed for standard button OnetimePaymentSuccess Donation Button One-time donation button payment

Successful OnetimePaymentSuccess Marketplace Button One-time marketplace button payment

Successful OnetimePaymentSuccess Standard Button One-time standard button payment

Successful OnetimePaymentSuccessACH One-time ACH payment successful RefundSuccess Donation Button Refund of donation charge successful RefundSuccess Marketplace Button Refund of marketplace button charge

Successful

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPSettleFailureEmailToMerchant.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPSettleSuccessEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPSettleSuccessEmailToMerchant-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPSettleSuccessEmailToMerchant-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ASPSettleSuccessEmailToMerchant-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/BAVerifFailed.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/BAVerifStartedForBasicPremier.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/BAVerifStartedForDeveloper.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/BAVerifSuccess.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/CCVerifFailedPremier.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ConfirmEmailBasic.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/ConfirmEmailPremium.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/DailySummary.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/DepositFailure.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/DepositFundsInitiated.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/DepositSuccess.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/MonthlyNotif.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/MPFeeRegistrationCallerPaysFee.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/MPFeeRegistrationRecipientPaysFee.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/MultiPaymentFailure.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/MultiPaymentSuccess.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentACHInit.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentFailure-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentFailure-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentFailure-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentSuccess-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentSuccess-Mkt.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentSuccess-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/OnetimePaymentSuccessACH.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/RefundSuccess-Don.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/RefundSuccess-Mkt.html


48

Email Template Name Description RefundSuccess Standard Button Refund of standard button successful RefundSuccess Subscription Button Refund of subscription charge successful SubscriptionCancellationByFPSToSender Subscription canceled due to payment

failure SubscriptionCancellationByRecipientToRecipient Subscription canceled by subscriber SubscriptionCancellationByRecipientToSender Subscription canceled notification from

merchant to subscriber SubscriptionCancellationBySenderToRecipient Subscription canceled notification from

Merchant SubscriptionCancellationBySenderToSender Subscription canceled notification form

Merchant SubscriptionCreatedEmailForMerchant Subscription created notification to merchant SubscriptionCreatedEmailForSender Subscription created notification to

subscriber SubscriptionPayFailureEmailForMerchant Notify merchant that payment for

subscription has failed SubscriptionPayFailureEmailForMerchant Notify merchant that payment for

subscription has failed SubscriptionPaymentMethodChangeEmail Subscription payment failed to subscriber SubscriptionPaySuccessEmailForMerchant Notify merchant that a subscription payment

is successful SubscriptionPreNotifEmail Subscription payment due UpgradePersonalToBusiness Upgrade to business account successful VerifyEmailSuccessPersonal Email address verified for personal account VerifyEmailSuccessBusiness Email address verified for business account WithdrawFailure Withdraw failed, bank unable to accept

electronic transaction WithdrawFundsInitiated Withdraw funds has been initiated

Amazon Simple Pay WSDL and Schema Amazon Simple Pay is built on the Amazon Flexible Payments Service (FPS) and uses the FPS WSDL and FPS Schema.

The WSDL defines the web service language that computers use to exchange information. The Amazon Simple Pay WSDL is a subset of the Amazon Flexible Payments WSDL. In this guide, the WSDL elements relevant to Amazon Simple Pay are listed in the Simple Pay FPS Actions API Reference. For the full raw WSDL, see the Amazon FPS WSDL.

The schema defines the data types used within the WSDL. For your convenience we have included a list of the data types relevant to Amazon Simple Pay in the section, Data Types.

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/RefundSuccess-Std.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/RefundSuccess-Sub.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCancellationByFPSToSender.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCancellationByRecipientToRecipient.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCancellationByRecipientToSender.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCancellationBySenderToRecipient.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCancellationBySenderToSender.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCreatedEmailForMerchant.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionCreatedEmailForSender.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionPayFailureEmailForMerchant.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionPayFailureEmailForMerchant.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionPaymentMethodChangeEmail.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionPaySuccessEmailForMerchant.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/SubscriptionPreNotifEmail.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/UpgradeBasicToPremium.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/VerifyEmailSuccessBasic.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/VerifyEmailSuccessPremier.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/WithdrawFailure.html

http://docs.amazonwebservices.com/AmazonFPS/2008-09-17/FPSEmailExamples/WithdrawFundsInitiated.html

https://fps.amazonaws.com/doc/2010-08-28/AmazonFPS.wsdl


49

The latest Amazon FPS WSDL is at: https://fps.amazonaws.com/doc/2010-08-28/AmazonFPS.wsdl. The latest Amazon FPS schema is at: https://fps.amazonaws.com/doc/2010-08-28/AmazonFPS.xsd.



https://fps.amazonaws.com/doc/2010-08-28/AmazonFPS.xsd


50


This section discusses the operations available in the Amazon Simple Pay Application Programming Interfaces (APIs), their semantics, and their required parameters. Examples of requests and responses are also provided.

The Amazon Simple Pay APIs are a subset of the Amazon Flexible Payments Service actions. This section contains all the information you need to use Amazon Simple Pay APIs. For more information about Amazon FPS APIs, see the Amazon FPS Basic Guide.

Note In order to use and test these actions, you need to get an Amazon Payments developer account and its associated sandbox account, as specified in Amazon Payments Developer Account.

Flexible Payments Service Actions Available with Amazon Simple Pay Amazon Simple Pay includes a subset of the Amazon Flexible Payments Service actions. This section contains the information you need to use the Cancel, CancelSubscriptionAndRefund, GetSubscriptionDetails, GetTransactionsForSubscription, GetTransactionStatus, Refund, Settle, and VerifySignature APIs.

API Description Cancel Cancel a reserved or pending transaction. For more

information, see “Cancel.” CancelSubscriptionAndRefund Cancel a subscription and, if a refundAmount is specified,

refund the specified amount from the last subscription payment charged to the subscriber. For more information, see “CancelSubscriptionAndRefund.”

GetSubscriptionDetails Get the details of a subscription. For more information, see “GetSubscriptionDetails.”

GetTransactionsForScription Get the transactions which have been made against a subscription. For more information, see “GetTransactionsForSubscription.”

GetTransactionStatus Get the current status of a particular transaction. For more information, see “GetTransactionStatus.”

Refund Refund a successfully completed payment transaction. For more information, see “Refund.”

https://amazonpayments.s3.amazonaws.com/FPS_ASP_Guides/FPS_Basic_Quick_Start.pdf


51

API Description Settle Charge the buyer's payment instrument for the purchase

that was reserved. For more information, see “Settle.” VerifySignature Validate a signature in an Amazon Payments response.

For more information, see “VerifySignature.”

Cancel Description The Cancel action cancels a reserved or pending transaction. Once the transaction is canceled, you cannot settle it. You cannot use Cancel on a completed transaction. Once a transaction is completed, you can do a refund if you want to reverse the order.

If the sender's credit card was in a reserved state, it is not part of this action to make sure the reserved status is removed. There is no action required to remove the reserved status, it will automatically expire after 7 days.

Note This action is an Amazon Flexible Payment Service (Amazon FPS) action. In order to execute this action, you must have an AWS Developer account. For information about how to get an account, see "Before you Begin" in the Amazon Simple Pay Getting Started Guide.

Request Parameters Parameter Description Required TransactionId

The unique ID generated by Amazon FPS and returned in response to a successful transaction. Type: String Constraint: 35 characters maximum Ancestor: RefundResult, ResponseMetadata

Yes

Description Describes the reason for cancellation. Type: String Default: None

No

You must also use parameters that are common to all requests that are described in Common Request Parameters. Parameter names are case sensitive.

Response Elements Element Description ResponseMetadata Provides information about the request, including the request ID.

Always returned. Type: Common Response Elements

TransactionId This is the ID of the completed transaction. Returned only if the transaction is successful.




52

Element Description Type: String: Max size = 35 characters

TransactionStatus Specifies the status of the cancellation request. Always returned. Type: TransactionStatus

Responses also include elements common to all responses. For more information, see “Common Response Elements.”

Errors This action can return the following errors:

• AccessFailure • AccountClosed • AuthFailure • ConcurrentModification • InvalidClientTokenId

• InternalError • InvalidParams • InvalidTransactionState • SignatureDoesNotMatch

Examples

Note In order to provide a secure request, you must generate a signature whenever you make a call using this action. For more information, see “Keeping Payments Secure.”

Sample REST Request This section shows a sample REST request.

https://fps.sandbox.amazonaws.com? Action=Cancel &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &Description=MyWish &Signature=yOedrTuiMoMrKt8SwugDDnfd0nydyoX9uPq1H1SUCl4%3D &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2009-10-06T09%3A14%3A58.796Z &TransactionId=14GKI1SKSR1V6DO1RCCB32RBR6KLODMGQUD &Version=2008-09-17

Sample Response to REST Request This section shows a sample response to a REST request.

<CancelResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <CancelResult> <TransactionId>14GKI1SKSR1V6DO1RCCB32RBR6KLODMGQUD</TransactionId> <TransactionStatus>Cancelled</TransactionStatus> </CancelResult> <ResponseMetadata> <RequestId>6fe4b755-a328-419d-8967-e1d3b43779fc:0</RequestId>


53

</ResponseMetadata> </CancelResponse>

Sample IPN Success Notification to Rest Request This section shows a sample IPN notification to a REST request.

transactionId: 14GKI1SKSR1V6DO1RCCB32RBR6KLODMGQUD statusMessage: The transaction was explicitly cancelled by the caller. transactionDate: 1254820475 signatureVersion: 2 signatureMethod: RSA-SHA1 buyerEmail: [email protected] notificationType: TransactionStatus callerReference: CallerReference08 transactionAmount: USD 1.00 transactionStatus: CANCELLED operation: RESERVE recipientEmail: [email protected] buyerName: Test Business signature: jWDbBxtEhw2rQEyMeEXcpWCgoZvm8rjLEnmg38oYoPPR7NbMGgmMA9/5CDjt9Q/FMktKMbARXnZFYTzHj3YOKiAM3vxI0zT1oTiSdBx1KBRFzK7mauxxlQv5BYxjFX+R5cl+keCaT2nQyrp3agdrIIp5MZ5Oy9dBuYMwMFWXoZZor90EidD23hBdZSOOzQRUdzKaKJsF14RQVrKcf5pDCs1HaB6LBKbATaNTRSxxrviIXy9JcWRQhJwzcc1H6cFOJDpNFSJ03b0Z94eL/XNu9BU7bT4KRWb+OHF0Pn53yf4zyBT9jTD+94WeujCxwE2rF0j5+brmXp/+Sn/RccDG7w== recipientName: Test Business paymentMethod: CC certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem paymentReason: Reserve statusCode: Cancelled


54

CancelSubscriptionAndRefund Description The CancelSubscriptionAndRefund action cancels a subscription and, if a refundAmountis specified, refunds the specified amount from the last subscription payment charged to the subscriber.


For canceling a subscription with no refund, use the SubscriptionId parameter by itself (and optionally, the CancelReason parameter). If a subscription is already canceled or completed, you will receive the InvalidSubscriptionState error with an appropriate error message.

For canceling a subscription with a refund, use the SubscriptionId, CallerReference, and RefundedAmount parameters (and optionally, the CancelReason parameter). If the subscription is already canceled or completed, the cancellation request is ignored and the refund is executed.

Request Parameters Parameter Description Required CallerReference A value you provide that uniquely identifies the

request. This identifier is maintained for seven days by Amazon FPS. Type: String Constraints: 128 bytes maximum Default: None

Only if you specify a value for Refund Amount.

CancelReason String that explains the reason for the cancellation. Type: String Default: None

No

RefundAmount If you want a part of the last subscription payment to be refunded to the subscriber, you can specify the amount in this parameter. If a value for RefundAmount is not specified, the Action is treated as a cancellation for SubscriptionId. Type: Amount Default: None

Only if you want to make a refund.

SubscriptionId SubscriptionId of the subscription to be canceled. Type: String Default: None

Yes




55


Response Elements Element Description RefundTransactionId If you set a refund amount in the request, the transaction ID of

the refund transaction is returned here. This element is returned only if the refund transaction could be initiated. Type: String


Errors If the cancellation of the subscription passes but the refund fails, the system returns an error code showing why the refund transaction failed. The error message contains more details about why the refund transaction failed.

The following is a list of possible errors for this action:

• AuthFailure • ConcurrentModification • DuplicateRequest • InsufficientBalance • InvalidAccountState_Caller • InvalidAccountState_Sender • InvalidClientTokenId

• RefundDenied • SignatureDoesNotMatch • InvalidParams • InvalidSubscriptionID • MissingRequiredParameter • OriginalTransactionFailed

Examples


Sample REST Request

https://fps.sandbox.amazonaws.com? Action=CancelSubscriptionAndRefund &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &CallerReference=CallerReference07 &CancelReason=MyWish &RefundAmount.CurrencyCode=USD &RefundAmount.Value=1 &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Signature=1uFUSSFvau1zadnSzKRS5ZchuLMn9p5M3ifaHGHie7M%3D


56

&SubscriptionId=17d62772-c53e-4bdb-9667-65d7b7841cfc &Timestamp=2009-10-06T08%3A05%3A13.296Z &Version=2008-09-17

Sample Response to REST Request

<CancelSubscriptionAndRefundResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <CancelSubscriptionAndRefundResult> <RefundTransactionId> 14GKE3B85HCMF1BTSH5C4PD2IHZL95RJ2LM </RefundTransactionId> </CancelSubscriptionAndRefundResult> <ResponseMetadata> <RequestId>bfbc0b1e-3430-4a74-a75e-5292f59107ca:0</RequestId> </ResponseMetadata> </CancelSubscriptionAndRefundResponse>


signatureVersion: 2 signatureMethod: RSA-SHA1 status: SubscriptionCancelled signature: sNaPeP1aNg5pjehHYJ97BAPWoZVPxFpXGOmDmprYk Pq8KN1cuZotBW2j+goUqA5tue/2FDlNk5+Z KMBtshSLiqtG1R6AH9qaNjZQwg4dm4t0OqP2eOjoH73wQwIaCCEr690o2lxjN+vx7KO+w4wmnyqF xL9/j5wBjC2zpoy3NrN8uM0R547rYjjOaTODYb0cesYfvXXPGvFBniDloPGpxx7G2ryIVZpFaeJ9 2XF2k6ho8M8rkdTp3MHPLiyZHjFl6+cKen2XynOqHD5RkG/aIgG9waus3E3esn9Zweo8m4vdiL67 MyS4zQzyRg973bi45+Knv6AuuhhcTta41zSR8g== subscriptionId: 17d62772-c53e-4bdb-9667-65d7b7841cfc certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem statusReason: CancelledByRecipient


57

GetSubscriptionDetails Description GetSubscriptionDetails enables you to retrieve the subscription details for a specific SubscriptionId.

Request Parameters Parameter Description Required SubscriptionId The subscription ID for the

subscription of interest. Type: String Default: None Constraint: Cannot be null or empty

Yes

You must also use the Action parameter as described in Common Request Parameters. Parameter names are case sensitive.

Response Elements Element Description SubscriptionDetails A single SubscriptionDetails Type object, containing the details

for the subscription.



• InternalError • InvalidSubscriptionID

Examples

Sample REST Request This section shows a sample request.

https://fps.sandbox.amazonaws.com/? Action=GetSubscriptionDetails &SubscriptionId=YourSubscriptionId &AWSAccessKeyId=YourAccessKey &Version=2010-08-28 &Timestamp=2011-03-11T06%3A46%3A23Z &SignatureVersion=2 &Signature=YourCalculatedSignature &SignatureMethod=HmacSHA256


58

Sample Response to REST Request This section shows a sample REST response.

<GetSubscriptionDetailsResponse xmlns="http://fps.amazonaws.com/doc/2010-08-28/"> <GetSubscriptionDetailsResult> <SubscriptionDetails> <SubscriptionId>YourSubscriptionId</SubscriptionId> <Description>SubscriptionDescription</Description> <SubscriptionAmount> <CurrencyCode>USD</CurrencyCode> <Value>10.000000</Value> </SubscriptionAmount> <PromotionalAmount> <CurrencyCode>USD</CurrencyCode> <Value>4.000000</Value> </PromotionalAmount> <NumberOfPromotionalTransactions> </NumberOfPromotionalTransactions> <StartDate>2011-04-07T08:16:52.000-07:00</StartDate> <EndDate>2011-04-07T08:19:52.000-07:00</EndDate> <SubscriptionPeriod> <Value>18</Value> <TimeUnit>week</TimeUnit> </SubscriptionPeriod> <SubscriptionFrequency> <Value>6</Value> <TimeUnit>week</TimeUnit> </SubscriptionFrequency> <SubscriptionStatus>Completed</SubscriptionStatus> <NumberOfTransactionsProcessed>3</NumberOfTransactionsProcessed> <RecipientEmail>[email protected]</RecipientEmail> <RecipientName>RecipientName</RecipientName> <SenderEmail>[email protected]</SenderEmail> <SenderName>SenderName</SenderName> </SubscriptionDetails> </GetSubscriptionDetailsResult> <ResponseMetadata> <RequestId>RequestId</RequestId> </ResponseMetadata> </GetSubscriptionDetailsResponse>


59

GetTransactionsForSubscription Description GetTransactionsForSubscription enables you to get the details of the transactions processed against a given SubscriptionId. The action returns a list of SubscriptionTransaction Type objects. Each object specifies a separate transaction.

Note If the subscription has had no transactions, no SubscriptionTransaction object is returned.

Request Parameters Parameter Description Required SubscriptionId The subscription ID against which the

transactions have occurred. Type: String Default: None Constraint: Cannot be null or empty

Yes


Response Elements Element Description SubscriptionTransaction A list of SubscriptionTransaction Type objects. If no transactions are

found, then nothing is returned. Type: SubscriptionTransaction



• InternalError • InvalidSubscriptionID

Examples


https://fps.sandbox.amazonaws.com? Action=GetTransactionsForSubscription &SubscriptionId=YourSubscriptionId


60

&AWSAccessKeyId=YourAWSAccessKey &Timestamp=2011-04-07T11%3A20%3A33.609Z &Version=2010-08-28 &Signature=CalculatedSignature &SignatureMethod=HmacSHA256 &SignatureVersion=2


<GetTransactionsForSubscriptionResponse xmlns="http://fps.amazonaws.com/doc/2010-08-28/"> <GetTransactionsForSubscriptionResult> <SubscriptionTransaction> <TransactionId>TransactionId</TransactionId> <TransactionDate>2011-02-07T08:54:38.522-07:00</TransactionDate> <TransactionSerialNumber>1</TransactionSerialNumber> <TransactionAmount> <CurrencyCode>USD</CurrencyCode> <Value>1.000000</Value> </TransactionAmount> <Description>TransactionDescription</Description> <TransactionStatus>Success</TransactionStatus> </SubscriptionTransaction> <SubscriptionTransaction> <TransactionId>TransactionId</TransactionId> <TransactionDate>2011-03-07T08:54:48.522-07:00</TransactionDate> <TransactionSerialNumber>2</TransactionSerialNumber> <TransactionAmount> <CurrencyCode>USD</CurrencyCode> <Value>1.000000</Value> </TransactionAmount> <Description>TransactionDescription</Description> <TransactionStatus>Success</TransactionStatus> </SubscriptionTransaction> <SubscriptionTransaction> <TransactionId>TransactionId</TransactionId> <TransactionDate>2011-04-07T08:54:58.522-07:00</TransactionDate> <TransactionSerialNumber>3</TransactionSerialNumber> <TransactionAmount> <CurrencyCode>USD</CurrencyCode> <Value>1.000000</Value> </TransactionAmount> <Description>TransactionDescription</Description> <TransactionStatus>Success</TransactionStatus> </SubscriptionTransaction> </GetTransactionsForSubscriptionResult> <ResponseMetadata> <RequestId>RequestId</RequestId> </ResponseMetadata> </GetTransactionsForSubscriptionResponse>


61

GetTransactionStatus Description The GetTransactionStatus action returns the status of the transaction specified by the TransactionId. You could use this action if you choose not to process Instant Payment Notifications (IPNs) that you receive from Amazon Payments (for more information, see “Using Instant Payment Notification.”

Request Parameters Parameter Definition Required TransactionId The transaction's ID.

Type: String Constraint: Max size = 35 characters Default: None

Yes

For REST requests, you must also include parameters that are common to all requests. These parameters are included by default in SOAP requests. For more information, see “Common Request Parameters.”

Response Elements Element Description CallerReference A value you provide that uniquely identifies the

request. Type: String Size: 128 bytes

StatusCode Shorthand code that specifies the status of the transaction. Expands on the information in the TransactionStatus field. For example, if TransactionStatus is PENDING, this field might be PendingVerification, or PendingNetworkResponse. Type: String Size: 64 bytes Valid Values: See “Status Codes”

StatusMessage A description of the transaction status. Type: String (LOB, Large Object)

TransactionId Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String Size: 35 Bytes

TransactionStatus The status of the transaction. Provides a short code on the status of the transaction, for example "PENDING.” Type: TransactionStatus Size: 20 bytes


62


Status Codes This action can return the following values for StatusCode.

Status Code Message Canceled The transaction was explicitly canceled by the

caller. Expired This reserved amount on the payment

instrument was not settled within the timeout period OR The transaction could not be completed within the specified timeout.

PendingNetworkResponse This transaction is awaiting a response from the backend payment processor OR (Message returned by backend payment processor)

PendingVerification The transaction has been flagged for manual investigation

Success The requested amount was reserved successfully against the givenpayment instrument. OR The transaction was successful and the payment instrument was charged.

TransactionDenied (Message returned by backend payment processor). OR The transaction was denied after investigation.

Errors This action can return the following synchronous errors, which occur within the status for this action.

• AccessFailure • AuthFailure • InternalError • InvalidClientTokenId • InvalidParams • InvalidTransactionId • SignatureDoesNotMatch


63

Examples The following sections show a sample request and response.

Sample REST Request

https://fps.sandbox.amazonaws.com? Action=GetTransactionStatus &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &Signature=2l60qD6%2BDIfVEN7ZiHM0AcUKACZt0GYKFtIryqkCb6g%3D &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2009-10-06T09%3A12%3A06.921Z &TransactionId=14GKE3B85HCMF1BTSH5C4PD2IHZL95RJ2LM &Version=2008-09-17

Sample Response to REST Request

<GetTransactionStatusResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <GetTransactionStatusResult> <TransactionId>14GKE3B85HCMF1BTSH5C4PD2IHZL95RJ2LM</TransactionId> <TransactionStatus>Success</TransactionStatus> <CallerReference>CallerReference07</CallerReference> <StatusCode>Success</StatusCode> <StatusMessage> The transaction was successful and the payment instrument was charged. </StatusMessage> </GetTransactionStatusResult> <ResponseMetadata> <RequestId>13279842-6f84-41ef-ae36-c1ededaf278d:0</RequestId> </ResponseMetadata> </GetTransactionStatusResponse>


64

Refund Description You use Refund to refund a successfully completed payment transaction. You can refund less than the amount paid. The default, however, is to refund the full price to the buyer.

The Refund operation can be used only by the caller of the original transaction. Refunds are processed in batch so they often take a while before completing.


Request Parameters Parameter Description Required CallerDescription A field that contains the caller's description of the

transaction. Type: String Constraint: 160 characters maximum Default: None

No

CallerReference A value you provide that uniquely identifies the request. This identifier is maintained for seven days by Amazon FPS. Type: String Constraints: 128 bytes maximum Default: None

Yes

MarketplaceRef undPolicy

Specifies the details of the refund, in particular, whether or not the caller or Amazon FPS are refunding their fees. Type: MarketplaceRefundPolicy Default: None

No

RefundAmount Specifies the amount to be refunded.The total refund amount cannot exceed the original transaction amount. If this value is not specified, Amazon FPS refunds any remaining amount from the original transaction. Type: Amount Data Types Default: None

No

TransactionId The unique ID generated by Amazon FPS and returned in response to a successful transaction. Type: String Constraint: 35 characters maximum Ancestor: RefundResult, ResponseMetadata

Yes




65


Response Elements Element Description TransactionId This is the ID of the transaction named in the request. Returned if the

transaction is successful Type: String Constraints: 35 characters Ancestor: RefundResult, ResponseMetadata

TransactionStatus Provides the status of the transaction. Always returned. Type: TransactionStatus Ancestor: ResponseMetadata



• AccessFailure • AmountOutOfRange • AuthFailure • ConcurrentModification • DuplicateRequest • InternalError • InvalidAccountState_Caller • InvalidAccountState_Recipient • InvalidAccountState_Sender • InvalidClientTokenId • InvalidParams

• InvalidTransactionId • OriginalTransactionFailed • OriginalTransactionIncomplete • RefundAmountExceeded • SignatureDoesNotMatch • TransactionDenied • TransactionFullyRefundedAlready • TransactionTypeNotRefundable • UnverifiedEmailAddress_Caller • UnverifiedEmailAddress_Sender

Examples



https://fps.sandbox.amazonaws.com? Action=Refund &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &CallerDescription=MyWish &CallerReference=CallerReference03 &RefundAmount.CurrencyCode=USD &RefundAmount.Value=1


66

&Signature=V6pU3PvDPkPhR9Eu7yZXnFZHuEFafLE5sBPgqqCELEU%3D &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2009-10-06T05%3A51%3A49.578Z &TransactionId=14GK4TNCAQ84NK9VITEHKAS94RAD9ZE2AQD &Version=2008-09-17


<RefundResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <RefundResult> <TransactionId> 14GK6F2QU755ODS27SGHEURLKPG72Z54KMF </TransactionId> <TransactionStatus>Pending</TransactionStatus> </RefundResult> <ResponseMetadata> <RequestId>1a146b9a-b37b-4f5f-bda6-012a5b9e45c3:0</RequestId> </ResponseMetadata> </RefundResponse>


transactionId: 14GK6F2QU755ODS27SGHEURLKPG72Z54KMF statusMessage: The transaction was successful and the payment instrument was charged. transactionDate: 1254808324 signatureVersion: 2 signatureMethod: RSA-SHA1 parentTransactionId: 14GK4TNCAQ84NK9VITEHKAS94RAD9ZE2AQD referenceId: Refund for [original_reference_id] buyerEmail: [email protected] notificationType: TransactionStatus callerReference: CallerReference03 transactionAmount: USD 1.00 transactionStatus: SUCCESS operation: REFUND recipientEmail: [email protected] buyerName: Test Business signature: sDq9YvW7L29W2NSIC/wjC5yLyR4QJSQyt/7iHhNiEdwFoGVkrLjJHiBloPfJxzznHnmMtCR sUQ+A d3tZ0NdemMxf0qYM9NX93PyG0KBKXShKeM0Da39cvnC05tZmtxpfCuZT5ECRydr+BqRo/DOlx1Yg 93gihZ83qHWR8bpqQcBwsu7vD4c4m4mTZ4I75gw+NXKRDD+vCPFDNEKRnh5kQz+Tjjg4bnNYEEcG


67

Rf6UZfS2lvMzdj0c37RUY6t4gQ3W3Z9G/REGjC98JBuTimk/kc1HoSc+xe6WtAH/siNurisyqgoB HWnQM8iRqLEHj/m9y6vx5EBHBokD1BJMIiiZNg== recipientName: Test Business paymentMethod: CC certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem paymentReason: MyWish statusCode: Success

Settle Description The Settle operation charges the buyer's payment instrument for the purchase that was reserved. When you do not select the Do you want to settle immediately? check box (see “Configuring Default Button Values”), the buyer is not actually charged by Amazon Simple Pay for their purchase; rather the purchase price is reserved against their payment instrument. To charge the buyer for their purchase, you must settle the charge using the Settle operation. One way you could settle a transaction is to charge the payment instrument when you fulfill the order, for example, when you ship the purchased items.


Request Parameters Parameter Description Required ReserveTransactionId An identifier returned by Reserve that identifies

the reserved transaction to be settled. Type: String Constraint: 35 characters maximum Default: None

Yes

TransactionAmount Amount to be settled. This cannot exceed the reserve amount. Type: Amount Default: The amount reserved in the Reserve request

No


Response Elements Element Description TransactionId Identifies the transaction that was settled. Always returned.




68

Type: String TransactionStatus Provides the status of the transaction. Always returned.

Type: TransactionStatus Responses also include elements common to all responses. For more information, see “Common Response Elements.”


• AccessFailure • AccountClosed • AmountOutOfRange • AuthFailure • ConcurrentModification • InternalError • InvalidAccountState_Caller • InvalidAccountState_Recipient • InvalidAccountState_Sender • InvalidClientTokenId

• InvalidParams • InvalidTransactionId • InvalidTransactionState • SettleAmountGreaterThanReserveAmount • SignatureDoesNotMatch • TransactionDenied • UnverifiedAccount_Recipient • UnverifiedEmailAddress_Caller • UnverifiedEmailAddress_Recipient • UnverifiedEmailAddress_Sender

Examples


Sample REST Request

https://fps.sandbox.amazonaws.com?ReserveTransactionId=14GKD9GE66FAA63E6O6B2JD PZKN53LZ7F22 Action=Settle &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &Signature=SJJLsIBghi7VIycBjX7c3hnfgZ%2FBvZbzqLtAZXDL8ys%3D &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Version=2008-09-17 &Timestamp=2009-10-06T07%3A53%3A11.750Z &TransactionAmount.CurrencyCode=USD &TransactionAmount.Value=1 &Version=2008-09-17


<SettleResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <SettleResult>


69

<TransactionId>14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22</TransactionId> <TransactionStatus>Pending</TransactionStatus> </SettleResult> <ResponseMetadata> <RequestId>9ed2008b-b230-4ed0-9210-095f77fc2359:0</RequestId> </ResponseMetadata> </SettleResponse


transactionId: 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22 statusMessage: The transaction was successful and the payment instrument was charged. transactionDate: 1254815482 signatureVersion: 2 signatureMethod: RSA-SHA1 buyerEmail: [email protected] notificationType: TransactionStatus callerReference: CallerReference05 referenceId: [original_reference_id] operation: SETTLE transactionStatus: SUCCESS transactionAmount: USD 1.00 recipientEmail: [email protected] buyerName: Test Business signature: pwozZP+lYONFq39g13ux44vFFMRAt4eJ9kOUWMV2uPCrvBqzi4LFYDQY5UE3VW8OUiW+qp bukqFz YNvE+8mh7adhX/qee2U8ZUUNZi6LaM3sKtpPxus2ZJ3wDVPjuO02Obtu1G6Eo79iMi8viX7Dz1LL 8pFTdhspHZb0XDWkuOt2pK2aELa7TOZ/pXXUFLvGrn4MOd6INwbyM2fvnJpIDTcNdzedBO3Rw3vp 2f2GfpFAZJD6Imu57rsr9RsHVUqu2bIhJaAgTRFleVKzMHQJqft5jo6M9N4vKmPfccsuAvoF+rDn +/6a9VEvTBrVcvAhJ5jrBp3FkXYkOPbHchqHfQ== recipientName: Test Business paymentMethod: CC certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem paymentReason: Reserve statusCode: Success

mailto:[email protected]


70

VerifySignature Description VerifySignature enables you to verify the signature included with outbound notifications. A correctly formatted call using VerifySignature returns a positive result when the signature is valid for the response that contained it.

This action is a component of signature version 2. Because of this, you may only use it with responses which have a SignatureVersion value of 2. As of 10 February, 2011, Amazon Payments signs all outbound responses with signature version 2. Unsigned outbound responses are no longer supported.

Note You sign VerifySignature as you would any other Amazon FPS action.

Request Parameters Parameter Description Required UrlEndPoint A required field that contains the appropriate originating

endpoint (either the returnUrl or ipnUrl) that received the response. For example, if your web application resides at http://my-app-website.biz/, the returnUrl might be http://my-app-website.biz/amazon/success.php, and the IPNUrl might be http://my-app-website.biz/amazon/ipnProcessor.php. Type: String Default: None Constraint: Cannot be null or empty

Yes

HttpParameters Concatenated string of all URL-Encoded parameters which were included in the response containing the signature you want to verify.This includes the certificateUrl, signatureVersion, signatureMethod and signature parameters. For example, a correctly formatted and URL-encoded string resembles the following: First%20Name=Joe&Last%20Name=Smith&signatureVersion=2 &signatureMethod=HMACSHA256&certificateUrl=https%253A%252F%252Ffps.amazonaws.com%252Fcert%252Fkey.pem&signature=aoeuAOE123eAUdhf] Tip For validating the returnUrl, you can extract the query string from the returnUrl (excluding the '?' character). For validating the IPNUrl, concatenate the POST parameters. Type: String Default: None Constraint: Cannot be null or empty. In addition, because

Yes


71

Parameter Description Required VerifySignature is a component of signature version 2, the value for signatureVersion must be 2.


Response Elements Element Description VerificationStatus The result of the verification, either Success or

Failure. Type: VerificationStatus



• InternalServerError • InvalidParams

Examples


https://fps.sandbox.amazonaws.com/?Action=VerifySignature&UrlEndPoint=h ttp%3A%2F%2Fexample.com%3A8080%2Fipn.jsp&HttpParameters=expiry %3D08%252F2015%26signature%3DynDukZ9%252FG77uSJVb5YM0cadwHVwYKPMKO O3PNvgADbv6VtymgBxeOWEhED6KGHsGSvSJnMWDN%252FZl639AkRe9Ry%252F7zmn9CmiM %252FZkp1XtshERGTqi2YL10GwQpaH17MQqOX3u1cW4LlyFoLy4celUFBPq1WM2ZJnaNZRJ IEY%252FvpeVnCVK8VIPdY3HMxPAkNi5zeF2BbqH%252BL2vAWef6vfHkNcJPlOuOl6jP4E %252B58F24ni%252B9ek%252FQH18O4kw%252FUJ7ZfKwjCCI13%252BcFybpofcKqddq8C uUJj5Ii7Pdw1fje7ktzHeeNhF0r9siWcYmd4JaxTP3NmLJdHFRq2T%252FgsF3vK9m3gw%2 53D%253D%26signatureVersion%3D2%26signatureMethod%3DRSA-SHA1%26certific ateUrl%3Dhttps%253A%252F%252Ffps.sandbox.amazonaws.com%252Fcerts%252F09


72

0909%252FPKICert.pem%26tokenID%3DA5BB3HUNAZFJ5CRXIPH72LIODZUNAUZIVP7UB7 4QNFQDSQ9MN4HPIKISQZWPLJXF%26status%3DSC%26callerReference%3DcallerRefe renceMultiUse1&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Timestamp=2010-02-26 T19%3A48%3A05.000Z&Version=2008-09-17&SignatureVersion=2&SignatureMetho d=HmacSHA256&Signature=fKRGL42K7nduDA47g6bJCyUyF5ZvkBotXE5jVcgyHvE%3D


<VerifySignatureResponse xmlns="http://fps.amazonaws.com/doc/2008-09-17/"> <VerifySignatureResult> <VerificationStatus>Success</VerificationStatus> </VerifySignatureResult> <ResponseMetadata> <RequestId>197e2085-1ed7-47a2-93d8-d76b452acc74:0</RequestId> </ResponseMetadata> </VerifySignatureResponse>


73

Common Request Parameters Each action in the API has its own specific set of parameters, but there is also a set of parameters that all actions use. This section describes those input parameters.

You only need to add these parameters in REST requests. SOAP requests include them by default.

The following table describes parameters that can be used in all requests.

Parameter Description Required Action The API operation, for example, Settle or

Refund. Type: String: Default: None Constraint: Must be a valid operation such as Cancel, Refund, and so on.

Yes

AWSAccessKeyId A string, distributed by Amazon FPS when you sign up to be a developer, that uniquely identifies the caller. Type: String Default: None

Yes

Signature value calculated using the request parameters and a SHA256 (preferred) or SHA1 HMAC encryption algorithm. Type: String Default: None

Yes

SignatureVersion A value that specifies the Signature format. Type: Integer Default: None Valid Value: 2

Yes

SignatureMethod A value that specifies the signing method. Type: String Default: None Valid Values: HmacSHA256 (preferred) and HmacSHA1.

Yes

Timestamp A date-time value that marks the day and time the request was sent. Requests expire after a certain length of time to prevent malicious users from capturing requests and resubmitting them at a later time. Type: dateTime, for example, 2008-09-18T13:00:01Z Default: None

Yes

Version The version number of the WSDL to use Yes


74

Parameter Description Required in processing the request.Version numbers are dates, such as 2008-09-17. For a list of version numbers, go to the Amazon Resource Center at http://aws.amazon.com/resources. Type: String Default: None

http://aws.amazon.com/resources


75

Common Response Elements Each action in the API has its own set of response elements it uses. There are, however, a set of response elements that all actions use. The following table describes those common elements.

Element Description ResponseMetadata Container element. RequestId Amazon FPS returns a RequestId element for every API call

accepted for processing. The request ID is a reference to your API request that Amazon FPS can use to troubleshoot any issues related to the request.We recommend you store the request ID value for future reference. Because responses and requests can return asynchronously, you can use the request ID to sync responses with requests. Type: String Max Size: 64 Bytes

signatureVersion A value that specifies the Signature format. Type: Integer Valid Values: 2

signatureMethod A value that specifies the signing method. Type: String Valid Values: HmacSHA256 (preferred) and HmacSHA1.

Common Errors This section includes error response parameters and error codes.

Error Response Elements Unless otherwise noted, Amazon Simple Pay returns error information RESTfully as a xml document fragment within the TransactionStatus element. The following table details the elements involved in an error return.

Element Description Code One of the error codes described previously.

Type: String Message Human readable description of the error.

Type: String RequestId Unique identifier for this request. Please provide this to AWS support for

debugging purposes. Type: String


76

Errors Error Description AccessFailure Account cannot be accessed.

You can display the following message to your customers: Your account cannot be accessed. Retriable:Yes

AccountClosed Account is not active. You can display the following message to your customers: Your account is closed. Retriable:Yes

AmountOutOfRange The transaction amount is more than the allowed range. Ensure that you pass an amount within the allowed range. The transaction amount in a Pay operation using credit card or bank account must be greater than $0.01. Retriable: No

AuthFailure AWS was not able to validate the provided access credentials. Please make sure that your AWS developer account is signed up for FPS. Retriable:Yes

ConcurrentModification A retriable error can happen when two processes try to modify the same data at the same time. The developer should retry the request if this error is encountered. Retriable:Yes

DuplicateRequest A different request associated with this caller reference already exists. You have used the same caller reference in an earlier request. Ensure that you use unique caller references for every new request. Even if your earlier request resulted in an error, you should still use a unique caller reference with every request and avoid this error. Retriable: No

InsufficientBalance The sender, caller, or recipient’s account balance has insufficient funds to complete the transaction. You must ask your customers to fund their accounts. You can then retry this request. Funding an account can take up to three to four business days using a bank account transfer. This error is also displayed if the party paying the Amazon FPS fees does not have a sufficient account balance. Retriable:Yes

InternalError A retriable error that happens due to some transient problem in the system. The caller should retry the API call if this error is encountered. Retriable:Yes

InvalidAccountState The account is either suspended or closed. Payment


77

Error Description instructions cannot be installed on this account. You must ask your customer to set up a new account if the account is closed. Retriable:Yes

InvalidAccountState_Caller The developer account cannot participate in the transaction. Your account is not active. Contact your AWS Representative for more information. Retriable:Ye

InvalidAccountState_Recipient Recipient account cannot participate in the transaction. You can display the following message to your customer (sender): Your Amazon Payments account is not active. Please visit http://payments.amazon.com for more details. Retriable:Yes

InvalidAccountState_Sender Sender account cannot participate in the transaction. You can display the following message to your customer (sender): Your Amazon Payments account is not active. Please visit http://payments.amazon.com for more details. Retriable:Yes

InvalidClientTokenId The AWS Access Key Id you provided does not exist in our records. Please check that the AWS Access Key Id used to make the request is valid. Retriable: No

InvalidParams One or more parameters in the request is invalid. For more information, see the parameter descriptions for the action in the API Reference. Parameters are case sensitive. Retriable: No

InvalidSubscriptionID The supplied subscription ID is invalid. Please ensure that the subscription id passed in the input is correct and is owned by the calling account. Retriable: No

InvalidSubscriptionState This subscription is already canceled or completed. None Retriable: No

InvalidTokenId You did not install the token that you are trying to cancel. You do not have permission to cancel this token. You can cancel only the tokens that you own. Retriable: No

InvalidTransactionId The specified transaction could not be found or the caller did not execute the transaction or this is not a Pay or Reserve call. Specify the correct the transaction ID. Retriable: No

InvalidTransactionState The transaction is not complete, or it has temporarily failed. Specify a duration of more than one hour. Retriable: No




78

Error Description MissingRequiredParameter The request is missing a required parameter.

Check that you have specified all the parameters and values required by the action. Retriable: After you have provided the complete parameter set.

OriginalTransactionFailed The original transaction has failed. You cannot refund a transaction that has originally failed. Retriable: No

OriginalTransactionIncomplete The original transaction is still in progress. Retry after the original transaction has completed. Retriable:Yes

RefundAmountExceeded The refund amount is more than the refundable amount. You are not allowed to refund more than the original transaction amount. Retriable: No

RefundDenied The refund was denied. There are no successful transactions associated with this subscription that can be canceled. Please wait for a successful payment to be made for this transaction. Retriable:Yes

SettleAmountGreaterThanDebt The amount being settled or written off is greater than the current debt. You cannot settle an amount greater than what is owed. Retriable: No

SignatureDoesNotMatch The request signature calculated by Amazon does not match the signature you provided. Check your AWS Secret Access Key and signing method. For more information, see "Working with Signatures.” Retriable: No

SystemError There was a system error. The transaction did not complete. Retriable:Yes

TransactionDenied This transaction is not allowed. You are not allowed to do this transaction. Check your credentials. Retriable: No

TransactionFullyRefunded Already

This transaction has already been completely refunded. You are not allowed to refund more than the original transaction amount. Retriable: No

TransactionTypeNotRefundable You cannot refund this transaction. Refund is allowed only on the Pay operation. Retriable: No

UnverifiedAccount_Recipient The recipient's account must have a verified bank account or a credit card before this transaction can be initiated. You can display the following message to your customer (recipient): Your Amazon Payments account is not active.


79

Error Description Please visit http://payments.amazon.com for more details. Retriable: No

UnverifiedEmailAddress_Caller The caller account must have a verified email address. You cannot make a web service API call without verifying your email address. Go to http://payments.amazon.com web site and make payments. Retriable: No

UnverifiedEmailAddress_ Recipient

The recipient account must have a verified email address for receiving payments. You can display the following message to your customers: You cannot receive payments. Please verify your email address. Go to http://payments.amazon.com to verify your account and receive payments. Retriable: No

UnverifiedEmailAddress_Sender The sender account must have a verified email address for this payment You can display the following message to your customers: You cannot make payments. Please verify your email address. Go to http://payments.amazon.com to verify your account and make payments. Retriable: No






80

Data Types This section describes the data types common to the Amazon Simple Pay actions.

Amount Data Types Name Description CurrencyCode The currency code of the amount. Amazon FPS currently supports only

USD. Type: String Valid Values: USD

Value The transaction amount. Type: String

SubscriptionDetails Type Name Description Type SubscriptionId The ID of the subscription String Description The description provided when the subscription

was created. String

Subscription Amount

The monetary cost of the subscription Amount

NextTransaction Amount

The next value to be charged to the subscription

Amount

Promotional The amount for the promotion Amount

Amount

NumberOfPromo tionalTransactions

How many free editions Integer

StartDate When the subscription begins Date EndDate When the subscription ends Date Subscription Period How long does the subscription last

Duration

Subscription Frequency

How often does the subscription happen Duration

OverrideIPNUrl Custom IPN target String SubscriptionStatus The status of the subscription SubscriptionStatus

Type NumberOfTrans actionsProcessed

The number of transactions have already passed

Integer

RecipientEmail Email contact for the subscriber String RecipientName Name of the subscriber String SenderEmail Email contact for the subscription buyer String SenderName Name of the subscription buyer String


81

NextTransactionDate When will the next value be charged to the subscription

Date

SubscriptionStatus Type Name Description Type Active The subscription is active. String Cancelled The subscription was cancelled. String Cancelled The subscription was cancelled. String

SubscriptionTransaction Type Name Description Type TransactionId The ID of the transaction String TransactionDate When the transaction occurred Date Transaction SerialNumber

Serial number for the transaction. Integer

Transaction Amount

The monetary cost of the transaction Amount

Description The description provided when the subscription was created.

String

Transaction Status

The final status of the transaction TransactionStatus

MarketplaceRefundPolicy Data Types Name Description MarketplaceTxnOnly Caller refunds his fee to the recipient.

Type: String MasterAndMarketplaceTxn Caller and Amazon FPS refund their fees to the sender, and the

recipient refunds his amount Type: String

MasterTxnOnly Caller does not refund his fee. Amazon FPS refunds its fee and the recipient refunds his amount plus the caller's fee to the sender. Type: String


82

API TransactionStatus Data Types Name Description Type Cancelled The transaction was canceled. String Failure The transaction failed.The API operation failed

and Amazon FPS did not receive String or record a transaction. You can retry the transaction only if a retriable error was returned.

String

Pending The transaction is pending. String Reserved The reserve request on the transaction

succeeded. Amazon FPS reserves the String purchase price against the sender's payment instrument.

String

Success The transaction succeeded. You can fulfill the order for the customer.

String


83


This appendix provides an overview of the sample code for several key tasks you need to accomplish for Amazon Simple Pay. Updated for signature version 2, they include a button generator for each button, as well as samples to validate and process return URLs and IPN notifications.

Packaged in five programming languages (C#, Java, Perl, PHP, and Ruby), they are available from the Amazon Web Services developer community, under the Amazon Flexible Payments Service category.

Understanding the Amazon Simple Pay Button Samples Amazon provides four sample-specific buttons in five programming languages which show you how to create a specific button programmatically. In this section, we will briefly go over the essential details for the standard button, Java version only. The other samples differ only in the parameters that comprise them, and the programming language used for rendering them. For specific comprehensive information on a particular sample, see that sample’s ButtonGenerationWithSignature/README.html file.

For information on which parameters are specific to which buttons, please see “Amazon Simple Pay Button Input Reference.”

When you download a sample file, such as ASPStandard-JAVA-2.0, it contains three separate samples. This section describes the sample contained in the ButtonGenerationWithSignature folder.

Each button generator sample contains three primary components in the ASPStandard-JAVA-2.0/ButtonGenerationWithSignature/src folder. For the standard button, these are:

Class Description StandardButtonSample.java This class contains the program entry point. It sets up initial

parameter values for the standard button, and then calls the static method ButtonGenerator.GenerateForm with those values. You set the static parameter environment to either sandbox or prod, depending on which target you are building the button for.

ButtonGenerator.java Invoked from StandardButton.java, this class generates the HTML form, by assembling the parameter values provided to the GenerateForm method. It adds other parameters required by the form, such as signatureMethod and signingVersion. In addition, it obtains a well-formed signature version 2 signature from the

http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=191


84

Class Description SignatureUtils.java class.

SignatureUtils.java Invoked from ButtonGenerator.java, this class uses the signature version 2 process to create the string to sign and calculate the button-specific signature. It contains static methods to compile the string to sign, URL encode the string, and sign it.

In addition to these primary components, a sample may include other required resources. For example, the Java samples all include the lib/commons-codec/jars/commons-codec-1.3.jar file, which must be in your classpath in order to compile the sample.

Using the Standard Button Generator Sample

1. Set up your programming environment so that the program compiles without warnings or errors. For the Java sample, this includes ensuring that the ASPStandard-JAVA-2.0/ButtonGenerationWithSignature/src folder and the lib/commons-codec/jars/commons-codec-1.3.jar file are available to the compiler, either by including them as a command line option, or, if you build using an IDE, by including them as project resources.

2. The StandardButtonSample class declares public static variables which correspond to the fields required by the Amazon Simple Pay button. Modify these values to suit the button you want to build. These are the fields most likely to change if you are creating a number of buttons using the sample. Set the StandardButtonSample.environment variable to sandbox now. After you have debugged your button, you can set it to prod in step 6, below.

Note These are the minimal values you need to change. If you want to change the signature method, the cobranding style, or the button image, you can change the appropriate static variables in the ButtonGenerator class.

3. Compile the sample. For example, if you are including the lib/commons-codec/jars/commons-codec-1.3.jar as using the linux command line, you would type:

$javac -cp .:lib/commons-codec/jars/commons-codec-1.3.jar StandardButtonSample.java SignatureUtils.java StandardButtonSample.java

On Windows, you would type:

$javac -cp .;lib/commons-codec/jars/commons-codec-1.3.jar StandardButtonSample.java SignatureUtils.java StandardButtonSample.java

4. Run the sample. Continuing the previous example, on linux, you would type:

$javac -cp .:lib/commons-codec/jars/commons-codec-1.3.jar


85

StandardButtonSample

On Windows, you would type

$javac -cp .;lib/commons-codec/jars/commons-codec-1.3.jar StandardButtonSample

The complete signed button is printed to standard out. 5. When you are satisfied with the way the button works, you can change the

StandardButtonSample.environment variable to prod, and rebuild a button ready for your production environment.

Understanding the IPNAndReturnURLValidation Sample Amazon provides samples in four programming languages which show you how to perform a server-side verification of the signatures in both the return URL and in IPN notifications. In this section, we will briefly go over the essential details of the standard button, Java version only. The other samples differ only in the programming language used for rendering them. For specific comprehensive information on a particular sample, see the sample’s IPNAndReturnURLValidation/README.html file.

When you download a sample file, such as ASPStandard-JAVA-2.0, it contains three separate samples. This section describes the sample contained in the IPNAndReturnURLValidation folder, which is used for server-side signature verification.

This section describes the IPNAndReturnURLValidation sample, which is used for server-side signature verification.

Each IPNAndReturnURLValidation sample contains three primary components in the ASPStandard-JAVA-2.0/IPNAndReturnURLValidation/src folder. These are:

File Description ReturnUrlVerificationSampleCode.java This class contains the program entry point for

verifying the signature contained in a return URL, and thereby validating the return URL content. It sets up initial parameter values for standard button return URL responses, and then calls the static method SignatureUtilsForOutbound.validateRequest with those values.

IPNVerificationSampleCode.java This class contains the program entry point for verifying the signature contained in an IPN notification. It sets up initial parameter values for standard button IPN notifications, and then calls the static method


86

File Description SignatureUtilsForOutbound.validateRequest with those values.

SignatureUtilsForOutbound.java Invoked from ReturnUrlVerificationSampleCode.java and IPNVerificationSampleCode.java, this class uses the signature version 2 process to validate the signature. It contains methods to reassemble the string to sign, URL encode the string, and sign it using the Amazon certificate listed as the signer. Finally, it validates the signature and prints the result to standard out.

In addition to these primary components, a sample may include other required resources. For example, the Java samples all include the lib/commons-codec-1.3.jar file, which must be in your classpath in order to compile the sample.

To use the sample, do the following

Using the Standard Button IPNAndReturnURLValidation Sample

1. Set up your programming environment so that the program will compile without warnings or errors. For the Java sample, this includes ensuring that the ASPStandard-JAVA-2.0/IPNAndReturnURLValidation/src folder and the lib/commons-codec-1.3.jar files are available to the compiler, either by including them as command line parameters, or, if you build using an IDE, by including them as project resources.

2. The ReturnUrlVerificationSampleCode and IPNVerificationSampleCode classes use a HashMap to store parameters which correspond to the fields returned during a return URL response or an IPN notification. Modify these values to suit the response you want to validate. These are the only values you need to change using this sample.

3. Compile the sample. For example, if you are including the [package-root]lib/commons-codec/jars/commons-codec-1.3.jar using the linux command line, you would type

$javac -cp .:[package-root] /lib/commons-codec-1.3.jar ReturnUrlVerificationSampleCode.java SignatureUtilsForOutbound.java


$javac -cp .;[package-root]lib/commons-codec-1.3.jar ReturnUrlVerificationSampleCode.java SignatureUtilsForOutbound.java

4. Run the sample. Continuing the previous example, on linux, you would type

$javac -cp .:[package-root] lib/commons-codec-1.3.jar ReturnUrlVerificationSampleCode


87


$javac -cp .;[package-root] lib/commons-codec-1.3.jar ReturnUrlVerificationSampleCode

The result "Is signature correct: true" is printed to standard out if the verification determines the signature to be valid.

Understanding the VerifySignature Sample Amazon provides five samples in five programming languages in the Amazon Simple Pay SDK which show you how to invoke the Amazon FPS actions available with Amazon Simple Pay.

When you download a language-specific SDK, such as ASP-JAVA-2.0, it contains the following five separate samples (in the FPSApis\src\com\amazonaws\fps\samples folder) showing how to invoke an FPS API.

Class Description CancelSample.java This class contains the program entry point for

invoking a Cancel request. GetTransactionStatusSample.java This class contains the program entry point for

invoking a GetTransactionStatus request. RefundSample.java This class contains the program entry point for

invoking a Refund request. SettleSample.java This class contains the program entry point for

invoking a Settle request. VerifySignatureSample.java This class contains the program entry point for

invoking a VerifySignature request.

These samples depend on the classes in com.amazonaws.fps.model, com.amazonaws.fps.mock, and com.amazonaws.utils which are provided in the FPSApis/src folder. These must be in your project classpath.

In addition to these primary components, a sample may include other required resources. For example, the Java samples all include numerous jar files in the FPSApis/src/third-party folder, which must be in your classpath in order to compile the sample.

This section explains how to use the VerifySignature API only. For specific comprehensive information on a particular language-specific sample, see the sample’s FPSApis/README.html file.

Using the VerifySignature Action Sample 1. Set up your programming environment so that the program will compile without warnings

or errors.


88

For the Java sample, this includes ensuring that the required folders and .jar files are in the in the java CLASSPATH environment variable. If you plan to invoke javac from within the com\amazonaws\fps\samples folder, you will need to include the following as the -cp argument: .;..\model; ..\mock; ..\..\utils; ..\..\fps; ..\..\..\..\..\src; ..\..\..\..\..\third-party\commons-codec-1.3\commons-codec-1.3.jar; ..\..\..\..\..\third-party\commons-httpclient-3.0.1\commons-httpclient-3.0.1.jar; ..\..\..\..\..\third-party\commons-logging-1.1\commons-logging-1.1.jar

2. In the FPSApis/src/config.properties file, set the values for AwsAccessKey and AwsSecretKey using your security credentials. To get your credentials, see “Using Access Identifiers.” In the same file, if you want to target the sandbox, change the AwsServiceEndPoint property to https://payments-sandbox.amazon.com.

3. In the FPSApis/src/com/amazonaws/fps/samples/VerifySignature.java file, find the section containing the lines:

VerifySignatureRequest fpsRequest = new VerifySignatureRequest(); // @TODO: set request parameters here // invokeVerifySignature(service, fpsRequest);

(The VerifySignatureRequest, VerifySignatureResult, and VerifySignatureResponse classes are located in FPSApis/src/com/amazonaws/fps/model folder.)

4. Remove the comment on invokeVerifySignature, and add the VerifySignature parameter assignments. For example:

fpsRequest.setUrlEndpoint("http://myApplication/my-ipn-response.pgp"); fpsRequest.setHttpParameters("Name1=Value1&" +"Name2=Value2&" + "signatureVersion=2&" + "signatureMethod=HMACSHA256&" + "certificateUrl=https://fps.amazonaws.com/cert/key.pem&" + "signature=aoeuAOE123eAUdhf]"); invokeVerifySignature(service, fpsRequest);

For information on the parameters to VerifySignature, see “VerifySignature.” 5. Compile the sample. For example, from the linux command line, you would type

$javac VerifySignatureSample.java


$javac VerifySignatureSample.java

6. Run the sample. Continuing the previous example, on linux, you would type

$javac VerifySignatureSample


$javac VerifySignatureSample



89

The program copies to standard out a representation of the VerifySigatureResponse XML fragment similar to the following:

VerifySignature Action Response ======================================= VerifySignatureResponse VerifySignatureResult True VerificationStatus Success ResponseMetadata RequestId bda6-4f5f-b37b-1a146b9a-b9e45c3012a5:0

In addition to simple invocation, the samples provide you the following advanced options:

• The ability to simulate a mock Amazon FPS service, to get responses without a live connection.

• Specifying a proxy host and port, through config.properties. • Setting the endpoint, through config.properties • Logging, through log4j.properties


90

Adding Amazon as an Additional Payment Option This example shows a way to implement a script that forces the submission of the form during the document.body.onload event.

<html> <head></head>  <body onload="document.getElementByName('TheForm').submit()">   <form name="TheForm" action=https://authorize.payments.amazon.com/pba/paypipeline method="post"> <input type="hidden" name="abandonUrl" value="http://www.merchantweb site.com/cancel.htm"/> <input type="hidden" name="accessKey" value="AKIAIOSFODNN7EXAMPLE"/> <input type="hidden" name="amount" value="USD 199.00"/> <input type="hidden" name="description" value="Sale of iPod"/> <input type="hidden" name="immediateReturn" value="TRUE"/> <input type="hidden" name="referenceId" value="ip123"/> <input type="hidden" name="returnUrl" value="http://www.merchantweb site.com/return.htm"/> <input type="hidden" name="SignatureMethod" value="HmacSHA256"/> <input type="hidden" name="SignatureVersion" value="2"/> <input type="hidden" name="signature" value="<userinput>[insert the signature you created here]</userinput>"/> <input type="hidden" name="ipnUrl"


91

value=http://www.merchantwebsite.com/instantpaymentnotification/> <input type="hidden" name="processImmediate" value="FALSE"/> </form>

Getting the Samples The code samples are available in five programming languages (C#, Java, Perl, PHP, and Ruby).

To download Amazon Simple Pay samples:

1. Go to Amazon Web Services developer community. 2. Choose your sample of interest in the programming language you prefer. To obtain the

sample applications listed in this guide, look for sample applications whose package name resembles the format "ASPButton name-LANGUAGE-2.0.” For example, the Java sample for the standard button is available in the file ASPStandard-JAVA-2.0.zip.

3. Read the instructions on the page. When you are ready to proceed, click Download. The download window opens. Ensure it is the sample you want, and Click OK.

4. Extract the zipped files to a convenient location on your workstation.

Each download includes sample-specific instructions in its README.txt file. For general guidance on the samples applicable to this edition of Amazon Simple Pay, see “Appendix: Sample Code.”

http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=191

Appendix: Return Values

92


After customers authorize payment, Amazon Payments redirects them to the Return or User Abandon URL that you specified.

http://yourwebsite.com/return.php? transactionId=123456789123456678 &status=PS&[email protected]

Amazon Payments also appends to the URL additional parameters and values related to the transaction. The following tables show those additional parameters. If a parameter is not related to the transaction, Amazon Payments does not include it in the URL.

API Return Values Parameter Description addressLine1 The name of the buyer. This parameter is returned in case the

collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

addressLine2 The line 2 of the address of the buyer. This parameter is returned in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

addressName The name of the buyer. This parameter is returned in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

buyerEmail The email address of the buyer. Type: String

buyerName The name of the buyer. Type: String

city The city of the address of the buyer. This parameter is returned in case the collectShippingAddress parameter was passed as true in the HTML form.

mailto:&status=PS&[email protected]


93

Parameter Description Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

country The country of the address of the buyer. This parameter is returned in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

errorMessage A human-readable string returned for the ME status. (see the description for ME in the “Return URL Status Codes” table). Type: String

operation The payment operation for this transaction. Can take values reserve and pay. Type: String Valid values: pay, reserve

paymentMethod The payment method used by the buyer. Type: String

paymentReason The payment reason as specified in the user interface. Type: String

phoneNumber The phoneNumber of the buyer. This parameter is returned in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

recipientEmail The email address of the seller. Type: String

recipientName The name of payment recipient (the seller). Type: String

referenceId If you specified a referenceId in the button, Amazon Payments returns the referenceId to you. Type: String

signature Amazon Payments calculates the signature using all the parameters in the returnUrl.We recommend that you calculate the return URL's signature using the same method that you used to calculate the signature while customizing the standard button. This is to be sure that you are receiving the response from Amazon Payments. The signature is only returned when the request is signed using the seller or developer's access key. If the seller or developer chooses to use unsigned standard buttons, this parameter is not provided. Type: String

state The state of the address of the buyer. This parameter is


94

Parameter Description returned in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

status The status of the transaction. See “Return URL Status Codes” for possible values for this field. Type: String Valid values:

transactionAmount The amount of this transaction, for example, USD 10.00. Type: String

transactionDate The date when this transaction occurred, specified in seconds since January 1, 1970. Type: String

transactionId Type: String zip The zip of the address of the buyer. This parameter is returned

in case the collectShippingAddress parameter was passed as true in the HTML form. Type: String Constraint: All address-related parameters associated with collectshippingaddress except addressLine2, must have values, or else none of the parameters apply.

Additional Return Values for Marketplace Fee Requests Parameter Description recipientEmail The email address of the recipient

Type: String refundTokenID Refund tokenID for the recipient. This value is not used with

Amazon Simple Pay Type: String

tokenID The tokenID for the recipient. This value is not used with Amazon Simple Pay Type: String


95

Additional Return Values for Subscription Requests Parameter Description noOfPromotionTransactions Number of payment periods where the promotional discount is

applied to a subscription. For example, if the subscription payment frequency is monthly and the promotional discount is for the first two months, the value of noOfPromotionTransactions is 2, i.e., two promotional discount transactions before the regular subscription price is charged. Type: Integer

promotionAmount Discount off the regular subscription price. Type: Integer

recurringFrequency Subscription payment frequency, such as monthly or annual. Type: String

subscriptionId A string that uniquely identifies a subscription. Type: String

subscriptionPeriod The duration of the subscription. Type: String

subscriptionReason A string that describes the subscription. Type: String

transactionSerialNumber A string that uniquely identifies the transaction that purchased the subscription. Type: String

Return URL Status Codes The following table describes the status codes you can receive through the Return URL.

Code Description A The pipeline was abandoned. ME Merchant error. Either the button parameter names are invalid, or there is a shipping

address error from the co-branded user interface. PS The payment transaction was successful. PF The payment or reserve transaction failed and the money was not transferred. If the

account is not suspended, you can redirect your customer to the Amazon Payments Payment Authorization page to select a different payment method.

PI Payment has been initiated. It will take between five seconds and 48 hours to complete, based on the availability of external payment networks and the riskiness of the transaction.

PR The reserve transaction was successful. RS The refund transaction was successful. RF The refund transaction failed.


96

Code Description SE A service error has occurred. SF The subscription failed. SI The subscription has initiated. SR The marketplace fee transaction was accepted by the recipient. SS The subscription was completed. UE User error for donations. The donation amount was less than the minimum donation

amount. UF Subscription update failed. The subscriber has failed to update the subscription

payment method. US Subscription update was successful. The subscriber succeeded updating the

subscription payment method.

Appendix: IPN Response Elements for Transactions

97


The details in the notification describe the payment information and the sender information for the transaction. The tables in the following sections show the values included in the payment information, which vary depending on the exact nature of the transaction.

The following IPN response elements are returned for standard and donation transactions, and for any other transaction that generates IPNs and is not specifically covered here.

Common IPN Response Elements These IPN response elements are common to most types of transactions. For a list of IPN response elements for subscription transactions, see “IPN Response Elements” for Subscription. For a list of IPN response elements for marketplace transactions, see “IPN Responses for Marketplace Transactions.”

Name Description addressFullName Full name of the buyer/sender.

Type: String addressLine1 Sender's address (first line). For IPN, this element is returned only

if the value has been updated with Amazon. Type: String

addressLine2 Sender's address (second line). For IPN, this element is returned only if the value has been updated with Amazon. Type: String

addressState Sender's state. For IPN, this element is returned only if the value has been updated with Amazon. Type: String

addressZip Sender's post code. For IPN, this element is returned only if the value has been updated with Amazon. Type: String

addressCountry Sender's country. For IPN, this element is returned only if the value has been updated with Amazon. Type: String

addressPhone Sender's phone number. For IPN, this element is returned only if the value has been updated with Amazon. Type: String

buyerEmail Sender's email address. Note The buyerEmail element is not returned when the


98

Name Description recipient is not the caller (i.e., marketplace transactions). Type: String Size: 65 bytes

buyerName Sender's name. Type: String Size: 128 bytes

certificateUrl A url specifying the location of the certificate used for signing the response. Type: String Max Size: 1024 bytes

customerEmail Customer's email address. Type: String Size: 65 bytes

customerName Buyer/Sender Full Name. Type: String Size: 128 bytes

dateInstalled If the notificationType element (below) is TokenCancellation, this element contains the date the token was installed. Type: String Size: 30 bytes

isShippingAddressProvided If the IPN results include address updates, this element contains TRUE. Otherwise this element is not present in the response. Type: String

operation The name of the payment action, also called an operation, used for this transaction. Type: String Max Size: 20 bytes

notificationType Notification type may be either TokenCancellation or TransactionStatus Type: String Size: 20 bytes

paymentMethod The payment method used by the sender. Type: String Size: 20 bytes

paymentReason Reason for payment. Type: String

recipientEmail Recipient's email address. Note As a security precaution, you should always check that the recipient email is the same as the one in your original request. Type: String Size: 65 bytes

recipientName Recipient's name. Type: String Size: 128 bytes

referenceId If you specified a referenceId in the button creation form, Amazon Payments returns the referenceId to you.


99

Name Description Type: String

signature The encoded string the caller uses to verify the IPN. Amazon Payments calculates the signature using the elements in the returnURL. The merchant must have manually signed the request.. Type: String Size: 512 bytes

signatureVersion A value that specifies the Signature format. Type: Integer Valid Values: 2

signatureMethod A value that specifies the signing method. Type: String Valid Values: HmacSHA256 (preferred) and HmacSHA1.

tokenId If notificationType is TokenCancellation, this element contains the ID of the cancelled token. Type: String Size: 65 bytes

tokenType If notificationType is TokenCancellation, this element contains the type of the canceled token. Type: String Size: 20 bytes

transactionAmount Specifies the amount payable in this transaction; for example, USD 10.00. Type: String Size: 30 bytes

transactionDate The date when this transaction occurred, specified in seconds Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String Size: 35 bytessince the start of the epoch. Type: Long Size: 40 bytes

transactionId Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String Size: 35 bytes

transactionStatus Specifies the status of the transaction. Type: String


100

IPN Response Elements for Subscriptions The following IPN response elements are returned for successful creation of subscriptions.

Name Description addressLine1 Sender's address (first line). This element is returned only if the

collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

addressLine2 Sender's address (second line).This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

addressName Sender's name. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

buyerEmail Sender's email address. Note The buyerEmail element is not returned for transactions where the recipient is not the caller (i.e., marketplace transactions). Type: String

buyerName Sender's name. Type: String

City Sender's address - city. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

Country Sender's address - country. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

noOfPromotionTransactions Number of transactions for this promotion. This element is only returned if there was a trial period with a special promotional rate. Type: Integer

paymentMethod The payment method used by the sender. Type: String


phoneNumber Sender's telephone number. This element is returned only if the collectShippingAddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

promotionAmount Amount charged for this promotion. This element is only returned if there was a trial period with a special promotional rate. Type: String


101

Name Description recipientEmail Recipient's email address.

Type: String recipientName Recipient's name.

Type: String recurringFrequency Tells how often the subscription fee will be charged.

Type: String referenceId If you specified a referenceId in the button creation form,

Amazon Payments returns the referenceId to you. Type: String

Signature The encoded string the caller uses to verify the IPN. Amazon Payments calculates the signature using the elements in the returnURL. The merchant must have manually signed the request. For more information, see “Handling the Receipt of IPN Notifications.”We recommend that you always verify the signature using the method in How to Verify the IPN Signature. Type: String

startValidityDate Date the subscription begins. This is expressed as the timestamp value from the epoch in seconds. Type: String

State Sender's address - state. This element is returned only if the collectshippingaddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

Status For a successful creation, the status code returned is SubscriptionSuccessful. Type: String

subscriptionId A unique value identifying the subscription that is generated by Amazon Payments. Type: String

subsciptionPeriod Total time period to charge for the subscription. Type: String

transactionAmount Specifies the amount payable in this transaction; for example, USD 10.00. This element is not being returned in the current version. Type: String

transactionSerialNumber For Subscriptions, a unique value identifying the subscription that is generated by Amazon Payments. This element is returned only for subscription transactions. Type: Integer

zip Sender's zip code. This element is returned only if the collectshippingaddress parameter was passed as true in the Amazon Simple Pay HTML form. Type: String

The following IPN elements are returned for successful completion of subscriptions.


102

Name Description subscriptionId A unique value identifying the subscription that is generated by

Amazon Payments. Type: String

Status For a successful cancellation, the status code sent is SubscriptionCanceled. Type: String

statusReason Reason for this status. Type: String

The following IPN elements are returned for successful completion of subscriptions.

Name Description subscriptionId A unique value identifying the subscription that is generated by

Amazon Payments. Type: String

status For a successful completion, the status code sent is SubscriptionCompleted. Type: String

IPN Responses for Marketplace Transactions The following IPN response elements are returned only for marketplace transactions.

IPN Marketplace Transaction Elements

Name Description buyerName Sender's name.

Type: String Operation The name of the payment action, also called an operation, used

for this transaction. Type: String Max Size: 20 bytes

paymentMethod The payment method used by the sender. Type: String


recipientEmail Recipient's email address. Type: String

recipientName Recipient's name. Type: String


103

Name Description referenceId If you specified a referenceId in the button creation form,

Amazon Payments returns the referenceId to you. Type: String

Signature The encoded string the caller uses to verify the IPN. Amazon Payments calculates the signature using the elements in the returnURL.The merchant must have manually signed the request. For more information, see “Handling the Receipt of IPN Notifications.”We recommend that you always verify the signature using the method in How to Verify the IPN Signature. Type: String

Status Specifies the status of the transaction. Type: String

transactionAmount Specifies the amount payable in this transaction; for example, USD 10.00. This element is not being returned in the current version. Type: Double

transactionDate The date when this transaction occurred, specified in seconds since the beginning of the epoch. Type: Long

transactionId Unique ID generated by Amazon FPS for this transaction. This element is returned if the transaction was accepted by Amazon FPS. Type: String

IPN Status Codes The following table describes the status codes you can receive through Instant Payment Notification.

Status Code Description PS The payment transaction was successful. PF The payment transaction failed and the money was not

transferred. You can redirect your customer to the Amazon Payments Payment Authorization page to select a different payment method.

PI Payment has been initiated. It will take between five seconds and 48 hours to complete, based on the availability of external payment networks and the riskiness of the transaction.

PR The reserve transaction was successful. RS The refund transaction was successful. RF The refund transaction failed. PaymentSuccess Amazon collected a subscription payment. PendingUserAction Amazon tried to collect a payment which failed due to a

payment method error. The subscriber has been advised to adjust the method. Amazon will retry the payment after 6 days.


104

Status Code Description PaymentRescheduled Amazon tried to collect a payment which failed due to an error

not involving a payment method. Amazon will retry the payment after 6 days.

PaymentCancelled Amazon has failed to collect a payment, and will not make any more attempts. Other subscription payments will be attempted on schedule.

SubscriptionCancelled The subscription was canceled successfully. Amazon will make no further attempts to collect payment against the subscription.

SubscriptionCompleted The subscription was completed. All payments have been collected.

SubscriptionSuccessful The subscription was created successfully.

Amazon Simple Pay Related Resources

105

Amazon Simple Pay Related Resources

The table below lists related resources that you'll find useful as you work with this service.

Resource Description Amazon Simple Pay Getting Started Guide

The Getting Started Guide provides an explanation of how to use the basic features of Amazon Simple Pay for each button type.

Amazon Simple Pay FAQs Frequently-asked questions about using Amazon Simple Pay on your website.

Amazon Simple Pay Release Notes

The release notes give a high-level overview of the current release. They specifically note any new features, corrections, and known issues.

Amazon Simple Pay and FPS Discussion Forum

A community-based forum for developers to discuss technical questions related to Amazon Simple Pay and FPS.

Product information about Amazon Simple Pay

The primary web page for information about Amazon Simple Pay.

For questions related to your AWS account: Contact Us

This is only for account questions. For technical questions, use the Discussion Forums.

Conditions of Use Detailed information about the copyright and trademark usage at Amazon.com.



https://payments.amazon.com/sdui/sdui/about?nodeId=30017

http://developer.amazonwebservices.com/connect/entry.jspa?externalID=2436&categoryID=124

http://developer.amazonwebservices.com/connect/entry.jspa?externalID=2436&categoryID=124

http://developer.amazonwebservices.com/connect/forum.jspa?forumID=35

http://developer.amazonwebservices.com/connect/forum.jspa?forumID=35

https://payments.amazon.com/help/Amazon-Simple-Pay

https://payments.amazon.com/help/Amazon-Simple-Pay

http://aws.amazon.com/contact-us/

http://aws.amazon.com/contact-us/

http://www.amazon.com/gp/help/customer/display.html/104-5054883-7838319?ie=UTF8&%2AVersion%2A=1&nodeId=508088&%2Aentries%2A=0

Glossary

106

Glossary

access key rotation To enhance the security of your application, you can make use of

more than one set of security credentials, with an older set continuing to be active as you distribute a new set.

AWS Access Key ID A string distributed by AWS that uniquely identifies an AWS developer. The value of this ID is included in every Amazon Simple Pay request.

buyer Individual who sends a payment using an Amazon Simple Pay button. The buyer pays the seller for a product or service.

HMAC Hash Message Authentication Code. Amazon Simple Pay uses an HMAC for signatures to enhance the security of your buttons.

HTML Form A block of HTML code that contains the endpoint and parameters for an Amazon Simple Pay request.

inbound request Button click or other form request to Amazon Payments Instant Payment Notification Also IPN. A notification (separate from the buyer redirect) that is

sent whenever a payment, refund, or reserved payment completes successfully or fails. The developer must host this notification service and provide Amazon Simple Pay with an IPN response URL.

marketplace A feature of Amazon Simple Pay that allows a third party to charge for hosting a merchant's offers and facilitating payment.

outbound notifications Response from Amazon Payments to your Simple Pay application by way of Return URL or IPN.

payment method failure An error caused by an irregularity in the customer's chosen payment method, such as an insufficient bank balance, or an expired credit card.

reserve The purchase price that is put in reserve against a credit card but not charged. The transaction is settled typically when a purchase is finished, such as when a product ships.

seller Individual who receives a payment from a buyer using an Amazon Simple Pay button. The seller receives money from a buyer in exchange for a service or product.

RSA-SHA1 Amazon Simple Pay uses RSA-SHA1 as the signature method for outbound notifications.

settle The act of delaying the completion of a transaction. If a buyer is not charged immediately upon the initiation of the purchase, the transaction is settled later, such as when the purchased product is shipped. Amazon Simple Pay does not support settling purchases. You have to use the Settle operation in the Amazon

Glossary

107

Simple Pay API to implement that functionality. server-side signature verification

With Amazon Simple Pay, you can use server-side verification to validate IPN and Return URL responses with the FPS Action, VerifySignature.

SHA1, SHA256 Secure Hash Algorithms used for Amazon Web Services signatures. SHA1 is an earlier version of the algorithm, which is currently being deprecated for Amazon Web Services. SHA256 is its more secure replacement.

signature A URL encoded string composed of request parameters and their values encrypted using an HMAC algorithm. Signatures are used to authenticate and safeguard requests

Amazon Simple Pay Subscription

A button that enables you to collect periodic payments for your products.

website owner A developer who creates any Amazon Simple Pay button.

Document History

108

Document History

This documentation is associated with the 2010-08-28 release of Amazon Simple Pay. This guide was last updated on 10-March-2013.

The following table describes the important changes since the last release of the Amazon Simple Pay documentation.

Change Description Date New Feature Amazon Simple Pay now provides the

GetSubscriptionDetails and GetTransactionsForSubscription action. For more information, see “GetSubscriptionDetails” and “GetTransactionsForSubscription.” This release also incorporates a new WSDL version, 2010-08-28.

In this Release

Feature Rollback

Amazon FPS has discontinued support for signature verification using signature version 1. The feature is completely deprecated as of 10 February 2011. If your application is using this feature, you must convert to a server-side call with the VerifySignature action. For more information, see “Verifying the ReturnURL and IPN Notifications.”

2011-02-10

Feature Rollback

Amazon FPS has discontinued support for client-side signature verification using PKI. The feature is completely deprecated as of 10 February 2011. If your application is using this feature, you must convert to a server-side call with the “VerifySignature” action. For more information, see “Verifying the ReturnURL and IPN Notifications.”

2010-09-14

Enhancement Minor changes and typographical fixes applied from a maintenance edit.

2010-06-11

Enhancement Examples of the e-mail messages sent by Amazon Payments which are relevant to Amazon Simple Pay are now included as part of this guide. Please see “Email Notification Templates.”

2010-01-29

New Feature Amazon Simple Pay now supports signature version 2, which will completely replace signature version 1 on 10 February, 2011. The enhanced security features include: A more secure way of calculating signatures for inbound requests and outbound notifications.

2009-11-03

Document History

109

Change Description Date For more information, see “How to Generate a Signature.” Support for SHA256 signing algorithm The new VerifySignature FPS Action for server-side testing of return URL responses and IPN notifications. For more information, see “VerifySignature.” (Deprecated as of 2010-09-14, see above) Support for PKI based authentication for client-side testing of return URL responses and IPN notification.

Enhancement The Access Keys page has been renamed the Security Credentials page, located at https://aws.amazon.com/security-credentials.

2009-09-09

Correction Editorial Updates 2009-09-02 Clarification Rules for subscription cancellation due to

payment problems 2009-07-25 have been clarified. Please see “What Happens When Subscription Payments Fail.”

2009-07-25

Document Update

AWS Developer Resource and Support Centers have been removed.

2013-09-12

Editorial Update Added language to clarify that 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 and Windows operating systems).

2013-10-18

Correction CancelSuccessRefundFailed, added another possible error code for this API call: RefundDenied.

2014-02-21

https://aws.amazon.com/security-credentials

Documents

ASP Advanced Users Guide...Amazon Simple Pay Getting Started Guide details the processes and procedures involved to make use of Amazon Simple Pay's standard features without needing