paygate-ruby

paygate-ruby is a simple Ruby wrapper for PayGate Korean payment gateway's OpenPayAPI.

Installation

Add this line to your application's Gemfile:

gem 'paygate-ruby'

Configuration

You can pass a block to the configure method to make changes to the Paygate configuration.

Paygate.configure do |config|
  config.mode = :sandbox
end

Default value for mode is :live. It uses different API urls in different modes for making payments.

Usage

To start making the transactions on PayGate, you will need a Member ID and a Secret, for which you can register here.

After a successful registration, you will have access to the dashboard.

NOTE: Unless otherwise stated, all the following documentation is for making payments with Korean local credit cards in currency 'WON'.

Contents:

1. Purchase
2. Verify
3. Refund
4. Profile Pay
5. JavaScript helpers

1. Purchase

1.1. Include JavaScript

Add Paygate::Rails::FormHelper to your controller.

class ApplicationController < ActionController::Base
  include Paygate::Rails::FormHelper

Then include the OpenPayAPI.js file in <head> of your payment page.

<%= javascript_include_tag paygate_open_pay_api_js_url %>

1.2 Payment form

Render the PayGate payment form in your view file.

<%= paygate_open_pay_api_form %>

You will see a form with all the necessary fields for making payment with a credit card. Some of the fields have default values set. You can also set the value and placeholder for almost all the fields while rendering the form. See example below:

<%= paygate_open_pay_api_form(
      mid: { value: 'testmid', placeholder: 'Merchant ID' },
      currency: { value: 'USD' },
      amount: { value: 2000 }
    ) %>

Here is a list of all the form fields which you can set:

mid
locale (default: 'US')
charset (default: 'UTF-8')
title
currency (default: 'WON')
amount
meta1, meta2, meta3, meta4, meta5
pay_method (default: 'card')
customer_name
customer_email
card_number
expiry_year
expiry_month
cvv

The form also contains some fields which are filled after the response is returned by the API. They are:

card_auth_code
response_code
response_message
tid
profile_no
hash_result

Lets explore some of these fields more.

mid

You need to set your Member ID in this field.

If you have setup separate Member IDs for Korean and International cards, you can fill the value of mid accordingly. To know whether the credit card number entered by a customer is Korean or not, you can check the first 6 digits of card number to match Korean BIN numbers. Full list is available as Paygate::KOREA_BIN_NUMBERS.

pay_method

Value of pay_method for Korean cards should be set to "card" and for international cards, it should be "104".

locale

Use Paygate.mapped_locale to get the locale in correct format for the form input.

Paygate.mapped_locale(:en)
#=> 'US'

Paygate.mapped_locale('ko')
#=> 'KR'

Valid inputs are "en", "en-US", "ko", "ko-KR", "ja", "zh-CN" and their symbolized versions. Passing nil would return default locale i.e. "US".

currency

Use Paygate.mapped_currency to get the currency in the correct format.

Paygate.mapped_currency('USD')
#=> 'USD'

Paygate.mapped_currency('KRW')
#=> 'WON'

Passing nil above would return default currency i.e. "WON".

amount

You need to contact PayGate to know the correct amount for making a successful transaction in test mode.

Remember, in test mode too, PayGate makes real transactions and you need to refund them.

meta1, meta2, meta3, meta4, meta5

These fields can be used to pass any additional data to PayGate. If server-to-server callbacks are enabled, the gateway then sends all of these back when making a callback request to your server.

tid

For every transaction a tid is created by PayGate JS before making a request to the API.

response_code

This is filled automatically by PayGate JS when response is returned. A response_code of "0000" means successful transaction.

response_message

In case of failure, you can see the error message returned by the API here.

profile_no

If Profile Payment Service is enabled on your Member ID, then you will get a subscription ID for customer in this field. You can use this profile_no to make payments for the same customer in future.

1.3. Response screen

You also need to add a screen at the same HTML level as above form. OpenPayAPI popups for further authentication as well as the response from the API is displayed in this screen.

= paygate_open_pay_api_screen

1.4. JavaScript callback

You also need to implement a few callbacks to handle the API response. Add these to your JavaScript.

// This is called when a response is returned from PayGate API
function getPGIOresult() {
  displayStatus(getPGIOElement('ResultScreen'));
  verifyReceived(getPGIOElement('tid'), 'callbacksuccess', 'callbackfail');
}

// This is called when a response (success/failure) is returned from the API
function callbacksuccess() {
  var replycode = getPGIOElement('replycode');

  if (replycode == '0000') {
    alert('Payment was successful');
  } else {
    alert('Payment failed with code: ' + replycode);
  }
}

// This is called when there is a system error
function callbackfail() {
  alert('System error. Please try again.');
}

1.5. Submit the form

Now finally, lets add an event to make a call to OpenPayAPI on submit of the form. If you are using jQuery, you can do it as follows:

$('form[name="PGIOForm"]').on('submit', function(event){
  event.preventDefault();
  doTransaction(document.PGIOForm);
})

And, your payment form is all set to make payments.

2. Verify

