Quick installation guide for PayGate OpenPayAPI.pdf

Quick Installation Guide for PayGate OpenPayAPI

Version I

Table

I. Overview

II. What is OpenPayAPI?

III. Features of OpenPayAPI

IV. OpenPayAPI Payment Module

V. Basic outline of OpenPayAPI Process

VI. How to integrate OpenPayAPI

VII. OpenPayAPI Step by Step Guide

VIII. Testing the payment system

IX. Appendix

I. Overview

Quick installation guide for PayGate OpenPayAPI

This is installation manual for OpenPayAPI. The following is a brief introduction to OpenPayAPI and simple a

step by step guide.

OpenPayAPI is the latest and most flexible payment module available. Merchants have been very satisfied with

its stability and reliability. It was developed based on the latest internet tools, applications, and technology (Web

2.0) and input from end users. Our API allows merchants to customize the payment system according to their

needs.

We recommend using OpenPayAPI, which is embedded into a merchant’s online store, because of its reliability

and stability. However, if you prefer a traditional method like Post or Popup window, please send request mail

to [email protected].

-Popup

Very common method for the local market in Korea. Payment window is a pop-out from merchant page.

-Post

Traditional method to send payment information using HTTPS Post to PayGate server.

II.What is OpenPayAPI?

OpenPayAPI is a new payment method and is embedded on merchant page based on Web 2.0 tools and

applications.

It does not require moving to another page or opening a pop-up.

By clicking the purchase button, payment options are displayed seamlessly on the merchant’s page, so the end

user can pay easily and quickly.

All communication between customer’s browser and PayGate server via OpenPayAPI is securely protected by

strong HTTPS protocol.

III. Features of OpenPayAPI

By simply modifying the html and JavaScript code on the merchant’s checkout page, all payment modules can

be customized and made to order.

OpenPayAPI does not require installing another application or extra software. It can be easily modified by a

non-professional programmer.

It is compatible with all browsers which support ECMA script standard and DOM level1.

--Internet Explorer, Firefox, Safari, Opera, Google Chrome.

Also, all Operating Systems, which support the above browsers, are compatible with OpenPayAPI .

- Microsoft Windows XP, Vista, 2003, 2008 servers, Mac OSX, Linux.

mailto:[email protected]

IV. OpenPayAPI Payment Module

The payment screen will be displayed on the merchant’s order page using secure JavaScript with asynchronous

communication between client browser and server.

After activating payment screen, an additional popup like “Secure click” or “ISP” screen may show up

according to the payment condition of local credit cards in Korea.

Add the following script tag to HEAD location of the merchant order page, and then payment environment can

be available. <script type="text/JavaScript" src="https://api.paygate.net/ajax/common/OpenPayAPI.js">

V. Basic outline of OpenPayAPI Process

1. Load OpenPayAPI.js from PayGate server.

2. Call doTransaction (document.PGIOForm) from OpenPayAPI.

3. doTransaction (document.PGIOForm) shows payment screen in <div id="PGIOScreen"> </ div> with

the basic customer information recorded on order form.

4. If additional values which requires encryption like credit card number and password are required,

PGIOScreen displays the input form.

5. After completion of the payment, getPGIOresult() is automatically called and the transaction result is

available.

6. getPGIOresult () which has been defined by merchant manager will help him/her to use the results of

the payment.

VI. How to integrate OpenPayAPI

Assume the order page is composed as below.

The order page has to be configured like the illustration below:.

VII. OpenPayAPI Step by Step Guide

1. Please follow W3C standard HTML tag usage.

Ex) <body> tag can’t be used two times in <html> and <form> or <div> are not allowed to use before

<HEAD>.

2. Include the basic module--OpenPayAPI.js.

JavaScript is necessary for processing payment.

Before After

<html> <head>

<title>Order Form</title>

<script type="text/javascript" src="/script/order.js"></script>

</head>

<body>

...

<html>

<head> <title>Order Form</title>

<script language="javascript" type="text/javascript"

src="https://api.paygate.net/ajax/common/OpenPayAPI.js"></script> <script type="text/javascript" src="/script/order.js"></script>

</head>

<body> ...

