## Table of Contents

* [Scope](#scope)
* [Payment process](#payment-process)
  * [Client script](#client-script)
  * [Collecting data](#collecting-data)
* [API](#api)
  * [Configuration](#configuration)
  * [Constructor](#constructor)
  * [Response](#Response)
  * [Catch all](#catch-all)
  * [Constants](#constants)
  * [Rollback](#rollback)
  * [Report](#report)

## Scope
This gem is a Ruby porting of the XPay client library used by the [Dacom LGD](http://lgdacom.net/) payment gateway for Korea.  

## Payment process
The LGD XPay client is used to generate some unique keys mandatory to complete the
payment process with LGD.  

### Client script
The payment work flow happens on LGD servers by including a [JavaScript](https://xpay.lgdacom.net/xpay/js/xpay_crossplatform.js) in the page that:
* reads the data generated by the ruby library and set some hidden fields of a form
* set the form action
* open an iframe windows pointing to the LGD platform
* submit the forms with parameters collected by the iframe

### Collecting data 
Once the payment is completed, the iframe is closed and some data retruned to the parent site.  
These data has to be send via the Ruby XPay client and the response of the service has to be collected by Site.

## API
The API of the client is pretty small. The library expose one single public method, called *tx*, used to communicate the data to LGD server.  
The data are collected by using a hash object, then submitted as the form-data attribute.

### Configuration
Some configuration, such as the merchant key, id and other options, are fetched by a YML file.  
Some configuration keys are available for the test environment too.

### Constructor
Several instance variables are instantiated at construction time:
* the data fetched by the configuration collaborator
* the hashed keys created by using the SHA1 digest
* the hash object used to set the request form data 

### Response
A response object collaborator is used and always returned by the library. 
The data of the response are collected by parsing the JSON returned by LGD or by
rescuing from an error.
The object is always filled with a code and a message attributes.

### Catch all
The library does not halt on exceptions, but on the higher ones (aka system failure).  
This design is used to allow returning meaningful responses basing on the kind of errors raised (JSON parse, timeout, SSL error, etc).  
All exceptions are wrapped by a general one, then rescued by the *tx* method. 
I know using exceptions as control flow is not terrific, but i tried to mimic as much as possible the original behaviour of the PHP/Java versions.   
To mitigate i log every error on a custom collaborator.

### Constants
A set of constants are defined by an external module. They identifies the error codes to be used in case of exceptions and are set on the response object.

### Rollback
In case of issues the library notifies LGD with a rollback request. The object subclass the Client one, since it needs to initialize the same hash keys.

### Report
The same approach is used to report LGD about the failure. Both communications happens inside a separate thread of execution to have less impact on the system.