Home

Overview

There are a few main components of the Spree Amazon Payments extension.

• Amazon Controller - Similar to the checkout controller in Spree but modified to do the required work.
• Amazon Callback Controller - Handles Refund Notification Callback
• Spree Config Settings
• Amazon Transaction Model
• Payment Gateway
• Model Overrides
• Views/Partials

Amazon Controller

Similar to the checkout controller in Spree but modified to do the required work. This is one likely place you're going to be customizing. The primary actions match up to the steps of a traditional Spree checkout:

• Address
• Delivery
• Payment
• Confirm
• Complete

Because of the workflow with the widgets, however, with the Amazon checkout things don't flow quite in that order. The actual process for a user is:

• Address
• Payment
• Delivery
• Confirm
• Complete

In our case, the Payment step is never rendered, it is called with a javascript callback when the payment widget is filled in, and stores the Amazon Order Reference number on the AmazonTransction. (You can customize this by overriding app/views/spree/amazon/_payment, which is displayed when an address is selected.)

Address Action

When the address action is called, we reset the order back to the cart state, and render the javascript widgets.

Delivery Action

When the delivery action is called, we get the order data from Amazon (based on the reference number stored in the payment action). We fill that into Spree objects the best we can, and advance the state machine to the appropriate place. We aren't able to get all of the data about the order at this point, because we need to pick a shipping method to determine the total cost in order to confirm the order (required to get the full address from the API).

Confirm Action

When we get to the Confirm step, we've picked a shipping method and therefore can set the order total and confirm the order with Amazon. This doesn't finalize the order, but locks the total in and allows us to get the full address. We get that saved, and give the user one last chance to review their order before they place it.

Complete Action

The complete action advances the state machine to complete (allowing Spree to do its standard order processing routines) and shows the order information.

Amazon Callback Controller

Handles Refund Notification Callback Handles posts to /amazon_callback from the Instant Notification to recieve callbacks when an order is refunded. See the README for information on how to set this up. When JSON is received for a refund, we find the payment based on the refund id and log that it has been properly refunded. There is likely no need to modify this controller.

Spree Config Settings

Config is all provided from your Amazon Payments dashboard once you've signed up for an account.

• amazon_client_id
• amazon_merchant_id
• amazon_aws_access_key_id
• amazon_aws_secret_access_key

Amazon Transaction Model

The AmazonTransaction model has a payment as its source, holds the Amazon order reference, and determines whether a payment can be captured, credited, and closed.

Payment Gateway

The Gateway class is like any other payment gateway (see https://guides.spreecommerce.com/developer/payments.html) and implements authorization, capture, etc.

Model Overrides

Payment

We've modified the Payment state machine, but it matches the standard state machine, with the addition of the closed state and close transition, used to indicate that the payment has been closed on Amazon and can't be modified.

Order

Added the relationship to amazon_transactions and added a few convenience methods. No modification of existing methods.

AppConfiguration

Added relevant configuration settings, no changes to existing config.

Views/Partials

The views as they exist are fairly straightforward, modeled off the standard Spree views, with the modifications needed to load the Amazon Payment widgets and process the custom checkout flow.

_login.html.erb

This partial is loaded on the cart page, and adds the "Pay with Amazon" button.

_order_details.html.erb

This partial is a duplicate of the stock Spree partial with the links to return to previous steps in the checkout removed.

_payment.html.erb

This partial contains the payment widget, rendered when the address is selected.

The payment widget has an onPaymentSelect callback which posts the order reference number to the Amazon controller and adds the submit button to the view.

address.html.erb

This view loads the required javascript for both the address and payment widgets, and places the divs in the view. If you want to change how these are displayed, this will likely be what you will want to change.

The address widget has an onAddressSelect callback which we use to render the payment javascript widget (contained in a partial for clarity). You could add additional functionality here.

complete.html.erb

This view shows all the order details after it is completed.

confirm.html.erb

This view shows the order details one last time before the order is completed.

delivery.html.erb

This view has the form to point at the amazon controller, and then renders the standard Spree delivery form.