quick installation guide for paygate · pdf file · 2015-08-10openpayapi is new...
TRANSCRIPT
Quick installation guide for PayGate OpenPayAPI
Version I
Table
I. Overview
II. What is OpenPayAPI?
III. Feature of OpenPayAPI
IV. Payment Module of OpenPayAPI
V. How to integrate OpenPayAPI
VI. How to integrate OpenPayAPI
VII. OpenPayAPI Step by Step Guide
VIII. Test the payment system in advance
IX. Other References
I. Overview
Quick installation guide for PayGate OpenPayAPI
This is integration manual for OpenPayAPI. The following is the brief introduction of OpenPayAPI and simple guideline for installation. OpenPayAPI is the latest and flexible payment module and already got the proof of it’s stability and reliability through many merchants over 3 years. It has been developed based on the latest interactive web-page and the experience of users and this allows merchants to customize the necessary input/ output for the payment system.
We recommend using OpenPayAPI, but if you want a traditional method like Post or Popup, please send request mail to [email protected]. -Popup Very common method for the local market in Korea. Payment windows is pop-out from merchant page. -Post Traditional method to send payment information using HTTPS Post to PayGate server.
II.What is OpenPayAPI?
OpenPayAPI is new payment method and is embedded on merchant page based on web 2.0 technologies.
It does not require moving to new page or opening popup.
By clicking pay button, the proper payment interfaces according to payment methods is displayed on the merchant’s page, so the user can pay easily. All communication between customer browser and PayGate server through OpenPayAPI is securely protected by strong HTTPS protocol.
III.Feature of OpenPayAPI
By modifying the html and JavaScript simply in the merchant order page, all payment modules can be ready.
It does not require installing application or customizing software and can be easily handled by non-professional programmer.
All browsers which support ECMA script standard and DOM level1 are available. - Internet Explorer, Firefox, Safari, Opera, Google Chrome.
Also, all Operating Systems, which support the above browsers, are available. - Microsoft Windows XP, Vista, 2003, 2008 servers, Mac OSX, Linux.
IV.Payment Module of OpenPayAPI
The merchant order page is used for payment.
The payment screen will be displayed on the merchant order page using secure JavaScript with asynchronous communication between client browser and server. After activating payment screen, additional popup like “Secure click” or “ISP” screen can be required according to the payment condition of local credit cards in Korea.
Add 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.The Procedure of OpenPayAPI
1. Load OpenPayAPI.js from PayGate server.
2. Call doTransaction (document.PGIOForm) method of OpenPayAPI.
3. doTransaction (document.PGIOForm) shows payment screen in <div id="PGIOScreen"> </ div> with the basic information recorded in order form.
4. If additional values which require security like credit card num. and password are required,
PGIOScreen display the input form.
5. After completion of the payment, getPGIOresult() is automatically called and the transaction result can be available.
6. getPGIOresult () which has been defined by merchant manager will help 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 as following.
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 of OpenPayAPI.js.
l JavaScript is necessary for proceeding 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> ...
l Add OpenPayAPI.js script tag to the next line after <HEAD> tag to keep browser
compatibility.
3. Fill up the values in PGIOForm.
l The form name must be "PGIOForm" and all required payment information must be filled in PGIOForm.
Before After
<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> Goodcode : <input name="product_orderno" value="PGSystem"></input> </form> In case of card payment,
<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> 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>
In case of Mobile payment,
<form name="PGIOForm"> <input name="mid" value="testshop" />Merchant ID <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>
<form name="PGIOForm"> <input name="mid" value="testshop" />Merchant ID
In case of Real-time bank transfer, After activating real time bank transfer module, the amount will be transferred to the merchant’s bank account in real time.
<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>
In case of bank transfer, Notify customers that the amount is 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 <input name="replycode" value="" />payment result code <input name="replyMsg" value="" />payment result message </form>
In case of card, mobile and real time bank transfer, Let 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
<input name="replycode" value="" />payment result code <input name="replyMsg" value="" />payment result message </form>
In case of overseas transaction with card, Verify following variable payment method. langcode English : US Japanese : JP goodcurrency US Dollar : USD Japan Yen : JPY other 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="cardsecretnumber" />card cvv2 value <input name="cardownernumber" />last 7 digit of SSN <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>
l PGIOForm variables are filled before calling doTransaction() or auto-filled with another
JavaScript method
l All "variables" need to be prepared even though it was not filled with "value".
l As for overseas transaction, additional variables can be required for langcode, goodcurrency, etc, so please refer to the Official OpenPayAPI manual.
l Following variables are necessary to be filled.
§ mid: The assigned merchant ID from PayGate. § Goodname : Product name or code. § Unitprice: Payment amount. § Paymethod : Creit card payment will be designated if there is no assigned payment
method.
l All required variables are able to co-exist to support all payment methods.
l Recommend filling in the following variables for better transaction management. § Receiptname : The customer name is searchable in PayGate transaction management
area. § Receipttel : Can send an SMS to the customer by the request of merchant after
transaction. § Receiptemail : Sending an email to the customer for transaction notification. § Charset : Recommend using the proper charset like UTF-8, EUC-KR, otherwise
The transaction can be failed or the name of product can be broken.
l Refer to the detailed manual for other variable types and more details.
4. Guide for CUP/Alipay payment
The upgrade of Paygate system enable CUP payment to be set up in OpenPayAPI system. -Quick Installation Guide for OpenPayAPI: https://docs.google.com/a/paygate.net/Doc?docid=0Ac8xChBlSAiTZGN4cXhjdDJfMTU0bTNxbjk4ZjY&hl=en * CUP payment through OpenPayAPI.
In case of CUP(China PRC Debit Card)
payment,
Verify following variable
paymethod :105
langcode
China: CN
goodcurrency
China, Yuan Renminbi : CNY
<form name="PGIOForm">
<input name="mid" value="testshop"
/>Merchant ID
<input name="paymethod" value="105"
/>paymethod
<input name="goodname" value="tgoods"
/>goodname
<input name="unitprice" value="50" />price
<input name="goodcurrency" value="CNY"
/>currency
<input name="langcode" value="CN"
/>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="cardsecretnumber" />card
cvv2 value
<input name="cardownernumber" />last 7
digit of SSN
<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>
*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
<form name="PGIOForm">
<input name="mid" value="testshop"
/>Merchant ID
<input name="paymethod" value="106"
/>paymethod
<input name="goodname" value="tgoods"
/>goodname
<input name="unitprice" value="50" />price
<input name="goodcurrency" value="CNY"
/>currency
<input name="langcode" value="CN"
/>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="cardsecretnumber" />card
cvv2 value
<input name="cardownernumber" />last 7
digit of SSN
<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>
As for exchange rate for CUP/Alipay,
Country Payment Price of Products Payment amount Amount Billing
to Customer Settlement to Paygate Settlement to Merchant Remark
Alipay 1,000 CNY 1,000/6.82=146.62 USD 146.62 USD*6.82 =
999.94 CNY 146.62 USD - Transaction fee 146.62 USD - Transaction fee= _____UDS or JPY
China CUP 1,000 CNY 1,000 CNY 1,000 CNY 1,000 CNY*0.123=123 USD 146.62 USD - Transaction fee= _____UDS or JPY
Credit Card 1,000 CNY 1,000/6.82=146.62 USD 146.62 USD*6.82 =
999.94 CNY 999.94 CNY*0.147=146.99 USD 146.62 USD - Transaction fee= _____UDS or JPY
5. Call doTransaction to proceed 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>
l doTransaction(document.PGIOForm); In order to make doTransaction workable, all five basic
elements(PGIOForm, PGIOScreen, doTransaction, OpenPayAPI, getPGIOresult) are required.
l Merchants have to validate the variables before calling doTransaction() method.
l PayGate proceeds payment under the condition all elements are properly prepared. If there is any incorrect, the proper error message will be shown.
6. Designate the area for PGIOScreen.
Before After
// Payment screen can be positioned at this part.
// Payment screen can be positioned at this part. <div id="PGIOscreen"></div>
l PGIOScreen div tag can be located in any place of order page. Please be aware that the layout screen can be broken due to the additional PGIOScreen div tag.
l PGIOScreen includes <form> to put in information and should not be surrounded by any
other <form> tag .
l Merchant is able to change CSS style of PGIOScreen and please refer to the manual to use the defined style.
7. getPGIOresult() is called after the completion of transaction
Before After
<script type="text/javascript"> function startPayment() { doTransaction(document.PGIOForm); } </script>
<script type="text/javascript"> 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>
l When getPGIOresult() is called, all result values are already filled in PGIOForm.
l By calling getPGIOresult, the API is able to verify authentication number, transaction result
and message from credit card companies.
l If no getPGIOresult() is defined, transaction result can’t be proceeded even though the transaction is successfully completed.
l If merchant does not prepare for getPGIOresult, only PayGate keeps the transaction in server and the merchant can’t check the result.
l Please use getPGIOresult() and keep the record in your server so that you can also check the order information.
8. Identify the payment breakdown(Verification) Please add the following function to avoid any missing of payment breakdown on your screen due to the environment of browser and instability of sever during the process of storing payment breakdown of PayGate system into your DB.
l While payment is under proceeding, please add verifyNum +1 when payment module (doTransaction (document.PGIOForm)) is called and call function getPGIOresult () after the payment, afterward, 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 DB 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 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 of variable 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 OF PAYMENT SYSTEM.
After integration of the payment system of PayGate, there are several convenient functions you can add for end-users.
When the transaction is successfully finished, text message can be sent to customers or designated administrators.
o To administrators
§ You can assign two administrators. While you are busy and don’t have time to manage, this service will help you for a quick delivery service.
o To customers § Upon completion of the card transaction, usually, card companies send a text
message to the customer. But there is no this kind of service for bank transfer payment and you can use the following service for this payment and customer will have more confidence wit this service.
When the transaction is complete, a sales slip can be available.
o Upon completion of the transaction, customers will receive an email for the transaction detail, but this service will not be available if the customers don’t put their e-mail address during the transaction.
o 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.Test the payment system in advance
All transaction is real. Please remind that the amount you paid for test will be actually charged. In order to cancel transaction, please notify the transaction information (TID, date, amount and type of card) to [email protected]
1. (Test page for 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 basic information(id, goodname, unit price), payment can be proceeded. o According to payment types, additional variables(receipt name, charset on payment page,
language on payment module, etc) can be required.
2. Test sample page of all payment methods(Useful for debugging o https://api.paygate.net/orderforms/order.html
o
1. Fill-in minimum value by manual and click "OpenPayAPI" button. Displaying the agreement.
2. By card types, Visa 3D popup or ISP control can be displayed.
3. After completing the transaction, getPGIOresult() method is called.
IX.Other References Most of Korea Card Issuers require safety payment through Visa3D or ISP. . Please make the selection of card type & installment on your order page. If no card type is selected, PayGate API will display all supported card types and in this case, it may happen that customers will keep trying with the card which is not registered at the merchant. Please test at your side and make sure. Test has to be done on the server. API will not work on the local file..
Evaluation of shopping Mall by Card Company for registration To activate Korea Local Card transaction, all merchants have to be registered to card issuers. After integration the payment, PayGate requests each card issuer to verify merchant page.
Reference for the integration of overseas credit card payment
* As for oversea card transaction, only cards issued abroad like VISA and MASTER card can be tested (With any cards issued in the domestic, can’t pay with USD. Please contact technology development team for the test of oversea card transaction.
· How to request: Please send an email to [email protected]. · Requirement :
o Please inform test id & pw if the payment is not workable with nonmember. o If the transaction amount is high (more than $ 100), please prepare a low amount of virtual
goods o Please advise the absolute address of the product and the method to enter if the process of
payment is complicated.