• Scope
• Workflow
  • Client script
  • Collecting data
• Installation
  • Configuration
• Usage
  • Load credentials
  • Manage form data
    • Set form data
    • Submit data
    • Response
    • Rollback and error reporting
  • Logging

This gem is a Ruby porting of the XPay client library used by the LGU+ (former Dacom) payment gateway used in Korea.

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

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 ;)

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.

Add this line to your application's Gemfile:

gem "dacom"

And then execute:

bundle

Or install it yourself as:

gem install dacom

This library assumes you have valid LGU+ credentials inside yaml file like that:

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

The Config class is responsible to load the LGU+ credentials contained into the yaml file:

require "dacom"

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

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+:

client = Dacom::Client.new(config: config)

In order to fill the client form data with the ones collected by the iframe, you can use the #set method:

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"])

Once the form data are set you're ready to communicate them back to LGU+ along with the authorization data:

 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:

client.tx do |req, res|
  p req.body # inspecting the raw body
  p res # inspecting raw response form LGU+
end

The Response object is a struct that contains parsed JSON data from LGU+, use it to provide feedback on success/failure:

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)

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:

report_error: true  # set to false to avoid reporting on failure
auto_rollback: true # set to false to avoid sending a rollback procedure

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:

my_logger = Logger.new(STDOUT)
my_logger.log_level = Logger::WARN
client = Dacom::Client.new(config: config, logger: my_logger)