ASP Advanced Users Guide

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

Amazon Simple Pay Advanced Users Guide 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.

i

Amazon Simple Pay Advanced Users Guide

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 ii

Amazon Simple Pay Advanced Users Guide 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 iii

Amazon Simple Pay Advanced Users Guide 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 Request Parameters.......................................................................................................54 iv

Amazon Simple Pay Advanced Users Guide Response Elements .......................................................................................................55 Errors .............................................................................................................................55 Examples .......................................................................................................................55 Sample REST Request ..................................................................................................55 Sample Response to REST Request ..............................................................................56 Sample IPN Success Notification to Rest Request .........................................................56 GetSubscriptionDetails.......................................................................................................57 Description .....................................................................................................................57 Request Parameters.......................................................................................................57 Response Elements .......................................................................................................57 Errors .............................................................................................................................57 Examples .......................................................................................................................57 Sample REST Request ..................................................................................................57 Sample Response to REST Request..............................................................................58 GetTransactionsForSubscription ........................................................................................59 Description .....................................................................................................................59 Request Parameters.......................................................................................................59 Response Elements .......................................................................................................59 Errors .............................................................................................................................59 Examples .......................................................................................................................59 Sample REST Request ..................................................................................................59 Sample Response to REST Request ..............................................................................60 GetTransactionStatus ........................................................................................................61 Description .....................................................................................................................61 Request Parameters.......................................................................................................61 Response Elements .......................................................................................................61 Status Codes ..................................................................................................................62 Errors .............................................................................................................................62 Examples .......................................................................................................................63 Sample REST Request ..................................................................................................63 Sample Response to REST Request ..............................................................................63 Refund ...............................................................................................................................64 Description .....................................................................................................................64 v

Amazon Simple Pay Advanced Users Guide Request Parameters.......................................................................................................64 Response Elements .......................................................................................................65 Errors .............................................................................................................................65 Examples .......................................................................................................................65 Sample REST Request ..................................................................................................65 Sample Response to REST Request..............................................................................66 Sample IPN Success Notification to Rest Request .........................................................66 Settle .................................................................................................................................67 Description .....................................................................................................................67 Request Parameters.......................................................................................................67 Response Elements .......................................................................................................67 Errors .............................................................................................................................68 Examples .......................................................................................................................68 Sample REST Request ..................................................................................................68 Sample Response to REST Request ..............................................................................68 Sample IPN Success Notification to Rest Request .........................................................69 VerifySignature ..................................................................................................................70 Description .....................................................................................................................70 Request Parameters.......................................................................................................70 Response Elements .......................................................................................................71 Errors .............................................................................................................................71 Examples .......................................................................................................................71 Sample REST Request ..................................................................................................71 Sample Response to REST Request ..............................................................................72 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 vi

Amazon Simple Pay Advanced Users Guide 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

vii

Welcome

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 Get started with Amazon FPS quickly Learn about the advanced Amazon Simple Pay features Modify the sample code to create a specific button Learn about the HTML components of a wellformed Amazon Simple Pay buttons Make use of the response and transaction content returned by your buttons and by Amazon Payments Cancel and modify subscriptions Validate responses

Amazon Simple Pay detail page. Amazon Simple Pay Getting Started Guide Overview of Amazon Simple Pay Amazon Simple Pay Concepts Creating Button Forms Dynamically Amazon Simple Pay Button Input Reference Handling Return Content

Working with Subscription Buttons Using Instant Payment Notification How to Verify the IPN Signature Settling and Refunding Transactions Programmatically Simple Pay FPS Actions API Reference

Refund or settle a payment Use the Flexible Payments Service actions available with Amazon Simple 1

Welcome How do I?

See These Sections

Pay Work with Instant Payment Notification Use the sandbox for testing and error simulation Set defaults for a cancel subscription URL, an IPN URL, and the signing of buttons created using Amazon Payments online forms Learn about Amazon Simple Pay WSDL and Schema Find sample Code for signing buttons, verifying return data, or generating a button request

Using Instant Payment Notification Testing your Applications in the Amazon Payments Sandbox Configuring Default Button Values

Amazon Simple Pay WSDL and Schema Appendix: Sample Code

2

Introduction to Amazon Simple Pay

Introduction to Amazon Simple Pay 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 3


2.

