The FPS service supports a mechanism called Pay Now widgets for accepting payments on your web site. A Pay Now widget is an HTML form containing input fields that define and authenticate an FPS payment operation for purchasing an item. When a customer submits the form a POST request is sent to the FPS service, and the customer is directed to a payment pipeline that guides her to log in to her Amazon account, select a payment method, and authorize the payment.
Here is a Pay Now widget form that allows a customer to purchase an item named “My Product” for the price of $20.
<form method="post"
action="https://authorize.payments-sandbox.amazon.com/pba/paypipeline">
<input type="hidden" name="amazonPaymentsAccountId"
value="ABCDEFGHIJ1234567890ABCDEFGHIJ12345678">
<input type="hidden" name="accessKey" value="ABCDEFGHIJ1234567890">
<input type="hidden" name="signature" value="ykkLrMaSvdS+qgFZtlHUY+B9USg=">
<input type="hidden" name="description" value="My Product">
<input type="hidden" name="amount" value="USD 20.00">
<input type="image" border="0" src=
"https://authorize.payments-sandbox.amazon.com/pba/images/payNowButton.png">
</form>Pay Now widgets allow a customer to make an FPS payment in much the same way as she would through the Co-branded UI SingleUse Sender Pipeline (see Acquire a SingleUse Sender Token”). The widget is signed using your AWS secret key to ensure it is not altered, but this signature does not expire so the widget will remain valid indefinitely. Widgets offer two key advantages over using the SingleUse Sender pipeline:
The widgets pipeline performs the payment without any interaction from your application. If you use the SingleUse Sender pipeline, your application is obliged to retrieve a sender token and perform the Pay API operation once the customer has approved a payment. This step is not required when you use a widget, so your application need be nothing more than a simple server script for generating widget forms.
Both the customer and the vendor receive an email notification message from the pipeline when a payment is completed.
The Pay Now widgets are divided into three categories: static button, dynamic button, and alternative payment method. The distinction between three kinds of widgets is more confusing than enlightening, because the only real difference between widgets is how they are used rather than anything intrinsic in the widget itself. Here is a description of the three categories of widget:
This refers to a widget that describes a payment amount and item description that does not change over time. As these values do not change, the widget need only be created once and can be reused multiple times. If a static button widget meets your needs, the easiest way to create one is to use the widget generation tool available on Amazon’s FPS web site. Visit your Amazon Payments account and click the Create “Pay Now” Widget link at the top of the page. This tool produces an HTML form that you can copy and paste into your web site.
This refers to a widget that will contain changing payment, description, or other information and must therefore be generated on demand. We will present code below that will generate Pay Now widget HTML forms for inclusion in your web site.
This is a glorious term for a widget form that is submitted by a piece of browser scripting code, rather than by the user clicking on the form’s submit button directly. As any of the widgets—or indeed any HTML form—can be submitted with a browser script, we consider this widget category to be little more than a slight variation on the dynamic button widget and will say no more about it.
It is worth reiterating that the content of your widgets will be almost entirely the same, regardless of which category the widget belongs to.
The HTML form that constitutes a Pay Now widget is a standard POST form with an action argument directed at the widget payment pipeline, and a submit image button with Amazon Payments branding. Here is the boilerplate template for a widget form that works with the FPS sandbox environment.
<form method="post"
action="https://authorize.payments-sandbox.amazon.com/pba/paypipeline">
<!-- Input fields that define the payment go here -->
<input type="image" border="0" src=
"https://authorize.payments-sandbox.amazon.com/pba/images/payNowButton.png">
</form>A widget that works in the FPS production environment looks much the same, except the URLs for the form’s action and input image will not contain the -sandbox string.
Table 10-27 lists the names of the input fields that may be included in a Pay Now widget form and describes the purpose of each field.
Table 10-27. Pay Now widget input fields
| Field Name | Value | Required? |
|---|---|---|
| amazonPaymentsAccountId | A unique identifier for your FPS account. This ID is not your AWS access key. The easiest way to obtain your FPS account ID
is to use the online widget generation tool in your Amazon
Payments account to create a widget form (the type or content
of the form is unimportant) and copy the value of the | Yes |
| accessKey | Your AWS access key. | Yes |
| amount | The amount the customer will pay in dollars and cents. All payments are in US dollars. | Yes |
| description | A description of the reason for the payment, such as the product’s name. | Yes |
| signature | A signature value that authorizes the form. The signature proves to FPS that you generated the form, and that the content of the form has not been changed since you generated it. To sign the form, you combine the name and value of all the form’s input fields into a string in alphabetical order and generate a HMAC value of the string using your AWS secret key. | Yes |
| referenceId | An identifier for the payment that you can set to be a value that is meaningful to your application. | No |
| returnUrl | A website URL to which the customer’s browser is redirected after a successful payment. If this field is not included, the default return URL specified in you CoBranded Pipeline settings is used. | No |
| abandonUrl | A website URL to which the customer’s browser is redirected after he has canceled a payment. If this field is not included, the default abandon URL specified in you CoBranded Pipeline settings is used. | No |
| immediateReturn | A boolean value that specifies whether a user should be
shown the final status page for the payment before being
redirected back to your website. If this field has a value of
0, the customer will be
shown the status page and must click a continue button to
return to your website, while if it has a value of 1 the customer will be redirected as
soon as the payment is completed. | No |
Example 10-18 defines a Ruby method that generates an authenticated Pay Now widget HTML form. To use the widget produced by this method, you simply include the form in an HTML document on your web site.
Example 10-18. Build a Pay Now widget: S3.rb
def build_payment_widget(payments_account_id, amount, description,
extra_fields={})
fields = extra_fields.clone
# Mandatory fields
fields['amazonPaymentsAccountId'] = payments_account_id
fields['accessKey'] = @aws_access_key
fields['amount'] = "USD #{amount}"
fields['description'] = "#{description}"
# Generate a widget description and sign it
widget_desc = fields.sort.to_s
fields['signature'] = generate_signature(widget_desc)
# Combine all fields into a string
fields_string = ''
fields.each_pair do |n,v|
fields_string += %{<input type="hidden" name="#{n}" value="#{v}">\n}
end
return %{<form method="post" action=
"https://authorize.payments-sandbox.amazon.com/pba/paypipeline">
#{fields_string}
<input type="image" border="0" src=
"https://authorize.payments-sandbox.amazon.com/pba/images/payNowButton.png">
</form>
}
endThe following example shows how to generate a Pay Now widget form that will allow a customer to purchase the Moon for the bargain price of $500.
# Define your FPS Payments Account ID
irb> payments_account_id = 'ABCDEFGHIJ1234567890ABCDEFGHIJ12345678'
# Define optional field settings that will be included in the widget
irb> options = {
irb> 'referenceId' => 'ProductCode-1234',
irb> 'returnUrl' => 'http://my.website.com/post_payment_success',
irb> 'abandonUrl' => 'http://my.website.com/post_payment_cancel',
irb> 'immediateReturn' => '1'
irb> }
# Generate an authenticated Pay Now widget HTML form
irb> form = fps.build_payment_widget(payments_account_id, 500.00, 'Moon', options)
# Here is the HTML form generated by the method. We can include this form
# in a web page and start collecting payments from our customers
<form method="post"
action="https://authorize.payments-sandbox.amazon.com/pba/paypipeline">
<input type="hidden" name="signature" value="ykkLrMaSvdS+qgFZtlHUY+B9USg=">
<input type="hidden" name="returnUrl"
value="http://my.website.com/post_payment_success">
<input type="hidden" name="abandonUrl"
value="http://my.website.com/post_payment_cancel">
<input type="hidden" name="accessKey" value="ABCDEFGHIJ1234567890">
<input type="hidden" name="amazonPaymentsAccountId"
value="ABCDEFGHIJ1234567890ABCDEFGHIJ12345678">
<input type="hidden" name="immediateReturn" value="1">
<input type="hidden" name="description" value="The Moon">
<input type="hidden" name="amount" value="USD 500.0">
<input type="hidden" name="referenceId" value="ProductCode-1234">
<input type="image" border="0" src=
"https://authorize.payments-sandbox.amazon.com/pba/images/payNowButton.png">
</form>When a customer completes a payment through the Pay Now widget pipeline or cancels the payment process, her web browser is redirected to a URI of your choosing. Typically, this URI will be a location in your web site where you can provide feedback, to the customer. To help you provide useful feedback, the redirection URI sent by the FPS service includes a number of parameter values that describe the result of the payment process. Your application can interpret these parameters to find out what happened, allowing it to display the appropriate summary to the customer.
You use this feature in the same way as you would use the result URIs generated by the Co-Branded UI pipeline, as we discussed in Interpreting CBUI Result URIs.” Please refer to the earlier discussion to find out how to interpret result URIs from an FPS pipeline. The parameters and status code values in Pay Now result URIs differ slightly from those returned by the Co-Branded UI pipeline, but they can be processed in the same way. Table 10-28 lists the parameters that may be included in the Pay Now widget result URIs.
Table 10-28. Pay Now widget result URI parameters
| Parameter | Description |
|---|---|
| transactionId | The Amazon Payments transaction ID. |
| referenceId | The reference ID for the payment, if any. |
| status | A status code indicating the overall result of a Pay Now pipeline operation. This status code is included in all result URIs. |
| errorMessage | A message describing why a pipeline operation failed. This parameter is only included when an error occurs during a pipeline operation. |
| signature | A signature value generated by the Pay Now pipeline to authenticate its result URI. Your application should verify this signature to ensure that the result URI was indeed generated by FPS. |
Table 10-29 lists the
status codes that may be returned in the status parameter of a Pay Now widget result
URI.
Table 10-29. Pay Now widget result URI status codes