Add OpenPayAPI.js script tag to the next line after <HEAD> tag to keep browser

compatibility.

3. Fill in values in PGIOForm.

The form name must be "PGIOForm" and all required payment information must be filled.

Before After

<form name="order">

Goodname : <input type="text"

name="product_name" value="PayGate

System"></input>

Price : <input type="text" name="product_price"

<form name="order">

Goodname : <input type="text" name="product_name"

value="PayGate SYstem"></input>

Price : <input type="text" name="product_price"

value="110000">KRW110,000 </input>

value="110000">KRW110,000 </input>

Goodcode : <input

name="product_orderno" value="PGSystem"></input>

</form>

For credit card payment

Goodcode : <input name="product_orderno" value="PGSystem"></input>

</form>

<form name="PGIOForm">

<input name="mid" value="testshop" />Merchant ID

<input name="paymethod" value="card" />Paymethod <input name="goodname" value="product A"

/>Goodname

<input name="unitprice" value="110000" />Price <input name="cardquota" value="" />Card Quota

<input name="cardexpiremonth" />Card Expiry month

<input name="cardexpireyear" />Card Expiry year <input name="cardsecretnumber" />Card CVV2 value

<input name="cardownernumber" />last 7 number of card owner SSN

(for Korean user only)

<input name="cardtype" />CardType

<input name="cardnumber" />CardNumber

<input name="cardauthcode" />Approval No <input name="replycode" value="" />Payment Result Code

<input name="replyMsg" value="" />Payment Result Message

</form>

For mobile phone payment



<input name="paymethod" value="801" />paymethod <input name="goodname" value="product A"

/>goodname

<input name="unitprice" value="110000" />price <input name="goodcurrency" value="WON" />currency

<input name="socialnumber" value="8101011010101" />phone

owner's SSN

<input name="carrier" value="SKT" />Mobile Carrier

<input name="receipttotel" value="01099995555" />phone no

<input name="replycode" value="" />payment result code <input name="replyMsg" value="" />payment result message

</form>

For real time bank transfer



<input name="paymethod" value="4" />paymethod <input name="goodname" value="product A"

/>Goodname

<input name="unitprice" value="110000" />Price <input name="socialnumber" value="8101011010101" />Customer

SSN

<input name="receipttoname" value="Tester" />Customer Name

<input name="replycode" value="" />payment result code

<input name="replyMsg" value="" />payment result message </form>

Notification is sent to customer that the

payment has been remitted to merchant’s

or PayGate’s account.

<form name="PGIOForm"> <input name="mid" value="testshop" />

<input name="paymethod" value="7" />

<input name="goodname" value="PayGate System" /> <input name="unitprice" value="110000" />

<input name="receipttoname" value="tester" />customer name

<input name="bankcode" value="110" />bank code <input name="bankaccount" value="212234113512" />merchant bank

account no

<input name="bankexpyear" value="2008" /><input name="bankexpmonth" value="10" /><input name="bankexpday"

value="23" />due year/month/day

<input name="receipttosocialnumber" value="01088885555" />personal phone number



In case of card, mobile and real time bank transfer, lets the customer select payment

method.

<form name="PGIOForm"> <input name="mid" value="testshop" />merchant id

<input name="paymethod" value="???" />transaction method

<input name="goodname" value="상품 A" />product

<input name="unitprice" value="110000" />price

<input name="cardquota" value="" />card quota

<input name="cardexpiremonth" />card expiry month <input name="cardexpireyear" />card expiry year

<input name="cardsecretnumber" />card cvv2 value

<input name="cardownernumber" />last 7 digit of cardowner SSN <input name="cardtype" />cardtype

<input name="cardnumber" />cardnumber

<input name="cardauthcode" />approval number <input name="socialnumber" value="8101011010101" />phone owner

SSN

<input name="carrier" value="SKT" />mobile carrier <input name="receipttotel" value="01099995555" />phone no

<input name="socialnumber" value="8101011010101" />customer

SSN

<input name="receipttoname" value="tester" />customer name



For overseas credit card transaction, verify

the following variables:

langcode

English : US

Japanese : JP

goodcurrency

US Dollar : USD

Japan Yen : JPY

total of 23 currencies