3.

4. 5.

6.

developer account, see the “Amazon Payments Developer Account” section of this guide. 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. 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. Submit the form on the user's behalf if you need to control the flow between your website and Amazon Payments. 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. 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.

4


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

• • • 5

GetTransactionStatus Refund Settle

Introduction to Amazon Simple Pay • •

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

6


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.

7


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 cobranded 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/securitycredentials. 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

8

Introduction to Amazon Simple Pay 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.

9

Working with Amazon Simple Pay Buttons

Working with Amazon Simple Pay Buttons 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 Creating Button Forms Dynamically

Learn how to create a signed button of any type Modify the sample code to create a standard, donation, marketplace, or subscription button Use the response and transaction content returned by your buttons and by Amazon Payments Validate responses for the Return URL and Instant Payment Notification Understand subscription button particulars Use Amazon Flexible Payments Service actions available with Amazon Simple Pay Use Instant Payment Notification (IPN) Settle or refund money Work with signatures Get sample code for signing buttons, verifying return data, and generating a button request

Understanding the Amazon Simple Pay Button Samples

Handling Return Content

Verifying the ReturnURL and IPN Notifications

Working with Subscription Buttons API Reference

Using Instant Payment Notification, How to Verify the IPN Signature and Verifying the IPN How to Settle and Refund Transactions Programmatically Creating Button Forms Dynamically, How to Generate a Signature, and About Signature Version 2. Appendix: Sample Code

10


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.

11


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

12

Working with Amazon Simple Pay Buttons 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: For information on the high-level process for creating a button, see “Creating Button Forms Dynamically.”

13


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

14

Working with Amazon Simple Pay Buttons 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. For information on the high-level process for creating a button, see “Creating Button Forms Dynamically.” 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. 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 15

Working with Amazon Simple Pay Buttons &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: For information on the high-level process for creating a button, see “Creating Button Forms Dynamically.”

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.

16

Working with Amazon Simple Pay Buttons 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 Your AWS Access Key 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.” Enter the amount you want to collect for the item Optionally, set to a cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred) Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information Enter a description of the item Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0. Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction information Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0. Default value is 1 Optionally provide a unique identifies of this transaction for your records Optionally enter the URL where

No

accessKey amazonPaymentsAccountId

amount cobrandingStyle

collectShippingAddress

description immediateReturn

ipnUrl

processImmediate

referenceId

returnUrl

17

Yes Yes

Yes No

No

Yes No

No

No

No

No

Working with Amazon Simple Pay Buttons Parameter

signature signatureMethod signatureVersion

Description

Required

buyers should be redirected after they complete the transaction A value calculated using the form parameters. The signing algorithm, either HmacSHA1 or HmacSHA256. A value that specifies the signature format. Currently, the only valid value is 2.

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

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 Your AWS Access Key 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.” Enter the amount you want to collect for the item Optionally, set to a cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred) Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information Enter a description of the item Optionally set to the type of donation. Valid values are fixedAmount, minimumAmount and anyAmount. Default value is anyAmount. Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0. Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction

No




description donationType

immediateReturn

ipnUrl

19

Yes Yes

Yes No

No

Yes No

No

No

Working with Amazon Simple Pay Buttons Parameter isDonationWidget minimumDonationAmount

processImmediate

referenceId

returnUrl


Description

Required

information Always 1 for a donation button. The minimal payment allowed or the donation. Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0. Default value is 1 Optionally provide a unique identifies of this transaction for your records. Optionally enter the URL where buyers should be redirected after they complete the transaction A value calculated using the form parameters. The signing algorithm, either HmacSHA1 or HmacSHA256. A value that specifies the signature format. Currently, the only valid value is 2.

Yes Yes, if the value for donationType is minimumAmount No

No

No

Yes Yes Yes

For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Samples.” Donation Button Well-Formed HTML Example HTML for a basic donation button with no added fee, signed using the signature version 2 method. 20


Accept Marketplace Fee Button Input Reference This button may be use to set terms for either the Marketplace button or the Marketplaceenabled 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 Optionally, a value to uniquely identifies this transaction Set to 1 if you want Amazon Payments to return the buyer's email address as part of the transaction information

Yes

callerReference collectEmailAddress

21

