Amazon Flexible Payments Service. Developer Guide API Version

Transcription

1 Amazon Flexible Payments Service Developer Guide

2 Amazon Flexible Payments Service: Developer Guide Published Copyright 2007 Amazon.com Amazon Web Services LLC or its affiliates. All rights reserved.

3 What's New This What's New is associated with the release of Amazon Flexible Payments Service. This guide was last updated on 16 October This is the first public release of the Amazon Flexible Payments Service (Amazon FPS). The Amazon FPS Developer Resource Center contains information on the features available in this release of Amazon FPS. 1

4 Audience Welcome This is the. This section describes who should read this guide, how the guide is organized, and other resources related to Amazon Flexible Payments Service. The Amazon Flexible Payments Service will occasionally be referred to within this guide as simply "Amazon FPS"; all copyrights and legal protections still apply. Topics: Audience HowThisGuideIsOrganized RelatedResources Audience This guide is intended for developers who would like to embed payment functionality into their applications. Required Knowledge and Skills Use of this guide assumes you are familiar with the following: XML (See W3 Schools XML Tutorial) Basic understanding of web services (See W3 Schools Web Services Tutorial)) A programming language for consuming a web service and any related tools You should also have read the Amazon FPS Getting Started Guide, which includes basic information on concepts and a simple Hello World type tuturial. How This Guide Is Organized This guide is organized into several major sections described in the table below. 2