<form name="PGIOForm"> <input name="mid" value="testshop" />Merchant ID

<input name="paymethod" value="104" />paymethod <input name="goodname" value="tgoods" />goodname <input name="unitprice" value="11" />price

<input name="goodcurrency" value="USD" />currency <input name="langcode" value="US" />language code

<input name="receipttoname" value="test buyer" /> <input name="cardquota" value="" />card quota

<input name="cardexpiremonth" />card expiry month <input name="cardexpireyear" />card expiry year


<input name="cardownernumber" />last 7 digit of SSN

<input name="cardtype" />cardtype


<input name="cardauthcode" />approval no <input name="replycode" value="" />payment result code

<input name="replyMsg" value="" />payment result message

</form>

PGIOForm variables are filled in before calling doTransaction() or auto-filled with another

JavaScript method

All "variables" need to be prepared even though it was not filled in with "value".

As for overseas transactions, additional variables can be required in langcode, goodcurrency,

etc, so please refer to the Official OpenPayAPI manual.

Following variables need to be filled in.

mid: The assigned merchant ID from PayGate

Goodname: Product name or code

Unitprice: Payment amount

Paymethod: Credit card is the default payment method if no payment method is

chosen.

All required variables work with all payment methods.

Recommend filling in the following variables for better transaction management.

Receiptname: Customer name is searchable in PayGate transaction management area.

Receipttel: Send an SMS to customer by the request of merchant after transaction.

Receiptemail: Send an email to the customer for transaction notification.

Charset: Recommend using UTF-8 or EUC-KR, otherwise, transaction may fail or the

name of product can look garbled.

Refer to the detailed manual for other variable types and more details.

4. Guide for CUP/Alipay payment

An upgrade of Paygate system enables China Union Pay (CUP) payment to be set up in OpenPayAPI system.

Quick Installation Guide for OpenPayAPI can be found here:

https://docs.google.com/a/paygate.net/Doc?docid=0Ac8xChBlSAiTZGN4cXhjdDJfMTU0bTNxbjk4ZjY&hl=en

* CUP payment through OpenPayAPI.

For CUP (China UnionPay) payment,

Verify following variables

paymethod :105

langcode

China: CN

goodcurrency

China, Yuan Renminbi : CNY



<input name="paymethod" value="105" />paymethod

<input name="goodname" value="tgoods" />goodname


<input name="goodcurrency" value="CNY" />currency

<input name="langcode" value="CN" />language code

<input name="receipttoname" value="test buyer" />


<input name="cardexpiremonth" />card expiry month

<input name="cardexpireyear" />card expiry year





<input name="cardauthcode" />approval no



</form>

*Alipay Payment through OpenPayAPI.

In case of Alipay payment,

Verify following variable

paymethod :106

langcode

China: CN

goodcurrency

China, Yuan Renminbi : CNY

US Dollar: USD



<input name="paymethod" value="106" />paymethod

<input name="goodname" value="tgoods" />goodname


<input name="goodcurrency" value="CNY" />currency

<input name="langcode" value="CN" />language code

<input name="receipttoname" value="test buyer" />


<input name="cardexpiremonth" />card expiry month

<input name="cardexpireyear" />card expiry year





<input name="cardauthcode" />approval no



</form>

The exchange rate for CUP/Alipay

Payment Payment amount Amount Billed to Customer Settlement to Paygate Settlement to Merchant

Alipay 1,000/6.82=146.62USD 146.62USD*6.82 = 999.94CNY 146.62USD - fee 146.62USD - fee = ___USD

CUP 1,000CNY 1,000CNY 1,000CNY*0.123=123 USD 146.62USD - fee = ___USD

Credit

Card 1,000/6.82=146.62USD 146.62USD*6.82 = 999.94CNY 999.94CNY*0.147=146.99 USD 146.62USD - fee = ___USD
































5. Call doTransaction to process payment.

Before After

<script type="text/javascript">

function startPayment() {

// TODO payment integration

}

</script>

<form name="order">

goodname : <input type="text" name="product_name" value="PayGate system"></input>

price : <input type="text" name="product_price"

value="110000">annually 110000won</input>

goodcode : <input name="product_orderno"