No No


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. 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. The kind of token you are creating. For Amazon Simple Pay, this value is always Recipient. Set this value to True if the recipient agrees to pay the fees, otherwise set this value to False. Optionally enter the URL where buyers should be redirected after they complete the transaction A value calculated using the form parameters. The signing algorithm, either HmacSHA1 or HmacSHA256 A value that specifies the signature format. Currently, the only valid value is 2.

No

maxVariableFee

pipelineName recipientPaysFee returnURL signature signatureMethod signatureVersion

No

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

Marketplace Payment 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 Your AWS Access Key Enter the amount you want to collect for the item Optionally, set to a cobranding style.Valid values are "logo" or banner.” ("logo" is preferred) Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information Enter a description of the item 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. Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0. Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction

No

accessKey amount cobrandingStyle


description fixedMarketplaceFee

immediateReturn

ipnUrl

23

Yes Yes No

No

Yes No

No

No

Working with Amazon Simple Pay Buttons Parameter processImmediate

recipientEmail referenceId

returnUrl

secretKey signature signatureMethod signatureVersion

variableMarketplaceFee

Description

Required

information Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0. Default value is 1 The email address of the seller Optionally provide a unique identifies of this transaction for your records. Optionally enter the URL where buyers should be redirected after they complete the transaction Your AWS secret key A value calculated using the form parameters The signing algorithm, either HmacSHA1 or HmacSHA256. A value that specifies the signature format. Currently, the only valid value is 2. 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

Yes No

No

Yes Yes Yes Yes

No

For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Samples.” Marketplace Payment Button Well-Formed HTML Example HTML for a marketplace button, signed using the signature version 2 method.

25


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 Your AWS Access Key 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.” Enter the amount you want to collect for the item Optionally, set to a cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred) Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information Enter a description of the item Optionally set to the type of donation. Valid values are fixedAmount, minimumAmount and anyAmount. Default value is anyAmount. 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. Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0. Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction information Always 1 for a donation button. The minimal payment allowed or the donation.

No




description donationType

fixedMarketPlaceFee

immediateReturn ipnUrl

isDonationWidget minimumDonationAmount

processImmediate

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

Yes Yes

Yes No

No

Yes No

No

No No

Yes Yes, if the value for donationType is minimumAmount No

Working with Amazon Simple Pay Buttons Parameter referenceId recipientEmail returnUrl

variableMarketplaceFee


Description

Required

Default value is 1 Optionally provide a unique identifies of this transaction for your records. E-mail address of the merchant who will receive the payment. Optionally enter the URL where buyers should be redirected after they complete the transaction 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. A value calculated using the form parameters. The signing algorithm, either HmacSHA1 or HmacSHA256. A value that specifies the signature format. Currently, the only valid value is 2.

No Yes No

No

Yes Yes Yes

For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Samples.” 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.

Subscription 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 Your AWS Access Key Enter the amount you want to collect for the item 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.” Optionally, set to a

No

accessKey amount amazonPaymentsAccountId

cobrandingStyle

28

Yes Yes Yes

No



description immediateReturn

ipnUrl

noOfPromotion Transactions processImmediate

promotionAmount

recurringFrequency

recurringStartDate

referenceId

returnUrl

Description

Required

cobranding style.Valid values are "logo" or "banner.” ("logo" is preferred) Optionally set to 1 if you want Amazon Payments to return the buyer's shipping address as part of the transaction information Enter a description of the item Optionally set to 1 to skip the final status page in Amazon Payments. Default is 0. Optionally type the URL of your host page to which Amazon Payments should send the IPN transaction information Optionally set to the number of transactions in the promotion period. Optionally set to 1 to settle the transaction, otherwise set processImmediate to 0. Default value is 1 The optional amount you are providing for a promotional price. 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. Optionally enter the start date for the subscription. By default, the subscription will be processed as soon as subscription is created Optionally provide a unique identifies of this transaction for your records. Optionally enter the URL where buyers should be redirected after they complete the transaction 29

No

Yes No

No

Yes, if promotionAmount is not null or zero. No

No

Yes

No

No

No


Description

Required

signature

A value calculated using the form parameters. The signing algorithm, either HmacSHA1 or HmacSHA256. A value that specifies the signature format. Currently, the only valid value is 2. 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.

Yes

signatureMethod signatureVersion

subscriptionPeriod

Yes Yes

