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.

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.
After John clicks the Download Now link, he is directed to the Amazon FPS web site. To access the Amazon FPS web site he signs onto his Amazon Payments account from the Amazon Sign In page using his Amazon.com e-mail ID and password.
Once he signs in, John views the optional Payment Method Selection page. This page will appear only if John does not have a default payment method set up with Amazon. This page allows him to select a payment method for the transaction.
John selects his Amazon Payments account balance (ABT) as the payment method and clicks the Continue button.
After he clicks Continue, John views the Confirm Payment Authorization page. He reviews the payment details and confirms the payment by clicking Confirm.
After clicking Confirm, 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.
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 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

The following code snippet creates the signed URL for this use case, for example:

  https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start?callerKey=<caller credentials>
  &pipelineName=SingleUse
  &returnURL=http://<destination-hostname>:<port-number>/amazonfpssdk/usecases/digitalDownload/paymentDetails.jsp?PaymentAmount=0.10&Download=Now+and+Forever+-+Richard+Marx&uniqueId=1177495829105
  &callerReference=DigitalDownload1177495829105
  &transactionAmount=0.10
  &paymentReason=Now and Forever - Richard Marx
  &awsSignature=<Encrypted signature value>

Parameter	Value	Meaning
`callerReference`	`DigitalDownload1177495829105`	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. This value means that the sender will authorize the payment for a maximum of $0.10.
`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`	`http://<destination-hostname>:<port-number>/ amazonfpssdk/usecases/digitalDownload/paymentDetails.jsp? PaymentAmount=0.10&Download=Now+and+Forever+-+Richard+Marx &uniqueId=1177495829105`	URL to which the user is redirected 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. Please note that this value can be less than or equal to the amount authorized by the sender in the UI pipeline earlier.
`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.
`CallerDescription`	`DigitalDownload web site`	Text to describe the transaction or other details.
`MetaData`	`Digital Content downloaded: Now and Forever - Richard Marx`	Used to specify transaction details like order number, invoice number.
`SenderDescription`	`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

	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.