Solidus Six Saferpay

The solidus_six_saferpay engine adds checkout options for the Saferpay Payment Page (Integration Guide, JSON API documentation) and the Saferpay Transaction (Integration Guide, JSON API documentation).

This gem is built to be a general-purpose integration of the Six Saferpay payment interface. However due to lack of resources and because we are (as far as we know) the only users of this gem, we are only testing our use cases (PaymentPage). Therefore we can not guarantee that this will work in any other solidus shop. If you consider using this gem, please test everything thoroughly.

Add solidus_six_saferpay to your Gemfile:

gem 'solidus_six_saferpay'

Bundle your dependencies and run the installation generator:

bin/rails generate solidus_six_saferpay:install

Add the following javascript to your application.js manifest file below the //= require spree line:

//= require solidus_six_saferpay/saferpay_payment

Configure the credentials for the Saferpay API. These credentials must be set as ENV variables. You can find the required information in the Saferpay interface under https://test.saferpay.com/BO/Settings/Terminal

SIX_SAFERPAY_CUSTOMER_ID='XXXXXX'
SIX_SAFERPAY_TERMINAL_ID='XXXXXXXX'
SIX_SAFERPAY_USERNAME='your api basic auth username'
SIX_SAFERPAY_PASSWORD='your api basic auth password'
SIX_SAFERPAY_BASE_URL='https://test.saferpay.com/api/'
SIX_SAFERPAY_CSS_URL='' # currently not tested

Configure the host for your application so that we can give Saferpay an absolute URL to redirect on success or failure

# in development.rb
Spree::Core::Engine.routes.default_url_options { 'http://localhost:3000' }

# in production.rb
Spree::Core::Engine.routes.default_url_options { 'https://url-to-your-solidus-shop.tld' }

After adding the solidus_six_saferpay gem to your Solidus Rails app, you can create new payment methods Saferpay Payment Page and Saferpay Transaction in the admin backend under "Settings" > "Payment". When adding a new Saferpay payment method, you can configure the payment method with the information you have received from SIX when creating a new test account.

Notable configuration options are:

• as_iframe: If checked, the payment form is displayed on the "Payment" checkout page. If unchecked, the user needs to select a payment method and then proceed with the checkout to be redirected to the Saferpay payment interface.
• require_liability_shift: If checked, payments are only accepted if Saferpay grants liability shift for the payment. If a payment has no liability shift, then the checkout process fails and the customer needs to use other means of payment.

All other configuration options are restrictions for available payment methods. If you don't check any payment methods, then the interface will make all payment methods available. If you restrict the available payment methods for the user, the interface will reflect your choice. If you select only a single payment method, the user is directly forwarded to the input form for the selected payment method without having to choose themselves.

If you want to display the masked number on the confirm page, you must override the default _payment.html.erb partial of spree so that the provided partial can be rendered (instead of just displaying the name of your payment method).

<!-- This is the default "app/views/spree/payments/_payment.html.erb" (including our modification) -->
<% source = payment.source %>

<!-- Add this code to render our provided partial that shows the masked number -->
<% if source.is_a?(Spree::SixSaferpayPayment) %>
  <%= render source, payment: payment %>
  
<!-- turn this "if" into an "elsif" to prevent rendering the payment method name -->
<% elsif source.is_a?(Spree::CreditCard) %>
  <span class="cc-type">
    <% unless (cc_type = source.cc_type).blank? %>
      <%= image_tag "credit_cards/icons/#{cc_type}.png" %>
    <% end %>
    <% if source.last_digits %>
      <%= t('spree.ending_in') %> <%= source.last_digits %>
    <% end %>
  </span>
  <br />
  <span class="full-name"><%= source.name %></span>
<% elsif source.is_a?(Spree::StoreCredit) %>
  <%= content_tag(:span, payment.payment_method.name) %>:
  <%= content_tag(:span, payment.display_amount) %>
<% else %>
  <%= content_tag(:span, payment.payment_method.name) %>
<% end %>

There are several options for extending or overriding default behaviour such as the params used for initializing a payment or the type of items provided. To configure this functionality, take a look at SolidusSixSaferpay::Configuration and start from there.

This section should provide a birds-eye view of the implementation to help you not get lost when you dive into the details below.

The basic flow for a Saferpay Payment goes like this:

1. User chooses Saferpay payment method on "Payment" checkout step
2. Controller receives AJAX request to initialize Saferpay payment
3. The InitializePayment service requests a token from the Saferpay API and stores this token in a SixSaferpayPayment
4. User enters payment information and submits Saferpay form
5. Controller receives the success request from Saferpay
6. Controller asserts/authorizes payment via AuthorizePayment service with help of the previously stored token
7. If assert/authorize are successful, Controller validates and processes the payment via ProcessPayment service which results in a Spree::Payment
8. Controller redirects to the "Confirm" checkout step
9. User confirms the purchase
10. During completing the order, Spree::Payment initiates the capture! of the payment

As you can see, most interactions with the Saferpay API are encapsulated in service objects, which then call the appropriate gateway methods to perform requests.

A note about error handling: If the user aborts the checkout at any point or the payment fails for some other reason, the user is redirected to the "Payment" step of the checkout process and shown an error message. Additionally, already authorized payments are voided so that no money stays allocated for longer than necessary.

In this section, we provide detailed information about the checkout flow and its implementation. Note that the flow is almost identical for both the PaymentPage and the Transaction interface. Because of this, there is usually a base service class that contains the logic, and then there are subclass services for the PaymentPage and Transaction interface that configure the base service class.