No

Note If this parameter is not provided, or the value is forever, the subscription will be for an unlimited period.

Subscription buttons have special features to consider. See “Working with Subscription Button Advanced Features.” For information on using the Amazon Simple Pay to create buttons, see “Understanding the Amazon Simple Pay Button Samples.” Subscription Button Well-Formed HTML Example HTML for a subscription button, signed using the signature version 2 method. 30


31


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.

32

Working with Amazon Simple Pay Buttons As an example, the following XML fragment shows a simplified response to a REST request for a Settle action. 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22 Pending 9ed2008b-b230-4ed0-9210-095f77fc2359:0

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


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

Working with Amazon Simple Pay Buttons 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.

35

Working with Amazon Simple Pay Buttons 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.

36


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.

37

Working with Amazon Simple Pay Buttons 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 38

Working with Amazon Simple Pay Buttons 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. 39

Working with Amazon Simple Pay Buttons 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.

40


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.

41


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

42

Working with Amazon Simple Pay Buttons 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. 2. 3. 4. 5.

Copy any one of the HTML examples in Amazon Simple Pay Button Input Reference. Remove the enclosing FORM element from your copy. Remove the Signature field and the HTML comments from your copy. Create a signature using the instructions in How to Generate a Signature. 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.

43


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

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

Payment Error

Occurs when a downstream process is not available. 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 Co44


Return URL

User Abandon URL

Subscription Cancellation URL

URL for Instant Payment Notification

Sign the buttons?

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

45


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. An Amazon Simple Pay marketplace button payment has failed to complete. The recipient has not received the intended funds. An Amazon Simple Pay standard button payment has failed to complete. The recipient has not received the intended funds. An Amazon Simple Pay donation button payment has succeeded. An Amazon Simple Pay marketplace button payment has succeeded. An Amazon Simple Pay standard button payment has succeeded. An Amazon Simple Pay button refund has failed to complete. The recipient has not received the intended funds. An Amazon Simple Pay donation button refund has succeeded. An Amazon Simple Pay marketplace button refund has succeeded. An Amazon Simple Pay standard button refund has succeeded. An Amazon Simple Pay marketplace button reserve request has failed. An Amazon Simple Pay standard button reserve request has failed. An Amazon Simple Pay marketplace button reserve request has succeeded. An Amazon Simple Pay standard button reserve request has succeeded.

ASPPayFailureEmailToRecipient Marketplace Button

ASPPayFailureEmailToRecipient Standard Button

ASPPaySuccessEmailToRecipient Donation Button ASPPaySuccessEmailToRecipient Marketplace Button ASPPaySuccessEmailToRecipient Standard Button ASPRefundFailedEmailToRecipient

ASPRefundSuccessEmailToRecipient Donation Button ASPRefundSuccessEmailToRecipient Marketplace Button ASPRefundSuccessEmailToRecipient Standard Button ASPReserveFailureEmailToMerchant Marketplace Button ASPReserveFailureEmailToMerchant Standard Button ASPReserveSuccessEmailToMerchant Marketplace Button ASPReserveSuccessEmailToMerchant Standard Button 46

Working with Amazon Simple Pay Buttons Email Template Name

Description

ASPSettleFailureEmailToMerchant

An Amazon Simple Pay button settle request has failed. An Amazon Simple Pay marketplace button settle request has succeeded. An Amazon Simple Pay marketplace button settle request has succeeded. Bank account verification failed Bank account verification started for personal and business account Bank account verification started for developer account Bank account verification successful Credit card verification failed for business Account Email confirmation sent to confirm the email address for the personal account. Email confirmation sent to confirm the email address for a business account. Daily summary of transactions Deposit failed Request to deposit funds initiated Deposit successful Notification for monthly statement MarketPlace registration email, fee paid by Caller MarketPlace registration email, fee paid by Recipient Payment failure from a multi use token (payment authorizations) Payment success from a multi use token (payment authorizations) One-time payment (ACH) initiated One-time donation button payment failed One-time marketplace button payment failed One-time payment failed for standard button One-time donation button payment Successful One-time marketplace button payment Successful One-time standard button payment Successful One-time ACH payment successful Refund of donation charge successful Refund of marketplace button charge Successful

