Boomerang

Boomerang is a library for working through the often very back-and-forth process of Amazon.com FPS payment transactions. In particular, this library was developed for and is most helpful to building "marketplace applications."

Install

If you want to use this code in a Rails application, just add it to your Gemfile:

gem "boomerang"

To use the code in a non-Rails application, first install the gem:

gem install boomerang

Then require the library in your code:

require "boomerang"

Either way, you will want to setup Boomerang as your application loads. I recommend just setting a constant you can then refer to throughout your application. In Rails, I would put the following code in config/initializers/boomerang.rb. Setup is easy, just add you AWS credentials:

FPS = Boomerang.new( "ACCESS_KEY_ID",
                     "SECRET_ACCESS_KEY",
                     true )  # use sandbox (false sends to production)

Usage

Boomerang can generate Co-branded UI forms for your views. These are used to bounce a user over to Amazon.com to agree to some terms of payment. Amazon.com will send them back to the specified :return_url with key parameters like tokenID and refundTokenID (for Recipient tokens).

You would create a form for a Recipient token like this:

<%= FPS.cbui_form( :recipient,
                   return_url:         "http://youapp.com/receive_tokens",
                   caller_reference:   "YOUR_ID_FOR_THE_TRANSACTION",
                   max_fixed_fee:      "10.00",
                   recipient_pays_fee: "True" ) %>

You are free to use any other Recipient token parameters in the camelCase Amazon.com expects or in the snake_case more natural to Rubyists.

A form for a Recurring sender token is similar:

<%= FPS.cbui_form( :recurring,
                   return_url:         "http://youapp.com/receive_tokens",
                   caller_reference:   "YOUR_ID_FOR_THE_TRANSACTION",
                   recipient_token:    "RECIPIENT_TOKEN",
                   recurring_period:   "1 month",
                   transaction_amount: "100.00" ) %>

Again, use any Recurring token parameters in camelCase or snake_case.

As the requests come back to your application, you need to verify the data with Amazon.com to ensure it has not been tampered with. Boomerang has a method for that:

valid = FPS.verify_signature?( request.url[/\A[^?]+/],  # or :return_url
                               params )

When the time comes, Boomerang will help you use the various tokens you have collected to start a payment transaction:

payment = FPS.pay( caller_reference:      "YOUR_ID_FOR_THE_TRANSACTION",
                   charge_fee_to:         "Recipient",
                   marketplace_fixed_fee: "10.00",
                   recipient_token_id:    "RECIPIENT_TOKEN",
                   sender_token_id:       "RECURRING_TOKEN",
                   transaction_amount:    "100.00" )

The returned Hash contains important details like the :transaction_id that you can later use to check up on the payment:

{ :transaction_id     => "AMAZON_PAYMENT_ID",
  :transaction_status => "Pending",
  :request_id         => "AMAZON_REQUEST_ID" }

Finally, you can check up on your payment to see when it clears or is declined:

status = FPS.get_transaction_status("AMAZON_PAYMENT_ID")

Again, you get a Hash with all the key details:

{ :transaction_id     => "AMAZON_PAYMENT_ID",
  :transaction_status => "Success",
  :caller_reference   => "YOUR_ID_FOR_THE_TRANSACTION",
  :status_code        => "Success",
  :status_message     => "HUMAN_READABLE_STATUS_MESSAGE",
  :request_id         => "AMAZON_REQUEST_ID" }