Sie sind auf Seite 1von 13

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 merchants 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 dev@paygate.net. -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 merchants page, so the end user can pay easily and quickly. All communication between customers 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 merchants 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.

IV. OpenPayAPI Payment Module


The payment screen will be displayed on the merchants 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 cant be used two times in <html> and <form> or <div> are not allowed to use before <HEAD>. Include the basic module--OpenPayAPI.js. JavaScript is necessary for processing payment.
Before After

2.

<html> <html> <head> <head> <title>Order Form</title> <title>Order Form</title> <script language="javascript" type="text/javascript" <script type="text/javascript" src="/script/order.js"></script> src="https://api.paygate.net/ajax/common/OpenPayAPI.js"></script> </head> <script type="text/javascript" src="/script/order.js"></script> <body> </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 <form name="order"> Goodname : <input type="text" name="product_name" value="PayGate System"></input> Price : <input type="text" name="product_price" 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>

value="110000">KRW110,000 </input> Goodcode : <input name="product_orderno" value="PGSystem"></input> </form>

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 credit card payment

For mobile phone 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 <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> <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> <form name="PGIOForm"> <input name="mid" value="testshop" />merchant id <input name="paymethod" value="???" />transaction method

For real time bank transfer

Notification is sent to customer that the payment has been remitted to merchants or PayGates account.

In case of card, mobile and real time bank transfer, lets the customer select payment 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> <form name="PGIOForm"> <input name="mid" value="testshop" />Merchant ID <input name="paymethod" value="104" />paymethod <input name="goodname" value="tgoods" />goodname For overseas credit card transaction, verify <input name="unitprice" value="11" />price the following variables: <input name="goodcurrency" value="USD" />currency <input name="langcode" value="US" />language code langcode <input name="receipttoname" value="test buyer" /> English : US <input name="cardquota" value="" />card quota Japanese : JP <input name="cardexpiremonth" />card expiry month <input name="cardexpireyear" />card expiry year goodcurrency <input name="cardsecretnumber" />card cvv2 value US Dollar : USD <input name="cardownernumber" />last 7 digit of SSN Japan Yen : JPY <input name="cardtype" />cardtype total of 23 currencies <input name="cardnumber" />cardnumber <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 <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>

goodcurrency China, Yuan Renminbi : CNY

*Alipay Payment through OpenPayAPI.


In case of Alipay payment, Verify following variable paymethod :106 langcode China: CN <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>

goodcurrency China, Yuan Renminbi : CNY US Dollar: USD

The exchange rate for CUP/Alipay Payment


Alipay CUP Credit Card

Payment amount
1,000/6.82=146.62USD 1,000CNY 1,000/6.82=146.62USD

Amount Billed to Customer


146.62USD*6.82 = 999.94CNY 1,000CNY 146.62USD*6.82 = 999.94CNY

Settlement to Paygate
146.62USD - fee 1,000CNY*0.123=123 USD 999.94CNY*0.147=146.99 USD

Settlement to Merchant
146.62USD - fee = ___USD 146.62USD - fee = ___USD 146.62USD - fee = ___USD

5.

Call doTransaction to process payment.


Before <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> After <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 <script type="text/javascript"> function startPayment() { doTransaction(document.PGIOForm); } <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>

</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 wont 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 merchants 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 PayGates payment system, there are several convenient functions you can add for your end-users.

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 dont 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 dev@paygate.net

1. Page for testing payment


o o o o o https://api.paygate.net/ajax/cardform.html ( Korea Local Card) https://api.paygate.net/ajax/cardform_USD2.html ( International Cards) https://api.paygate.net/ajax/Phone_form.html ( Korea Mobile phone) With just basic information (id, goodname, unit price), payment can be processed. 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. 3.

Depending on card type, Visa 3D popup or ISP control will be displayed. 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 dev@paygate.net. 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.