Amazon Simple Pay Advanced Users Guide

117 Pages·2014·0.55 MB·English

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 ................................................................................................................1 03
Amazon Simple Pay Related Resources .................................................................................1 05
Glossary..................................................................................................................................1 06
Document History ...................................................................................................................1 08

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 Amazon Simple Pay detail page.
needs
Get started with Amazon FPS quickly Amazon Simple Pay Getting Started Guide
Learn about the advanced Amazon Overview of Amazon Simple Pay
Simple Pay features Amazon Simple Pay Concepts
Modify the sample code to create a specific Creating Button Forms Dynamically
button
Learn about the HTML components of a well- Amazon Simple Pay Button Input Reference
formed Amazon Simple Pay buttons
Make use of the response and transaction Handling Return Content
content returned by your
buttons and by Amazon Payments
Cancel and modify subscriptions Working with Subscription Buttons
Validate responses Using Instant Payment Notification
How to Verify the IPN Signature
Refund or settle a payment Settling and Refunding Transactions
Programmatically
Use the Flexible Payments Service actions Simple Pay FPS Actions API Reference
available with Amazon Simple
1
Welcome

How do I? See These Sections
Pay
Work with Instant Payment Notification Using Instant Payment Notification
Use the sandbox for testing and error Testing your Applications in the Amazon
simulation Payments Sandbox
Set defaults for a cancel subscription URL, an Configuring Default Button Values
IPN URL, and the signing of buttons created
using Amazon Payments online forms
Learn about Amazon Simple Pay WSDL and Amazon Simple Pay WSDL and Schema
Schema
Find sample Code for signing buttons, Appendix: Sample Code
verifying return data, or generating a button
request
2