UnlockGateway

Base gateway for Unlock's payment gateway integrations

Installation

Create a Rails full Engine with:

rails plugin new unlock_my_gateway_name --full

Add this line to your gateway's .gemspec file:

s.add_dependency "unlock_gateway"

Require unlock_gateway before anything else:

# On lib/unlock_my_gateway_name.rb
require "unlock_gateway"

Usage

Gateway module

Every gateway should implement a module UnlockMyGatewayName::Models::Gateway that follows the pattern described here. You should add the following to this module:

include UnlockGateway::Models::Gateway

Contribution module

Every gateway should implement a module UnlockMyGatewayName::Models::Contribution that follows the pattern described here. You should add the following to this module:

include UnlockGateway::Models::Contribution

Setting class

To let Unlock know what are the settings for this gateway, you should implement a method called available_settings in your UnlockMyGatewayName::Models::Gateway that returns an array of UnlockGateway::Setting. Here is an example:

# In your lib/unlock_my_gateway_name/models/gateway.rb
module UnlockMyGatewayName
  module Models
    module Gateway

      include UnlockGateway::Models::Gateway

      def available_settings
        settings = []
        settings << UnlockGateway::Setting.new(:token, "Your API token", "Instructions")
        settings << UnlockGateway::Setting.new(:key, "Your API key", "Instructions")
      end

    end
  end
end

Controller

You should define a ContributionsController in your gateway, such as

class UnlockMyGatewayName::ContributionsController < ::ApplicationController
  is_unlock_gateway
end

Calling is_unlock_gateway inside you controller will extend UnlockGateway::Controller::ClassMethods and include UnlockGateway::Controller, preparing your controller to be an unlock gateway controller. You can check out what is added to your controller here.

Views

The only view you need to create is a partial called unlock_my_gateway_name/contributions/_form, that will receive a local variable gateway. In this partial you can render the sandbox_warning and base_form partials to avoid duplicating code. Here is an example:

# In your views/unlock_my_gateway_name/contributions/_form.html.slim
= form_for @contribution, url: my_gateway_name_contributions_path, method: :post do |form|
  = render partial: 'initiatives/contributions/sandbox_warning', locals: { gateway: gateway }
  = render partial: 'initiatives/contributions/base_form', locals: { form: form, gateway: gateway }
  = form.submit "Proceed to checkout"

Routes

You should add a :my_gateway_name_contributions resource in your config/routes.rb that uses UnlockMyGatewayName::ContributionsController and has the same path as you've defined in UnlockMyGatewayName::Models::Gateway#path. You should also always add member actions activate and suspend. Here is an example:

# In your config/routes.rb
Rails.application.routes.draw do

  resources :my_gateway_name_contributions, controller: 'unlock_my_gateway_name/contributions', only: [:create, :edit, :update], path: '/my_gateway_name' do
    member do
      put :activate
      put :suspend
    end
  end

end

Registering the gateway with Unlock's Gateway model

You should add an initializer to register the gateway, otherwise it won't show as an option for Unlock's users.

# In your config/initializers/register.rb
UnlockGateway.register 'UnlockMyGatewayName'

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

This project rocks and uses MIT-LICENSE.