Ruby SDK

Introduction

The Ruby SDK helps you to communicate with the  Acquiring API . More specifically, it offers a fluent Ruby API that provides access to all the functionality of the RESTful Server API. Below, we discuss the following topics in detail.

• Initialization of the SDK

• Exceptions

• Logging

• Advanced use: Connection pooling

• Advanced use: Customization of the communication

• Notes

The source code of the SDK is available on  Github . There you can find installation instructions.

The API documentation of the latest version of the SDK is available  here . For a specific version, add the actual version to the URL.

Initialization of the Ruby SDK

All Ruby code snippets presented in the API Reference assume you have initialized the Ruby SDK before using them in your Development Environment. This section details the initialization of the Ruby SDK.

Initializing is simple, and requires only one key task: use our  Factory  class to create an instance of  Client , which contains the actual methods to communicate with the Acquiring API.

The  Factory  needs the following input information to provide you with an initialized  Client

• A String to the configuration file with your connection configuration.

• The oauth2_token_uri , oauth2_client_id and oauth2_client_secret .

The property file should contain the following keys:

acquiring.api.integrator: <your company name>
acquiring.api.endpoint.host: api.preprod.acquiring.worldline-solutions.com
acquiring.api.authorizationType: OAuth2
acquiring.api.oauth2.tokenUri: https://auth-test-eu-west-1.aws.bambora.com/connect/token
acquiring.api.connectTimeout: 5 # use -1 for no timeout
acquiring.api.socketTimeout: 300 # use -1 for no timeout
acquiring.api.maxConnections: 10 # to support 10 concurrent connections

We recommend keeping the timeout values at these values. See  API endpoints  for the possible hosts and token URIs.

If a proxy should be used, the property file should additionally contain the following key(s):

acquiring.api.proxy.uri: <URL to the proxy host including leading http:// or https://>
# omit the following two lines if no proxy authentication is required
acquiring.api.proxy.username: <username for the proxy>
acquiring.api.proxy.password: <password for the proxy>

You can create an instance of  Client  using the  Factory  with this code snippet:

client = Factory.create_client_from_file(configuration_file_name, "oauth2_client_id", "oauth2_client_secret")

Connection management

Connection pooling is configured with the  max_connections  setting in  CommunicatorConfiguration  or in the configuration file. Its value determines how many connections to the Server API are kept alive for re-use in a connection pool. If there are more requests in progress than this maximum number of connections, then a new connection will be temporarily opened.

Exceptions

All calls can raise one of the following runtime exceptions:

• A  ValidationException  if the request was not correct and couldn't be processed (HTTP status code 400)

• An  AuthorizationException  if the request was not allowed (HTTP status code 403)

• An  IdempotenceException  if an idempotent request caused a conflict (HTTP status code 409)

• A  ReferenceException  if an object was attempted to be referenced that doesn't exist or has been removed, or there was a conflict (HTTP status code 404, 409 or 410)

• A  PlatformException  if something went wrong on the Worldline platform. The Worldline platform was unable to process a message from a downstream partner/acquirer, or the service that you're trying to reach is temporary unavailable (HTTP status code 500, 502 or 503)

• An  ApiException  if the RESTful Server API returned any other error

A payment attempt can now be handled as follows:

begin
  response = client.v1.acquirer(acquiirer_id).merchant(merchant_id).payments.process_payment(request)
rescue ValidationException => e
  $stderr.puts "Input validation error: " + e.detail
rescue AuthorizationException => e
  $stderr.puts "Authorization error: " + e.detail
rescue ReferenceException => e
  $stderr.puts  "Incorrect object reference: " + e.detail
rescue PlatformException => e
  $stderr.puts "Error occurred at Worldline or a downstream partner/acquirer: " + e.detail
rescue ApiException => e
  $stderr.puts "Worldline error: " + e.status_code + ", " + e.detail

Exception overview

The following table is a summary that shows when each of these exceptions will be raised:

Logging

The Ruby SDK supports logging of requests, responses, and exceptions of the API communication.

