Reserve and Settle Use Case

This use case describes the reserve and the settle method for making a payment transaction.

Topics in this section

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.

John visits the DigitalDownload web site, enters his name, selects an MP3, and clicks the Download Now button.
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 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 credit card as the payment method and clicks Continue.
John is then shown a Confirm Payment Details page, where he can review the payment details and confirm the payment by clicking Confirm.
On clicking Confirm, John is redirected to the DigitalDownload web site. DigitalDownload reserves the amount (cost of the music file) on John's credit card.

Note
The payment transaction is not executed on the Amazon FPS web site; it is executed by DigitalDownload by making a web service call.

	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.

On the homepage, John clicks the Your Account link.
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

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`	`http://www.digialdownload.com/downloadfile.jsp`	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 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 listed in the following table.

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 - 1172655110015`	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`	`2007-02-08T09:32:12.727Z`	Specifies the date when the transaction is executed.
`CallerDescription`	`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.
`SenderDescription`	`John Customer of DigitalDownload. Reserve and Settle transaction`	Text description about the sender involved in the transaction.
`SenderReference`	`Reserve and Settle Customer1172655110015`	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.

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 listed in the following table.

Parameter	Value	Meaning
`SettlementAmount`	`0.30`	The amount to be settled.
`TransactionId`	`1243R2LQKQTCGELBDDZNC536COMCBNRKEL1`	Specifies the transaction Id that was received as part of the `Reserve` call.
`TransactionDate`	`2007-02-10T09:32:36.672Z`	Specifies the date of the transaction.

Documentation References

You can see the sections in the following table 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