5 Related Resources List links to actual major section titles and sections. Information Relevant Sections General information about Amazon FPS Introduction to Amazon Flexible Payments Service Making requests to Amazon FPS Making Requests to Amazon FPS Understanding and creating tokens Creating tokens Caller token Sender token (single-use token, multi-use token, recurring payments token Recipient token Using tokens Using tokens for making payments Making a Pay request Handling Responses Synchronous responses Asynchronous responses using the GetResult operation and web service notifications. Token management Token management Account management Account management Prepaid and Postpaid Using prepaid Using prepaid Reserve and Settle Reserve and Settle Typographic and symbol conventions Document Conventions Related Resources 3

6 Related Resources The table below lists related resources that you'll find useful as you work with this service. Resource Amazon FPS Getting Started Guide The Getting Started Guide provides a quick tutorial of the service based on a simple use case. Examples and instructions for Java,.Net, Ruby, and Perl are included. Amazon FPS Developer Guide The Developer Guide provides a detailed discussion of the service. It includes an programming reference, API reference, co-branded UI API reference, GateKeeper language reference and Troubleshooting section. Amazon FPS Release Notes The Release Notes give a high-level overview of the current release. They specifically note any new features, corrections, and known issues. AWS Developer Resource Center A central starting point to find documentation, code samples, release notes, and other information to help you build innovative applications with AWS. Amazon FPS information The primary web page for information about Amazon FPS. Discussion Forums A community-based forum for developers to discuss technical questions related to Amazon Web Services. address for questions related to your AWS account: webservices@amazon.com This address is only for account questions. For technical questions, use the Discussion Forums. 4

7 Amazon FPS Functionality Introduction to Amazon Flexible Payments Service Amazon Flexible Payments Service (Amazon FPS) is the first payments service designed from the ground up specifically for developers. The set of web services API"s allows the movement of money between any two entities, humans or computers. It is built on top of Amazon"s reliable and scalable payment infrastructure. This introduction to Amazon Flexible Payments Service (Amazon FPS) is intended to give you a detailed summary of this web service. After reading this section, you should have a good idea of what it offers and how it can fit in with your business. Amazon FPS Functionality You can use the extensive feature set of Amazon FPS to conduct a wide variety of transactions under virtually any set of constraints. Key features include: Send and receive money using credit card, bank account or Amazon Payments balance transfer as payment methods. Create "Payment Instructions" to define conditions and constraints desired for a given transaction, and programmatically obtain payment authorizations or "tokens" that represent these Payment Instructions from customers. Execute one-time, multiple, or recurring payments on behalf of customers. Aggregate micro-transactions into a single larger transaction using Prepaid and Postpaid capabilities. Build payment applications where you are neither the sender nor the recipient of funds. Rather, you can build marketplace applications that enable the movement of money between two third parties. View account balances, transaction histories, and transaction details on the Amazon Payments Web site ( Utilize the Amazon FPS sandbox to build and test applications without using real money or incurring any transaction charges. 5

8 Making Requests to Amazon FPS Programming Reference This programming reference provides detailed information on all the Amazon FPS features that are introduced in the Amazon FPS Getting Started Guide. The topics in this programming reference are organized in the order in which you could use Amazon FPS. As a first time user of Amazon FPS, we recommend that you follow the topics in the order that is presented. The topics, however, are self-contained and can be used as a direct reference. The programming reference contains information on: the type of requests, how you can make them and handle their responses. the type of tokens, and setting up and managing tokens. how to make a Pay call to transfer money from a sender's account to a recipient's account. how to manage your Amazon Payments account balance how you can set up aggregated payments using prepaid and postpaid functionality. using the reserve and settle functionality Topics: Making Requests to Amazon FPS Creating tokens Using tokens for Payments Managing Tokens Managing Your Account Prepaid Postpaid Reserve and Settle Use cases Making Requests to Amazon FPS Amazon FPS supports three different request types. This topic introduces the request types and provides information on how you can use them for various tasks. The supported request types are: 6

9 SOAP / REST Requests SOAP / REST request Amazon FPS Co-branded UI Pipeline request SOAP / REST Requests You can make SOAP or REST requests to do the following operations on Amazon FPS: Installing tokens on your account Retrieving information on tokens Executing transactions and fetching the transaction results. Accessing your account activity. Receiving or poll for payment notifications. Querying for prepaid and postpaid balances. Issuing refunds See the Constructing a SOAP Request and the Constructing a REST Request section for more information. Amazon FPS Co-branded UI Pipeline Request You can use the Amazon FPS Co-branded pipeline to install payment instructions on your customers account as part of the payment transaction process See the Using a Co-Branded UI Pipeline section for more information. Constructing a SOAP Request To construct a SOAP request 1. Set up an X.509 certificate on your developer account as described in the Setting Up Your AWS Developer Account topic in the Amazon FPS Getting Started Guide. 2. Download the Amazon FPS WSDL and XSD for the web service API from the AWS Resource Center. 3. Generate client-side stubs (code generated from WSDL) using the standard tools available in the language of your choice. For example, for a Java application you can use the WSDL2Java tool packaged with Axis ( 4. Include the security library (sighelper) provided in the Amazon FPS SDK. The security library uses the X.509 certificate that you have set up on your developer account for signing the SOAP message to make it tamper resistant. Note This security library is language dependent. 5. List all the parameters for the API you want to call and construct a request using the required parameters. For example, the GetTransaction operation request can be constructed as shown below: /*----- Begin Construct GetTransactionBatchRequest */ GetTransactionRequest gettransactionrequest = new GetTransactionRequest(); 7

10 Constructing a REST Request /* Set Required Parameters. */ // Set the identifier for the transaction of interest. gettransactionrequest.settransactionid(transactionid); // This is the call to the 'GetTransaction' Operation. GetTransactionResponse gettransactionresponse = afps.gettransaction(gettransactionrequest); See the API Reference section for more information about the GetTransaction operation and its parameters. The SOAP message is now sent over the Secure Sockets Layer (SSL), which ensures that the message is confidential. This is a one-way SSL handshake, where the client verifies the peer using the Amazon FPS public certificate. Authenticating SOAP Requests The ITU-T standard for public key infrastructure (PKI), X.509, specifies the standard formats for public key certificates and certification path validation algorithms. Amazon Web Services does not implement the full PKI defined in the standard. We only use the certificate information to authenticate requests to AWS. AWS accepts any syntactically and cryptographically valid X.509 certificate. AWS won't verify whether a certificate is expired or revoked. Certificates can be self-signed or signed by any key. Certificates generated by AWS are self-signed certificates with no expiry. Message Expiration Signed messages must contain an expiration timestamp, represented as an Expires element within a Timestamp element in the WS-Security header. The Expires element should not have a Value attribute, and the Timestamp element might have a created child element. A typical Timestamp element is shown below:... <wsu:timestamp xmlns:wsu=" tility-1.0.xsd" wsu:id="timestamp"> <wsu:created> t09:07:43.199z</wsu:created> <wsu:expires> t09:12:43.199z</wsu:expires> </wsu:timestamp>... Constructing a REST Request You can construct a REST request using the parameters and values of an operation required for your transaction. The format of a REST request is: FPS web service end point/? AWSAccessKeyId= &Timestamp= &Signature= &SignatureVersion= &Version= &Action= 8

11 Constructing a REST Request &= &= &... Example of a REST Request The following sample request makes the GetTransaction request: > ---> ---> ---> ---> ---> ---> ---> &Action=GetTransaction &AWSAccessKeyId=Your access key &Signature=Signature for the request &SignatureVersion=1 &Timestamp= T06%3A18%3A45Z &TransactionId=125UI1FPZIU2BHN7VQAR5QBDJSHIPZAZD7U &Version= The parameters used in the sample REST request are explained below. Line 1 specifies the URL to send the request. Line 2 specifies the API name. Line 3, 4, and 5 are used to authenticate the request. See Authenticating Requests topic for more information. Line 7 specifies the transactionid for this request. Line 8 specifies the version of the WSDL ( You can find the WSDL version from the Amazon FPS Resource Center. Specifying an array list of parameters and values The DiscardResults operation allows you to specify multiple transaction IDs in the request. You can specify multiple transaction IDs as illustrated below: &Action=DiscardResults &...other parameters... &TransactionIDs.0= ; &TransactionIDs.1= ; &TransactionIDs.2= ;.... &TransactionIDs.n=xxxxxxx; Note The transaction ID index must always start at 0 (zero) even if there is only one transaction ID. Authenticating Requests Every request must contain a signature. The signature is used to secure your requests to Amazon FPS. 9

12 Constructing a REST Request The signature is placed as the value for the query parameter Signature in the URL being constructed. For example, the fictitious company DigitalDownload constructs the following request using the parameters and values to install a caller token on its own account. yid=0656nb6bl316j5ea83g2&token=unrestricted&signatureversion=1 &PaymentInstruction=MyRole=='Caller';&CallerReference=AmazonFPSSDK Caller000&PaymentReason=paymentReason &Version= &TokenFriendlyName=AmazonFPSSDK - Caller &Timestamp= T13:00:01Z Calculating Signature Amazon FPS supports only signature version 1 for calculating a signature. This version would catch spoofing of any of the request parameters and is a safer method of signing requests.. To calculate a signature (version 1) 1. List all the parameters in sorted order (including SignatureVersion and excluding Signature, the value of which is being created), ignoring case. Optional parameters not included in the request should not be canonicalized as empty parameters. That is, if no value for a ParameterA is specified in the request, there should not be a ParameterA entry in the canonicalized string. The DiscardResults operation allows you to specify multiple transaction IDs in the request. If you have multiple transactions, for example 12, to be discarded, then you must sort the transaction IDs as illustrated below: TransactionIds.0 TransactionIds.1 TransactionIds.10 TransactionIds.11 TransactionIds.12 TransactionIds TransactionIds.9 The transaction ID index must always start at 0 (zero). Important Do not URL-encode the parameters and their values in this step. Parameter Values Action InstallPaymentInstruction AWSAccessKeyId 0656N1J5EBSV68NA83G2 CallerReference AmazonFPSSDK - Caller000 PaymentInstruction MyRole=='Caller'; 10

13 Constructing a REST Request Parameter Values PaymentReason paymentreason SignatureVersion 1 Timestamp T13:00:01Z TokenFriendlyName AmazonFPSSDK - Caller Token Unrestricted Version Create the string to sign by appending the name and values from the above sorted list. This string does not contain the & (ampersand) and = (equals) character ActionInstallPaymentInstructionAWSAccessKeyId0656N1J5EBSV68NA83G2CallerReferenceAmazonFPSSDK - Caller000 PaymentInstructionMyRole=='Caller';PaymentReasonpaymentReasonSignatureVersion1 Timestamp T13:00:01ZTokenFriendlyNameAmazonFPSSDK - CallerTokenUnrestrictedVersion Calculate the RFC 2104 complaint HMAC signature of the UTF-8 encoded string. Base64 encode the HMAC signature of the generated string. The following sample code generates the HMAC signature.... public static calculaterfc2104hmac( stringtosign, key)throws NoSuchAlgorithmException, InvalidKeyException { result; // get an hmac_sha1 key from the raw key bytes SecretKeySpec signingkey = new SecretKeySpec(key.getBytes(), Config.HMAC_SHA1_ALGORITHM); // get an hmac_sha1 Mac instance and initialize with the signing key Mac mac = Mac.getInstance(Config.HMAC_SHA1_ALGORITHM); mac.init(signingkey); // compute the hmac on input string data bytes byte[] rawhmac = mac.dofinal(stringtosign.getbytes()); // base64-encode the hmac result = Base64.encode(rawHmac); System.out.println(" to sign:" + stringtosign); System.out.println("signature:" + result); return result; } Append the original URL with the signature string ( Signature=signature string) created from the previous step as shown below. This URL and the signature value are not URL-encoded in this step. skeyid=0656nb6bl316j5ea83g2 &Token=Unrestricted&SignatureVersion=1&PaymentInstruction=MyRole=='Cal 11

14 Using a Co-Branded UI Pipeline ler' &CallerReference=AmazonFPSSDK Caller000&PaymentReason=paymentReason&Version= &TokenFriendlyName=AmazonFPSSDK - Caller&Timestamp= T13:00:01Z &Signature=<Specify the signature value> 6. Finally, URL-encode (UTF-8 format) the parameter values of the URL in the previous step and create the final query URL. This URL contains the Amazon FPS end-point followed by the parameters and their values. The final URL should resemble: skeyid=0656n1j5ebsv68na83g2 &CallerReference=AmazonFPSSDK+-+Caller000&PaymentInstruction=MyRole+%3D%3D +%27Caller%27%3B &PaymentReason=paymentReason&SignatureVersion=1&Timestamp= T13%3A 00%3A01Z &TokenFriendlyName=AmazonFPSSDK+-+Caller&Token=Unrestricted&Version= &Signature=<URL-encoded signature value> The sample code for REST implementation is available in Java. See the Community code category in the Amazon FPS Resource center. Using a Co-Branded UI Pipeline You must direct your customers to the Amazon FPS Co-branded UI pipeline where they can set up payment authorizations required for your transaction. To direct your customers to the Amazon FPS Co-branded UI pipeline you must create a signed URL with parameters required for the payment authorization. To build a co-branded UI request 1. Construct a request URL using all the parameters and their values as per your use case. See the Amazon FPS Co-branded UI API reference for more information. 2. Generate a signature using the Amazon FPS SigHelper tool and append it to the request URL using the awssignature parameter. You can pass the unsigned URL and your secret key (associated with your AWS developer account) to the SigHelper tool to generate a signed URL. The SigHelper tool uses the steps described below in the Signing A URL topic to sign a URL. The SigHelper code samples are available for various lanaguages in the Community code category of the Amazon FPS Resource Center. Note After you extract the library or sample applications package from the Amazon FPS Resource center, go to the srcfolder to locate the SigHelpercode samples. Signing A URL Information transferred between a merchant web site and the Amazon FPS co-branded UI pipeline are secured using signed URLs. For example, the fictitious company DigitalDownload constructs the following URL using the parameters and values required for its use case. 12

15 Using a Co-Branded UI Pipeline ctionamount=10&callerreference=bl316 &pipelinename=singleuse&recipienttoken=sbdkwll83932ldkdlaksksskkkll891919askd FSS&callerKey=11RLBBGBROL2006 &returnurl=http%3a%2f%2fwww%2edigitaldownload%2dweb%2dsite%2ecom Important Ensure that you URL encode the values in parameter=value strings as specified in RFC1738, section 2.2. To sign a URL, you must do the following: 1. Sort the query parameters 2. Create a URL signature Sorting the Query You must sort the parameters alphabetically as shown in the comparison of unsorted and sorted parameters below: Unsorted Parameters transactionamount=10&callerreference=bl316&pipelinename=singleuse&recipienttoken=sbd KWLL83932LDKDLAKSKSSKKKLL891919ASKDFSS &callerkey=11rlbbgbrol2006&returnurl=http%3a%2f%2fwww%2edigitaldownload%2dweb %2Dsite%2Ecom Sorted Parameters callerkey=11rlbbgbrol2006&callerreference=bl316&pipelinename=singleuse&recipienttok en=sbdkwll83932ldkdlaksksskkkll891919askdfss &returnurl=http%3a%2f%2fwww%2edigitaldownload%2dweb%2dsite%2ecom&transactiona mount=10 Creating URL Signature You must do the following to create a URL signature: 1. Compute a RFC 2104compliant HMAC signature of the sorted parametersstring appended to the path information. /cobrandedui/actions/ start?callerkey=11rlbbgbrol2006&callerreference=bl316&pipelinename=singleu se &recipienttoken=sbdkwll83932ldkdlaksksskkkll891919askdfss&returnurl=http%3 13

16 Creating Tokens A%2F%2Fwww%2Edigitaldownload%2Dweb%2Dsite%2Ecom &transactionamount= Encode the resultant signature using Base64. URL encode (percent-encode) the resultant value. Append this signature using the awssignature parameter to your request URL to direct your customers to the Amazon FPS Co-branded UI pipeline. The final URL should resemble: ctionamount=10&callerreference=bl316 &pipelinename=singleuse&recipienttoken=sbdkwll83932ldkdlaksksskkkll891919askd FSS&callerKey=11RLBBGBROL2006 &returnurl=http%3a%2f%2fwww%2edigitaldownload%2dweb%2dsite%2ecom &awssignature=the signature created using the steps explained here. See the Amazon FPS Getting Started Guide for more information. Creating Tokens For executing any payment transaction on Amazon FPS, you must provide a sender token, a recipient token, and a caller token. A token is a long string (64 characters) returned as a handle to the payment instructions installed on an account. Payment instructions are set of rules written in the GateKeeper language and passed to the InstallPaymentInstruction operation to create and set up tokens. The GateKeeper language provides flexible set of constructs to specify wide variety of conditions, constraints, and preference instructions for allowing and executing Amazon FPS transactions. Restriction / Condition Pay using credit card. Accept payments using credit card only. GateKeeper language Constructs PaymentMethod = 'credit card'; PaymentMethod == 'credit card'; Details This construct is used in a sender token. The = operator is used to assign a value to a variable This construct is used in a recipient token. The == operator is used to assert the value of a variable. Amount <= 10; Pay not more than $10 This construct can be used in a sender token to restrict payment to a maximum of $10. MyRole == 'Sender'; Specify your role in a payment process This construct asserts the role you want to play in a payment transaction. This instruction ensures that this token can only be 14

17 Installing tokens on your account Restriction / Condition GateKeeper language Constructs Details used as a sender token. Installing tokens on your account You can use the GateKeeper language to construct payment instructions and pass them as inputs to the InstallPaymentInstruction operation. You can create caller, sender or recipient token based on the role assertion that you specify in the payment instruction. Installing tokens on other's accounts You cannot install tokens on other's (your customer's) account using the InstallPaymentInstruction operation. You can, however, acquire tokens from your customers (senders and recipients) using one of the following methods : Offline Exchange Other developers can install payment instructions on their accounts using the InstallPaymentInstruction operation. The tokens can then be sent to you offline, for example, through an . Note Only developers (callers) can install payment instructions on their accounts using the InstallPaymentInstruction operation. Amazon FPS Co-branded UI Pipeline You can direct your customers to the Amazon FPS Co-branded UI pipeline to install payment instructions on their accounts and return you a token. You can control the payment instructions that your customers install using the input parameters in the co-branded UI pipeline. The Amazon FPS co-branded UI pipeline is invoked when your customer clicks a link (to buy or to checkout) on your web site. This link directs your customers to the Amazon FPS co-branded UI pipeline. After your customers sign in using their Amazon.com login ( Id) and password they can view the payment instructions in the human-readable form. They must authorize the installation of these payment instructions on their accounts. Once the payment instructions are installed on their accounts, your customers are redirected to your web site (along with a token created on their account). Note The redirection to your web site can fail due to network issues that can result in loss of tokens. Amazon FPS provides a way to retrieve such lost tokens using the GetTokensByCaller operation. The callerreference that was passed as input to the Amazon FPS co-branded UI pipeline is the key to retrieve the right tokens. Installing Tokens on your Account You can use the InstallPaymentInstruction operation to install tokens (payment instructions) on your account. To install the token you must: 15

18 Installing Tokens on your Account 1. Create GateKeeper constructs 2. Provide the GateKeeper constructs as inputs to the InstallPaymentInstruction operation Creating GateKeeper Constructs You can create GateKeeper construct based on the token's role in the transaction. This section provides GateKeeper constructs for each of the roles. Creating a caller token You can create a caller token using this simple GateKeeper construct: // This GateKeeper construct asserts that the token can be // used only for a caller. MyRole == 'Caller' orsay 'Role does not match'; Additionally, you can add other assertions to this GateKeeper construct. However, for most transactions you can use the caller token with the given GateKeeper construct. Creating a recipient token You can create a recipient token using this GateKeeper construct: //This GateKeeper construct asserts that this token can be used only for a recipient. MyRole =='Recipient' orsay 'Role does not match'; Additionally, you can add more assertions to the recipient token. PaymentMethod == 'abt'; Amount >= 1.00; // # Specifies that the recipient will accept a minimum amount $1.00. TransactionTimeStamp >= August ; // # Specifies that the transaction must happen after Aug Creating Sender Tokens You can create GateKeeper constructs based on the token usage in the caller application to create sender tokens. There are three types of sender tokens: Single-use tokens Multi-use tokens Recurring tokens Single-use Token - A single-use token can only be used once in a transaction. The GateKeeper construct for a single-use token can have the following variables: Role CallerTokenId RecipientTokenId TransactionAmount 16

19 Installing Tokens on your Account PaymentMethod Example //A sample GateKeeper construct for a single-use MyRole == 'Sender' orsay 'Role does not match'; this token. CallerTokenId == '34KBL SZ'; this token. RecipientTokenId == 'SSK343S...LKJ33'; ceives payment. TransactionAmount := 10; PaymentMethod == 'abt'; Payments account balance. sender token. // Asserts on the role of // The caller who can use // The recipient who re// The transaction amount. // This Token uses Amazon Multi-use Token - A Multi-use token may be used multiple times in a transaction. There are additional GateKeeper variables that you can specify to describe usage limits. Example: MyTokenUsageLimit1 <= 5; MyTokenUsageLimit1 = Count ; For more details on creating GateKeeper constructs, see Constructing Payment Instructions section of GateKeeper Reference. Recurring-use Token - A recurring token can be used multiple times but only for a predetermined frequency and amount. There are additional GateKeeper variables that you can specify to describe usage limits. Providing GateKeeper constructs as inputs to InstallPaymentInstruction Operation You can use the InstallPaymentInstruction to install payment instructions in your Amazon Payments developer account. See the sample code given below: Java import import import import import import java.net.malformedurlexception; java.net.url; java.rmi.remoteexception; java.util.calendar; javax.xml.rpc.serviceexception; com.amazonaws.fps.*; /* * This Class makes a simple InstallPaymentInstruction call to FPS and captures the response. * * - Specify the location of the client configuration file -> client-config.wsdd * - Specify the URL Endpoint of <b>fps Sandbox</b> to test this sample. * * You can compile and run this code by filling out the sender, recipient and caller tokens in the appropriate places. */ public class InstallPaymentInstruction { public static AmazonFPSPort setup() throws MalformedURLException, 17

20 Installing Tokens on your Account ServiceException { /* Begin SETUP */ /* * Set System configuration. This step constructs the SOAP Headers with the configuration provided in the * client-config.wsdd. * You will be able to set up security using these three lines of code. */ System.setProperty("axis.ClientConfigFile", "client-config.wsdd"); //Sets up the Amazon FPS Service Port from the URL endpoint provided to you. URL endpoint = new URL(" AmazonFPSPort amazonfpsport = new AmazonFPSLocator().getAmazonFPSPort(endpoint); /* End SETUP */ return amazonfpsport; } public static void main([] args) throws ServiceException, RemoteException, MalformedURLException { //Execute the setup method AmazonFPSPort afps = setup(); // Creating a 'InstallPaymentInstructionRequest' object. InstallPaymentInstructionRequest insreq = new InstallPaymentInstructionRequest(); // InstallPaymentInstruction operation requires a unique callerreference. insreq.setcallerreference("amazonfpssdk - Caller" + Calendar.getInstance().getTimeInMillis()); // Setting the GK text for a caller token. insreq.setpaymentinstruction("myrole == 'Caller';"); // Setting the Token. This can be like SingleUse, MultiUse etc. insreq.settoken(token.unrestricted); /* Set Optional Parameters. */ // Setting a human readable friendly name for this payment instruction. insreq.settokenfriendlyname("amazonfpssdk - Caller"); // Making the API call to Amazon FPS. InstallPaymentInstructionResponse insres = afps.installpaymentinstruction(insreq); // Retrieving the API response status. insstatus = insres.getstatus().getvalue(); // Processing the API response based on the status returned. if (insstatus.equals(responsestatus._success)){ tokenid = insres.gettokenid(); // Printing the token in case the API call was successful. System.out.println("Caller Token Installed is: " + tokenid); } else { error = "Error in creating Caller Token: " + insres.geterrors().geterrors(0).to() + "Is Retriable: " + insres.geterrors().geterrors(0).isisretriable() + "Error : " + insres.geterrors().geterrors(0).geterror() + 18

21 Installing Tokens on your Account "Error Code: " + insres.geterrors().geterrors(0).geterrorcode() + "Error Reason: " + insres.geterrors().geterrors(0).getreasontext()+ "Please Redeploy the application to install the user tokens."; // Printing the error in case the API call was unsuccessful. System.out.println(error); } } } PHP..... // Installing Caller Token $pirequestcaller = array('body'=>array( 'PaymentInstruction'=>"MyRole == 'Caller';", 'TokenFriendlyName'=>"AmazonFPS_PHPSDK - Caller", 'CallerReference'=>"AmazonFPS_PHPSDK - Caller", 'Token'=>"Unrestricted",)); $piresponsecaller = $SoapClient->call('InstallPaymentInstruction', "UniqueMessageId-".microtime(true), $keystorelocation,$keystorepsswd,$pirequestcaller,$namespace); if(strcmp($piresponsecaller['status'],"success")==0) { $callertoken = $piresponsecaller['tokenid']; $mylogger->log("[propertiesinvalid.php] Caller token installed successfully.",pear_log_info); } else { /* Handling InstallPaymentInstruction Operation Failure Case */ $serviceerrors = $piresponsecaller['errors']; $error.= "Following errors occured in the InstallPaymentInstuction API Call while installing the caller token. "; foreach ($serviceerrors as $key => $value) { $error.= "<br><br>error: ". $value['error']; $error.= "<br>errorcode: ". $value['errorcode']; $error.= "<br>reasontext: ". $value['reasontext']; } }..... Ruby require 'http-access2' require "wss4r/tokenresolver/certificateresolver" require 'target/gensrc/defaultdriver.rb' require 'HeaderHandler.rb' include WSS4R::Tokenresolver require 'CreateHeader.rb' ## Installing a Caller Token on Caller's Account to be used in all use 19

22 Installing Tokens on your Account cases cert_dir= "Give complete path to your certs directory" unique_id = ((Time.now.to_f*1000).to_i).to_s passphrase="afpsfoo" endpoint_url= " sp = AmazonFPSPort.new(endpointUrl) # Specify the operation (API) name api_name="installpaymentinstruction" #CreateHeader CreateHeader.new(sp,endpoint_url,api_name,cert_dir,passphrase) #Setting the request parameters # PaymentInstruction => "MyRole == 'Caller';" # TokenFriendlyName => "AmazonFPS - Caller" # CallerReference => "AmazonFPS - Caller"+@unique_id # Token => "Unrestricted" # PaymentReason => "PaymentReason" install_pi_request_obj = InstallPaymentInstructionRequest.new("MyRole == 'Caller';","AmazonFPS - Caller","AmazonFPS Caller"+unique_id,"Unrestricted","PaymentReason") #Handle Response install_pi_response_obj = sp.installpaymentinstruction(install_pi_request_obj) if( install_pi_response_obj.status <=> "Success") token_id = install_pi_response_obj.tokenid caller_token = token_id else error = "Error in installing the caller token:" + install_pi_response_obj.errors().errors().at(0).to_s + "Is Retriable: " + install_pi_response_obj.errors().errors().at(0).isretriable() + "Error : " + install_pi_response_obj.errors().errors().at(0).error() + "Error Code: " + install_pi_response_obj.errors().errors().at(0).errorcode() + "Error Reason: " + install_pi_response_obj.geterrors().errors().at(0).reasontext() puts error end Installing a Payment Instruction - Response Example of a SOAP response <env:envelope xmlns:env=" <env:header> <wsa:relatesto xmlns:wsa=" ruction456000</wsa:relatesto> <wsa:to xmlns:wsa=" 2004/08/addressing/role/anonymous</wsa:To> <wsa:action xmlns:wsa=" ruction:response</wsa:action> <wsa:messageid xmlns:wsa=" </env:header> <env:body> <ns4:installpaymentinstructionresponse xm- 20

23 Acquiring Tokens lns:ns2=" xmlns:ns3=" xmlns:ns4=" /* Caller token returned by Amazon FPS */ <TokenId>84C7...4ADVE</TokenId> <Status>Success</Status> <RequestId>edaab4b8-ac3a-498f bd87ecd12a9:0</RequestId> </ns4:installpaymentinstructionresponse> </env:body> </env:envelope> Example of a REST response <?xml version="1.0" encoding="utf-8"?> <ns4:installpaymentinstructionresponse xmlns:ns2=" xmlns:ns3=" xmlns:ns4=" /* Caller token returned by Amazon FPS */ <TokenId>84C7...4ADVE</TokenId> <Status>Success</Status> <RequestId>d85f585a-9d60-46bd-8ade-5c4fbda65a36:0</RequestId> </ns4:installpaymentinstructionresponse> Acquiring Tokens This section explains acquiring tokens from your customers (recipients and senders) using the Amazon FPS co-branded UI pipelines. Acquiring tokens is different from creating tokens on your account. To acquire tokens from senders or recipients you must direct them to the Amazon FPS co-branded UI from your website. In this request you specify key-value pairs that control the payment instructions installed on their accounts. We have mapped the most useful subset of the GateKeeper constructs as key-value pairs which are the input parameters to this request. See the Using a Co-Branded UI Pipeline section for information on making HTTP redirect requests to the Amazon FPS co-branded UI. Topics: Acquiring Single-use Tokens Acquiring Multi-use Tokens Acquiring Recurring Payments Tokens Acquiring Recipient Tokens Acquiring Single-use Tokens You can allow your customers to set up a single-use sender token that you can use in your transaction. A single-use sender token can be used for making a one-time payment in your transaction. The following are the rules or features of a single-use sender tokens: A single-use sender token is installed on your customers account using the Amazon FPS single-use sender token installation pipeline. You can, however, install a single-use sender token on your own 21

24 Acquiring Tokens account using the InstallPaymentInstruction operation. A single-use sender token can only be used once to make a payment. After a single-use sender token is used in a transaction, it becomes obsolete and cannot be used in any further Amazon FPS transactions. If the same sender wishes to make another purchase on your web site, you must direct the sender to the Amazon FPS co-branded UI pipeline to set up a new token. A single-use sender token should contain the parameters specified in the single-use token installation pipeline topic. Amazon FPS uses these parameters to install the token. See the single-use token installation pipeline topic and the InstallPaymentInstruction operation topic for more information. Installing a single-use token In a typical scenario a single-use sender token is installed using the Amazon FPS co-branded UI pipeline. You can set up a URL on your web site that directs your customers (senders) to the Amazon FPS co-branded UI pipeline to install a single-use sender token. The following flowchart uses the one-time payment use case to illustrate the steps involved in setting up a single-use sender token using the Amazon FPS single-use token installation pipeline. Single-use token installation process 1. DigitalDownload is a licensed online retailer that sells audio files (MP3). 2. A sender (customer) visits the DigitalDownload web site, selects a digital content, and clicks the Buy Now button. 3. A signed URL linked to the button directs the sender to the Amazon FPS co-branded UI pipeline. You must create a signed URL using the parameters required to install the token. Example of a signed URL: 22

25 Acquiring Tokens the caller key that is associated with your developer account&pipelinename=singleuse &returnurl= 0.10&Download=Candle+In+the+Wind+-+Elton+John%26uniqueId& &callerReference=DigitalDownload & transactionamount=0.10&paymentreason=to download Candle In the Wind - Elton John&?PaymentAmount=0.10&Download=Candle+In+the+Wind+-+Elton+John &uniqueid= &callerreference=digitaldownload &transactionamount=0.10&paymentreason=candle%20in%20the%20wind%20-%20elton% 20John &awssignature=the awssignature value calculated by you using the URL parameters See the Using a Co-Branded UI Pipeline topic for more information about creating a signed URL. of parameters used in this example are: Parameter Value in this use case callerkey This is a unique value that allows Amazon FPS to identify the caller. This the caller key that is associated with your developer account. pipelinename This is the name of the Amazon FPS co-branded UI pipeline. SingleUse returnurl Amazon FPS uses this URL to redirect the sender to the htweb site with the installed token and status of the intp:// stallation. ldownload.com/paymen tdetails.jsp?payme ntamount& 0.10&Download=C andle+in+the+wi nd+-+elton+john %26uniqueId& &c allerreference=digitaldownl oad & transactionamount=0.10 &paymentreason= To download Candle In the Wind - Elton John callerreference This is a unique value that you must specify to identify the token. You can use this value to retrieve a lost token. 23 DigitalDownload

26 Acquiring Tokens Parameter Value in this use case To keep the value unique this use case appends the timestamp to the callers application title.. paymentreason This is a text in a human readable form that specifies the reason for this payment transaction. To download Candle In the Wind - Elton John transactionamount The transaction amount in this use case The sender views the Amazon.com Sign In page and signs into the Amazon Payments account using the amazon.com Id and password. If the sender does not have an Amazon Payments account, an account registration page is displayed that allows the sender to immediately create an Amazon Payments account See the Amazon FPS Getting Started Guide for more information on Amazon Payments account. After the sender successfully signs into the Amazon Payments account, the payment authorization page is displayed. The payment authorization page displays the transaction details and provides the sender with the option to select a payment method. After selecting the payment method, sender clicks the Continue button. The sender views the summary of payment authorization information. This page displays the transaction details and the payment method selected by the sender. The clicks the Confirm button to proceed. If the sender clicks the Cancel button to abort the pipeline, Amazon FPS redirects the sender to the URL specified in the returnurl parameter with the status of the co-branded UI pipeline request. After the sender clicks the Confirm button, Amazon FPS executes the InstallPaymentInstruction to install the single-use sender token on the sender's account. The sender is then automatically redirected to the destination specified in the returnurl parameter passed to Amazon FPS co-branded UI pipeline. Amazon FPS can return one of the following information about your request: Success the payment instruction (token) installation was successful and a token is returned that you can use in your subsequent Pay call. Error a system error has prevented the token installation on the sender's Amazon Payments account. Cancel the sender has aborted the pipeline by clicking the Cancel button and canceled the token installation. Based on the status parameter returned by the Amazon FPS co-branded UI pipeline, you can perform various tasks. In this example, if the status is success, you can make a Pay web service call on Amazon FPS with the token returned by Amazon FPS and display a success message and a download link to the sender. If the status is error or cancel, you can display a relevant error message to the sender. Co-Branding You can customize the Amazon FPS payment instruction installation and payment authorization web pages to provide your customers with a consistent look-and-feel of the website during their entire 24

27 Acquiring Tokens transaction process. See the Co-branding Preferences section for more information. Acquiring Multi-use Tokens Multi-use tokens are sender tokens that can be set up using the Amazon FPS Co-branded UI pipeline. A multi-use token is the most flexible token that your senders can set up for your application. As the name suggests, a multi-use token can be used multiple times based on the restrictions specified by the sender while setting up the token. A multi-use token can have two types of restrictions Amount limit and Usage limit. You, as a caller, can use this token to charge the sender multiple times to pay a single or multiple recipients. A multi-use token, however, cannot be used to charge the sender for unlimited amount or for unlimited amount of time. Important If you charge your customers at a regular interval for a fixed amount, then you should use the recurring token. Usage Restrictions A multi-use token provides the flexibility of usage based on restrictions or limitations. You can specify two two types of restrictions for a multi-use token amount limit and usage limit. Amount Limit Amount limit specifies maximum amount that can be charged using the token within a specified period or for the life time of the token. For example, the token can be used for a maximum amount of $30 in a month starting from August 10, 2007 or Token can be used for a maximum amount of $30 Usage Limit Usage Limits specifies maximum number of times you can charge the token with in a specified period or for the life time of the token. For example, the token can be used a maximum of 10 times or token can be used for 10 times in a day starting from August 10, 2007 A maximum of 3 usage restrictions can be specified for a multi-use token. For example, a combination of usage restrictions mentioned above will restrict a token to be used 10 times a day for a maximum of $30 in a month. Important Amazon FPS requires you to always to set the maximum amount limit. In addition to the usage restrictions, you can also set one of the following restrictions on the transaction amount. These apply individually to each transaction and not across multiple transactions. Maximum transaction amount for each transaction. Minimum transaction amount for each transaction. Exact transaction amount for each transaction. Calling Application Restriction A multi-use token can be used to pay multiple recipients in a marketplace application. To enable this, the calling application should specify the list of recipients that will receive payments. Once the list of recipients are specified in the token, it cannot be modified. 25

28 Acquiring Tokens Setting Up Multi Use Token The multi-use token installation process is similar to the single-use token installation process, however, the token accepts different set of parameters. You can use the Multi-use Token Installation Pipeline to install a multi-use token on your customers account. As a caller, however, you can use the InstallPaymentInstruction operation to install the multi-use token on your own account. Example - Using Multi-Use Tokens The Multiple Payments Use Case is a complete example on using a multi-use token. Acquiring Recurring Payments Tokens Recurring Payments tokens are subset of multi-use tokens with the following restriction types: Pre-determined fixed amount (Specified at the time of token installation.) Regular interval For example, a subscription for a magazine which charges users $9.99 every month for one year starting on the 10th of March Usage limit restriction: A maximum of once a month Fixed Transaction Amount: Transaction amount is $9.99 Token Validity: Token expires on 10 March :59:59 PM PST Installing Recurring Tokens The recurring token installation process is similar to single-use token installation process. However, a recurring token pipeline accepts different parameters as key-value pair inputs to the pipeline. You must use a recurring token Installation Pipeline if the amount is fixed and frequency of usage is pre-determined. The following are some of the parameters passed during the installation of a recurring payment token: CallerKey = AWS Access Key PipelineName = Recurring Payment Reason = Reason for setting up this token Recipient = Recipient token Return URL = The URL of the page to which the user is redirected back after the token is installed. See the Recurring-use Token Installation Pipeline for more information on the parameters passed in a recurring payments token installation pipeline. Acquiring Recipient Tokens In a market place application, you can make Amazon FPS web service calls to transfer money between a sender and a recipient. In this case you must acquire a recipient token apart from the sender token. A recipient token can have the following restrictions: 26

29 Acquiring Tokens Accepted payment method Agreement to pay fees (if the caller disagrees to pay the fees) Validity of the token Authorizing caller to transfer money The following diagram describes the recipient token installation process using the Recipient Token Installation Pipeline. The recipient token installation process returns two tokens: a recipient token and a refund token. You must store the refund token returned in this pipeline to issue refunds to senders from their respective recipients. Recipient Token Installation Process 27

30 Acquiring Tokens Signed URL See the Signing A URL section for more information about signing a URL. Following are some parameters and respective values that are passed in the market place use case: Parameter Value in this Use Case callerkey This is an access identifier used to identify the caller. NA83EBSV60656N1J58G2 28

31 Acquiring Tokens Parameter Value in this Use Case pipelinename Name of the pipeline being used. Recipient returnurl This parameter is used to specify the caller destination website from the Amazon FPS UI pipeline. sp recipientpaysfee Set this value to true, if the recipient agrees to pay the fees, else set this value to false. True callerreference This is a unique, Caller specific reference used in the token installation to retrieve the token installed by this pipeline. My2Cents Note This use case appends a time stamp to the use case title to keep the value unique. validitystart The validity start date should be within one year from the current date. The date cannot be beyond one year or earlier than the current date. By default this date is current date. Provides seconds using EPOCH time validityexpiry The expiry date should be within one year from the current date. The date cannot be beyond one year or earlier than the current date. By default this date is current date. Provides seconds using EPOCH time paymentmethod A comma separated string that ABT allows you to pass payment methods supported by the recipient. You can specify only CC and ACH as payment methods. If this is not specified then all the three payment methods (CC, ACH, and ABT) are considered to be available. By default, ABT will always be given as payment method option. Note An additional parameter awssignature is appended to the unsigned URL during the 29

32 Using Tokens for Making Payments signing process. This value makes the URL tamper proof. Using Tokens for Making Payments This section explains a simple payment transaction using Amazon FPS. The sequences of events in a payment transaction are: 1. You (caller) need three compatible tokens (sender, caller, and recipient) to execute a Pay call. The GateKeeper constructs in the tokens must be compatible with each other. 2. You can use the InstallPaymentInstruction operation to create a caller token for your account. This is a one-time process. Depending on your role in the transaction, you should also install a recipient token or a sender token on your account using the InstallPaymentInstruction operation. 3. To acquire a recipient token, you must redirect the recipient to the Recipient Token installation pipeline. This is a one-time process for a given merchant. You must store the token Id returned by Amazon FPS. You can skip this if you are a recipient. 4. To acquire the sender token, you must redirect the sender to the single-use or multi-use token or recurring tokeninstallation pipeline. This is done for every purchase made by a sender. You must capture the TokenId returned by Amazon FPS. This TokenId is used as a handle to the sender's Amazon Payments account. 5. You can now use the three tokens as inputs to the Pay operation to execute a payment transaction. Note The sender and recipient token used in the same payment transaction cannot be installed on a same account. The following sections explain the basic concepts in making payments using tokens: Making a Pay Request Handling the Pay response Based on the payment method used in the Pay call, Amazon FPS will return the following types of responses: See the Handling Synchronous Responses section if your Pay uses Amazon Payments account as payment method. See the Using the GetResults Operation section, if your Pay uses credit card or bank account as payment method. Getting Transaction Details Making a Pay Request This section demonstrates the Pay operation request using a simple example. DigitalDownload is a licensed on-line music store that hosts and sells mp3 audio files for $0.10 each. John is a DigitalDownload customer, who uses his credit card to purchase mp3 files. This example has the following roles: DigitalDownload is the caller and the recipient 30

33 Making a Pay Request John is the sender. This example assumes that a caller token and a recipient token is installed on your account and you have used the co-branded pipeline to acquire the sender token. You can use the three tokens to create a Pay operation request along with the following parameters: RecipientTokenId, SenderTokenId, CallerTokenId- Specify the respective token Ids here. TransactionAmount USD TransactionDate - The date of this transaction. SenderReference - DIGUSR12 RecipientReference - Since Caller and Recipient are same, this value is not specified. CallerReference - P3DownloadId-AF12ES ChargeFeeTo - Caller Sender - John Recipient - Since Caller and Recipient are same, this value is not specified. Caller - Digital Content Download MetaData - Digital Content downloaded: Wonderful Tonight - Eric Clapton See the Pay operation reference for more information on each of these parameters. Pay Request Code Sample The following code sample makes a Pay request to Amazon FPS and also handles responses. This Java code sample uses Apache Axis to make web service calls. Note You must change the URL end-point before using this code in the Amazon FPS production environment. The code sample includes in-line comments for more explanation. package usingtokens; import import import import import import java.net.malformedurlexception; java.net.url; java.rmi.remoteexception; java.util.calendar; javax.xml.rpc.serviceexception; com.amazonaws.fps.*; /* * This Class makes a simple Pay Operation to Amazon FPS and captures the response. * It also takes care of handling Pay Response which is the critical part of a Pay Operation. * - Specify the location of the client configuration file -> client-config.wsdd * - Specify the URL Endpoint of <b>amazon FPS Sandbox</b> to test this sample. * * You can compile and run this code by filling out the sender, recipient and caller tokens in the appropriate places. */ public class Pay { 31

34 Making a Pay Request public static AmazonFPSPort setup() throws MalformedURLException, ServiceException { /* Begin SETUP */ /* * Set System configuration. This step constructs the SOAP Headers with the configuration provided in the * client-config.wsdd. This also gives the location and password for the SSL Certificate. * You will be able to set up Security using these three lines of code. */ System.setProperty("axis.ClientConfigFile", "client-config.wsdd"); //Sets up the Amazon FPS Service Port from the URL endpoint provided to you. URL endpoint = new URL("Enter your web service end point URL"); AmazonFPSPort amazonfpsport = new AmazonFPSLocator().getAmazonFPSPort(endpoint); /* End SETUP */ return amazonfpsport; } public static void main([] args) throws ServiceException, RemoteException, MalformedURLException { //Do a setup. AmazonFPSPort amazonfpsport = setup(); /* Begin construction of Pay Request */ //Creating a 'PayRequest' object PayRequest payrequest = new PayRequest(); /* Set Required Parameters. */ /* Specify the Caller, Recipient and Sender Tokens here. * In this Example, Caller and Recipient Tokens are installed on DigitalDownload's Amazon Payments * using InstallPaymentInstruction API Call.Sender Token is installed on John's Amazon Payments and * acquired by DigitalDownload. * */ payrequest.setcallertokenid("specify the caller token Id"); payrequest.setrecipienttokenid("specify the recipient token Id"); payrequest.setsendertokenid("specify the sender token Id"); //Transaction Amount of $0.10 for the Mp3 Requested by John. payrequest.settransactionamount(new Amount(CurrencyCode.USD, "0.10")); /* Pay is idempotent on CallerReference. Make sure that you pass a unique CallerReference for * each transaction. This CallerReference represents your business logic to retrieve transactions. * In this use-case, this is the unique DownloadId for this particular download. * */ payrequest.setcallerreference("mp3downloadid-af12es"+ Calendar.getInstance().getTimeInMillis()); /* Set the ChargeFeeTo parameter which defines how the fees will be distributed. * Amazon FPS Fees can be paid either by the Caller or the Recipient. * In this use-case, since caller=recipient, it doesn't matter. 32

35 Making a Pay Request */ payrequest.setchargefeeto(chargefeeto.caller); /* The caller can specify a transaction date that will be saved along with the transaction as shown below. */ payrequest.settransactiondate(calendar.getinstance()); /* Set Optional Parameters. */ /* Caller can be set to give additional information about the caller. */ payrequest.setcaller("digital Content Download."); /* Set MetaData which is a free form field to store 2KB of transaction related data*/ payrequest.setmetadata("digital Content downloaded: Wonderful Tonight - Eric Clapton"); /*Recipient Related Information. * In this use-case, it doesn't make sense to set Recipient information because caller=recipient * */ payrequest.setrecipient(""); payrequest.setrecipientreference(""+calendar.getinstance().gettimeinmillis()); /* Sender Related Information * In this use-case, Sender reflects the name of the sender and sender reference reflects the user id of the sender. * */ payrequest.setsender("john"); payrequest.setsenderreference("digusr12"+calendar.getinstance().gettimeinmillis()) ; /* End Construct PayRequest */ // This is the call to the 'Pay' Operation. PayResponse payresponse = amazonfpsport.pay(payrequest); /* Start Handling PayResponse */ // Checking the status returned by the 'pay' API call. if (payresponse.getstatus().getvalue().equals(responsestatus._success)) { /* Handling Pay Operation Success Case */ //Get the Transaction response. TransactionResponse transactionresponse = payresponse.gettransactionresponse(); //Get the TransactionId for the Pay Operation Executed. transactionid = transactionresponse.gettransactionid(); /* This Sample Code prints only the TransactionId and a message. * You can take some action like storing the Transaction details, marking your Db etc. according to your business logic. */ /* Handle Syncronous Response */ if (transactionresponse.getstatus().getvalue().equals(transactionstatus._success )) { /* Transaction Status Success. Instant success happens in Account Balance Transfer where the money moves * from the Sender's Amazon Payments to the Recipient's Amazon Payments. */ System.out.println("Pay Succeeded and the money has been transferred from the Sender's Payment Instrument to the Recipient's Amazon Payments."); Sys- 33

36 Making a Pay Request tem.out.println(transactionresponse.getstatusdetail()); // This Sample code prints the TransactionId only. You can get the Transaction Details by using GetTransaction Operation. System.out.println("TransactionId: " + transactionid); } if (transactionresponse.getstatus().getvalue().equals(transactionstatus._tempora rydecline)) { /* Transaction Status RetriableFailure. This happens due to some locks on the accounts or tokens used in the Pay Operation. * You can Retry the Transaction using a background thread using the RetryTransaction Operation. */ System.out.println("Retry after some time for the pay to succeed!"); System.out.println(transactionResponse.getStatusDetail()); System.out.println("Use this TransactionId \"" + transactionid + "\" in the RetryTransaction Operation."); } /* Handle Asynchronous Response */ if (transactionresponse.getstatus().getvalue().equals(transactionstatus._initiat ed)) { /* Transaction Status Initiated. This happens when Amazon FPS has initiated a transaction, but will take some time to complete. * This happens when the Sender uses either a Credit Card or a Bank Account to make a payment. Normally Credit Card transactions * take 6-7 seconds to complete and Bank Account Transactions take about 4 days to complete. */ //You can use either GetResults\DiscardResults or Caller Notifications to poll for the Transaction Status. System.out.println("Transaction Initiated. Poll for results to know the Transaction Status."); System.out.println(transactionResponse.getStatusDetail()); System.out.println("TransactionId: " + transactionid); } if (transactionresponse.getstatus().getvalue().equals(transactionstatus._failure )) { /* Transaction Status Failure. This happens only when Transaction Status was Initiated sometime back. */ System.out.println("Transaction Failed"); System.out.println(transactionResponse.getStatusDetail()); //In this case you can execute your business logic like stop shipping the product etc. } } else { /* Handling Pay Operation Failure Case */ //Note that handling pay operation failure case is Synchronous. ServiceError[] serviceerrors = payresponse.geterrors().geterrors(); System.out.println("Following errors occured in the Pay API Call."); for (int i = 0; i< serviceerrors.length ; i++) { System.out.println("There is some Business error in the Pay Operation Call. " 34

37 Making a Pay Request + "Refer to the ErrorCode and ReasonText for specific information."); System.out.println("ErrorCode: " + payresponse.geterrors().geterrors(0).geterrorcode()); System.out.println("ReasonText: " + payresponse.geterrors().geterrors(0).getreasontext()); } } /* End Handling PayResponse */ } } Pay Request Code Sample - Detail The following section discusses the Pay request code sample. The sample code discussed is written in the Java language. One-Time Setup This part of the code snippet is used to setup the system configuration information required to construct SOAP headers and SSL certificate. client-config.wsdd - Contains information that Apache Axis uses to construct SOAP addressing and security headers. This file also contains the location of the Caller's X.509 certificate. See line 1 of the code snippet. Amazon FPS Sandbox URL end-point - The location of Amazon FPS Sandbox. See line 4 of the code snippet. Line 5 of the code snippet creates a AmazonFPSPort object from the Sandbox URL end-point. This object takes care of sending a valid request to the web service end-point and receiving a response. This object encapsulates a remote function call on the client side. /* Begin SETUP */ 1. System.setProperty("axis.ClientConfigFile", "<Enter the location of client-config.wsdd file.>"); 4. URL endpoint = new URL("<Specify Amazon FPS Sandbox endpoint>"); 5. AmazonFPSPort amazonfpsport = new AmazonFPSLocator().getAmazonFPSPort(endpoint); /* End SETUP */ Constructing Pay Reqest This part of the code snippet constructs a PayRequest for payment. A Pay operation can contain one or more Pay requests and are submitted using a PayBatchRequest. Lines 1, 2 & 16 construct the PayReqest by adding a single Pay request object. Lines 3-15 sets the parameters of the Pay request object. Lines 3,4 & 5 specify the tokens involved in the payment transaction. Line 6 specifies the transaction amount. In this use-case, the transaction amount of $0.10 is set for the mp3 file requested by John. Line 7 specifies a unique Caller reference (MP3DownloadId-AF12ES) for this download. 35

38 Making a Pay Request Line 8 specifies the participant that will pay the transaction fees. Amazon FPS transaction fees are paid either by the Caller or the Recipient. In this use-case, Caller and Recipient are the same entity. Lines 9-15 sets the optional parameters for the Pay request. The optional parameters are specific to the roles and can be retrieved as a part of transaction details. In this use-case, line 14 specifies the unique SenderId for John on DigitalDownload.... /* Begin Construct Pay Request */ //Creating a 'PayRequest' object 1 --> PayRequest payrequest = new PayRequest(); /* Set Required Parameters. */ /* Specify the Caller, Recipient and Sender Tokens here. * In this Example, Caller and Recipient Tokens are installed on DigitalDownload's Amazon Payments * using InstallPaymentInstruction API Call.Sender Token is installed on John's Amazon Payments and * acquired by DigitalDownload. * */ 2 --> payrequest.setcallertokenid("specify the caller token Id"); 3 --> payrequest.setrecipienttokenid("specify the recipient token Id"); 4 --> payrequest.setsendertokenid("specify the sender token Id"); //Transaction Amount of $0.10 for the Mp3 Requested by John. 5 --> payrequest.settransactionamount(new Amount(CurrencyCode.USD, "0.10")); /* Pay is idempotent on CallerReference. Make sure that you pass a unique CallerReference for * each transaction. This CallerReference represents your business logic to retrive transactions. * In this use-case, this is the unique DownloadId for this particular download. * */ 6 --> payrequest.setcallerreference("mp3downloadid-af12es"+ Calendar.getInstance().getTimeInMillis()); /* Set the ChargeFeeTo parameter which defines how the fees will be distributed. * Amazon FPS Fees can be paid either by the Caller or the Recipient. * In this use-case, since caller=recipient, it doesn't matter. */ 7 --> payrequest.setchargefeeto(chargefeeto.caller); /* The caller can specify a transaction date that will be saved along with the transaction as shown below. */ 8 --> payrequest.settransactiondate(calendar.getinstance()); /* Set Optional Parameters. */ /* Caller can be set to give additional information about the caller. */ 9 --> payrequest.setcaller("digital Content Download."); /* Set MetaData which is a free form field to store 2KB of transaction related data*/ 10 --> payrequest.setmetadata("digital Content downloaded: Wonderful Tonight - Eric Clapton"); /*Recipient Related Information. * In this use-case, it doesn't make sense to set Recipient information because caller=recipient * */ 11 --> payrequest.setrecipient(""); 12 --> payrequest.setrecipientreference(""+calendar.getinstance().gettimeinmillis()); /* Sender Related Information * In this use-case, Sender reflects the name of the sender and sender reference reflects the user id of the sender. * */ 13 --> payrequest.setsender("john"); 14 --> payrequest.setsenderreference("digusr12"+calendar.getinstance().gettimeinmillis()) ; /* End Construct Pay Request */ 36

39 Handling Synchronous Responses... Making the Pay Request This part of the code snippet makes a Pay operation request to Amazon FPS and retrieves the response. See Lines 1 & /* End Construct PayBatchRequest */ 1 --> 2 --> // This is the call to the 'Pay' Operation. PayResponse payresponse = amazonfpsport.pay(payrequest); /* Start Handling PayResponse */... Resending a Request A Pay operation request to Amazon FPS or its response from Amazon FPS might not reach its destination due to underlying network failures. During such situations, you can resend the request to Amazon FPS. If Amazon FPS receives the same request again, a response is sent with the result of the previous request sent with exactly the same parameters. Amazon FPS will not execute a new transaction. Important All the parameters that in the request you resend should contain the same parameters that were sent in the initial request. Handling Synchronous Responses Amazon FPS sends a synchronous response if you use Amazon Payments account, Prepaid, or Postpaid as a payment method. This section provides information on handling synchronous responses for a Pay request. Steps involved in handling synchronous responses 37

40 Handling Synchronous Responses The following steps explain the various tasks in handling a response. The code snippets are part of the Pay operation request constructed in the Making a Pay Request section: 1. Pay operation request is sent to Amazon FPS. Amazon FPS processes the request and returns a response. See Constructing Pay Reqest for code sample. 2. The following code snippet captures the response returned by Amazon FPS and checks for the response status PayResponse payresponse = paybatchresponse.getresponses(0); /* Start Handling PayResponse */ 2. if (payresponse.getstatus().getvalue().equals(responsestatus._success)){... The response can either be success or failure. 38

41 Handling Synchronous Responses 3. Response status = failure. A Pay operation request can fail due to many reasons. For example: One of the parameters in the Pay request is incorrect The request contains incompatible tokens Insufficient funds in the sender's account Some of these failures are marked with a flag isretriable=true. In such cases, you can use the same request or create a new request with same caller reference and resend it to Amazon FPS. For example, this flag is set, if the funds in sender's account are insufficient. You can resend the same request and it will succeed if the sender has added funds. See the Web Service API Reference section for a complete list of errors and failures. The following code snippet handles business errors: if(error.equals(error._business)){ 2. System.out.println("There is some Business error in the Pay Operation Call." + "Refer to the ErrorCode and ReasonText for specific information"); 3. System.out.println("ErrorCode: "+payresponse.geterrors().geterrors(0).geterrorcode()); 4. System.out.println("ReasonText: "+payresponse.geterrors().geterrors(0).getreasontext()); 5. if(payresponse.geterrors().geterrors(0).isisretriable()){ 6. System.out.println("Retry after some time for the pay to succeed!"); 7. } 8. } Response status = success. The following code snippet captures the transactionid corresponding to the transaction.... /* Handling Pay Operation Success Case */ transactionid = payresponse.gettransactionid();... Note You must store the transaction Id, caller reference and other parameters as show in the table (?) Check the transaction status. If the transaction status is success, you can use the transactionid in a GetTransaction operation request to retrieve more details about the transaction. The following code snippet uses the transactionid to print the status of the success transaction if(payresponse.gettransactionstatus().equals(transactionstatus._success)){ 2. System.out.println("Pay Succeeded and the money has been transferred from the sender's payment instrument to the recipient's Amazon Payments Account."); 3. System.out.println("TransactionId: "+transactionid); 4.}... The code samples section lists the complete code required to get transaction details. a. Response status=success and Transaction status = initiated. You will receive the inititated transaction status in an asynchronous response. You can handle asynchronous responses using either the GetResults operation or by subscribing to Amazon FPS notifications. 39

42 Handling Asynchronous Responses Note You must subscribe to Amazon FPS web service notification functionality before executing the transaction. This ensures that you do not loose the transaction results. To poll for results you can use the GetResults operation or to receive notifications on your transactions you can subscribe to the notification functionality. See Using the GetResults Operation section for more information about handling asynchronous response using GetResults operation. b. Response status =Success and Transaction status =Temporary decline. You can either retry the transaction till it succeeds using the Retry operation or invoke a error handling code. The following code snippet handles retriable failures and prints the transactionid if(payresponse.gettransactionstatus().equals(transactionstatus._retriable Failure)){ 2. System.out.println("Retry after some time for the pay to succeed!"); 3. System.out.println("Use this TransactionId \""+transactionid+"\" in the RetryTransaction Operation."); 4. }... In the sandbox environment, the temporary decline will return a success result after you retry the transaction twice. See the Sandbox page for more information. Handling Asynchronous Responses Amazon FPS transactions that use credit card or bank accounts are not completed synchronously. You can use either the GetResults operation or the web service notification functionality to manage the asynchronous responses. Handling asynchronous responses using the GetResults operation Handling asynchronous responses using the web service notification Important You can use only either of the options to handle asynchronous response. If you subscribe to the notifications functionality you will not be able to use the GetResults operation and vice versa. Using the GetResults Operation Credit card and bank account transactions might not complete before the Pay operation returns a synchronous response. For such transactions, you can use the GetResults operation to poll for transaction results. The GetResults operation has options to filter results based on these payment operations Pay, Refund, FundPrepaid, SettleDebt, and Reserve. In addition, you can also specify the number of transaction results (maximum of 25) to be polled from Amazon FPS. When you make a GetResults request, Amazon FPS will return the number of results as specified in 40

43 Handling Asynchronous Responses the request. You should process these results and discard them using the DiscardResults operation before requesting for a new set of results. Important If you request for new set of results without discarding the results, Amazon FPS may return the same set of results that were sent in the previous request. Amazon FPS sets a read-lock timeout of 60 seconds on the results returned for a previous GetResults request. This read-lock timeout automatically expires after 60 seconds, unless the results are discarded before that. This allows you to initiate multiple GetResults requests to simultaneously poll for transaction results, thus increasing the throughput of your application. The following table illustrates this behavior: Run Time No of available results Results requested Results returned Results discarded Note 1 08:10: new results 0 Results are not discarded 2 08:12: from the previous result 20 Results are discarded after the GetResults call. 3 08:14: new results :14: new results :14: new results :14: new results 0 These requests were made within 60 seconds. Best practices for using the GetResults operation We recommend that you use the GetResults operation only if there are any transactions from these payment operations Pay, Refund, FundPrepaid, SettleDebt, and Reserve in the initiated or reinitiated state. Discarding Results When you use the GetResults operation to poll for results, Amazon FPS will return the number of results (or a maximum of 25) as specified in the request. You can process these results and discard them before you poll for the next set of results. To discard old results use the DiscardResults operation. 41

44 Handling Asynchronous Responses You should discard results to avoid receiving the same set of results again. Amazon FPS returns fresh results only if at least one of the previous results is discarded and the discarded results are not retained by Amazon FPS. The following table illustrates how the DiscardResults operation works: Run Results Available Results Received Results Discarded 1 35 First First 20 and next All remaining All How often you can use the GetResults operation to poll for results depends on the payment method used in the transaction. Transactions that use credit card as payment method take 3 to 4 seconds to complete, so you can poll for results in short intervals of time. Transactions that use bank accounts, however, take 5 to 7 days to complete. If your transaction uses a bank account and you used the GetResults operation in short intervals of time, Amazon FPS probably won't send any results. You should, however, poll for results frequently if you have many transactions in the initiated state. Handling GetResults Response This part of the topic explains how you can handle GetResults response. As an illustration, we will see how the DigitalDownload (see One-time payment use case) stores all the details corresponding to each transaction (download request) executed on the web site. The table below is an illustration on the type of information stored by DigitalDownload: Download Id Transaction Id User Id User Name Transaction Status Business Operation DL111 A11 Jn476GB John Initiated Download Audio MP3 DL222 B22 Je712RL Joe Failure Download Video MPEG DL333 C33 My333TP Mary Success Download Audio MP3 DL444 D44 LZ749BB Orchid Initiated Download Audio MP3 DL555 E55 Jm487RL Jim Success Download Video MPEG DownloadId This is the primary key used as the Caller reference in the original transaction. TransactionId This is the reference to the original transaction returned by Amazon FPS. 42

45 Handling Asynchronous Responses UserId This is a unique ID given to every customer by DigitalDownload. This is also used as the Sender reference in the original transaction. Transaction Status This is the status of the original transaction based on which a business decision is made. Business Operation This is the business operation performed by DigitalDownload for a particular transaction. Status of Business Operation Displays the action taken on the business operation. Code snippet from the Pay request that handles asynchronous response /* GetResults API response will contain the particular Transaction ID when the * transaction has finally been completed. * This is expected to happen in a very short duration of time on the Sandbox Environment. */ /* Create a 'GetResultsRequest' object */ GetResultsRequest getresultsrequest = new GetResultsRequest(); /* Set Required Parameters. */ /* Set the maximum number of results. Max value for this field is 24 */ getresultsrequest.setmaxresultscount(new BigInteger("24")); /* This is the call to the 'GetResults' Operation.*/ GetResultsResponse getresultsresponse = afps.getresults(getresultsrequest); /* Begin Process GetResults Response */ /* Check the status returned by the 'getresults' API call. */ if (getresultsresponse.getstatus().getvalue().equals(responsestatus._success)) { /* Handling GetResults Operation Success Case */ TransactionResult[] transactionresults = getresultsresponse.gettransactionresults(); if (transactionresults!= null) { /* Initializing an array to store the transaction ids which have to be discarded later. * * NOTE: The code below makes a list of all the transaction results received. If there are * more than 24 old undiscarded results, then your new transaction results might not be * returned until you discard the old results. So, below all the old results of this caller * account are discarded until the required result (of the current transaction) is returned. * * IMPORTANT: Before discarding all the old results make sure that you will not be needing them * in future. * */ discardtransactionids = new [transactionresults.length]; for(int i=0; i<transactionresults.length; i++) { discardtransactionids[i] = transactionresults[i].gettransactionid(); if (transactionresults[i].gettransactionid().equals(transactionid)) 43

46 Handling Asynchronous Responses { // Search for the required Transaction ID in the results returned by the // Get Results API. callgetresults = false; resultfound = true; transactionstatus = transactionresults[i].getstatus().getvalue(); log.info("getresults API call successful for Transaction ID: " + transactionid); if (transactionstatus.equals(transactionstatus._success)) { /* Transaction Status Success. Instant success happens in Account Balance Transfer where the money moves * from the Sender's Amazon FPS Account to the Recipient's Amazon FPS Account. * We will have Instant transfers from Credit Card\Bank Account to Amazon FPS Account in future. */ log.info("pay Succeeded and the money has been transferred from the Sender's Payment Instrument to the Recipient's Amazon FPS Account."); // This Sample code logs the TransactionId only. You can get the Transaction Details by using GetTransaction Operation. log.info("transactionid: " + transactionid); } else if (transactionstatus.equals(transactionstatus._temporarydecline)) { /* Transaction Status TemporaryDecline. This happens due to some locks on the accounts or tokens used in the Pay Operation. * You can Retry the Transaction using a background thread using the RetryTransaction Operation. */ error = "Pay request has been declined temporarily. Please retry after some time for Pay to succeed!<br>"; error += "<br>transactionid: " + transactionid; error += "<br>please refer to the developer documentation for more information about RetryTransaction API."; errormessages += "Your transaction has been declined temporarily. Please check the status later by visiting " + "your account section of this web site."; } else if (transactionstatus.equals(transactionstatus._failure)) { /* Transaction Status Failure. This happens only when Transaction Status was Initiated sometime back. * It might fail due to various reasons like "not enough balance in the Bank Account" etc. * You get this status by polling for a transaction. */ error = "Pay Transaction Status: " + transactionstatus; //+ ".<br> Please click on the link below to proceed to the home page."; error += "<br>transactionid: " + transactionid; 44

47 Handling Asynchronous Responses //In this case you can execute your business logic like stop shipping the product etc. errormessages += "Your transaction has been declined."; } /* In case the required transaction result (of the current transaction) is received, * there is no need to discard all the old results. So the array below is reinitialized * such that only the current transaction's result will be discarded. * */ discardtransactionids = new [] {transactionid}; break; } } } } else { callgetresults = false; /* Handling GetResults Operation Failure Case */ ServiceError[] serviceerrors = getresultsresponse.geterrors().geterrors(); error = "Following errors occured in the GetResults API Call. "; for (int i = 0; i< serviceerrors.length ; i++) { error += "<br><br>error: " + serviceerrors[i].geterror().getvalue(); error += "<br>errorcode: " + serviceerrors[i].geterrorcode(); error += "<br>reasontext: " + serviceerrors[i].getreasontext(); } error += "<br><br><i><span class=\"note\">these are the error codes returned by Amazon FPS. " + "You can map them to your business logic.</span></i>"; } /* End Processing of GetResults Response */ } The following figure shows the types of transaction status received in a GetResults response. 45

48 Handling Asynchronous Responses For each result of the GetResults operation you must check the transaction status and take appropriate action. If the transaction status is: Temporary Decline, see Temporary Decline Status Failure, see Failure Status Success, see Success Status When DigitalDownload makes a GetResults operation request, the following transaction results are returned: Temporary Decline status for Caller reference DL111 Failure status for Caller reference DL222 Success status for Caller reference DL333 Temporary Decline Status Amazon FPS returns a Temporary Decline for the following reasons: Temporary system failure Pending investigation When Amazon FPS returns temporary decline status, you can retry the transaction within four days of the failure using the RetryTransaction operation. The RetryTransaction operation can return the following status on the transaction: Failure Success Note 46

49 Handling Asynchronous Responses Amazon FPS rejects the request to retry a transaction that is not in the retriable failure state. The following diagram illustrates handling a temporary failure response. 1. Retrieve the row corresponding to the caller reference DL111 from the database table. Download Id DL111 Transaction Id A11 User Id Jn476GB User Name John Transaction Status Initiated Business Operation Download Audio MP3 Status of Business Operation Download Pending 2. DigitalDownload can decide to retry the transaction. If DigitalDownload decides to retry the transaction, the following steps are executed: a. DigitalDownload calls the RetryTransaction operation with the TransactionId. Results can be polled for this transaction at later point in time. b. After retrieving the result, DigitalDownload calls the DiscardResults operation after processing the transaction. It is important to discard results to avoid receiving the same results for every GetResults operation. If DigitalDownload decides not to retry the transaction, the following steps are executed: a. DigitalDownload marks the transaction status as Failure and the download status as Download Canceled. 47

50 Handling Asynchronous Responses Down load Id DL111 Trans action Id A11 User Id Jn476GB User Name John Trans action Status Failure Business Operation Download Audio MP3 Status of Business Operation Download Canceled b. DigitalDownload sends an to John describing the failure encountered in processing the payment transaction. c. DigitalDownload calls the DiscardResults operation after processing the transaction. It is important to discard results to avoid receiving the same results for every GetResults operation. Note You will receive the results of the retried transaction synchronously or asynchronously based on the payment method used in the transaction. Failure Status The following diagram illustrates handling failure responses. 48

51 Handling Asynchronous Responses 1. DigitalDownload retrieves the row corresponding to the Caller reference DL222 from the database table. Download Id DL222 Transaction Id B22 User Id Je712RL User Name Joe Transaction Status Failure Business Operation Download Video MPEG Status of Business Operation Download still pending 2. DigitalDownload marks transaction status as Failure and download status as canceled.. 49

52 Handling Asynchronous Responses Download Id DL222 Transaction Id B22 User Id Je712RL User Name Joe Transaction Status Failure Business Operation Download Video MPEG Status of Business Operation Download Canceled 3. DigitalDownload sends an to your customer (Joe) describing the failure encountered in processing the payment transaction. 4. DigitalDownload makes a DiscardResults operation after processing the transaction. It is important to discard results to avoid receiving the same results for every GetResults operation. Success Status The following diagram illustrates about handling success status. 1. Retrieve the row corresponding to the Caller reference DL333 from the database table. 50

53 Handling Asynchronous Responses Download Id DL333 Transaction Id C33 User Id My333TP User Name Mary Transaction Status Success Business Operation Download Audio MP3 Status of Business Operation Download Successful 2. Mark the transaction status as Success and update the business operation status as Download Successful. Download Id DL333 Transaction Id C33 User Id My333TP User Name Mary Transaction Status Success Business Operation Download Audio MP3 Status of Business Operation Download Successful 3. DigitalDownload sends an to the customer with a link to download the MP3 file. 4. DigitalDownload calls the DiscardResults operation after processing the transaction. It is important to discard results to avoid receiving the same results for every GetResults operation. Using the Web Service Notifications Amazon FPS allows you to handle the asynchronous transaction responses using the web service notification. You can subscribe to the web service notification using the SubscribeForCallerNotification operation. After you subscribe to the notification service, all the asynchronous responses are sent as web service notifications. Asynchronous responses for the transactions executed during this period (after subscribing for the web service notification) are no longer available in the GetResults operation response. If you want to use the GetResults operation for asynchronous responses again you must unsubscribe to the web service notification. Call the the UnSubscribeForCallerNotification operation to unsubscribe. The notification functionality allows you to receive notifications after you make a transaction operation or cancel a token. To receive these notifications you must set up and host a web service as described in this topic. Important Amazon FPS sends the notifications only using the HTTPS protocol. Amazon FPS currently sends the notifications for the transaction operations and token cancellations. The following transaction operations are supported: Pay 51

54 Handling Asynchronous Responses Refund Reserve Settle RetryTransaction FundPrepaid SettleDebt Setting Up Your Web Service to Receive Notifications To build the web service application Implement the web service using the Amazon FPS notification service WSDL. The notification service WSDL is available in the JAVA web service notification sample uploaded in the Amazon FPS Resource center (Community Code category). The sample applications in Java SDK uses Apache Axis to generate server side stubs to implement the notification service. To create server trust store Your web server's trust store must contain the Amazon FPS notification certificate. Download the sandbox and production X.509 certificates from the Amazon FPS Resource Center ( Import the notification service certificate using the keytool. keytool -import -file cert.pem -alias alias -keystore keystore_filename storepass keystore_password To set up the Tomcat server 1. You must create a keystore using the AWS X.509 certificate (public) and the private key pair associated with your AWS developer account. You can download these key pairs from the AWS web site ( These keys are required to set up an SSL connection between Amazon FPS and your service. See the Setting Up Your AWS Developer Account section in the Getting Started Guide for more information. Note If you have created a keystore for the SDK application you can use the same keystore for setting up the web service and skip to step Execute the following command from the folder that contains the private key file and the certificate file: openssl pkcs12 -export -inkey private_key_file_name.pem -in certific- 52

55 Handling Asynchronous Responses ate_file_name.pem -name "tomcat" -out keystore 3. This creates the keystore. After you generate the keystore, host the web service on the default HTTPS port (443) on your Tomcat server. An example of the server.xml file (TOMCAT_BASE/conf folder) for setting up the web service on Tomcat is given below.... <Connector port="443" maxhttpheadersize="8192" maxthreads="150" minsparethreads="25" maxsparethreads="75" enablelookups="false" disableuploadtimeout="true" acceptcount="100" scheme="https" secure="true" clientauth="false" sslprotocol="tls" keystorefile="keystore filename" keystorepass="keystore password" keystore="pkcs12"/> Restart Tomcat. You web server is now ready to receive notifications from Amazon FPS. Sample Notification The following SOAP request is an example notification sent by Amazon FPS to your web server after a Pay operation. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" <SOAP-ENV:Header> <wsse:security xmlns:wsse=" SOAP-ENV:mustUnderstand="1"> <wsse:binarysecuritytoken xmlns:wsu=" tility-1.0.xsd" Encoding=" curity-1.0#base64binary" Value=" -profile-1.0#x509v3" wsu:id="xwssgid ">miicjzccaxccagzgma0gcsqgsib3dqebbqua MDkxIjAgBgNVBAMTGUFtYXpvbi5jb20gSVQgU2Vj dxjpdhkgq0exezarbgnvbaotckftyxpvbi5jb20whhcnmdcwnda5mtexnzq5whcnmtiwnda4mtexnzq5w jblmqswcqydvqqgewjvuzetmbega1uecbmkv2 FzaGluZ3RvbjEYMBYGA1UEChMPQW1hem9uLmNvbSBJbmMuMScwJQYDVQQDEx5mcHMtbm90aWZzZXJ2aW NlLmFtYXpvbmF3cy5jb20wgZ8wDQYJKoZIhvcN AQEBBQADgY0AMIGJAoGBALBZncasOW4eObM2ZbVEs50IzDbJe8inZ+SUE+/KIWiVSk5VvHXu6aTBw 8eKCC2pAaxDBktnXZdTqW8kVUexUVyvZ2Mbw1m5I+ 9B7rDIWal11moRxEvBlbWfKaA/eyHtH+zq053OsHFGQ+2iofYKIb8GWgJ2SjaJioC5ds7UjtN7AgM BAAEwDQYJKoZIhvcNAQEFBQADggEBALWRYBv/WNxv 0g+JKIGo3tgRnccQ0FfuTlsvzLd6ZRvTfltKX2WL4pQsf4ZF/yqA41ZSLC3ca5OKhiEcQrNWnBRmQ PIwuVw3FESylfl/ymAJ93yuFtg3TL6F0eyQP6Sn2q DODIdevJfII5qsaj+Nt0xkCSesFTq7UVfyIDCnPVJqPvX3YafYLZUbXMhFdIeT5LXyhVyKwWWZfzD SZuJZjpg6w2d5fFIWVm+C5YDPggsDhyZoxwIKVp13 HYpyhw+5S8/FNmKfoGbCkz462Y2n95gASrQtXMIgYfF0xQ+1dDC+OAuRvkmAwUApaPiz6H/3sRB9/J/UK OPkrBY6nWmvFWc= </wsse:binarysecuritytoken> <ds:signature xmlns:ds=" 53

56 Getting Transaction Details <ds:signedinfo> <ds:canonicalizationmethod Algorithm=" <InclusiveNamespaces xmlns=" PrefixList="wsse SOAP-ENV"/> </ds:canonicalizationmethod> <ds:signaturemethod Algorithm=" <ds:reference URI="#XWSSGID "> <ds:digestmethod Algorithm=" <ds:digestvalue>qayxyfqsz8gg4whrn3zif32se5k=</ds:digestvalue> </ds:reference> <ds:reference URI="#XWSSGID "> <ds:digestmethod Algorithm=" <ds:digestvalue>wtz2j+dbvyhdolxspnxqih7gqg8=</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue> HxC16F/yMDeLk+rXGx8p7s18iitnrmhloqFSWWSmcForyrp8GBYEmJ5BhpXb9H0b51N0k4EDxVTr TR4sFD4W4Gl+zkBZcPSO7Kfq6Qd7NjgpjQf3plTTCQBIWE8vMXv5Er5HlX79tz9NFHwn88QbfcnK qtnxynhdfqhzcgswthg= </ds:signaturevalue> <ds:keyinfo> <wsse:securitytokenreference xmlns:wsu=" tility-1.0.xsd" wsu:id="xwssgid "> <wsse:reference URI="#XWSSGID " Value= </wsse:securitytokenreference> </ds:keyinfo> </ds:signature> <wsu:timestamp xmlns:wsu=" tility-1.0.xsd" wsu:id="xwssgid "> <wsu:created> t14:18:37z</wsu:created> <wsu:expires> t14:18:42z</wsu:expires> </wsu:timestamp> </wsse:security> </SOAP-ENV:Header> <SOAP-ENV:Body xmlns:wsu=" tility-1.0.xsd" wsu:id="xwssgid "> <TransactionResult xmlns=" <TransactionId>12DK6BJOD5BOE7GZF8N54DP67OP5NE2F4VQ</TransactionId> <Operation>Pay</Operation> <CallerReference>ReferenceÅ-Å Å»ÅuC8j </CallerReference> <TransactionStatus>SUCCESS</TransactionStatus> </TransactionResult> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Getting Transaction Details You can use the GetTransaction operation to query specific details on any completed transaction. This operation gives the status of the transaction and history of the transaction. Important The GetTransaction is network and CPU intensive and should be used only when you 54

57 Managing Tokens need all information related to a transaction. Managing Tokens You have to store tokens acquired from your customers (sender or recipients) to use them in transactions. Amazon FPS allows you to query for tokens that your customers have installed to your application. For more information, see the Retrieving tokens section. Amazon FPS, does not allow you to modify tokens on any account other than your own account. You can get your customers to modify their tokens for the following reasons: The payment method associated with your customer's token is not valid. For example, the credit card validity has expired or credit card is canceled. The customer has changed to a new payment method. For example, the customer wants to use a credit card instead of the bank account. To edit tokens you can use the Amazon FPS edit token co-branded pipeline. See the Editing Tokens section for more information. Retrieving Customer Tokens In any co-branded UI pipeline a token is returned to you through the HTTP redirect. If your customer loses connectivity or the browser crashes while the customer is being redirected you may not get the token. You can query for the tokens that your customers have installed on their accounts for your application using the GetTokensByCaller operation. The co-branded UI pipelines accepts a unique caller reference as an input. You must always specifiy a unique caller reference. Though you can use GetTokensByCaller operation to retrieve all tokens, we recommend that you query for a specific token by passing the caller reference corresponding to that token. Editing Tokens You can edit an existing token using the edit token pipeline. Once the token is edited Amazon FPS cancels the old token and installs a new token on your customer's account. If your customer does not return to your web site you will still have an old token. Using this old token will cause the transactions to fail. To avoid using old tokens use the GetTokensByCaller operation with the old TokenId. This operation returns a new token. It is a good practice to call this operation before executing a transaction on Amazon FPS to avoid transaction failures. The edit token pipeline Displays information on the existing payment method and token details. Your customer can choose to abort and return to your web site if they are not interested in changing the payment details. Can be used to update the credit card expiry date. The old token is returned as an output to the pipeline in this case. Has the options to update payment method details and receive a new token. Your customers can choose to use a new payment instrument for the existing payment method or use a new payment method altogether. Example 55

58 Managing Your Account A customer who has previously used a credit card can update the payment method either by providing a different credit card or by using a bank account for transactions. You can control the payment method options available to your customers by passing your preferences as inputs to the pipeline. In such case you receive a new token which you must use for all the transactions. If you have already used the old token for making payments, the usage limits are transferred to this new token. Example For example, if the old token was used 10 times and the token's usage restriction is 20 times, then your new token inherits the old usage limit and you can use the new token for only 10 times. Managing Your Account This section provides information on account management features that help you to view your account activity, account balances, manage web site customization, manage Amazon FPS notifications, and manage customer refunds. Topics: View Account Activity Account Balance Co-branding preferences Notification preferences Issue Refunds Additionally, you can also manage the security certificates on your account. See the First Steps section in the Amazon FPS Getting Started Guide to understand how you can set up certificates on your account. View Account Activity and Transaction Details Amazon FPS provides an online user interface and web service API that allows you to get information on your account and transactions. Online User-interface Sign in to your Amazon Payments account and click the Account Management tab to view the following information about your account and transactions executed on your account: List of all transactions executed on your account List of all account activity with information on the payments made or received using credit cards, Amazon Gift Certificate or echecks and funds deposited or withdrawn from your account The Account Management page allows you to filter these results using the date and time stamp. To view the account management UI 56

59 Account Balance On the Amazon FPS sandbox environment, visit On the Amazon FPS production environment, visit Important We recommend that you first test your application in the Amazon FPS sandbox environment before using the Amazon FPS production environment. Web Service API The web service API is useful if you have more than 200 transactions per month or if you want to programmatically process the transaction details. You can use the GetAccountActivity operation to retrieve transaction details on your account for any given time period. You can also filter the transaction details by date-time range and payment methods. Note You get separate transaction details, each corresponding to your role in the transaction. The GetAccountActivity response provides all of the requested transaction details. However, if you want all the parameters that you passed to Amazon FPS, you can use the GetTransaction operation using the transactionid to get all the details. You can use the GetAccountBalance operation to get the current account balance on your account. Account Balance You can accumulate balance on your Amazon Payments account in two ways: Payments received from your customers (senders) Funds transferred from your bank to your Amazon Payments account balance You can view your current account balance by logging into your Amazon Payments account at Your Amazon Payments account provides the following information about your account: Available balance to withdraw is the amount that you can withdraw (transfer) to a verified bank account. Available balance to refund is the amount that can be used to refund transactions. You can use a verified bank account to withdraw an account balance to your bank account using the procedure given below. To withdraw an Amazon Payments account balance to your bank account: 1. Go to and add a bank account 2. Verify your bank account. This process can take about three or four days. 3. Amazon FPS deposits a random amount into your bank account and you have to inform us about those deposits. 57

60 Certificates 4. Visit to withdraw (transfer) to your bank account. Certificates Amazon FPS uses AWS access key identifiers to secure your messages. For accessing the Amazon FPS APIs you must use a self signed X.509 certificate. To access the co-branded UI pipeline you need the AWS access key identifiers (private and public). To view your Access key identifiers Sign into your developer account from the Amazon AWS website Move the mouse pointer over Your Web Services Account button. From the pop-up box, select View Access Key Identifiers. 4. Sign in again into your account. After signing in, you can view your private and public keys required to access the co-branded UI. This page also allows you to set up and manage your X.509 certificates. Currently, you cannot make changes to the AWS access identifiers from the web site. Co-Branding Preferences You can customize the Amazon FPS payment instruction installation and payment authorization web pages to provide your customers with a consistent look-and-feel of the website during their entire transaction process. Amazon FPS offers you two types of co-branding. Header Logo - You can add your custom image as a header logo by providing a URL to the image. This image is displayed as the header on each of Amazon FPS's payment authorization pages. The following are the rules for the custom header logo: The maximum size of the image is 780 (w) x 90 (h) pixels. You must store this image in a secure HTTP server. If you do not store the image on secure HTTP server, your customers will see a warning message. Header and Footer URL - Instead of an image, you can specify URL for the entire header and footer of Amazon FPS pages. Again, ensure that you host them from a secure HTTP server. Notification Preferences Amazon FPS sends notifications either through s or web service notifications. Notifications are sent to customers who have: Initiated transfers on their accounts to the recipients. Authorized payments for a recipient or a caller. Daily and monthly activity reports. Amazon FPS sends web service notifications to you (developers/caller) using a web service API. You can receive notifications for the following: 58

61 Refunds Results of transactions that didn't complete synchronously In the situation where a bank account transfer takes about 4-5 days to complete you might receive the result of the transaction only after four days. For all instantaneous transactions like account balance transfer Amazon FPS synchronously responds with results. See the Handling Synchronous Responses section for more information on how you can handle synchronous responses. Cancellations of payment authorizations If your customers prefer to cancel a payment authorization, they can visit the Amazon Payments account settings page ( to view the authorization details and cancel them. In this situation, Amazon FPS sends you a notification about the cancellation using a web service API. Refunds You can use the Refund operation to issue refunds for any transaction that you execute. This operation requires you to pass a refund sender token, which authorizes Amazon FPS to refund the transaction. Making calls to the Refund operation and handling responses is similar to a Pay operation. See the Handling Synchronous Responses section for more on how to handle responses. If you are the recipient as well as the caller, then you need to install a refund token with following rules: MyRole == 'Sender'; Operation = 'Refund'; In a market place application, where you are a caller, you must get a refund sender token from the recipient. Amazon FPS returns the refund token as an output to the recipient token installation pipeline. Using the co-branded pipeline, recipients can give you the refund token that authorizes you to refund senders on their behalf. These rules apply to a refund transaction. You can choose to refund the total or partial amount of the refund transaction. You cannot refund more than the original transaction amount. You can make multiple refunds on a single transaction, but the sum of all the refund amounts cannot exceed the original transaction amount. If you have executed a transaction, only you are allowed to refund the transaction. If the payment method used in the original transaction was a credit card, the refund will only be made to the credit card used in the transaction. If the payment method used in the original transaction was a bank account or account balance transfer, the refund will be made to the account balance of the original transaction sender. The fee paid to Amazon FPS will be refunded to the participant that paid the fee in the original transaction. The percentage of fee transferred is equal to the percentage of the amount refunded. For example, if the refund amount is 30% of the original transaction amount, then the fee refunded is 30% of the original fee. A refund transaction where the payment method used in the original transaction was a bank account or account balance is a synchronous operation, whereas a refund transaction using a credit card is an asynchronous transaction. Making calls using the Refund operation and handling responses is similar to a Pay operation. Refer to the Handling Synchronous Responses section for more on how to handle the synchronous responses. Disputes and Chargeback 59

62 Using Prepaid Amazon FPS ensures that all your transactions are problem free. If you encounter disputes or requests for chargeback from your customers, you can ask your customers to follow the procedures mentioned at To learn more about how Amazon FPS manages disputes and chargeback, please see the FAQ at Using Prepaid A sender can purchase a prepaid balance from a recipient and use that prepaid balance to pay for goods or services offered by the recipient. This section uses the hypothetical online retailer, DigitalDownload, to explain the Amazon FPS prepaid payment feature and the steps involved in creating and using a prepaid payment instrument. Important Amazon FPS supports the prepaid payment feature only when the caller and the recipient are the same. Example - DigitalDownload's Prepaid Card DigitalDownload is a licensed online retailer selling MP3 files for $0.50 each. John is a DigitalDownload customer who purchases a prepaid balance of $10 using his Amazon Payments account balance. Each time John purchases an MP3 file DigitalDownload makes a web service call to Amazon FPS and charges John's prepaid balance. After the purchase DigitalDownload displays John's prepaid balance on his account on the DigitalDownload web site. Amazon FPS rejects any prepaid Pay request from DigitalDownload after the prepaid balance is exhausted. The following topics provide detailed information on setting up and using the prepaid payment method: Topics Setting Up Prepaid Instruments Setting Up Prepaid Instruments Viewing Prepaid Balance Recharging Balance Refund Prepaid Balance Setting Up Prepaid Instruments A prepaid instrument is a special payment method (like a credit card or a bank account) that can be used by a sender in a payment instruction. You can define the following rules (also known as prepaid instructions) to specify the usage of the prepaid balance: Sender using the prepaid instrument Recipient offering the prepaid instrument Caller executing the prepaid transactions on Amazon FPS Recharge limit to which the prepaid instrument can be recharged 60

63 Setting Up Prepaid Instruments Validity of the prepaid instrument The rules (except the last two) can be expressed in the GateKeeper language. You can create a prepaid instrument using the Amazon FPS Prepaid Instrument Installation Pipeline. A prepaid instrument has two participants: the sender purchasing the prepaid instrument and the recipient issuing the prepaid instrument. Both the participants must agree to create a prepaid instrument. Only the recipients are allowed to issue prepaid instruments in Amazon FPS. Calling applications (or callers) in a marketplace scenario that involves a unique sender, a caller, and a recipient, cannot issue prepaid instruments on behalf of the recipients. The following steps are required to purchase a prepaid balance: Create the prepaid instrument. Set up a token to fund the balance associated with prepaid instrument. Set up a token to use prepaid balance. Fund the prepaid balance associated with the instrument. You can use the Prepaid Instrument Installation Pipeline to perform steps 1, 2, and 3. The step 4 is described in the Funding Prepaid Balance section. Creating Prepaid Instrument and Setting Up Tokens The following diagram illustrates the steps involved in creating a prepaid instrument and setting up tokens: Creating prepaid instrument 61

64 Setting Up Prepaid Instruments 1. The sender visits the DigitalDownload web site and purchases $10.00 prepaid card that is valid until December DigitalDownload redirects the sender to the prepaid instrument installation pipeline with following input parameters. Parameter Value fundingamount 10 The amount of the prepaid balanced purchased by the sender This value is specified in seconds from the EPOCH time. You customer will, however, see the validity date in the standard date-time format. PrepaidDigitalDownloadSender A unique value that is used to identify the sender token. This value can also be used to retrieve the token if it is lost or not returned from the Amazon FPS co-branded UI pipeline. PrepaidDigitalDownloadFunding A unique value that identifies the transaction. Buying a prepaid card The reason for making this payment. SetupPrepaid The name of this pipeline. validityexpiry callerreferencesender callerreferencefunding paymentreason pipelinename The sender signs in using an Amazon.com address and password. After successful authentication, the sender reviews the prepaid instrument details. The sender selects one of the available payment methods to purchase the prepaid instrument. Amazon FPS creates the following and sends them as output in the return URL. Prepaid instrument used as sender's payment method Funding token used to fund sender's prepaid instrument Sender token used to make payments from the prepaid balance 7. The sender confirms the payment authorization and clicks the Continue button. Funding Prepaid Balance You can use the FundPrepaid operation to fund a prepaid balance. A prepaid instrument is always created with a zero balance. Amazon FPS provides a funding token to fund the prepaid balance and you must explicitly use the funding token to fund the prepaid instrument. As explained in the Using Prepaid Instruments and Balances section a funding token is an output of the prepaid instrument installation pipeline. The funding token is a sender token installed on a sender's account and contains references to the payment method and instrument that should be used to fund the 62

65 Using Prepaid Instruments and Balances prepaid balance. The FundPrepaid operation accepts the following parameters as inputs: Funding amount Prepaid instrument Funding token For the complete list of parameters, see FundPrepaid request parameters section. The FundPrepaid operation does the following: 1. Transfers money from the sender's payment instrument (specified in the funding token), to the recipient's account balance. The fee charged is deducted from the funding amount and deposited into the recipient's account balance. 2. The sender's prepaid balance is credited with the funding amount. You can use either credit cards or the bank account to fund tokens: Note It takes 4 days for the sender to receive funds in a bank account transfer. Example If the funding amount is $10 and the Amazon FPS fee is $0.50, then the FundPrepaid operation transfers $9.50 into recipient's account and credits $10 into sender's prepaid balance. Handling the FundPrepaid operation response is similar to handling a Pay operation response. See the Using Tokens for Making Payments section for more information on how you can handle responses. Using Prepaid Instruments and Balances A prepaid instrument is a payment method that can be used in an Amazon FPS transaction. To use the prepaid instrument you must install a sender token that uses the prepaid instrument as the payment method. A prepaid instrument is always created with a zero balance. Amazon FPS provides a funding token to fund the prepaid balance and you must explicitly use the funding token to fund the prepaid instrument. A prepaid balance is the balance associated with a prepaid instrument. You can use a credit card, a bank account, or the Amazon Payments account balance to fund a prepaid balance during the purchase of a prepaid instrument. Note This prepaid balance is not the same as a recipient's or sender's account balance. Funding the prepaid balance Creates a prepaid balance that is equal to the funding amount Transfers the funds from the sender's payment method (credit card, bank account, or Amazon 63

66 Viewing Prepaid Balance Payments account balance) to the recipient's Amazon Payments account The prepaid balance of a prepaid instrument is same as any other account balance. You require a sender token which uses prepaid as the payment method and prepaid instrument as the payment instrument. Amazon FPS returns this sender token as an output of the Prepaid Instrument Installation Pipeline. A prepaid Pay call is like any other Pay call in Amazon FPS. A Pay web service call which uses the prepaid instrument as payment method always returns a synchronous response with the transaction Id. You can pass the transaction Id to the GetTransaction operation to get more details about the transaction. The transaction details are not available on your customer's account management UI. You can, however, provide the transaction history to your customers on your web site. Using Prepaid Balances A sender can use the prepaid instrument to buy goods or services until the prepaid balance is exhausted. Each time a sender initiates a purchase, the caller makes a Pay web service call to Amazon FPS and deducts sender's prepaid balance. This is called a prepaid transaction. When the prepaid balance is exhausted or when the balance is low, a sender can choose to recharge or top-up the prepaid instrument. A prepaid Pay request to Amazon FPS is like any other Pay request, except that the sender token uses the prepaid instrument as the payment method instead of a credit card, a bank account, or the Amazon Payments account balance. Viewing Prepaid Balance A sender cannot view the prepaid balance or the prepaid instrument on the Amazon FPS enabled web site. You can, however, use the GetPrepaidBalance operation to display the available prepaid balance to the sender on your web site. This GetPrepaidBalance operation accepts the PrepaidInstrumentId as input and returns the current prepaid balance. Recharging Balance Amazon FPS does not provide a function to recharge a prepaid balance. Refund Prepaid Balance Recipient's cannot refund or reverse the prepaid balance to a sender's Amazon Payments account or credit card. Amazon FPS allows only a caller to reverse a prepaid transaction. In our Example 8, - DigitalDownload's Prepaid Card, the $10 prepaid card that John purchased from DigitalDownload is non-refundable. After making the payment for the MP3 file if John realizes that he can't download the file, he can report the problem to DigitalDownload. DigitalDownload can reverse this transaction and credit the prepaid balance. Using Postpaid You can also extend credit using the postpaid capabilities and allow your customers to purchase goods or services and pay for them later. In both the cases, Amazon FPS enables you to track individual micro-transactions and the aggregated amount at any time. This section provides detailed information about setting up and using the postpaid payment capabilities of Amazon FPS. Topics: 64

67 Setting Up Credit Instruments Setting Up Credit Instruments Using Credit Instruments Viewing Debt Balance Settle Debt Balance Refund and Write-Off Debt Balance Setting Up Credit Instruments A credit instrument is a special payment method (like a credit card or a bank account) that is used by a sender in a payment instruction. A credit instrument captures the following rules (also known as payment instructions): a. b. c. d. e. Sender using the credit instrument Recipient offering the credit line Caller executing debt transactions on Amazon FPS Credit limit Validity of the credit instrument The rules (except: d and e) are expressed in the GateKeeper language. A credit instrument is created using the Amazon FPS postpaid instrument installation pipeline. A credit instrument has two participants: a sender, who purchases the credit instrument, and a recipient, who provides the credit line. After both the participants agree to create the credit instrument, you can use the co-branded UI pipeline to create the credit instrument. Important Amazon FPS mandates that recipients and callers must be the same in a postpaid transaction. Amazon FPS does not support a marketplace application in a postpaid transaction. You can use Postpaid Instrument Installation Pipeline to setup the debt balance. The following steps are required to set up a debt balance: 1. Creating a credit instrument 2. Setting up a token to use credit instrument 3. Setting up a token to settle the debt balance Creating Credit Instrument and Setting Up Tokens The following diagram illustrates the steps involved in creating a Postpaid instrument and setting up tokens. Creating a Postpaid Instrument 65

68 Setting Up Credit Instruments 1. The sender visits the DigitalDownload web site and clicks on the Register Now button to set up a billing agreement to make postpaid payments. DigitalDownload directs the sender to the Amazon FPS postpaid instrument installation pipeline using a signed URL. The signed URL contains all the required parameters to set up the postpaid (credit) instrument and some of them are: validitystart CallerReferenceSender CallerReferenceSettlement PaymentMethod CreditLimit erreferencesender=johnpp &callerreferencesettlement=johnpp &creditlimit=30&globalamountlimit= 50 &validitystart= &pipelinename=setuppostpaid&callerkey=11rlbbgbrol2 006 &returnurl= The sender signs into Amazon Payments account using the Amazon.com address and password. 3. After successful authentication, the sender views the Payment Authorization Details page. Sender selects a payment method that will be used to set up the credit limit and clicks the Continue button. 4. The sender reviews the payment authorization details and clicks the Confirm button. 5. Amazon FPS creates the following and redirects the sender to the web site specified in the return URL: 66

69 Using Credit Instruments Credit instrument Sender token Settlement token Using Credit Instruments Senders can use the credit line offered in the credit instrument to purchase goods and services. For every purchase initiated by a sender, Amazon FPS accumulates debt in senders credit instrument. This is called a debt transaction. The debt balance is different from the account balance of recipient or a sender. When the debt balance reaches the maximum credit limit specified in the instrument, Amazon FPS rejects further Pay operation request using that credit instrument. A debt Pay call to Amazon FPS is like any other Pay call except that the sender token uses the credit instrument as the payment method instead of a credit card, a bank account or the Amazon Payments account balance. Like other payment methods using debt requires a sender token with the payment method set as debt and the payment instrument Id set as the credit instrument Id. A Pay call that uses a credit instrument as the payment method always returns the result synchronously. The result contain the transaction Id. You can use GetTransaction operation with the transaction Id to get more details on the transaction. Your customers cannot see these transaction details on their account management UI. You can, however, provide the transaction history on your website for your customers. Viewing Debt Balance Senders cannot view their debt balances or credit instruments on the Amazon FPS destination web site. You can, however, use the GetDebtBalance operation to display the accumulated debt to the sender on your web site. The GetDebtBalance operation takes a credit instrument Id as input and returns the credit instrument ID's current debt balance. Settle Debt Balance The sender accumulates a debt balance when a credit instrument is used to pay the recipient. At a later point in time the sender can settle the accumulated debt using a credit card, a bank account, or the Amazon Payments account balance. After the settlement debt balance is reduced, the funds are transferred to the recipient's account using the payment instrument specified in the settlement token. When the credit instrument is created, you also get a settlement token as an output from the pipeline. A settlement token is a sender token that is installed on the sender's account which gives the payment method and the payment instrument used to settle the debt balance. Amazon FPS does not provide an automatic settlement of debt, however, you can explicitly settle the debt using the SettleDebt operation. The SettleDebt operation takes the settlement amount, credit instrument Id and settlement token among other parameters. The SettleDebt operation Moves money from the sender's payment instrument specified in the settlement token to the recipient s account balance. The transaction fee is deducted from the settlement amount and remaining amount is deposited into the recipient's account balance. Decrements the debt balance by the settlement amount. 67

70 Refund and Write-Off Debt Balance Example If the debt balance is $100, settlement amount is $90, and the Amazon FPS fee is $2.50 then the SettleDebt operation transfers $87.50 into the recipient's account balance and decrements the debt balance by $90. The debt balance is now $10. Important The SettleDebt operation cannot be used for transaction with amounts greater than the actual debt balance. If the debt balance is $100, you cannot settle the debt for $110. The Refund operation does not support debt settlements. A settlement token can use any of the following payment methods: Credit card Bank account Takes about 5 to 7 days to receive funds from a bank account transfer. Amazon Payments account balance Note You can use a settlement token to settle a debt multiple times. A maximum settlement limit must be specified on the total value of such settlements that is done using the settlement token. Amazon FPS displays this value to the senders when they set up the credit instrument using the co-branded UI pipeline. Refund and Write-Off Debt Balance Refund Debt Transactions Recipients can reverse a debt transaction but cannot refund a debt settle transaction against the debt. Write-Off Debt Balance You might want to write off a debt balance accumulated by a sender for business reasons like adjustment for errors, or as a promotion, or as a bad debt. Amazon FPS provides a web service API to write-off debt that is accumulated on a Amazon Payments account. This API takes a credit instrument Id and a write off amount to reduce the debt balance. The write-off amount cannot exceed the debt balance on the credit instrument. You cannot reverse a write-off debt operation. Reserve and Settle You can use the Reserve and Settle operations for reserving funds on a sender's credit card before the service or goods are delivered and then settle the amount after the service or goods are delivered. 68

71 Use cases Important Amazon FPS supports only credit cards for the reserve and settle functionality. The Reserve call is similar to a Pay call and accepts a sender token, recipient token, and caller token as input parameters. You can acquire the sender token by directing the sender to the Amazon FPS Co-branded UI pipeline. Here, the sender can authorize you to use the sender's credit card for a specific one-time amount. A token that captures this payment authorization is returned when the sender is redirected to the merchant web site. Settlement can happen for any amount equal to or less than the reserved amount specified at the time of the reserve. The Settle call takes the TransactionId that is returned as response for the Reserve operation. Making a Reserve and Settle Operation After a sender decides buy a product from your website, you direct him to the Amazon FPS Co-branded UI pipeline. The sender signs into the sender's Amazon Payments account and sets a payment authoriztion to use the credit card for making the payment. After setting up the payment authorization, Amazon FPS returns the sender to your web site along with the sender token. Using the sender token (returned by Amazon FPS), your caller token, and the recipient token you can make Reserve operation request. The Reserve operation places the amount on reserve on the sender's credit card. Important At this point, the amount is not transfered to you account. 5. Amazon FPS returns a transactionid corresponding to the reserve transaction. After the product is delivered to the sender, you can make the Settle operation request. If the Settle operation is successful, the amount is transfered into your account. Important You must settle the reserve amount within 7 days after the reserve succeeds. The Reserve operation uses a credit card, it takes few seconds to complete. The results of a Reserve operation is returned asynchronously. You can get the results of the transaction using GetResults operation. On each of the results you can use the GetTransaction operation to view the transaction status. See the "Handing Transaction Status" topic for more information about handling transactions with different status. [TBD] 69

72 Setting Up Sample Applications Use cases This section contains the examples of the following use cases that are bundled as sample applications in the Amazon FPS SDK: One Time Payment : DigitalDownload application Multi-use : Kids Currency application Marketplace : My-2-Cents for Your 2 Cents application Prepaid : DigitalDownload Prepaid application Postpaid : DigitalDownload Postpaid application Recurring Payments : e-subscription Recurring Payments application Reserve and Settle : DigitalDownload Reserve and Settle application Note All names of businesses and individuals used in these use cases are entirely fictitious. Setting Up Sample Applications The use cases in this section are explained using sample applications bundled with the Amazon FPS SDK. You must set up the sample applications before you can view them. The Readme file included in the SDK contains instructions on setting up the Amazon FPS SDK and the sample applications. To view the sample applications 1. Use your web browser to go to the URL where you have hosted the Amazon FPS SDK. For example, Where: server_name is the name of the server where you installed and set up the Amazon FPS SDK. port_number is the port at which the server receives requests. amazonfpssdk is the folder in which the Amazon FPS SDK is installed. For example, if you have hosted the Amazon FPS SDK on your local machine and set the port to 8080, then the URL to access the sample applications is 2. The sample applications are grouped under various tabs. You can click on the tab and select the application listed under that tab. For example, to see the DigitalDownload application, click the Simple Pay tab, and then click the DigitalDownload link. Recommended Reading We recommend that you read the Concepts section in the Amazon FPS Getting Started guide before proceeding with the use case descriptions. The Concepts section is an introduction to important Amazon FPS concepts. A lot of these concepts are used in the use case descriptions. One-Time Payment 70

73 One-Time Payment This use case describes how a single-use token is used for making a one-time payment transaction. Use Case Overview DigitalDownload is a licensed seller of a large selection of popular music and video downloads. It uses Amazon FPS to receive payments from its customers for purchases on its web site. John is a customer of DigitalDownload and also has an Amazon Payments account. He visits the DigitalDownload web site to purchase music and uses his Amazon Payments account to pay DigitalDownload for his purchases. User Experience The following steps show the sequence of events that take place in a typical transaction at the DigitalDownload web site: 1. John visits the DigitalDownload web site, selects an MP3 audio file Now and Forever-Richard Marx, selects Amazon Payments as the payment method and clicks the Download Now link. 2. After John clicks the Download Now link, he is directed to the Amazon FPS web site. To access Amazon FPS web site he signs onto his Amazon Payments account from the Amazon Sign In page using his Amazon.com Id and password. 71

74 One-Time Payment 3. Once he signs in, John views Payment authorization page. The Payment authorization page allows John to view the payment details and select a payment method for the transaction. He can view the following information: Recipient (Pay) Reason for the payment (For) Total transaction amount (Amount) John selects his Amazon Payments account balance (ABT) as the payment method and clicks the Continue button. 4. After he clicks the Continue button, John views the Confirm payment authorization page. He review payment details and confirms the payment by clicking the Confirm button. 5. After clicking the Confirm button, John is redirected to the DigitalDownload web site, where the payment transaction is executed. Important The payment transaction is not executed on the Amazon FPS web site. DigitalDownload makes a Pay operation web service call and executes the payment transaction. 72

75 One-Time Payment Where: a is the status of the Pay request made by DigitalDownload b is the status of the transaction. In this use case, the transaction was successful and the money was transferred from John to DigitalDownload. c is the transactionid for the transaction. DigitalDownload can use this for any future references or operations. How to Build the Use Case This topic contains information on building this use case with the assumption that you are playing the role of DigitalDownload. In this use case, you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments for purchases on your website. John is the sender in this use case who purchases music files. To execute any Amazon FPS transaction you will require a caller token, a recipient token, and a sender token. Install Caller and Recipient Tokens You must install a caller token and a recipient token on your account. A caller token allows you to make web service calls and a recipient token allows you to receive payments. To install tokens on your account, use the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. See the Acquiring Recipient Tokens section for more information on setting up a recipient token on your account. You only require one caller token and one recipient token for executing all the payment transactions in this use case. Installing a caller token and a recipient token is a one time activity. Acquire Sender Token You need the sender token to make payment transaction. You can get the sender token by directing 73

76 One-Time Payment senders to Amazon FPS web site where they set up a payment authorization and return your web site. Important Amazon FPS does not allow you to install tokens on senders account. You must direct the senders to a specific Amazon FPS UI pipeline to install tokens. See the Acquiring Tokens section for more information. In this use case, when John clicks the Download Now link on your web site, you must direct him to the Amazon FPS Single-use Token Installation Pipeline. To direct users to Amazon FPS pipeline, you must use a signed URL. A signed URL is created using the parameters required in this transaction. See the Signing A URL section for information on creating a signed URL. Example - Signed URL used in this use case Key=<caller credentials> &pipelinename=singleuse &returnurl= usecases/digitaldownload/paymentdetails.jsp?paymentamount=0.10&download=now+and+forever+-+richard+marx&uniqueid = &callerreference=digitaldownload &transactionamount=0.10 &paymentreason=now and Forever - Richard Marx &awssignature=<encrypted signature value> Parameter Value Meaning callerreference DigitalDownload A unique reference created to identify the sender token for your future reference. paymentreason Now and Forever Richard Marx Text describing this transaction. Your customers will see this when they view the payment details. paymentmethod abt,ba,cc Payment methods that you support. In this case it is account balance, bank transfers, credit cards. transactionamount 0.10 Price in USD. callerkey DigitalDownload's caller key Your AWS Access Key Id used to identify you. awssignature Encrypted signature Signature of the encoded URL created using your Access Key Id. pipelinename SingleUse Name of this pipeline. returnurl <destination-host URL to which the user is redir- 74

77 One-Time Payment Parameter Value Meaning name>:<port-number>/ amazonfpssdk/ usecases/digitaldownload/paymentdetails.jsp? PaymentAmount=0.10&Download=No w+and+forever+-+richard+ Marx &uniqueid= ected after completing the payment authorization. In this pipeline, John logs into his Amazon Payments account, views the payment details, selects a payment method, and confirms the payment. John is redirected back to your web site using the return URL along with the sender token. You can identify the payment method used in the token by looking at the value of the status response parameter. Making Pay Call You can now use the sender token received from the UI pipeline along with your caller token and recipient token installed on your account to make the Pay operation call. In this use case, since John used ABT as the payment method, this Pay call will return synchronous response. See the Making a Pay Request section for more information about using tokens to make a Pay call to Amazon FPS. Also see Pay section for information on the request and response parameters. The parameters and the values of the Pay call in this use case are: Parameter Value Meaning CallerTokenId Specify caller token Id Your caller token. RecipientTokenId Specify recipient token Id Specifies the recipient token. Your token to which the Sender makes the payment. SenderTokenId Specify sender token Id Specifies the sender token. This is the token that John created. TransactionAmount 0.10 Specifies the amount that will be charged to the sender. CallerReference MP3DownloadId-AF12ES A unique reference created to identify the sender token for your future reference. ChargeFeeTo DigitalDownload Specifies the fee that you will pay to Amazon FPS for executing this transaction. TransactionDate Date is automatically set Specifies the date when the transaction is executed. Caller DigitalDownload web site Text to describe the transaction or other details. MetaData Digital Content downloaded: Now and Forever Used to specify transaction details like order number, invoice 75

78 Multiple Payments Use Case Parameter Value Meaning - Richard Marx number. Sender John Customer of DigitalDownload Text description about the sender involved in the transaction. SenderReference johndigitaldownload A unique value used to identify the sender on your web site. Since this use case uses ABT as payment method, your Pay call will return synchronous response. The response from Amazon FPS contains status of the transaction and the transactionid. We suggest you store the transactionid for future reference. See the Handling Synchronous Responses section for more information. As a result of the Pay call, money is transferred from senders account to your account. You can view your account balance from the Amazon Payments account manager UI. See the Managing Your Account section for more information. View Transaction Details You can use Amazon FPS APIs to view transaction details on your account. To view details on a particular transaction, use the GetTransaction operation. To view the history of all transactions on your account, use the GetAccountActivity operation. Documentation References You can see the following sections in the Amazon FPS Getting Started guide and the developer documentation for more information on the concepts discussed in this use case. Section Contains information on Guide Concepts Amazon FPS concepts Amazon FPS Getting Started Guide. Acquiring Single-use Tokens Acquiring single use sender token Programming Reference Single-use Token Installation Pipeline The Amazon FPS UI pipeline used to create single-use tokens. Co-Branded UI Pipeline Reference Acquiring Recipient Tokens Acquiring recipient tokens Programming Reference Recipient Token Installation Pipeline The Amazon FPS UI pipeline used to redirect recipients to setup recipient tokens. Co-Branded UI Pipeline Reference Multiple Payments Use Case This use case describes the multi use token that allows multiple payments using a single authorization. Use Case Overview The Kids Currency application sells kids goods. Parents can set up payment authorization that allows 76

79 Multiple Payments Use Case their kids to make purchases using the Kids Currency application. The payment authorization allows parents to impose restrictions on the type of goods their kids can buy, the number of times their kids can make purchases and the total amount for which their kids can make purchases. In this use case, John creates virtual wallet for his kid, Jim. The virtual wallet is a payment authorization that permits Jim to make purchases using the Kids Currency application. John imposes the following restrictions on using the virtual wallet: The maximum amount spent using the virtual wallet is $30. The maximum amount spent using the virtual wallet in a day is $10. The number of times the virtual wallet can be used is 5 times per day. User Experience This topic contains the steps involved in creating and using a virtual wallet. Creating Virtual Wallet 1. John uses the Kids Currency application to create a virtual wallet. He provides the following information to create a virtual wallet: Enters the name of the kid (Jim). This name is used to identify the virtual wallet. Selects amount restriction of $10 per day. Selects Kidz-Bookstore and Kidz-Toys as the site where Jim is permitted to make purchases. Jim will not be permitted to make purchases at any other store. 2. John clicks the Create Virtual Wallet button. After John clicks the Create Virtual Wallet button, he is redirected to the Amazon FPS web site, where he views the Amazon.com Sign In page. John signs into his Amazon Payments account using his Amazon.com -id and password. 77

80 Multiple Payments Use Case 3. Once John signs onto his Amazon Payments account, he views the Payment Authorization page. The Payment Authorization page allows John to view the payment details and select a payment method for the transaction. The Payment details page displays information about: 4. Recipient Kids Currency Validity of the authorization Maximum amount that can be spent using this authorization in a day-$10 Maximum amount that can be spent using this authorization-$30 John selects Amazon Payments account balance (ABT) as the payment method and clicks the Continue button. After he clicks the Continue button, John views the Confirm Payment Details page. On this page he can review the payment details and confirm the payment authorization by clicking the Confirm button. 78

81 Multiple Payments Use Case 5. On clicking the Confirm button, John is redirected to the Kids Currency application. Making Purchases using the Virtual Wallet Note This application does not showcase a sign-in page. The homepage of this application is shown with the assumption that the user has logged in. 1. Jim visits the Kids Currency application to make purchases using the virtual wallet created for him by his father (John). He enters his name for the name of the wallet and clicks the Use Existing Wallet link. 79

82 Multiple Payments Use Case 2. After Jim clicks the Use Existing Wallet link, he views the Spending Options page. This page displays the various kids products and the total amount spent using the virtual wallet. 3. Jim selects the "Three Teddy Bears" book costing $4.54 clicks the Buy button. 80

83 Multiple Payments Use Case After Jim clicks the Buy button, the Kids Currency application executes the payment transaction by making a web service call to Amazon FPS. After executing the payment transaction, the Kids Currency application displays the Payment Details page. This page displays the status of the payment transaction and the Return to the website link. To continue shopping, Jim clicks the Return to the website button. After Jim clicks the Return to the website button, the Kids Currency application displays the Spending Options page. This page displays the total amount spent ($4.54) today using the virtual wallet. 81

84 Multiple Payments Use Case Jim can continue to buy books using the virtual wallet until he has spent $10. How to Build the Use Case This topic contains information on building this use case with the assumption that you are the Kids Currency application. In this use case, you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments for the goods sold on your web site. John is the sender who pays for the purchases made by his son, Jim. You will need a caller token, a recipient token, and a sender token to execute a payment transaction using the Amazon FPS. Install Caller and Recipient Token You must install a caller token on your account. A caller token allows you to make web service calls to Amazon FPS. To install a caller token on your account use the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. Note This application (Kids Currency) included in the SDK contains pre-configured recipients and their recipient tokens are hard coded. You will require only one caller token to execute all the transactions, hence this is a one-time set up. Acquire Multi-use Sender Token You can acquire multi-use sender tokens by redirecting senders to Amazon FPS web site where they setup a payment authorization and return to your web site with the multi-use token. In this use case, when John clicks the Create Wallet button, you must redirect him to the Amazon FPS 82

85 Multiple Payments Use Case co-branded Multi-use Token Installation Pipeline using a signed URL. A signed URL is created using the parameters required acquire the token and your caller credentials. See Creating a Signed URL section for information on creating a signed URL. Parameters and values used in this use case for acquiring a sender token are: Parameter Value callerreference KidsCurrency A unique reference created to identify the sender token for your future use. paymentreason Creating a virtual wallet - Kids Currency Text describing this transaction for your customers to understand when they look at the payment details paymentmethod abt Payment method used to make the payment. transactionamount 10 Price in USD callerkey Your caller key Your AWS Access Key Id to identify you in the pipeline. awssignature URL signature The URL signature that you calculate using the parameters of the URL used to direct sender to Amazon FPS co-branded UI pipeline. returnurl m/welcome.jsp Your website URL, where the user is redirected after completing the payment authorization. recipienttokenlist List of token Id The list of recipient token IDs to which the payment is made. globalamountlimit 30 The maximum amount that can be spent using this token. validitystart Validity of the virtual wallet. validityexpiry usagelimit1 Amount usagelimitvalue1 10 usagelimitperiod1 1 Days usagelimit2 Count usagelimitperiod2 1 Days These parameters restrict usage to a maximum of $10 in a day. These parameters restrict usage to a maximum of 2 times a day. Making a Pay Call You can now use the sender token received from the UI pipeline along with your caller token and a recipient token in the Pay call. In this use case, Amazon FPS creates a multi-use sender token (virtual wallet) for John. You must store this token and use it in your Pay call. Whenever Jim makes a purchase, you can make a Pay call to 83

86 Multiple Payments Use Case Amazon FPS using this sender token, your caller token and a recipient token. See the Making a Pay Request section for more information about using tokens to make a Pay call to Amazon FPS. Also see Pay section for information on the request and response parameters. The parameters and values are used in the Pay call are: Parameter Value CallerReference KidsCurrency A unique reference created to identify the sender token for your future use. CallerTokenId Your caller token ID Your caller token required for making the transaction. RecipientTokenId Recipient's token ID Specifies the recipient token to which the money is transfered. SenderTokenId Sender's token ID Specifies the sender token. The token created by Joe. PaymentMethod cc Payment methods allowed by you. In this case it is credit cards. TransactionAmount 4.54 Cost of the Toy in USD SenderReference John A unique value that identifies the sender in this transaction. RecipientReference Kids Currency Toys A unique value that identifies the recipient in this transaction. CallerReference Kids Currency A unique value that identifies the caller in this transaction. ChargeFeesTo Recipient Specifies the participant that will pay the fee to Amazon FPS for this transaction. Sender John - Customer of Kids Currency Text description about the sender. Recipient Kids Currency's Book Store Text description about the recipient. Caller Kids Currency Text description about the caller. MetaData Transaction for the purchase of a Toy. Used to specify brief description about the transaction. As a result of this Pay call money is transferred from John's Amazon Payments account balance to Kids Currency' account. You can view your account balance from the Amazon Payments account management UI. See the Managing Your Account section for more information. Since this use case uses ABT as payment method, your Pay call will return synchronous response. The response from Amazon FPS contains status of the transaction and the transactionid. We suggest you store the transactionid for future reference. See the Handling Synchronous Responses section for more information. 84

87 Market Place View Transactions You can use Amazon FPS APIs to view transaction details on your account. To view details on a particular transaction, use the GetTransaction operation. To view the history of all transactions on your account, use the GetAccountActivity operation. References The following topics in the programming guide provide more information on the concepts discussed in this use case. Acquiring Multi-use Tokens Multi-use Token Installation Pipeline Creating Tokens Acquiring Tokens Market Place This use case describes using of recipient tokens in a market place type application. Topics in this section Use Case Overview: Contains an overview of the use case and provides information on the participants involved in the transaction. User Experience: Contains information on the sequence of steps that happen in a typical transaction. Creating the Application: Contains information on how you can set up a similar application or payment transaction at your web site. The information in this section refers to the steps mentioned in User Experience topic. Use Case Overview The My 2 Cents for Your 2 Cents (My2C) application allows blog writers to receive payments from blog-readers. The My2C application is a registered developer (caller) with Amazon FPS and as a developer, it can make web service calls to Amazon FPS. In this use case, John is a blog-writer (recipient) who uses the My2C application to receive payments using his Amazon Payments account. Joe visits the blog site to read blogs and likes to make payments using his Amazon Payments account. User Experience This use case describes the user experience in posting a blog and reading a blog. Posting a Blog 1. John visits the My2C application and wishes to post a blog. He clicks the Blog Now button. 85

88 Market Place 2. After John clicks the Blog Now button, the My2C application redirects him to Amazon FPS web site, where he views the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com Id and password. 3. After John signs in, he views the payment authorization page. He can use this page to set up authorization to receive payments into his Amazon Payments account. The authorization page allows John to view the following details: Authorization to Amazon Payments to process payments done on his blogs at My2C application. Payment methods using which he will receive payments. Agreement to pay fees to Amazon FPS for this transaction. After viewing the payment authorization, he clicks the Continue button. 86

89 Market Place 4. After John clicks the Continue button, John is shown the summary of the payment authorization. 5. He clicks the Continue button to be redirected to the My2C application where he can write and post his blog. 6. After John submits his blog, the My2C application stores his blog and redirects him to the homepage where his blog is displayed. 87

90 Market Place Reading a Blog 1. Joe visits the blog web site, reads the blog posted by John, and wishes to make a payment to John. He clicks the Pay 2 Cents button. 2. After Joe clicks the Pay 2 Cents button, the My2C application redirects him to Amazon FPS UI pipeline, where he views the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com Id and password. 88

91 Market Place 3. Once Joe signs onto his Amazon Payments account, he views the payment details page. The payment details page allows Joe to view the following information: Recipient Reason for the payment Total transaction amount Joe s selects Amazon Payments account as the payment method for this transudation and clicks the Continue button. 4. Joe views the Confirm Payment Details page, where he can review the payment details and confirm the payment by clicking the Confirm button. 89

92 Market Place 5. On clicking the Confirm button, Joe is redirected to the My2C application, where the payment transaction is executed. Note The payment transaction is not executed on the Amazon FPS web site. The My2C application makes a web service all and executes the payment transaction. How to Build the Use Case This topic contains information on building this use case with the assumption that you are the My2C application (caller). The blog writer creates a recipient token to receive payments and the blog reader creates a sender token to make payments. As a caller, you can make web service calls to Amazon FPS and execute payment transactions. In this use case, John is the blog writer who receives payments and hence, is the recipient. Joe is the sender who makes the payments for reading blog entries and hence, is the sender. You will need a caller token, a recipient token, and a sender to execute any transaction using Amazon FPS. Install Caller Token 90

93 Market Place As a caller you must install a caller token on your account. A caller token allows you to make web service calls to Amazon FPS. To install a caller token in your account use the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. Note You will require only one caller token to execute all the transactions, hence this is a one-time set up. Acquire Recipient and Refund Token To make payments to the blog-writers (recipients), you must acquire recipient tokens from them. You can acquire recipient tokens from your recipients by redirecting them to Amazon FPS UI pipeline, where they can set up payment authorization and return to your application. To issue refunds to senders, you must acquire refund tokens from recipients that authorize you to issue refunds on their behalf. You must acquire and store the recipient token and the refund token for each of the recipients who register as blog-writers. In this use case, when John clicks on the Blog Now link, you can redirect him to Amazon FPS co-branded Recipient Token Installation Pipeline using a signed URL. A signed URL is created using the parameters required in this transaction and the caller credentials. See Signing A URL section for information on creating a signed URL. Parameters and values used in this use case for acquiring a recipient token and refund token are: Acquire Sender Token You can acquire sender tokens by redirecting senders to Amazon FPS web site where they setup a payment authorization and return your web site with the sender token. In this use case, when Joe clicks the Pay 2 Cents button, after reading the blog, you must redirect him to the Amazon FPS co-branded Single-use Token Installation Pipeline using a signed URL. A signed URL is created using the parameters required in this transaction and the caller credentials. See Signing A URL section for information on creating a signed URL. Parameters and values used in this use case for acquiring a sender token are: Parameter Value callerreference My2Cents A unique reference created to identify the sender token for your future use. paymentreason Payment for blog entry Amazon FPS Text describing this transaction for your customers to understand when they look at the payment details paymentmethod abt Payment method used to make the payment. transactionamount 0.02 Price in USD. callerkey Your caller key Your AWS Access Key Id to identify you in the pipeline. awssignature URL signature Signature of the encoded URL created using your Access Key 91

94 Market Place Parameter Value Id returnurl m/welcome.jsp Your website URL, where the user is redirected after completing the payment authorization. returnurl 2cents.com/readblog.jsp Your website URL, where the user is redirected after completing the payment authorization. In this pipeline, Joe logs into his Amazon Payments account, views the payment details, selects a payment method, and confirms the payment. Joe is redirected back to your web site using the returnurl along with the sender token. You will know the payment method was used in the token by looking at the value of the status response parameter. Making a Pay Call You can now use Joe's sender token received from the Amazon FPS UI pipeline along with your caller token and John's recipient token in the Pay operation call. In this use case, since Joe uses his Amazon Payments account balance (ABT) as the payment method, this result of the Pay call is returned synchronously. See the Making a Pay Request section for detailed information about using tokens to make a Pay web service call to Amazon FPS. See the Pay operation description for information on the request and response parameters. Parameters and the values used in this Pay call are: Parameter Value callerreference My2Cents A unique reference created to identify the sender token for your future use. callertokenid Your caller token Your caller token. recipienttokenid Recipients token ID Specifies the recipient token. The token to which the Sender makes the payment. sendertokenid Sender's token ID Specifies the sender token. The token created by Joe. paymentmethod abt Payment methods allowed by you. In this case it is John's Amazon Payments account balance. transactionamount 0.02 Cost of the Toy in USD SenderReference John A unique value that identifies the sender in this transaction. RecipientReference Joe A unique value that identifies the recipient in this transaction. ChargeFeesTo Recipient Specifies the participant that will pay the fee to Amazon FPS for this transaction. 92

95 Prepaid Use Case Parameter Value Sender John - Customer of Kids Currency Text description about the sender. Recipient Joe - The author of the blog. Text description about the recipient. Caller My2Cents - Blog host. Text description about the caller. MetaData Transaction for the payment of the blog. Since this use case uses ABT as payment method, your Pay operation call will return synchronous response. You have to process the response received from Amazon FPS. The response from Amazon FPS contains status of the transaction and the transactionid. You can store the transactionid for future references. See the Handling Synchronous Responses section for more information. As a result of the Pay call, money is transferred from senders account (John) to recipients account (Joe). You can view your account balance from the Amazon Payments account manager UI. See the Managing Your Account section for more information. View Transaction Details You can use Amazon FPS APIs to view transaction details on your account. To view transaction details, use the GetTransaction operation. To view the history of all transactions on your account, use the GetAccountActivity operation. Prepaid Use Case This use case describes buying and using prepaid balances in an Amazon FPS payment transaction. Important Amazon FPS supports the use of prepaid balances only in applications where a caller and recipient are the same participants. Use Case Overview DigitalDownload is a licensed seller of large selection of popular music and video downloads. Customers can buy prepaid balances from the DigitalDownload web site and use it to make payments for their purchases on the web site. John is a DigitalDownload customer who uses his Amazon Payments account to buy the prepaid balance and use it to pay for his purchases on the DigitalDownload web site. User Experience The user experience illustrates the steps in buying a prepaid balance and using the prepaid balance to make purchases at the DigitalDownload web site. Buying Prepaid Balance 1. John visits the DigitalDownload web site, enters a name, selects a prepaid balance amount and clicks the Buy Prepaid Card link. In this use case, he provides the following information: 93

96 Prepaid Use Case Name of the prepaid card=john Prepaid card option=$20 prepaid balance, Validity: 3 Months. Note To simplify the user experience, this application does not use a sign-in page. Instead, John enters a name that will be used to identify his prepaid card. 2. When John clicks the Buy Prepaid Card link, he is redirected to Amazon FPS web site where he views the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com address and password. 3. After John signs onto his Amazon Payments account, he views the Payment Details page. This page allows John to buy prepaid balance using a payment method displayed on the page. The Payment details displays information about: Recipient 94

97 Prepaid Use Case Reason for Payment Prepaid balance to be purchased 4. John selects his credit card as the payment method and clicks the Continue button. After John clicks the Continue button, he views the Confirm Payment Details page. On this page, he can review the payment details and confirm the payment by clicking the Confirm button. 5. On clicking the Confirm button, John is redirected to the DigitalDownload web site. Before redirecting John to the DigitalDownload web site, Amazon FPS will create a prepaid instrument with zero prepaid balance. After John is redirected the its web site, DigitalDownload will make a web service call to fund this prepaid balance for $20. Using Prepaid Balance 1. John visits the DigitalDownload web site, enters the name of his prepaid card and clicks the Go Shopping link. 95

98 Prepaid Use Case After John clicks the Go Shopping link, the DigitalDownload web site displays the Digital Download Options page. On the Digital Download options page, John selects the MP3 audio file- Now and Forever Richard Marx, and clicks the Download now link. On clicking the Download now link, DigitalDownload executes a payment transaction by making a web service call to Amazon FPS to use his prepaid balance. After receiving the payment, DigitalDownload displays a link to download the MP3 file. John clicks the Ready for Download button to download the MP3 file. 96

99 Prepaid Use Case On the Digital Download Options page, John can view the available prepaid balance. He can continue purchasing on the web site until his prepaid balance is exhausted. How to Build this Use Case This topic contains information that can help you in building a similar application with the assumption that you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments on your website for the music downloads. John is the sender in this use case who uses prepaid balance to purchases music files. See the Using Prepaid section for information on prepaid instruments, prepaid balances, creating prepaid instruments and more. Install Caller Token and Recipient Token As you play the role of a caller and a recipient, you need a caller token and a recipient token on your account. You can install these tokens using the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. See the Acquiring Recipient Tokenssection for more information on setting up a recipient token on your account. 97

100 Prepaid Use Case You will require only one caller token and one recipient token for executing all the payment transactions in this use case and hence, this is a one time set up. Acquire Prepaid Instrument, Funding Token and Sender Token In this use case, John plays the role of a sender who buys prepaid balance for $20 and uses it for multiple downloads. To setup the prepaid balance, you will require a prepaid instrument and a funding token to fund the prepaid balance associated with the instrument. You will also require a sender token to charge the prepaid balance when John makes a download on your web site. You can acquire the prepaid instrument, the funding token and the sender token by redirecting John to the Amazon FPS web site where he can set up a payment authorization and return to your web site. To redirect John to the Amazon FPS co-branded Prepaid Instrument Installation Pipeline, use a signed URL. A signed URL is created using your caller credentials and various parameters as explained below. Parameter Value callerreference PrepaidDigitalDownload A unique reference created to identify the sender token for your future use. paymentreason Downloading Digital Content Text describing this transaction for your customers to understand when they look at the payment details paymentmethod abt,ba,cc Payment method used to make the payment. fundingamount 20 The total value of the prepaid instrument. callerkey Your caller key Your AWS Access Key Id to identify you in the pipeline. awssignature URL signature Signature of the encoded URL created using your Access Key Id pipelinename SetupPrepaid Name of this pipeline returnurl Your website URL, where the user is redirected after completing the payment authorization. callerreferencefunding PrepaidDigitalDownload A unique reference created to identify the funding token for your future use. validitystart Validity of the prepaid instrument. validityexpiry Validity of the prepaid instrument. See the Signing A URL section for more information on creating a signed URL. The co-branded UI pipeline returns the following response parameters: 98

101 Prepaid Use Case Parameter Value sendertokenid Sender's token ID This is John s sender token that you will use in the Pay call. prepaidinstrumentid 57X2SQPECBV5LDLD6TVV1LQB 1MAETQMNUSZ567317U17R33C KVB53HZIXAV9WQVA This is the prepaid instrument associated with the prepaid balance. John s sender token will use this prepaid instrument as the payment method. fundingtokenid CKVB53HZI57X2SQPECBV5LDLD6 TVVNUSZ567317U17R33XAV91 LQB1MAETQMWQVA The used to fund the prepaid instrument. fundingamount 20 The total value of the prepaid instrument. status SC Status of the transaction. Since John uses credit card as the payment method to buy the prepaid balance, the status is SC. Fund Prepaid Balance You must fund the prepaid instrument before John can use it to purchase music downloads. To fund the prepaid instrument use the FundPrepaid operation. This operation transfers money from the senders account to your account and creates a prepaid balance for the sender. Parameter Value SenderTokenId Sender's token ID Specifies the sender token created by John. CallerTokenId Your caller token Your caller token. PrepaidInstrumentId 57X2SQPECBV5LDLD6TVV1LQB 1MAETQMNUSZ567317U17R33C KVB53HZIXAV9WQVA The prepaid instrument associated with the prepaid balance. FundingAmount 20 The total value of the prepaid instrument. TransactionDate T06:17:33.929Z The date on which the prepaid instrument creation request was send to Amazon FPS. SenderReference John A unique value used to identify the sender on your web site. RecipientReference Prepaid Digital Download A unique value used to identify the recipient on your web site. CallerReference Prepaid Digital Download A unique reference created to identify the sender token for your future reference. ChargeFeeTo DigitalDownload Specifies the participant paying 99

102 Prepaid Use Case Parameter Value the fees to Amazon FPS for the transaction. Sender John Text description about the sender involved in the transaction. Caller Prepaid Digital Download Text description about the caller involved in the transaction. Recipient Prepaid Digital Download Text description about the recipient involved in the transaction. MetaData Funding a prepaid card Used to specify details of the transaction. When the user returns to your web site you can display the prepaid balance using the GetPrepaidBalance operation. Making a Pay Call You can now use the sender token received from the Prepaid Instrument Installation Pipeline UI along with the caller token and the recipient token in the Pay operation. In this use case, the sender token uses the prepaid instrument as the payment method. Pay calls that use prepaid instrument as the payment method always result in a synchronous response. See the Making a Pay Request section for detailed information about using tokens to make a Pay call. Also see Pay operation section for information on the request and response parameters. Parameter Value SenderTokenId Sender's token ID Specifies the sender token created by John. CallerTokenId Your caller token Your caller token. RecipientTokenId Your recipient token The token to which the sender will make payments. In this use case this is your token. TransactionAmount 2.0 The cost of the MP3 audio file. TransactionDate T06:17:33.929Z The date on which the prepaid instrument creation request was send to Amazon FPS. SenderReference John A unique value used to identify the sender on your web site. RecipientReference Prepaid Digital Download A unique value used to identify the recipient on your web site. CallerReference Prepaid Digital Download A unique reference created to identify the sender token for your future reference. ChargeFeeTo DigitalDownload Specifies the participant paying 100

103 Postpaid Use Case Parameter Value the fees to Amazon FPS for the transaction. Sender John Text description about the sender involved in the transaction. Caller Prepaid Digital Download Text description about the caller involved in the transaction. Recipient Prepaid Digital Download Text description about the recipient involved in the transaction. MetaData Payment for MP3 file download at Digital Download using a Prepaid Card Used to specify details of the transaction. You have to process the response received from Amazon FPS. The response from Amazon FPS contains status of the transaction and the transactionid. You can store the transactionid for future references. See the Handling Synchronous Responses section for more information. As a result of the Pay call, the prepaid balance is reduced and the available prepaid balance is displayed to your customer. You can use the GetPrepaidBalance operation to get the available prepaid balance. You can view your account balance from the account manager UI. See the Managing Your Account section for more information. View Transaction Details You can use the Amazon FPS APIs to view the transaction details on your account. To view details about a particular transaction, use the GetTransaction. To view the history of all the transactions on your account, use the GetAccountActivity. Postpaid Use Case This use case describes setting up billing agreement in an Amazon FPS payment transaction. Important Amazon FPS supports the use of credit instrument only when a caller and recipient are the same. Use Case Overview DigitalDownload is a licensed seller of large selection of popular music and video downloads. Customers can download music or video files and pay for the downloads at a later point of time. Whenever the customers downloads a music or video file, their download usage is tracked and they are billed at a later point of time. DigitalDownload will charge the customers periodically or whenever the balance reaches the credit limit as agreed on the billing agreement. John is a DigitalDownload customer who uses his Amazon payments account to set up a postpaid billing 101

104 Postpaid Use Case agreement with DigitalDownload web site. User Experience The user experience illustrates the steps in setting up billing agreement and using it to make purchases at the DigitalDownload web site. Setting Up Billing Agreement 1. John visits the DigitalDownload web site, enters a name, selects a credit limit and clicks the Register Now link. In this use case, he provides the following information: Name=John Billing agreement option=$20, Validity: 3 Months. Note To simplify the user experience, this application does not use a sign-in page. Instead, John enters a name that will be used to identify his postpaid card. 2. When John clicks the Register Now link, he is redirected to Amazon FPS web site where he views the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com address and password. 102

105 Postpaid Use Case 3. After John signs onto his Amazon Payments account, he views the payment authorization page. This page allows John to set up payment authorization using a payment method displayed in the page. He can view the following information: 4. Billing Terms Payment Method Validity of the agreement Recipient Reason for the payment John selects his credit card as the payment method and clicks the Continue button. After John clicks the Continue button, he views the Confirm Payment Authorization page. On this page, he can review the payment details and confirms the payment authorization by clicking the Confirm button. 103

106 Postpaid Use Case 5. On clicking the Confirm button, John is redirected to the DigitalDownload web site. Before redirecting John to the DigitalDownload web site, Amazon FPS creates a credit instrument with a zero balance. Making Purchases 1. John visits the DigitalDownload web site, enters the name of his postpaid card and clicks the Go Shopping link. 2. After John clicks the Go Shopping link, the DigitalDownload web site displays the Digital Download Options page. On the Digital Download options page, John selects the MP3 audio file-now and Forever Richard Mark, and clicks the Buy now button. 104

107 Postpaid Use Case 3. On clicking the Buy now button, DigitalDownload executes a payment transaction by making a web service call to Amazon FPS. The web service call increases the balance on the credit instrument by the transaction amount. After the web service call is completed successfully, John can download the MP3 file and return to the DigitalDownload options page to download more digital content. The Digital Download options page also displays the balance. 105

108 Postpaid Use Case Settling the Balances 1. DigitalDownload signs in as an Administrator by clicking the Administrator link. 2. After signing in the administrator can settle the John's balance by clicking the Settle link. After the administrator clicks the Settle link, DigitalDownload makes a web service call to settle the accumulated balance on John s credit instrument. The next time John signs into his account on DigitalDownload, he see the updated balance. 106

109 Postpaid Use Case How to Build this Use Case This topic contains information that can help you in building a similar application with the assumption that you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments on your website for the music downloads. John is the sender in this use case who downloads the music files and pays for them later. See the Using Postpaid section for information on credit instruments, debt balances, creating postpaid instruments and more. Install Caller Token and Recipient Token As you play the role of a caller and a recipient, you need a caller token and a recipient token on your account. You can install these tokens using the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. See the Acquiring Recipient Tokens section for more information on setting up a recipient token on your account. You will require only one caller token and one recipient token for executing all the payment transactions in this use case and therefore, this is a one-time set up. Acquire Credit Instrument, Settlement Token and Sender Token In this use case, John plays the role of a sender who signs a billing agreement for $20 and uses it for purchases at the DigitalDownload web site. You must acquire a credit instrument, a settlement token and a sender token. The credit instrument is used to track to the download usage, the settlement token is used to settle the balance accumulated by John and the sender token is required in the pay call. To redirect John to the Amazon FPS co-branded Postpaid Instrument Installation Pipeline, use a signed URL. A signed URL is created using your caller credentials and various parameters as explained below. Parameter Value callerreference Postpaid Digital Download A unique reference created to identify the sender token for your future use. 107

110 Postpaid Use Case Parameter Value callerreferencesettlement Postpaid Settlement Digital Download A unique reference created to identify the sender token for your future use. paymentreason To download MP3 file Text describing this transaction for your customers to understand when they look at the payment details paymentmethod abt,ba,cc Payment method used to make the payment. creditlimit 20 The total value of the credit offered. callerkey Your caller key Your AWS Access Key Id to identify you in the pipeline. awssignature URL signature Signature of the encoded URL created using your Access Key Id pipelinename SetupPostpaid Name of this pipeline returnurl com/downloadfile.jsp Your website URL, where the user is redirected after completing the payment authorization. callerreferencefunding PostpaidDigitalDownload A unique reference created to identify the funding token for your future use. validitystart Validity of the credit instrument. validityexpiry Validity of the credit instrument. globalamountlimit 30 The maximum amount that can be charged using the settlement token. usagelimit1 Amount These parameters restrict usage to a maximum of $10 in a day. usagelimitvalue1 10 usagelimitperiod1 1 Days usagelimit2 Count usagelimitperiod2 1 Days These parameters restrict usage to a maximum of 5 times a day. See the Signing A URL section for more information on creating a signed URL. The co-branded UI pipeline returns the following response parameters: Parameter Value sendertokenid Sender's token ID This is John s sender token that you will use in the Pay call. 108

111 Postpaid Use Case Parameter Value InstrumentId 57X2SQPECBV5LDLD6TVV1LQB 1MAETQMNUSZ567317U17R33C KVB53HZIXAV9WQVA This is the credit instrument associated with the balance. John s sender token will use this prepaid instrument as the payment method. settlementtokenid VXLDPBB53HM7377DCTVMII6T 55X1QQBJM8QEECJEAV7WXVTB MSUS35C17F37CK2B The used to fund the prepaid instrument. status SC Status of the transaction. Since John uses credit card as the payment method to buy the credit instrument, the status is SC. Making a Pay Call You can now use the sender token received from the Postpaid Instrument Installation Pipeline UI along with the caller token and the recipient token in the Pay operation. In this use case, the sender token uses the credit instrument as the payment method. The Pay calls that use credit instruments as the payment method always result in a synchronous response. See the Making a Pay Request section for detailed information about using tokens to make a Pay call. Also see Pay operation section for information on the request and response parameters. Parameters and values used in this case are given below: Parameter Value RecipientTokenId Your recipient token The token to which the sender will make payments. In this use case this is your token. SenderTokenId Sender's token ID Specifies the sender token created by John. CallerTokenId Your caller token Your caller token. TransactionAmount 0.25 The cost of the MP3 audio file. TransactionDate T06:17:33.929Z The date on which the prepaid instrument creation request was send to Amazon FPS. SenderReference John A unique value used to identify the sender on your web site. RecipientReference Postpaid Digital Download A unique value used to identify the recipient on your web site. CallerReference Postpaid Digital Download A unique reference created to identify the sender token for your future reference. ChargeFeeTo DigitalDownload Specifies the participant paying the fees to Amazon FPS for the transaction. 109

112 Postpaid Use Case Parameter Value Sender John Text description about the sender involved in the transaction. Caller Postpaid Digital Download Text description about the caller involved in the transaction. Recipient Postpaid Digital Download Text description about the recipient involved in the transaction. MetaData Payment for MP3 file download at Digital Download using a Postpaid Card Used to specify details of the transaction. You have to process the response received from Amazon FPS. The response from Amazon FPS contains status of the transaction and the transactionid. You can store the transactionid for future references. See the Handling Synchronous Responses section for more information. As a result of the Pay call, the balance is reduced and the current balance is displayed to your customer. You can use the GetDebtBalance operation to get the current balance. You can view your account balance from the account manager UI. See the Managing Your Account section for more information. Settle Balances You can settle the accumulated balances using the SettleDebt operation. To settle the accumulated balance, you must pass the credit instrument and the settlement token that you have acquired from John. In this use case, the following parameters are passed in the SettleDebt operation: Parameter Value SenderTokenId Sender's token ID This is Johns sender token that you acquired. CallerTokenId Your caller token This is your caller token. CreditInstrumentId 672XIL72S3UIA49BZ9IC6VJA QB7ZLAXJJZUNG9EMMBX8KA26 3QIUILVWXMD4Z3XZ This is the credit instrument created for John by Amazon FPS. SettlementAmount The accumulated balance that you want to settle. TransactionDate T14:59:37.786Z The date of which you executed the transaction. SenderReference John This is a unique value that is used to specify the sender. RecipientReference Postpaid Digital Download This is a unique value that is used to specify the recipient. CallerReference Postpaid Digital Download This is a unique value that is used to specify the caller. 110

113 Recurring Payments Use Case Parameter Value ChargeFeeTo Recipient Specifies the participant who will pay the fee to Amazon FPS for this transaction. Sender John Text description about the sender. Recipient Postpaid Digital Download Text description about the recipient. Caller Postpaid Digital Download Text description about the caller. MetaData Settling Debt with Postpaid Digital Download Text description about the transaction. View Transaction Details You can use the Amazon FPS APIs to view the transaction details on your account. To view details about a particular transaction, use the GetTransaction. To view the history of all the transactions on your account, use the GetAccountActivity. Recurring Payments Use Case This use case describes how merchants (recipients) can accept fixed recurring payments from their customers using Amazon FPS. Use Case Overview Fast Route (a web site) is a real-time traffic information service that allows users to receive updates on city traffic conditions using their mobile phone. Users can select various subscription plans offered by Fast Route. The subscription plans offered by Fast Route are hourly, daily, and monthly charges. Users are charged depending on the subscription plan they choose. For demonstration purposes the subscription periods in the sample application is set to hours. However, in a real life use case, Amazon FPS supports subscription period in days, months and years. Also, all subscriptions have a validity of one year. User Experience The user experience illustrates the steps in subscribing and setting up payments for the online magazine subscription. Subscribing for the Online Magazine 1. John visits the Fast Route web site, enters a name, selects the subscription type, and clicks the Register Now button. In this use case, he provides the following information: Name = John 111

114 Recurring Payments Use Case 2. When John clicks the Register Now button, he is directed to Amazon FPS web site where he views the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com address and password. 3. After John signs onto his Amazon Payments account, he views the Payment Authorization page. This page displays the following information: Recipient Payment reason Amount of the subscription and validity Option to select a payment method 112

115 Recurring Payments Use Case 4. John selects his Amazon Payments account balance as the payment method and clicks the Continue button. After John clicks the Continue button, he views the Confirm Payment Details page. On this page, he can review the payment details and confirm the payment by clicking the Confirm button. 5. On clicking the Confirm button, John is redirected to the Fast Route web site. 6. Amazon FPS installs a recurring-use token on John's account. After John returns to the Fast Route web site, he views the status of his subscription. A thank you page is displayed, which confirms his subscription. 113

116 Recurring Payments Use Case The Fast Route web site will provide John with information and updates on his city's traffic condition on his mobile phone. Fast Route uses the recurring-use token to charge John depending on his subscription plan. Managing Subscription Payments 1. Fast Route administrators can manage subscription payments from their registered customers using the Administrator link. The administrator clicks the Administrator link and views the customer records. The customer record contains the customer's name, last payment date, and the due date for the next payment. 2. For a new customer, these dates are displayed as Not Set. If the administrators decide to charge John for his next payment, they click the Charge button. 114

117 Recurring Payments Use Case After the administrator clicks the Charge button, Fast Route will make a web service call and transfer money from John's account to the Fast Route's account. How to Build this Use Case This topic contains information that can help you in building a similar application with the assumption that you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments for the subscription. John is the sender in this use case who uses his Amazon Payment account balance to pay for the subscription. Fast Route is the caller that directs John to the Amazon FPS recurring-use token installation pipeline to install a token that will be used to charge John for his subscription. See the Acquiring Recurring Payments Tokens section for information on recurring payment tokens. Note This use case assumes that you are the caller and the recipient (Fast Route). Install Caller Token and Recipient Token Since you play the role of a caller and a recipient, you need a caller token and a recipient token on your 115

118 Recurring Payments Use Case account. You can install these tokens on your account using the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. See the Acquiring Recipient Tokenssection for more information on setting up a recipient token on your account. You will require only one caller token and one recipient token for executing all the payment transactions in this use case and therefore, this is a one-time set up. Acquire Recurring Payments Sender Token In this use case, John plays the role of a sender who registers at the Fast Route web site and uses his Amazon Payment account to subscribe to the real-time traffic information service. You must direct John to the Amazon FPS recurring-use token installation pipeline using a signed URL. A signed URL is created using your caller credentials and other required parameters as explained below. Parameter Value callerreference Fast Route A unique reference created to identify the sender token for your future use. paymentreason Payment for real-time traffic information service subscription Text describing this transaction for your customers. This information is available in the Payment Authorization page. recipienttokenid This is your recipient token Id This is used to identify the recipient. paymentmethod abt, ba, cc Payment methods used to make the payment. transactionamount 20 The cost of the subscription. callerkey Your caller key This is your AWS Access Key Id which is used by Amazon FPS to identify you in the pipeline. awssignature This is the URL signature Signature of the encoded URL created using your Access Key Id pipelinename Recurring Name of this pipeline returnurl hanks.jsp The web site URL, where the user is redirected after completing the payment authorization (token installation). validitystart Validity of the token. validityexpiry Validity of the token. recurringperiod 1 week The frequency at which Fast Route will charge John for the subscription. globalamountlimit 30 The maximum amount that can be charged using the recurring payment sender token. 116

119 Recurring Payments Use Case Parameter Value usagelimit2 Amount You can specify either Amount or Count (number of times) as the usage limit type. usagelimitperiod2 1 Week This takes the value of the following type (examples): 1 Month 4 Years A integer followed by one of the following strings Hour Day Week Month Year See the Signing A URL section for more information on creating a signed URL. The co-branded UI pipeline returns the following response parameters: Parameter Value TokenId 55X2BQEECJVXLDPDCTVM1QQB JM8ETBMSUS35M7377C17F37C KBB53HII6AV7WXVT This is John s sender token that you will use in the Pay call. status SC Status of the transaction. Since John uses credit card as the payment method to buy the credit instrument, the status is SC. Making a Pay Call You can now use the sender token received from the Amazon FPS recurring-use token installation pipeline along with your caller token and recipient token in the Pay operation to transfer money. See the Making a Pay Request section for detailed information about using tokens to make a Pay call. Also see Pay operation section for information on the request and response parameters. Parameters and values used in this case are given below: Parameter Value RecipientTokenId Your recipient token Id The token to which the sender will make payments. In this use case this is your token. SenderTokenId Your sender token Id Specifies the sender token cre- 117

120 Reserve and Settle Use Case Parameter Value ated by John. CallerTokenId Your caller token Id Your caller token. TransactionAmount 20 The cost of the subscription. TransactionDate T06:17:33.929Z The date on which the transaction is received by Amazon FPS. SenderReference John A unique value used to identify the sender on your web site. RecipientReference FastRoute A unique value used to identify the recipient on your web site. CallerReference FastRoute A unique reference created to identify the sender token for your future reference. ChargeFeeTo Recipient Specifies that the participant pays the fees to Amazon FPS for the transaction. Sender John Text description about the sender involved in the transaction. Caller FastRoute Online Traffic Information Text description about the caller in the transaction. Recipient FastRoute Online Traffic Information Text description about the recipient involved in the transaction. MetaData Payment for the weekly magazine subscription Used to specify details of the transaction. You have to process the response received from Amazon FPS. The response from Amazon FPS contains the status of the transaction and the transactionid. You can store the transactionid for future references. See the Handling Synchronous Responses section for more information. As a result of the Pay call, money is transferred from sender's account to the recipients account.you can view your account balance from the account management UI. See the Managing Your Account section for more information. View Transaction Details You can use the Amazon FPS APIs to view the transaction details on your account. To view details about a particular transaction, use the GetTransaction. To view the history of all the transactions on your account, use the GetAccountActivity. Reserve and Settle Use Case This use case describes the reserve and the settle method for making a payment transaction. Topics in this section 118

121 Reserve and Settle Use Case Use Case Overview topic contains an overview of the use case and provides information on the participants involved in the transaction. User Experience topic contains information on the sequence of steps that happen in a typical transaction. How to Build this Use Case topic contains information on how you can set up a similar application or payment transaction at your web site. Important Amazon FPS supports only the use of credit cards for reserve and settle. Use Case Overview DigitalDownload is a licensed seller of a large selection of popular music and video downloads. It uses Amazon FPS to receive payments from its customers for the purchases on its website. To provide a quality customer experience, DigitalDownload reserves the amount on the customer's credit card and settles the amount after the customer satisfactorily downloads the music file. John is a customer of DigitalDownload and also has an Amazon Payments account. He visits the DigitalDownload web site to purchase music and uses his Amazon Payments account to pay DigitalDownload for his purchase. User Experience The following steps show the sequence of events that take place in a typical transaction at the DigitalDownload web site. Reserving the Amount The following procedure describes the steps in reserving the amount. 1. John visits the DigitalDownload web site, enters his name, selects an MP3, and clicks the Download Now button. 119

122 Reserve and Settle Use Case 2. After John clicks the Buy Now button, DigitalDownload directs John to Amazon FPS web site where he is presented with the Amazon.com Sign In page. He signs into his Amazon Payments account using his Amazon.com Id and password. 3. Once he signs in, John views the payment authorization page. The payment authorization page allows John to view the payment details and select a payment method for the transaction. Payment details displays information about: Recipient Reason for Payment Total Transaction Amount 120

123 Reserve and Settle Use Case John selects his credit card as the payment method and clicks the Continue button. John is then shown a Confirm Payment Details page, where he can review the payment details and confirm the payment by clicking the Confirm button. On clicking the Confirm button, John is redirected to the DigitalDownload web site. DigitalDownload reserves the amount (cost of the music file) on John's credit card. 121

124 Reserve and Settle Use Case Note The payment transaction is not executed on the Amazon FPS web site; it is executed by DigitalDownload by making a web service call. Settling the Amount The following procedure describes the steps in settling the amount. 1. On the homepage, John clicks the Your Account link. 2. Johns account contains the link to download the song. He clicks on the Download button to download the song. How to Build this Use Case This topic contains information on building this use case with the assumption that you are DigitalDownload. In this use case, you are the caller and the recipient. As a caller you can make web service calls to Amazon FPS and as a recipient you can receive payments on your web site for the music downloads. John is the sender in this use case who purchases music files. In any Amazon FPS transaction you require a sender, recipient and caller tokens. Install Caller and Recipient Tokens 122

125 Reserve and Settle Use Case You must install a caller token and a recipient token on your account. A caller token allows you to make web service calls and a recipient token allows you to receive payments. To install tokens on your account, use the InstallPaymentInstruction operation. See the Installing Tokens on your Account section for more information on installing tokens on your account. See the Acquiring Recipient Tokens section for more information on setting up a recipient token on your account. You only require one caller token and one recipient token for executing all the payment transactions in this use case. Installing a caller token and a recipient token is a one time activity. Acquire Sender Token You need the sender token to make payment transaction. You can get the sender token by redirecting senders to Amazon FPS web site where they set up a payment authorization and return your web site. Important Amazon FPS does not allow you to install tokens on senders account. You must redirect the senders to an Amazon FPS UI pipeline and get the tokens from them. See the Acquiring Tokens section for more information. In this use case, when John clicks the Buy Now link on your web site, you must redirect him to the Amazon FPS Single-use Token Installation Pipeline. To redirect users to Amazon FPS pipeline, you must use a signed URL. A signed URL is created using the parameters required in this transaction. See the Signing A URL section for information on creating a signed URL. The parameters and its values for this use case are listed in the following table: Parameter Value Meaning callerreference DigitalDownloadMP3NaFERM A unique reference created to identify the sender token for your future reference. paymentreason MP3 Download- NowAndForever Text describing this transaction. Your customers will see this when they view the payment details. paymentmethod cc Payment methods that you support. In this case it is only credit card. transactionamount 0.30 Price in USD. callerkey Your caller key Your AWS Access Key Id used to identify you. awssignature URL signature Signature of the encoded URL created using your Access Key Id. pipelinename SingleUse Name of this pipeline. returnurl com/downloadfile.jsp URL to which the user is redirected after completing the payment authorization. 123

126 Reserve and Settle Use Case In this pipeline, John logs into his Amazon Payments account, views the payment details, selects a payment method, and confirms the payment. John is redirected back to your web site using the return URL along with the sender token. You can identify the payment method used in the token by looking at the value of the status response parameter. Making Reserve Call You can now use the sender token received from the UI pipeline along with the caller token and recipient token that you have installed on your account in the Reserve operation call. In this use case, since John has used his credit card as the payment method, this Reserve call will return asynchronously. See the Making a Pay Request section for more information about using tokens to make a web service call to Amazon FPS. Also see Reserve section for information on the request and response parameters. The parameters and the values of the Reserve call in this use case are: Parameter Value Meaning CallerTokenId Your caller token Your caller token. RecipientTokenId Your recipient token Specifies the recipient token. Your token to which the Sender makes the payment. SenderTokenId Sender's token Specifies the sender token. This is the token that John created. TransactionAmount 0.30 Specifies the amount that will be charged to the sender. callerreference Digital Content Download A unique reference created to identify the sender token for your future reference. ChargeFeesTo Recipient Specifies the fee that you will pay to Amazon FPS for executing this transaction. TransactionDate T09:32:12.727Z Specifies the date when the transaction is executed. Caller DigitalDownload web site Text to describe the transaction or other details. MetaData Reserving amount for Digital Download. Used to specify transaction details like order number, invoice number. Sender John Customer of DigitalDownload. Reserve and Settle transaction Text description about the sender involved in the transaction. SenderReference Reserve and Settle Customer A unique value used to identify the sender on your web site. Since this use case uses credit card as payment method, your Reserve call will return asynchronous response. You have to process the response received from Amazon FPS. The response from Amazon FPS contains status of the transaction and the transactionid. You can store the transactionid for future references. See the Using the GetResults Operation section for more information. 124

127 Testing Application using Sandbox As a result of the Reserve call, money is reserved on the senders credit card. View Transaction Details You can use Amazon FPS APIs to view transaction details on your account. To view transaction details, use the GetTransaction operation. To view the history of all transactions on your account, use the GetAccountActivity operation. Making Settle Call After the customer has successfully downloaded the music file you can settle the amount reserved on the credit card. When you settle the amount, the money is transferred to your account. You can settle the amount using the Settle operation call. In this use case, since John has used his credit card as the payment method, this Settle call will return asynchronously. See the Making a Pay Request section for more information about using tokens to make a web service call to Amazon FPS. Also see Settle section for information on the request and response parameters. The parameters and the values of the Settle call in this use case are: Parameter Value Meaning SettlementAmount 0.30 The amount to be settled. TransactionId 1243R2LQKQTCGELBDDZNC536 COMCBNRKEL1 Specifies the transaction Id that was received as part of the Reserve call. TransactionDate T09:32:36.672Z Specifies the date of the transaction. Documentation References You can see the following sections in the Amazon FPS Getting Started guide and the developer documentation for more information on the concepts discussed in this use case. Section Contains information on Guide Concepts Amazon FPS concepts Amazon FPS Getting Started Guide Acquiring Single-use Tokens Acquiring single use sender token Programming Reference Single-use Token Installation Pipeline The Amazon FPS UI pipeline used to create single-use tokens. Co-Branded UI Pipeline Reference Acquiring Recipient Tokens Acquiring recipient tokens Programming Reference Recipient Token Installation Pipeline The Amazon FPS UI pipeline used to redirect recipients to setup recipient tokens. Co-Branded UI Pipeline Reference Testing Application using Sandbox 125

128 Sandbox Test Accounts Sandbox End-Points Amazon FPS Sandbox web service API end-point is: fps.sandbox.amazonaws.com. Amazon FPS Sandbox Co-branded UI API end-point is: Sandbox Test Accounts You can create test accounts on sandbox from the Amazon Payments account management UI page ( Click the links provided in the Create Test Accounts box after you sign into the sandbox. To create a personal account, click the Create an Amazon FPS Personal Account on sandbox and to create a business account, click the Create an Business account on sandbox. Sandbox User Experience You can test the following user experience on Amazon FPS Sandbox: Registering for business or personal account Depositing funds into a test account's Amazon Payments account balance Checking test account's Amazon Payments account balance Checking test account's activity Co-branded UI experience Simulating Errors in Sandbox You can use the sandbox to simulate the following error conditions using the test data: Error Test Data Use the following sender tokens to simulate InvalidAccountState errors. address not verified J5B1P2Q4VIA2V3ZB475M6MQFSK9EZDARC CFV4UV7VTDB9ZVX6LEE3XRXFHTBEXI1 Suspended account H7PSM2Z9A53NVQFId834IIFM1G8JI1RKQUT K1MPAGMFZASSGFDV3RCDU4ZMNFIK4 Closed account Z1VR1HA7R7LXXSM7243F34ACQDPEZMLD 8V5QSSE4GU654MCZLIHICW8MTXC1TLF9 Use the following recipient tokens to simulate InvalidAccountState errors address not verified J4B1S2L4V7AEV3RBB7596ZQFXKUEZ9AHC CHV3UVVV7DBFZKX6IEP3XNXQHTTECIC Suspended account H5PS82X9AC31VQPIQ83BILFMBGGJI1RAQ URKPMP9GLFZNS1GFQVVRCTUFZM4FFKT Closed account Z5VRRHX7RZL4XS57Z43H32ACPDAEZ4LC8 V3QFSEAG365TM3ZLIHXCWXM1XCKTDF5 The following errors can be simulated using the Amount values. Temporary Decline Amounts that are of the format, N.6n, where N, 126

129 Amazon FPS Logo Placement Guidelines Error Test Data n are any number. Example, 100.6, 0.6, 2.61 Failure Amounts that are of the format, N.7n, or N.8n, where N, n are any numbers. Example, 20.7, , 4.8, 0.81 Amazon FPS Logo Placement Guidelines Amazon FPS provides payments mark graphics that you can use on your web site. The payments mark graphic on your web site represents your acceptance in using Amazon Payments as one of the preferred payment methods. Read the guidelines ( for using the Amazon Payments mark for more information for more information. You can download the Amazon Payments mark graphics using this link: Amazon Payments mark graphic: Examples of using the payment mark as a payment method option This image illustrates the use of Amazon Payments mark as a preferred payment method. This image illustrates how you can provide Amazon Payments as a payment method option using radio buttons. 127

130 Example of using the payments mark on your home page This image illustrates how you can provide Amazon Payments as a payment method option using a drop down list. Example of using the payments mark on your home page This image illustrates how you can use the payments mark graphic on your web site. The payments mark graphic informs the customer that the web site uses Amazon Payments for transactions. The Buy Now button is linked to the signed URL that directs the customer to the Amazon FPS co-branded UI pipeline. 128

131 Example of using the payments mark on your home page 129