https://github.com/costajob/dacom
A Ruby port of the Dacom/LGU+ payment library for Korea.
https://github.com/costajob/dacom
e-commerce korea lgu payment-gateway ruby
Last synced: over 1 year ago
JSON representation
A Ruby port of the Dacom/LGU+ payment library for Korea.
- Host: GitHub
- URL: https://github.com/costajob/dacom
- Owner: costajob
- License: mit
- Created: 2016-04-01T12:05:18.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2017-06-27T10:06:43.000Z (about 9 years ago)
- Last Synced: 2025-03-08T13:46:57.646Z (over 1 year ago)
- Topics: e-commerce, korea, lgu, payment-gateway, ruby
- Language: Ruby
- Homepage:
- Size: 35.2 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
## 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 the checkout page:
```
https://xpay.lgdacom.net/xpay/js/xpay_crossplatform.js
```
The JavaScript 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: ""
test_mert_id: "tlgdacomxpay"
test_mert_key: ""
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", )
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
# ""
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)
```