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."

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)

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" }