ASPSettleSuccessEmailToMerchant Marketplace Button ASPSettleSuccessEmailToMerchant Standard Button BAVerifFailed BAVerifStartedForPersonalBusiness BAVerifStartedForDeveloper BAVerifSuccess CCVerifFailedBusiness ConfirmEmailPersonal ConfirmEmailBusiness DailySummary DepositFailure DepositFundsInitiated DepositSuccess MonthlyNotif MPFeeRegistrationCallerPaysFee MPFeeRegistrationRecipientPaysFee MultiPaymentFailure MultiPaymentSuccess OnetimePaymentACHInit OnetimePaymentFailure Donation Button OnetimePaymentFailure Marketplace Button OnetimePaymentFailure Standard Button OnetimePaymentSuccess Donation Button OnetimePaymentSuccess Marketplace Button OnetimePaymentSuccess Standard Button OnetimePaymentSuccessACH RefundSuccess Donation Button RefundSuccess Marketplace Button

47

Working with Amazon Simple Pay Buttons Email Template Name

Description

RefundSuccess Standard Button RefundSuccess Subscription Button SubscriptionCancellationByFPSToSender

Refund of standard button successful Refund of subscription charge successful Subscription canceled due to payment failure Subscription canceled by subscriber Subscription canceled notification from merchant to subscriber Subscription canceled notification from Merchant Subscription canceled notification form Merchant Subscription created notification to merchant Subscription created notification to subscriber Notify merchant that payment for subscription has failed Notify merchant that payment for subscription has failed Subscription payment failed to subscriber Notify merchant that a subscription payment is successful Subscription payment due Upgrade to business account successful Email address verified for personal account Email address verified for business account Withdraw failed, bank unable to accept electronic transaction Withdraw funds has been initiated

SubscriptionCancellationByRecipientToRecipient SubscriptionCancellationByRecipientToSender SubscriptionCancellationBySenderToRecipient SubscriptionCancellationBySenderToSender SubscriptionCreatedEmailForMerchant SubscriptionCreatedEmailForSender SubscriptionPayFailureEmailForMerchant SubscriptionPayFailureEmailForMerchant SubscriptionPaymentMethodChangeEmail SubscriptionPaySuccessEmailForMerchant SubscriptionPreNotifEmail UpgradePersonalToBusiness VerifyEmailSuccessPersonal VerifyEmailSuccessBusiness WithdrawFailure WithdrawFundsInitiated

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.

48

Working with Amazon Simple Pay Buttons The latest Amazon FPS WSDL is at: https://fps.amazonaws.com/doc/2010-0828/AmazonFPS.wsdl. The latest Amazon FPS schema is at: https://fps.amazonaws.com/doc/2010-08-28/AmazonFPS.xsd.

49

Simple Pay FPS Actions API Reference

Simple Pay FPS Actions API Reference 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.” 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.” Get the details of a subscription. For more information, see “GetSubscriptionDetails.” Get the transactions which have been made against a subscription. For more information, see “GetTransactionsForSubscription.” Get the current status of a particular transaction. For more information, see “GetTransactionStatus.” Refund a successfully completed payment transaction. For more information, see “Refund.”

CancelSubscriptionAndRefund

GetSubscriptionDetails GetTransactionsForScription

GetTransactionStatus Refund

50

Simple Pay FPS Actions API Reference API

Description

Settle

Charge the buyer's payment instrument for the purchase that was reserved. For more information, see “Settle.” Validate a signature in an Amazon Payments response. For more information, see “VerifySignature.”

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 Describes the reason for cancellation. Type: String Default: None

Yes

Description

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 This is the ID of the completed transaction. Returned only if the transaction is successful.

TransactionId

51

Simple Pay FPS Actions API Reference Element

Description

TransactionStatus

Type: String: Max size = 35 characters 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. 14GKI1SKSR1V6DO1RCCB32RBR6KLODMGQUD Cancelled 6fe4b755-a328-419d-8967-e1d3b43779fc:0 52

Simple Pay FPS Actions API Reference 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/FM ktKMbARXnZFYTzHj3YOKiAM3vxI0zT1oTiSdBx1KBRFzK7mauxxlQv5BYxjFX+R5c l+keCaT2nQyrp3agdrIIp5MZ5Oy9dBuYMwMFWXoZZor90EidD23hBdZSOOzQRUdzK aKJsF14RQVrKcf5pDCs1HaB6LBKbATaNTRSxxrviIXy9JcWRQhJwzcc1H6cFOJDpN FSJ03b0Z94eL/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