value="PGSystem"></input>

<input type="button" value="PAY NOW" onclick="startPayment();"/>

</form>

<script type="text/javascript"> function startPayment() {

// TODO payment integration.

doTransaction(document.PGIOForm); }

</script>

<form name="order"> goodname : <input type="text" name="product_name"

value="PayGate system"></input>

price : <input type="text" name="product_price" value="110000">annually 110000won</input>

goodcode : <input name="product_orderno"

value="PGSystem"></input> <input type="button" value="PAY NOW"

onclick="startPayment();"/>

</form>

doTransaction(document.PGIOForm): In order to make doTransaction work, all five basic

elements(PGIOForm, PGIOScreen, doTransaction, OpenPayAPI, getPGIOresult) are required.

Merchants have to validate the variables before calling doTransaction() method.

PayGate processes the payment under the condition all elements are properly prepared. If there

is anything wrong or missing, the appropriate error message will be shown.

6. Designate the area for PGIOScreen.

Before After

PGIOScreen div tag can be located at any place on the order page. Please be aware that the

layout screen appear misaligned due to the additional PGIOScreen div tag.

PGIOScreen includes <form> to put in information and should not be surrounded by

anyother <form> tag .

Merchant is able to change CSS style of PGIOScreen. Please refer to the manual to use a

defined style.

7. getPGIOresult() is called after the completion of transaction

Before After


function startPayment() { doTransaction(document.PGIOForm);

}

</script>


function startPayment() {

doTransaction(document.PGIOForm); }

function getPGIOresult() {

verifyReceived(getPGIOElement('tid'), 'callbacksuccess',

'callbackfail');

}

function callbacksuccess() {

var replycode = getPGIOElement('replycode')

if (replycode == '0000') {

//for transaction success

document.PGIOForm.action = 'shop.co.kr/pay/record_payment.jsp';

document.PGIOForm.submit();

} else {

// for transaction failure

alert("Trasaction is failed. Please try again");

}

}

function callbackfail() {

// paygate system error

}

</script>

When getPGIOresult() is called, all result values are already filled in PGIOForm.

By calling getPGIOresult, the API is able to verify authentication number, transaction result

and message from credit card companies.

If no getPGIOresult() is defined, there will be no transaction result even though the

transaction is successfully completed.

If merchant does not input any variables for getPGIOresult, only PayGate keeps the

transaction on its server and the merchant won’t be able to check the result.

Please use getPGIOresult() and keep the record on your server so that you can also check the

purchase order.

8. Identify the cause of payment breakdown(Verification)

Please add the following function to avoid any problems with payment due to browser type and/or

instability of server during the process of storing payment information into your database.

While payment is being processed, please add verifyNum +1 when payment module

(doTransaction (document.PGIOForm)) is called and then call function getPGIOresult () after

the payment is processed. Check that verifyNum +1 is added.

