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

	Important
	Single-use tokens have an expiry time of 3 hours as compared to multiuse tokens, which have an expiry time of 1 year.The caller cannot determine the expiry time for single use tokens but can specify the expiry time for multi-use tokens.

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

DigitalDownload is a licensed online retailer that sells audio files (MP3).
A sender (customer) visits the DigitalDownload web site, selects a digital content, and clicks the Buy Now button.

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:

https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start
?callerKey=This the caller key that is associated with your developer account&pipelineName=SingleUse
&returnURL=http://www.digitaldownload.com/paymentDetails.jsp?PaymentAmount&
0.10&Download=Candle+In+the+Wind+-+Elton+John%26uniqueId&
1183401134535&callerReference=DigitalDownload1183401134541&
transactionAmount=0.10&paymentReason=To download Candle In the Wind - Elton John&
?PaymentAmount=0.10&Download=Candle+In+the+Wind+-+Elton+John
&uniqueId=1183401134535&callerReference=DigitalDownload1183401134541
&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.

Description of parameters used in this example are:

Parameter	Description	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 web site with the installed token and status of the installation.	`http://www.digitaldownload.com/paymentDetails.jsp?PaymentAmount& 0.10&Download=Candle+In+the+Wind+-+Elton+John%26uniqueId& 1183401134535&callerReference=DigitalDownload1183401134541& 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.	DigitalDownload1183401134541 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.	0.10

The sender views the Amazon.com Sign In page and signs into the Amazon Payments account using the amazon.com e-mail 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.
The sender views the summary of payment authorization information. This page displays the transaction details and the payment method selected by the sender. The transaction details were included in the signed URL used to direct the sender to the Amazon FPS CBUI pipeline. The sender 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. The download link lets the sender download the content from the Digital Download site. 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 transaction process. See the Co-branding Preferences section for more information.