53


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. 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. 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 String that explains the reason for the cancellation. Type: String Default: None 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 SubscriptionId of the subscription to be canceled. Type: String Default: None

Only if you specify a value for Refund Amount.

CancelReason

RefundAmount

SubscriptionId

54

No

Only if you want to make a refund.

Yes

Simple Pay FPS Actions API Reference 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

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

Responses also include elements common to all responses. For more information, see “Common Response Elements.” 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 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 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 55

Simple Pay FPS Actions API Reference &SubscriptionId=17d62772-c53e-4bdb-9667-65d7b7841cfc &Timestamp=2009-10-06T08%3A05%3A13.296Z &Version=2008-09-17 Sample Response to REST Request 14GKE3B85HCMF1BTSH5C4PD2IHZL95RJ2LM bfbc0b1e-3430-4a74-a75e-5292f59107ca:0 Sample IPN Success Notification to Rest Request This section shows a sample IPN notification to a REST request. signatureVersion: 2 signatureMethod: RSA-SHA1 status: SubscriptionCancelled signature: sNaPeP1aNg5pjehHYJ97BAPWoZVPxFpXGOmDmprYk Pq8KN1cuZotBW2j+goUqA5tue/2FDlNk5+Z KMBtshSLiqtG1R6AH9qaNjZQwg4dm4t0OqP2eOjoH73wQwIaCCEr690o2lxjN+vx7 KO+w4wmnyqF xL9/j5wBjC2zpoy3NrN8uM0R547rYjjOaTODYb0cesYfvXXPGvFBniDloPGpxx7G2 ryIVZpFaeJ9 2XF2k6ho8M8rkdTp3MHPLiyZHjFl6+cKen2XynOqHD5RkG/aIgG9waus3E3esn9Zw eo8m4vdiL67 MyS4zQzyRg973bi45+Knv6AuuhhcTta41zSR8g== subscriptionId: 17d62772-c53e-4bdb-9667-65d7b7841cfc certificateUrl: https://fps.sandbox.amazonaws.com/certs/090909/PKICert.pem statusReason: CancelledByRecipient

56


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 Yes subscription of interest. Type: String Default: None Constraint: Cannot be null or empty 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.

Responses also include elements common to all responses. For more information, see “Common Response Elements.” Errors This action can return the following errors: • •

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

57

Simple Pay FPS Actions API Reference Sample Response to REST Request This section shows a sample REST response. YourSubscriptionId SubscriptionDescription USD 10.000000 USD 4.000000 2011-04-07T08:16:52.000-07:00 2011-04-07T08:19:52.000-07:00 18 week 6 week Completed 3 [email protected] RecipientName [email protected] SenderName RequestId

58


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

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

Element

Description

SubscriptionTransaction

A list of SubscriptionTransaction Type objects. If no transactions are found, then nothing is returned. Type: SubscriptionTransaction

Responses also include elements common to all responses. For more information, see “Common Response Elements.” Errors This action can return the following errors: • •

InternalError InvalidSubscriptionID

Examples Sample REST Request This section shows a sample request. https://fps.sandbox.amazonaws.com? Action=GetTransactionsForSubscription &SubscriptionId=YourSubscriptionId 59

Simple Pay FPS Actions API Reference &AWSAccessKeyId=YourAWSAccessKey &Timestamp=2011-04-07T11%3A20%3A33.609Z &Version=2010-08-28 &Signature=CalculatedSignature &SignatureMethod=HmacSHA256 &SignatureVersion=2 Sample Response to REST Request This section shows a sample REST response. TransactionId 2011-02-07T08:54:38.522-07:00 1 USD 1.000000 TransactionDescription Success TransactionId 2011-03-07T08:54:48.522-07:00 2 USD 1.000000 TransactionDescription Success TransactionId 2011-04-07T08:54:58.522-07:00 3 USD 1.000000 TransactionDescription Success RequestId 60


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 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” A description of the transaction status. Type: String (LOB, Large Object) 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 The status of the transaction. Provides a short code on the status of the transaction, for example "PENDING.” Type: TransactionStatus Size: 20 bytes