When your payment is completed, the sum is going to be +2(verifyNum automatically

becomes +2 in the openPayApi system.

To determine whether the transaction result of your database is completed or not, please add

verifyNum +100, then it will notify that the transaction results have been inserted in your DB.

In order to add verifyNum to +100, you need to add the following method. You must call the

function after recording the payment breakdown in your database.

<% The logic of Merchant which records the result in the merchant’s database needs to be preceded. %>

<html>

<head> <title>Transaction Successfully Completed</title>

<script language="javascript" src="https://api.paygate.net/ajax/common/OpenPayAPI.js"></script>

<script language="javascript">

function businessverify() { setPGIOElement('apilog','100');

setPGIOElement('tid','the transaction ID');

verifyReceived(); [or verifyReceived('','Call script after update', 'The call name when failed ');

}

</script>

</head>

<body onLoad="javascript:business_verify();"> <form name='PGIOForm'></form> <--Must be as appendChild

The length of source can be considerably longer when script is implemented Some browsers may not

work.

Thanks for your transaction..

The product list you bought. </body></html>

9. Verify the transaction amount(sha-256)

PayGate hashes some variables to prevent the falsification of transaction amount and transaction methods.

The following is how to verify the hash result.

Put the result in hashresult variable and transmit.

result = replycode + tid + mb_serial_no + org_amt + currency

Designate the fixed api password as salt in my information at

hashresult = result + https://service.paygate.net .

* Sep-up method of api password - logging in – member > My Information Management-> API Authentication

Value( You can modify or register, here).

* Ex) hashresult = payment result code + trnsctn_no (PayGate unique number) + Order Number + amount +

currency unit (The value may vary if there are spaces for each value)

The unit of currency -Won-KRW, U.S. dollar-USD, Yen-JPY, yuan-CNY

function getPGIOresult() {

var replycode = getPGIOElement('replycode') var hashresult = getPGIOElement('hashresult') -- Transaction result hash value

if (replycode == '0000') {

document.PGIOForm.action = 'shop.co.kr/pay/record_payment.jsp'; document.PGIOForm.submit();

} else {

} }

In order to prevent the falsification of transaction result, you can handle it with the given hash value.

10. Customizing your Payment System.

After integration of PayGate’s payment system, there are several convenient functions you can add for

your end-users.

https://service.paygate.net/

When the transaction is successfully completed, a text message can be sent to customers or designated

administrators.

To administrators

You can assign two administrators. When you are busy and don’t have time to manage your

merchant account, this service will help you.

To customers

Upon completion of a credit card transaction, usually card companies send a text message to the

customer. But this kind of service for bank transfer payment is not common. We offer this service

merchants’ customers so that customers will have 100% confidence that their payment was

processed successfully.

When the transaction is complete, a sales slip is also be available.

Upon completion of the transaction, customers will receive an email with the transaction details.

However, this service is only available if the customers input their e-mail address during the

transaction.

In the red part of the following URL, please replace tid (payment variable) which is automatically generated

during the transaction and pop-up (Korean (KR) and English (US) are supported.) https://service.paygate.net/front/support/slipView.jsp?trnsctnNo=appletest_090107.873843&admMemNo=M000000001&langcode=KR

https://service.paygate.net/front/support/slipView.jsp?trnsctnNo=appletest_090107.873843&admMemNo=M000000001&langcode=US

VIII. Testing the payment system

All transactions are real. Please keep in mind that the amount you paid for test will be actually charged. In order

to cancel transaction, please email the transaction information (TID, date, amount and type of card) to

[email protected]

1. Page for testing payment o https://api.paygate.net/ajax/cardform.html ( Korea Local Card)

o https://api.paygate.net/ajax/cardform_USD2.html ( International Cards)

o https://api.paygate.net/ajax/Phone_form.html ( Korea Mobile phone)

o With just basic information (id, goodname, unit price), payment can be processed.

o Depending on payment type, additional variables (receipt name, charset on payment page,

language on payment module, etc) may be required.

2. Test sample page of all payment methods (Useful for debugging) https://api.paygate.net/orderforms/order.html

1. Fill-in minimum value manually and click "OpenPayAPI" button, which will display the

agreement.

2. Depending on card type, Visa 3D popup or ISP control will be displayed.

3. After completing the transaction, getPGIOresult() method is called.

IX. Appendix

a. Miscellaneous Most Korean Card Issuers require secure payment through Visa3D or ISP.

Please select the appropriate card types and install on your order page.

If no card type is selected, PayGate API will display all supported card types. If this happens,

customers may keep trying in vain to pay with a card which is not registered with the merchant

Please test on your side and to make sure certain cards will work.

Test has to be done on the server. API will not work with a local file.

b. Evaluation of online merchant by card company

To activate credit card transactions in Korea, merchants have to be registered with card issuers.

After integration the payment, PayGate requests each card issuer to verify merchant page.

c. Integrating overseas credit cards as a payment method

As for overseas card transactions, only international cards like VISA and MASTERCARD can be

tested. Please contact technology development team for the test of overseas card transactions

How to request: Please send an email to [email protected].

Please inform test id & pw if the payment is not workable with nonmember.

If the transaction amount is high (< $100), please prepare a low amount of virtual goods

Please advise the absolute address of the product and the method to enter if the process of

payment is complicated.

mailto:[email protected]

Quick installation guide for PayGate OpenPayAPI.pdf

Documents

Transcript of Quick installation guide for PayGate OpenPayAPI.pdf