SolidusAffirm

This extension provides the Affirm payment option for your Solidus storefront by implementing the Affirm Direct API

Installation

Add solidus_affirm to your Gemfile:

gem 'solidus_affirm', github: 'solidusio-contrib/solidus_affirm'

Bundle your dependencies and run the installation generator:

bundle
bundle exec rails g solidus_affirm:install

Configuration

To generate the correct URL's in the JSON payload we need to specify the default_url_options for the Solidus engine. You can do that like this:

Spree::Core::Engine.routes.default_url_options = {
  host: 'example.com'
}

You will need to get your public and private API keys from the Affirm Dashboard, see the Affirm Documentation.

When you configure the payment gateway you need to provide those keys to the payment gateway and also the link to the Affirm JS Runtime script.

Make sure that during development and testing you use the sandbox version:

Sandbox = https://cdn1-sandbox.affirm.com/js/v2/affirm.js
Live = https://cdn1.affirm.com/js/v2/affirm.js

Hooks and extension points

We provide a configuration class the allows you customize the complete setup.

To do so, you can use the SolidusAffirm::Config class in an initializer, like config/initializers/spree.rb for example.

Callback controller

When performing a checkout on Affirm, there are 2 callbacks that Affirm could send to our system.

a POST to the confirm action.
a GET to the cancel action.

To change the controller that is handling those actions you can specify the route name like this:

SolidusAffirm::Config.callback_controller_name = 'my_custom_affirm'

Since the routes file here is within the Spree namespace you will have to provide the controller in that namespace. So with the above sample, my_controller, you should define a controller like this:

class Spree::MyCustomAffirmController < Spree::StoreController
  def confirm
    #implement your own confirm action here.
  end

  def cancel
    #implement your own cancel action here.
  end
end

Note that you could inherit from the provided controller as well if you just want to override one part. The default controller we have setup here is Spree::AffirmController.

If you just need to change the way you like to handle the confirm and cancel actions, read below. We provide a hook for that as well.

Callback flow for confirming and canceling

For confirming or canceling an Affirm payment we provide sane defaults for that in the SolidusAffirm::CallbackHook::Base class.

That class provides 3 methods that we use in the controller for:

setup the payment on the order correctly and use the checkout state_machine
the redirect url after the confirm action is done
the redirect url after the cancel action

To change that behaviour you can provide your own callback hook class like this:

class MyCallbackHook < SolidusAffirm::CallbackHook::Base
  def authorize!(payment)
    #do your magic here.
  end

  def after_authorize_url(order)
    'sample/endpoint/success'
  end

  def after_cancel_url(order)
    'sample/endpoint/cancel'
  end
end

Then configure this class name in an initializer like this:

SolidusAffirm::Config.callback_hook = MyCallbackHook

Checkout payload serializer

To generate the JSON payload for the order that Affirm needs to setup the payment we provide a default serializer in SolidusAffirm::CheckoutPayloadSerializer.

You can change that by providing your custom serializer. If you just need to override a few attributes you should inherit from SolidusAffirm::CheckoutPayloadSerializer and just provide the implementations of the attributes you would like to change. The untouched attributes will be inherited by default.

For example, to just override the shipping attribute you can do something like this:

class MyCustomPayloadSerializer < SolidusAffirm::CheckoutPayloadSerializer
  def shipping
    MyCustomAddressSerializerImpl(object.ship_address)
  end
end

Then configure this new class to be the serializer:

SolidusAffirm::Config.checkout_payload_serializer = MyCustomPayloadSerializer

Testing

First bundle your dependencies, then run rake. rake will default to building the dummy app if it does not exist, then it will run specs, and Rubocop static code analysis. The dummy app can be regenerated by using rake test_app.

bundle
bundle exec rake

When testing your applications integration with this extension you may use it's factories. Simply add this require statement to your spec_helper:

require 'solidus_affirm/factories'

ChristianRimondi/solidus_affirm