## Table of Contents

* [Scope](#scope)
* [Workflow](#workflow)
  * [Client script](#client-script)
  * [Collecting data](#collecting-data)
* [Installation](#installation)
  * [Configuration](#configuration)
* [Usage](#usage)
  * [Load credentials](#load-credentials)
  * [Manage form data](#manage-form-data)
    * [Set form data](#set-form-data)
    * [Submit data](#submit-data)
    * [Response](#response)
    * [Rollback and error reporting](#rollback-and-error-reporting)
  * [Logging](#logging)

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

## Workflow
The LGU+ XPay client is used to generate some unique keys mandatory to complete the
payment process with LGU+.  

### Client script
The payment workflow happens on LGU+ servers by including the following JavaScript:
into your checkout page:
```
https://xpay.lgdacom.net/xpay/js/xpay_crossplatform.js
```

The script is responsible to:
* reads the data generated by the ruby library and set some hidden fields present on the checkout page
* set the form action
* open an iframe window pointing to the LGU+ server
* submit the form with parameters collected by LGU+ upon iframe closure

The official documentation is kind of private unless you have a valid LGU+ account, by checking the JavaScript source you should figure out how it works ;)

### Collecting data 
The data submitted by form need to be processed by the Ruby client and the response of the service has to be collected by Site.

## Installation
Add this line to your application's Gemfile:
```ruby
gem "dacom"
```

And then execute:
```shell
bundle
```

Or install it yourself as:
```shell
gem install dacom
```
### Configuration
This library assumes you have valid LGU+ credentials inside yaml file like that:
```yaml
url: "https://xpayclient.lgdacom.net/xpay/Gateway.do"
test_url: "https://xpayclient.lgdacom.net:7443/xpay/Gateway.do"
aux_url: "http://xpay.lgdacom.net:7080/xpay/Gateway.do"
server_id: "01"
timeout: 60
verify_cert: true
verify_host: true
report_error: true
auto_rollback: true
mert_id: "lgdacomxpay"
mert_key: "<your-key>"
test_mert_id: "tlgdacomxpay"
test_mert_key: "<your_merchant_id>"
test_mode: true
```

## Usage

### Load credentials
The `Config` class is responsible to load the LGU+ credentials contained into the yaml file:
```ruby
require "dacom"

config = Dacom::Config.new("./dacom.yml") # default to "~/dacom.yml"
```

### Manage form data
Once you've collected the form data from the iframe, you need to send them back to LGU+ to complete the purchasing.  
The `Client` class is responsible to sign the form data with valid authorization codes and communicate them to LGU+:
```ruby
client = Dacom::Client.new(config: config)
```

#### Set form data
In order to fill the client form data with the ones collected by the iframe, you can use the `#set` method:
```ruby
client.set("LGD_TXNAME", "PaymentByKey")
client.set("LGD_AMOUNT", <order_grand_total>)
client.set("LGD_AMOUNTCHECKYN", "Y")

# these data are collected by form hidden fields filled by LGU+ iframe
client.set("LGD_PAYKEY", params["LGD_PAYKEY"])
client.set("LGD_PAYTYPE", params["LGD_PAYTYPE"])
client.set("LGD_FINANCENAME", params["LGD_FINANCENAME"])
client.set("LGD_FINANCECODE", params["LGD_FINANCECODE"])
client.set("LGD_ACCOUNTOWNER", params["LGD_ACCOUNTOWNER"])
```

#### Submit data
Once the form data are set you're ready to communicate them back to LGU+ along with the authorization data:
```ruby
 res = client.tx

# check response code
if res.successful?
  # process order
else
  # present error page
end
```

The `tx` method also accept a block yielding request and response objects before any face-lifting:
```ruby
client.tx do |req, res|
  p req.body # inspecting the raw body
  p res # inspecting raw response form LGU+
end
```

#### Response
The `Response` object is a struct that contains parsed JSON data from LGU+, use it to provide feedback on success/failure:
```ruby
puts res
# "<Dacom::Response:70132949609560, code: \"XC01\", message: \"LGD_TXNAME 필드가 누락되었습니다.\", successful: false>"

p res.raw # check raw response
p res.code # check response LGU+ code (check constants.rb file)
p res.message# check message by LGU+ (in KR)
```

#### Rollback and error reporting
In case of payment issues the `Client` is responsible to communicate to LGU+ a rollback procedure and to report any error.  
These options are configurable by yaml values:
```yaml
report_error: true  # set to false to avoid reporting on failure
auto_rollback: true # set to false to avoid sending a rollback procedure
```

### Logging
By default the `Client` class accepts a logger pointing to `dev/null`. 
In case you want to replace it with yours, just pass it to the constructor:
```ruby
my_logger = Logger.new(STDOUT)
my_logger.log_level = Logger::WARN
client = Dacom::Client.new(config: config, logger: my_logger)
```