StatusCode

StatusMessage TransactionId

TransactionStatus

61


Responses also include elements common to all responses. For more information, see “Common Response Elements.” Status Codes This action can return the following values for StatusCode.

Status Code

Message

Canceled

The transaction was explicitly canceled by the caller. 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. This transaction is awaiting a response from the backend payment processor OR (Message returned by backend payment processor) The transaction has been flagged for manual investigation The requested amount was reserved successfully against the givenpayment instrument. OR The transaction was successful and the payment instrument was charged. (Message returned by backend payment processor). OR The transaction was denied after investigation.

Expired

PendingNetworkResponse

PendingVerification Success

TransactionDenied

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

AccessFailure AuthFailure InternalError InvalidClientTokenId InvalidParams InvalidTransactionId SignatureDoesNotMatch

62

Simple Pay FPS Actions API Reference 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

14GKE3B85HCMF1BTSH5C4PD2IHZL95RJ2LM Success CallerReference07 Success The transaction was successful and the payment instrument was charged. 13279842-6f84-41ef-ae36-c1ededaf278d:0

63


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

CallerDescription

A field that contains the caller's description of the transaction. Type: String Constraint: 160 characters maximum Default: None 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 Specifies the details of the refund, in particular, whether or not the caller or Amazon FPS are refunding their fees. Type: MarketplaceRefundPolicy Default: None 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 The unique ID generated by Amazon FPS and returned in response to a successful transaction. Type: String Constraint: 35 characters maximum Ancestor: RefundResult, ResponseMetadata

No

CallerReference

MarketplaceRef undPolicy

RefundAmount

TransactionId

64

Yes

No

No

Yes

Simple Pay FPS Actions API Reference 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

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 Provides the status of the transaction. Always returned. Type: TransactionStatus Ancestor: ResponseMetadata

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 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 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 request. https://fps.sandbox.amazonaws.com? Action=Refund &AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE &CallerDescription=MyWish &CallerReference=CallerReference03 &RefundAmount.CurrencyCode=USD &RefundAmount.Value=1 65

Simple Pay FPS Actions API Reference &Signature=V6pU3PvDPkPhR9Eu7yZXnFZHuEFafLE5sBPgqqCELEU%3D &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2009-10-06T05%3A51%3A49.578Z &TransactionId=14GK4TNCAQ84NK9VITEHKAS94RAD9ZE2AQD &Version=2008-09-17 Sample Response to REST Request This section shows a sample response to a REST request. 14GK6F2QU755ODS27SGHEURLKPG72Z54KMF Pending 1a146b9a-b37b-4f5f-bda6-012a5b9e45c3:0 Sample IPN Success Notification to Rest Request This section shows a sample IPN notification to a REST request. 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/7iHhNiEdwFoGVkrLjJHiBloPfJxzznH nmMtCR sUQ+A d3tZ0NdemMxf0qYM9NX93PyG0KBKXShKeM0Da39cvnC05tZmtxpfCuZT5ECRydr+B qRo/DOlx1Yg 93gihZ83qHWR8bpqQcBwsu7vD4c4m4mTZ4I75gw+NXKRDD+vCPFDNEKRnh5kQz+Tj jg4bnNYEEcG

66

Simple Pay FPS Actions API Reference Rf6UZfS2lvMzdj0c37RUY6t4gQ3W3Z9G/REGjC98JBuTimk/kc1HoSc+xe6WtAH/s iNurisyqgoB 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. 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

ReserveTransactionId

An identifier returned by Reserve that identifies the reserved transaction to be settled. Type: String Constraint: 35 characters maximum Default: None Amount to be settled. This cannot exceed the reserve amount. Type: Amount Default: The amount reserved in the Reserve request

Yes

TransactionAmount

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

TransactionId

Identifies the transaction that was settled. Always returned. 67

Simple Pay FPS Actions API Reference 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.” Errors This action can return the following errors: • • • • • • • • • •

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 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 https://fps.sandbox.amazonaws.com?ReserveTransactionId=14GKD9GE66 FAA63E6O6B2JD 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

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

68

Simple Pay FPS Actions API Reference 14GKD9GE66FAA63E6O6B2JDPZKN53LZ7F22 Pending 9ed2008b-b230-4ed0-9210-095f77fc2359:0