In order to start using the logging feature, an implementation of the  CommunicatorLogger  class should be provided. The SDK provides two example implementations for logging to  $stdout  ( StdoutCommunicatorLogger ) and logging to a  logger  ( RubyCommunicatorLogger ).

Logging can be enabled by calling the  enable_logging  method on a  Client  object, and providing the logger as an argument. The logger can subsequently be disabled by calling the  disable_logging  method.

The following code exemplifies the use of adding a logger:

client = Factory.create_client_from_file(configuration_file_name, "oauth2_client_id", "oauth2_client_secret")
logger = RubyCommunicatorLogger.new(Logger.new('logfile.log'), Logger::INFO)
client.enable_logging(logger)
# ... Do some calls
client.disable_logging

Advanced use: Connection pooling

A  Client  created using the  Factory  class from a properties file or  CommunicatorConfiguration  object will use its own connection pool. If multiple clients should share a single connection pool, the  Factory  class should be used to first create a shared  Communicator , then to create  Client  instances that use that  Communicator :

communicator = Factory.create_communicator(configuration_file_name, "oauth2_client_id", "oauth2_client_secret")
client = Factory.create_client_from_communicator(communicator)

Instead of closing these  Client  instances, you should instead close the  Communicator  when it is no longer needed. This will close all  Client  instances that use the  Communicator .

Connection management

Just like  Client ,  Communicator  also has method  close_expired_connections  that can be used to evict expired HTTP connections. You can call this method on the  Communicator  instead of on any of the  Client  instances. The effect will be the same.

Advanced use: Customization of the communication

A  Client  uses a  Communicator  to communicate with the RESTful API. A  Communicator  contains all the logic to transform a request object to an HTTP request and an HTTP response to a response object. If needed, you can extend this class. To instantiate a  Client  that uses your own implementation of  Communicator  you can use the following code snippet:

communicator = YourCommunicator.new
client = Factory.create_client_from_communicator(communicator)

However, for most customizations you do not have to extend  Communicator . The functionality of the  Communicator  is built on the following:

• The RESTful Server API endpoint URI.

• A  Connection , which represents one or more HTTP connections to the Worldline server.

• An  Authenticator , which is used to sign your requests.

• A  MetadataProvider , which constructs the header with metadata of your server that is sent in requests for BI and fraud prevention purposes.

• A  Marshaller , which is used to marshal and unmarshal request and response objects to and from JSON.

For your convenience, the  Factory.create_communicator_from_configuration , Factory.create_communicator_from_file , Factory.create_client_from_configuration and  Factory.create_client_from_file methods can take optional arguments to set the  Connection ,  Authenticator ,  MetadataProvider  or  Marshaller  components. For example, the following code snippet:

connection = YourConnection.new
session = Factory.create_client_from_file(configuration_file_name, "oauth2_client_id", "oauth2_client_secret",
                                          connection: connection)

Connection management

Calling  close_expired_connections  on a  Client  or a  Communicator  object only works if the  Connection  extends  PooledConnection , otherwise these methods do nothing. If you write a custom  Connection  that uses a pool of HTTP connections, extend  PooledConnection  instead.

Logging

To facilitate implementing logging in a custom  Connection , the SDK provides utility classes  RequestLogMessageBuilder  and  ResponseLogMessageBuilder . These can be used to easily construct request and response messages. For instance:

# In the below code, logger is the CommunicatorLogger set using enable_logging.
# Note that it may be nil if enable_logging is not called.
request_id = SecureRandom.uuid
request_log_message_builder = RequestLogMessageBuilder.new(request_id, method, uri)
# add request headers to request_log_message_builder
# if present, set the request body on request_log_message_builder
logger.log(request_log_message_builder.get_message)
start_time = Time.now * 1000
# send the request
end_time = Time.now * 1000
duration = end_time - start_time
status_code = ...
# note: duration is optional
response_log_message_builder = ResponseLogMessageBuilder.new(request_id, status_code, duration)
# add response headers to response_log_message_builder
# if present, set the response body on response_log_message_builder
logger.log(response_log_message_builder.get_message)

Notes

Renaming of properties

The Ruby SDK uses Ruby naming conventions. As a result, properties have been turned into so-called  Snake case . For example,  cardNumber  is called  card_number .