Worldline Acquiring Ruby SDK

Introduction

The Ruby SDK helps you to communicate with the Worldline Acquiring API. Its primary features are:

  • convenient Ruby library for the API calls and responses
    • marshalls Ruby request objects to HTTP requests
    • unmarshalls HTTP responses to Ruby response objects or Ruby exceptions
  • handling of all the details concerning authentication
  • handling of required metadata

See the Worldline Acquiring Documentation for more information on how to use the SDK.

Structure of this repository

This repository consists out of four main components:

  1. The source code of the SDK itself: /lib/worldline/acquiring/sdk/
  2. The source code of the SDK unit tests: /spec/lib/
  3. The source code of the SDK integration tests: /spec/integration/

Note that the source code of the unit tests and integration tests can only be found on GitHub.

Requirements

Ruby 2.3 or higher is required. As for JRuby, version 9.0.0.0 and higher are supported. In addition, the following packages are required:

Installation

Using RubyGems

To install the SDK using gem, execute the following command:

gem install acquiring-sdk-ruby

Using a pre-built gem

  1. Download the latest version of the Ruby SDK from GitHub. Choose the acquiring-sdk-ruby-x.y.z.gem file from the releases page, where x.y.z is the version number.

  2. Navigate into the folder where the gem file is downloaded to, and execute the following command:

    gem install acquiring-sdk-ruby-x.y.z.gem

  3. Feel free to delete the gem file at this point, it is no longer required.

From source

  1. Download the latest version of the Ruby SDK from GitHub. Choose the acquiring-sdk-ruby-x.y.z.zip file from the releases page, where x.y.z is the version number.

  2. Unzip the file, navigate into the folder where the file is unzipped to, and execute the following commands:

    gem build acquiring-sdk-ruby.gemspec
gem install acquiring-sdk-ruby-x.y.z.gem

  3. Feel free to delete the unzipped archive, the zip file and the gem file at this point, they are no longer required.

Uninstalling

After the Ruby SDK has been installed, it can be uninstalled using the following command:

gem uninstall acquiring-sdk-ruby

The required packages can be uninstalled in the same way.

Usage

After the Ruby SDK has been installed, it can be required in Ruby program as follows:

require 'worldline/acquiring/sdk'

Running tests

There are two types of tests: unit tests and integration tests. The unit tests will work out-of-the-box; for the integration tests some configuration is required. First, some environment variables need to be set:

  • acquiring_api_oauth2_clientId for the OAuth2 client id to use.
  • acquiring_api_oauth2_clientsecret for the OAuth2 client secret to use.
  • acquiring_api_merchantId for your merchant ID.

In addition, to run the proxy integration tests, the proxy URI, username and password should be set in the spec/fixtures/resources/properties.proxy.yml file.

In order to run the unit and integration tests, some additional dependencies are required:

They can be installed using the following command:

gem install rake rspec webmock sinatra

Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.

The following commands can now be executed from the root directory of the SDK folder (/) to execute the tests:

  • Unit tests:

    rake unit

  • Integration tests:

    rake integration

  • Both unit and integration tests:

    rake spec

Generating documentation

Documentation can be generated with YARD. YARD can be installed as a gem. The gems required to generate documentation are:

  • rake 12.3.3 or higher
  • yard 0.9.5 or higher

They can be installed using the following command:

gem install rake yard

Note: if rake is already installed as part of the Ruby installation, this will cause a conflict error. This can safely be ignored.

Once YARD and rake are installed, documentation can be generated with the following command (ran from the root folder):

rake yard

Documentation will be generated in the /doc folder. The file /doc/index.html is the main documentation file.