The same pattern also exists for the gateway: The SolidusSixSaferpay::Gateway implements the common logic, and the SolidusSixSaferpay::PaymentPageGateway and SolidusSixSaferpay::TransactionGateway only implement gateway actions that are unique for this interface.

During the "Payment" step of the checkout process, solidus renders a partial for all active and available payment methods. Our partial is called _saferpay_payment. When the partial is loaded, an AJAX request goes to the CheckoutController#initialize_payment action. From there, we make a request to the Saferpay server to initialize the Payment. This request happens via the SixSaferpay Gateway and is abstracted away in the InitializePayment service.

If this request is successful, a new SixSaferpayPayment object is created. This object contains the Saferpay Token for the current payment and links it with the current Spree::Order and the used Spree::PaymentMethod. It also stores the response of the PaymentInitialize request in hash form.

If the initialize request is not successful, then the user is shown an error message.

If Saferpay can successfully process the user-submitted information, then Saferpay redirects the user to a SuccessUrl, which is configured to be handled by CheckoutController#success. In this #success action, we find the SixSaferpayPayment record with the correct token that was created in the PaymentInitialize request. If the SixSaferpayPayment is found, a PaymentAuthorize request is performed (abstracted away the AuthorizePayment service).

If Saferpay can not successfully process the submitted information or the payment fails for some other reason, Saferpay redirects to a FailUrl, which is configured to be handled by SaferpayPaymentPageController#fail. In this #fail action, we try to find the SixSaferpayPayment record based on the token that was created in the PaymentPageInitialize request. If the SixSaferpayPayment is found, a PaymentPageInquire request is performed to gather information about the failure, and the user is redirected to the "Payment" step of the checkout process and shown an error with information about the failure. If the record can not be found, then a generic error is displayed.

If the user has entered the payment information successfully, we can perform an authorize request. Because this request is different depending on the payment interface, it is explained for each interface below. When the authorize request is successful, we update the SixSaferpayPayment record with the received data. This data most importantly includes:

• TransactionId
• TransactionStatus
• TransactionDate
• SixTransactionReference
• DisplayText

And, if a credit card was used:

• MaskedNumber
• ExpirationYear
• ExpirationMonth

If the PaymentPage interface is used, then the payment is authorized directly when the user submits the Saferpay form. In this case, we can not perform an authorize request and instead perform an assert request to gather information about the payment. After performing the assert request, we update the SixSaferpayPayment record based on the data from the assert request.

If the Transaction interface is used, then the payment must be authorized after it has been initialized. Therefore, we perform an authorize request to reserve the requested amount. If the authorize request is successful, we update the SixSaferpayPayment based on the data from the authorize request.

If the authorize request is successful, the received information is validated and processed in the ProcessPaymentPagePayment service. At the moment, the following validations are performed:

• Liability Shift: We check if the liability shift has been granted for the payment
• Payment Status: We check if the payment status of the Saferpay payment is AUTHORIZED
• Order Reference: We check if the order referenced by Saferpay matches the order that is being processed
• Matching Amount and Currency: We check if the Saferpay amount and currency match the total and currency of the processed order

If any of these checks fail, then the payment process is aborted and the user must restart the payment flow.

If the payment validation is successful, all previously existing payments for this order that are still valid are cancelled. After cancelling old payments, a new Spree::Payment is created based on the data stored in the SixSaferpayPayment record. This ensures that only one valid payment exists from this point onward.

If the payment processing fails, then the user is redirected to the "Payment" step of the checkout process and shown an error message.

When the user confirms the purchase in the checkout process, the saferpay payment is automatically captured. This action is triggered in the following way:

1. When the user confirms the order, Spree::CheckoutController#update triggers @order.complete (through #transition_forward)
2. Spree::Order::Checkout defines the state transition before_transition_to :complete, do: :process_payments_before_complete
3. Spree::Order defines #process_payments_before_complete and calls #process_payments! if any valid payments exist
4. Spree::Order::Payments defines #process_payments! which calls process! on each unprocessed payment
5. Spree::Payment::Processing defines #process! and calls #purchase!
6. Spree::Payment::Processing defines #purchase and calls #purchase on the PaymentMethod associated with the payment
7. Since this payment method is a Spree::PaymentMethod::SaferpayPaymentPage that inherits from Spree::PaymentMethod (through SaferpayPaymentMethod and CreditCard), the #purchase method is delegated to the #gateway
8. Spree::PaymentMethod::SaferpayPaymentPage#gateway_class defines the gateway to be the SolidusSixSaferpay::PaymentPageGateway
9. Therefore, the PaymentPageGateway#purchase action is called

When a user cancels a payment, the CheckoutController receives a fail request and handles this request in the #fail action. The result is that the user is shown an error message stating that the payment was aborted.

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec/spec_helper.rb:

require 'solidus_six_saferpay/testing_support/factories'

Or, if you are using FactoryBot.definition_file_paths, you can load Solidus core factories along with this extension's factories using this statement:

SolidusDevSupport::TestingSupport::Factories.load_for(SolidusSixSaferpay::Engine)

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Before and after releases the changelog should be updated to reflect the up-to-date status of the project:

bin/rake changelog
git add CHANGELOG.md
git commit -m "Update the changelog"

Please refer to the dedicated page on Solidus wiki.

Copyright (c) 2021 [name of extension author], released under the New BSD License.