Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Rails plugin to help with integration as an Amazon DevPay web-hosted product.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 MIT-LICENSE
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 init.rb
README.rdoc

Devpay

This Devpay plugin is designed to ease integration with Amazon’s DevPay services, specifically for web-hosted DevPay products.

Note: DevPay products for the desktop will very likely not find this plugin terribly useful. Sorry.

The DevPay Process

DevPay is designed to be a very hands-off payment processing and subscription management system. It allows developers to nearly ignore the process altogether. The pieces which are of concern, however, are as follows:

  1. Customer signs up for your product using a link you provide (see Devpay.purchase_url_for),

  2. The customer successfully signs up for your product and is redirected to a URL you'd previously provided during product registration,

  3. The redirection contains an activation key and product code which must be activated (see Devpay.activate!),

  4. Following activation, you'll receive a User Token and Persistent Identifier (both of which should be stored),

  5. The customer happily uses your hosted DevPay product,

  6. … you can periodically check the customer's subscription status (see Devpay.active?) …

  7. Profit!

Things You'll Need

Amazon Web Service Account

First, you'll need an Amazon Web Services account. Once you've got that, you'll have to provide the following to this plugin:

Access Key Id

Provided to you by Amazon when you signed up for Amazon Web Services

Secret Access Key

Provided to you by Amazon when you signed up for Amazon Web Services

These can be set by telling the plugin to use the same credentials for all requests (i.e. Devpay.access_key_id = 'ABCD1234'), or each request has optional parameters to allow for per-request credentials to be used.

Register Your DevPay Products

You will have to register your DevPay products once you have an AWS account. At the moment, each product must be approved prior to use by an AWS employee, this may take up to a few days.

Once you've registered your products, you'll need to record the following for each:

Product Code

An 8-digit alphanumeric code, given to you by Amazon.

Product Token

A 300+ digit hash that begins with {ProductToken}, given to you by Amazon.

Offer Code

An 8-digit alphanumeric code. You'll want to extract this from the purchase url Amazon provides to you (i.e. aws-portal.amazon.com/gp/aws/user/subscription/index.html?offeringCode=ABCD1234).

Examples

Lets say you're loading up your credentials into a global constant hash called AWS_CREDS, and you've stored your product identifiers into an ActiveRecord 'Product' model as product_code, product_token, and offer_code, respectively.

Setting Your Credentials

You can globally set your credentials, like so:

Devpay.access_key_id      = AWS_CREDS[:access_key_id]
Devpay.secret_access_key  = AWS_CREDS[:secret_access_key]

Or, you can pass your credentials as optional parameters to each Devpay method call you make:

Devpay.active?(pid, product_code, AWS_CREDS[:access_key_id], AWS_CREDS[:secret_access_key])

Product URLs

If you've got an object which responds to :offer_code, you can:

<%= link_to 'Buy Now', Devpay.purchase_url_for(product) %>

Otherwise, you can pass the offer code directly:

<%= link_to 'Buy Now', Devpay.purchase_url_for('ABCD1234') %>

See Devpay.purchase_url_for for more information.

Activation

Once the user comes back to your site, you'll get an Activation Key and a Product Code. If you're unlucky and the redirection failed, you may have to query your customer for these values, directly (probably a pull-down for the products would be better than asking for that one).

In your DevPayResponseController, you could:

# This URL was set in your DevPay product as the return URL (i.e. http://www.example.com/devpay_response/returned)
def returned
  if product                  = Product.find_by_product_code(params['ProduceCode'])
    activation_response       = Devpay.activate!(params['ActivationKey'], product)
    PaidUser.create!({
      ...
      :user_token             => activation_response.user_token,
      :persistent_identifier  => activation_response.persistent_identifier,
      ...
    })
  else
    # Handle unrecognized Product Code here.
  end
end

See Devpay.activate! for more information

Query for Active Product Codes

You could request a list of all active products which a customer is utilizing by your DevPay services:

Devpay.find_all_product_codes_for(paid_user)      #=> [ "ABCD1234", "ABCD1235" ]

In the above example, we're assuming paid_user responds with the correct persistent identifier when :persistent_identifier is called against it. See Devpay.find_all_product_codes_for for more information.

Subscription State

As Amazon does not alert you to changes in DevPay subscription states (like PayPal's Instant Payment Notification service, for example), it is up to you to periodically determine the state of the customer's subscription. This can be done with the following:

Devpay.active?(paid_user, product_paid_for)       #=> true
Devpay.active?(paid_user, product_not_paid_for)   #=> false

In the above example, we're assuming paid_user responds with the correct persistent identifier when :persistent_identifier is called against it. Further, we're also assuming that product is an object which responds to :product_code and returns a valid DevPay product code. See Devpay.active? for more information.

Notable, Miscellaneous Information

Raised Exceptions

All exceptions raised by this plugin inherit from Devpay::Error (a type of Exception). So, in general, a

rescue Devpay::Error => e
  puts "Devpay had a problem: #{e.class} '#{e.message}'"

Should catch any and all problems raised through the use of this plugin. More specific errors are nearly always raised, however. Nearly a hundred more specific errors are not publicly documented, but can be found in lib/errors/errors.rb and lib/errors/license_service/errors.rb.

Request Throttling

The Amazon License Service (used for activating and verifying DevPay subscriptions) may enter periods of request throttling. During these periods the service will respond with HTTP 503 Service Unavailable. Amazon's documentation states that you should retry these requests, but fails to stipulate a retry delay. This implementation defaults the delay period to a half-second. :)

More information can be found in the documentation for Devpay::LicenseService.

Copyright and Attributions

Copyright © 2008 Nathaniel E. Bibler, released under the MIT license.

Thanks to david@aws and Amazon.com for providing basic Ruby samples for interaction with the Amazon License Service.

Something went wrong with that request. Please try again.