Ingenico Direct Ruby SDK

Introduction

The Ruby SDK helps you to communicate with the Ingenico Direct Server 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 meta data

Its use is demonstrated by an example for each possible call. The examples execute a call using the provided API keys.

See the Ingenico Direct Developer Hub for more information on how to use the SDK.

Structure of this repository

This repository consists out of three main components:

  1. The source code of the SDK itself: /lib/ingenico/direct/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 direct-sdk-ruby

Using a pre-built gem

  1. Download the latest version of the Ruby SDK from GitHub. Choose the direct-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 direct-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 direct-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 direct-sdk-ruby.gemspec
gem install direct-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 direct-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 'ingenico/direct/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:

  • direct_api_apiKeyId for the API key id to use. This can be retrieved from the Configuration Center.
  • direct_api_secretApiKey for the secret API key to use. This can be retrieved from the Configuration Center.
  • direct_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.