If enabled, PayGate will send a server-to-server callback on every successful transaction to the URL provided by you. The same request is sent every 5 minutes (for 10 days) until your server responds with success.

This feature can be helpful if your JavaScript failed to receive the message from PayGate after a successful payment due to network issues.

So, once you receive a successful JavaScript callback (replycode == '0000'), to prevent PayGate from sending any callback requests for that transaction (tid), you need to make a verification request as follows:

txn = Paygate::Transaction.new('testmid_123456.654321')
response = txn.verify
#=> #<Paygate::Response:0x007fd4898f14b0 ... >

response.transaction_type
#=> :verify

response.http_code
#=> "200"

Here, testmid_123456.654321 is tid of the transaction you want to verify.

3. Refund

Initialize a Paygate::Member instance using the Member ID and Secret you have.

member = Paygate::Member.new('testmid', 'secret')
#=> #<Paygate::Member:0x007f96bdb70f38 @mid="testmid", @secret="secret">

member responds to methods mid, and secret.

member.mid
#=> "testmid"

member.secret
#=> "secret"

3.1. Full refund

response = member.refund_transaction('testmid_123456.654321')
#=> #<Paygate::Response:0x007fbf3d111940 @transaction_type=:refund, @http_code="200", @message="OK", @body="callback({\"replyCode\":\"0000\",\"replyMessage\":\"Response has been completed\",\"content\":{\"object\":\"CancelAPI tid:testmid_123456.654321 SUCCESS payRsltCode:0000\"}})", @json={"replyCode"=>"0000", "replyMessage"=>"Response has been completed", "content"=>{"object"=>"CancelAPI tid:testmid_123456.654321 SUCCESS payRsltCode:0000"}}, @raw_info=
  #<OpenStruct tid="testmid_123456.654321", tid_enc="AES256XQIdNnkzFwMQmhF7fuJhS3m0\n", request_url="https://service.paygate.net/service/cancelAPI.json?callback=callback&mid=testmid&tid=AES256XQIdNnkzFwMQmhF7fuJhS3m0%0A&amount=F">>

response provides some helpful accessor methods too.

response.transaction_type
#=> :refund

response.http_code
#=> "200"

response.json
#=> {"replyCode"=>"0000", "replyMessage"=>"Response has been completed", "content"=>{"object"=>"CancelAPI tid:testmid_123456.654321 SUCCESS payRsltCode:0000"}}

response.raw_info
#=> #<OpenStruct tid="testmid_123456.654321", tid_enc="AES256XQIdNnkzFwMQmhF7fuJhS3m0\n", request_url="https://service.paygate.net/service/cancelAPI.json?callback=callback&mid=testmid&tid=AES256XQIdNnkzFwMQmhF7fuJhS3m0%0A&amount=F">

response.raw_info.request_url
#=> "https://service.paygate.net/service/cancelAPI.json?callback=callback&mid=testmid&tid=AES256XQIdNnkzFwMQmhF7fuJhS3m0%0A&amount=F"

Apart from these it also responds to message and body.

3.2. Partial refund

For partial refunds, you need to pass amount as an option to refund_transaction method along with other options.

response = member.refund_transaction('testmid_123456.654321',
                                     amount: 1000,
                                     order_id: 'ord10001')

4. Profile Pay

You can use the profile_no returned from the OpenPayAPI after first payment by a customer to make future payments for him.

response = member.profile_pay('profile_1234567890', 'WON', 1000)

response.transaction_type
#=> :profile_pay

response.http_code
#=> "200"

response.json
#=> {"validecode"=>"00", "authcode"=>"12345678", "authdt"=>"20171120165728", "cardname"=>"BC \x00\x00\x00\x00", "cardnumber"=>"411111**********", "cardtype"=>"301310", "cardquota"=>"00", "cardexpiremonth"=>"11", "cardexpireyear"=>"2020", "merchantno"=>"12345678", "m_tid"=>nil, "paymethodname"=>"CARD_BASIC", "ReplyMsg"=>"\xBA\xBA\xBC\xBD\xC1\xC2\xC3\xC4        OK: 12345678", "ReplyCode"=>"0000", "receipttoname"=>"Test name\xC1\xD1\xB1\xB1\xC1\xA1", "receipttoemail"=>"dev@paygate.net", "subtotalprice"=>"1000", "transactionid"=>"testmid_123456.654321", "hashresult"=>"db1fdc6789cc8d088172b79ca680b3af8711e9fb32", "mb_serial_no"=>"\r\n"}

5. JavaScript helpers

paygate-ruby also provides a JavaScript class Paygate with some helper functions that can be used in your JavaScript e.g.

openPayApiForm - Returns the payment form
openPayApiScreen - Returns the screen for paygate API response
findInputByName - Find an input field in payment form by name. Pass the camelCased form of field names from section 1.2 above as arguments.
responseCode
responseMessage
tid
profileNo
fillInput - Accepts input name (camelCased) and a value to set
submitForm - Makes a call to PayGate API with the payment form inputs

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tablecheck/paygate-ruby.