Skip to main content

Merchant Help

 

Affirm Merchant Help

Spree Integration

Overview

This guide describes how to integrate Affirm into the Spree Ecommerce platform so you can provide Affirm as a payment option to your customers. After integrating Affirm, your Spree site will:

  • Offer Affirm as payment option on the checkout page
  • Process Affirm charges in your order management system
  • Display Affirm promotional messaging

The integration steps are:

  1. Install the Spree extension
  2. Configure Affirm as a payment method
  3. Add Affirm promotional messaging
  4. Review your order management functions
  5. Add the Confirmation Page function
  6. Test your integration
  7. Deploy to production

Before you begin

Before beginning integration, you should review:

Sandbox development

You should have received an email inviting you to create an Affirm account. Click here for information about accessing your account.

Develop and test the Affirm integration in your development environment connected to our sandbox. To use our sandbox, retrieve your sandbox API keys at https://sandbox.affirm.com/dashboard/#/apikeys for use during integration.

After development and testing, you'll need to update your integration to use your live API keys, which you can find at https://affirm.com/dashboard/#/apikeys.

1. Install the Spree extension

  1. Download the Spree extension
  2. Add the following line to your Spree Gemfile:
gem 'spree_affirm', :github => "affirm/spree_affirm"
  1. Install the gem with Bundler:
bundle install
bundle exec rails g spree_affirm:install
  1. Restart your Spree server

2. Configure Affirm as a payment method

  1. Sign in to the Spree admin page
  2. Go to Configurations > Payment Methods
  3. Click New Payment Method
  4. Set PROVIDER to Spree::Gateway::Affirm
  5. Enter Affirm Monthly Payments for NAME
  6. Click Create
  7. Keep SERVER set to sandbox.affirm.com for testing
  8. Check the TEST MODE box for testing
  9. Enter the API Key (public key) and Secret Key (private key) you retrieved from the Affirm sandbox merchant dashboard
  10. If your checkout process automatically captures the charge, set AUTO CAPTURE to Yes
  11. Set ACTIVE to Yes to enable Affirm as a payment method.
  12. Click Update

Screen Shot 2018-07-24 at 3.13.30 PM.png

3. Add Affirm promotional messaging

Affirm promotional messaging components—monthly payment messaging and educational modals—show customers how they can use Affirm to finance their purchases. Properly placed promotional messaging helps drive increased AOV and conversion.

Adding Affirm promotional messaging is a required integration step, and you should complete it before testing your integration. Click here for information about adding Affirm promotional messaging.

4. Review your order management functions

Processing orders (authorize, void, refund, and partial refund) in Spree updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Spree to keep order status synced with Affirm. For more information on processing orders in Spree, refer to their documentation.

5. Add the Confirmation Page function

When a customer completes their purchase, you can send their order and product information to Affirm for A/B testing, which will help you optimize your site. Send this information by adding the Confirmation Page function to your payment confirmation page. We only require orderId, total, productId, and quantity for A/B testing.

Click here for all the Confirmation Page function parameters.

affirm.analytics.trackOrderConfirmed({
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1
}]);

Required function parameters

Order object

Parameter Type Description
orderId string Your internal unique identifier representing the order. Maximum 500 characters.
total integer The total amount of the transaction, including tax and shipping, stated in USD cents (e.g., $100 = 10000).

Product object

Parameter Type Description
productId string Your internal unique identifier representing the product, such as the SKU or an internal database identifier. Maximum 500 characters.
quantity integer The quantity of the purchased product.

6. Test your integration

After completing your integration, do a thorough testing of both your front-end and order management functions in our sandbox to ensure that everything works as expected. Click here for our recommended test plan. However, you’ll need to tailor your testing plan to your specific systems, processes, and integration.

7. Deploy to production

Coordinate testing with Affirm

Before deploying the Affirm integration to your production site, Affirm will need to test it in your development or staging environment connected to our live environment. Contact your Client Success Manager to coordinate this test.

Connect to the live Affirm environment

  1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  2. In the Spree admin panel, go to Configurations > Payment Methods
  3. Select Affirm Monthly Payments
  4. Set SERVER set api.affirm.com
  5. Enter the API Key (public key) and Secret Key (secret key) you just retrieved from the Affirm merchant dashboard
  6. Uncheck the TEST MODE box
  7. Click Update

Launch to production

After you’ve connected to our live environment and we’ve tested your integration, you’re ready to deploy to your production environment and offer Affirm as a payment option to your customers.