INTRODUCTION MERCHANT INTEGRATION Ha noi, 14/06/2015 INTRODUCTION MERCHANT INTEGRATION 1
Contents 1. PURPOSE... 3 2. INTEGRATION... 4 2.1 Integrate payment gateway... 4 2.2 Parameters request to OnePAY... 5 2.3 Parameters response from OnePAY... 8 2.4 Response Code Descriptions... 9 2.5 IPN (Instant Payment Notification)... 10 2.5.1 What is IPN?... 10 2.5.2 Integatration method... 10 2.6 QueryDR... 11 2.6.1 URL... 11 2.6.2 Prameters... 11 2.6.3 Example... 12 2.7 Test case... 13 2.8 Testing information... 14 INTRODUCTION MERCHANT INTEGRATION 2
1. PURPOSE This document guides Merchant integrated payment gateway to website Merchant and secure payment gateway is integrated in accordance with standards of international card organizations and OnePAY. The payment flow for Domestic Payment Gateway (Vietnam ATM Card) INTRODUCTION MERCHANT INTEGRATION 3
2. INTEGRATION 2.1 Integrate payment gateway - Step 0: Download source code, documents from this site. URL to view MERCHANT ACCOUNT TEST, CARD ATM TEST: https://mtf.onepay.vn/developer/?page=modul_noidia URL to download jsp source code: https://mtf.onepay.vn/developer/?page=modul_noidia_jsp URL to download php source code: https://mtf.onepay.vn/developer/?page=modul_noidia_php URL to download C#.net: https://mtf.onepay.vn/developer/?page=modul_noidia_c URL to download Vb.net: https://mtf.onepay.vn/developer/?page=modul_noidia_vb URL to download ASP Classic: https://mtf.onepay.vn/developer/?page=modul_noidia_asp - Step 1: If module payment gateway is: o PHP then open index.php file o JSP then open VPC_JSP_3P.html file o ASP then open VPC_ASP_3P.html file o C#.net then open vpc_do.aspx file - Step 2: Running the Web Server module (or localhost) on the invironment Internet connection. Open the file in Step 1 payment form on a web browser, click the Checkout button, on to the website of the chosen card payment gateway OnePay, select the type of visa and entry card as the card information: INTRODUCTION MERCHANT INTEGRATION 4
+ Type of card: Vietcombank Connect24 + Card Name: NGUYEN HONG NHUNG + Card Number: 6868682607535021 + Issue date: 12/08 After that click Submit, the web page will redirect to Vietcombank semulator page for authorise card holder. Typing ten digit to Transaction code (Mã giao dịch) : + Code: 123456 + Click PAY - Step 3: Check information in return for a DR file s are successful, pending - unknown results or failed payment. Specifically: 1. Payment successfully: vpc_txnresponsecode = 0 Hash Validated Correctly: CORRECT 2. Pending payment s: Hash Validated Correctly: INVALID HASH vpc_txnressponsecode =0 3. The payment fails. vpc_txnresponsecode <> 0 2.2 Parameters request to OnePAY Request to: https://mtf.onepay.vn/onecomm-pay/vpc.op?[key]=[value]&[key]=[value]&... Parameter Requited Optional Field type Length Example Value vpc_version The version of the Virtual Payment Client being used. The current version is 2. Required Alphanumeric 1-8 2 INTRODUCTION MERCHANT INTEGRATION 5
virtualpaymentclienturl http address of payment gateway alphabet 1-45 vpc_command Indicates the type. This must be equal to pay Required Alphanumeric 1-16 pay vpc_accesscode The access code authenticates you on the Payment Server so that a merchant cannot access another merchant s MerchantId. The access code is provided to you when you registered your merchant profile with your Payment Provider. Required Alphanumeric 8 D67342C2 vpc_merchtxnref A unique value created by the merchant to identify the DO. It is used to track the progess of a and allows it to be identified on the Payment Server should a communication s failure occur and the DR is not received. It may be in part an order number or invoice number, but it should also reflect the attempt. For example, if a cardholder has insufficient funds on their card and you allow them to repeat the with another credit card. The value may be test1234/1 on the first attempt, test1234/2 on the second attempt and test1234/3 on the third attempt. It can use text made up of any of the base US ASCII characters in the range, hexadecimal20 to 126. Required Alphanumeric 1-40 Test1234/1 vpc_merchant The unique merchant Id assigned to you by your Payment Provider. Required Alphanumeric 1-16 ONEPAY vpc_orderinfo Your own identifier used to identify the with the cardholder. For example, a shopping cart number, an order number, or an invoice number. Required Alphanumeric 1-34 Test1234 vpc_amount INTRODUCTION MERCHANT INTEGRATION 6
The amount of the in the smallest currency unit expressed as an integer. Note: vpc_amount = Transaction Amount * 100 For example, if the amount is VND 59900 then the vpc_amount is 5990000. Required Alphanumeric 1-10 59954 vpc_returnurl The URL that is displayed to the cardholder s browser when the Payment Server sends the DR.It must be a complete URL. The Return URL must start with either http:// or https:// and may be up to 255 characters. If the return URL is not supplied, your default vpc_returnurl that you nominated when you registered your merchant profile with your Payment Provider is used. Required Alphanumeric 1-255 http://returnu rl/receipt.asp vpc_locale Language show on payment gateway. vn is Vietnamese, en is English Required Alphanumeric 2-5 vn vpc_currency The currency of the amount. The currency is VND Required Alphanumeric 1-3 VND vpc_ticketno Ticket No is IP address of the computer of the cardholder do the. Required Alphanumeric 1-45 210.245.0.11 vpc_securehash Required Alphanumeric 64 54616600DB8 B7610064074 1247D14E070 A5121DA926 B6D738436C ED590FB9DE E Note: Parameter name can be changed following merchant advice during integration. INTRODUCTION MERCHANT INTEGRATION 7
2.3 Parameters response from OnePAY Response: https://your-website/result-page?[key]=[value]&[key]=[value]&... Parameter Required Field Type Length Comment Optional vpc_version The value of the vpc_version DO input field that is returned in the DR. input Alphanumeric 1-2 2 vpc_command The value of the vpc_comand DO input field that is returned in the DR. Input Alpha 3 pay vpc_addition Addtion infor 255 [6 digits Card Bin] vpc_transactionno Payment server id vpc_merchtxnref The value of the vpc_merchanttxnref DO input field that is returned in the DR. Input Alphanumer 1-40 Test1234/1 ic - Special vpc_merchant The value of the vpc_merchant DO input field that is returned in the DR. Input Alphanumeric - Special 1-16 TESTMERCHANT01 vpc_orderinfo The value of the vpc_orderinfo DO input field that is returned in the DR. Input Alphanumeric Special characters 1-34 Test1234 vpc_amount The value of the vpc_amount DO input field that is returned the DR. Input Numeric 1-10 4995 INTRODUCTION MERCHANT INTEGRATION 8
vpc_currency Currency type of amount in alphabet 1-3 VND vpc_locale The value of the vpc_locale DO input field that is returned in the DR. It specifies th language thatis used on the Payment Server pages that are displayed to the cardolder. Input Alphanumer ic 2-5 vn vpc_txnresponsecod e A response code that is generated by the Payment Server to indicate the status of the. A vpc_responsecode of 0 indicates that the was processed successfully and approved by the Acquiring Bank. Any other value indicates the was declined Required Numeric 1 0 vpc_message Indicates any errors the may have encountered Optional Alphanumer ic 10-200 No reply from Bank vpc_securehash Optional Alphanumer ic 64 DDDF9FC7E67B7 0743E15796546A2 31BD4B3D438803 9B235DBEC632 C A88058DFC 2.4 Response Code Descriptions List of value for vpc_txnresponsecode field Response Code Desc 0 Approved 1 Declined 3 Merchant not exist 4 Invalid access code INTRODUCTION MERCHANT INTEGRATION 9
5 Invalid amount 6 Invalid currency code 7 Unspecified Failure 8 Invalid card Number 9 Invalid card name 10 Expired Card 11 NOT REGISTED SERVICE 12 Invalid card date 13 Exist Amount 21 INSUFFICIENT FUND 22 Invalid Account 23 Account Lock 24 Invalid Card Info 25 Invalid OTP 25 3 Transaction timeout 99 User cancel 2.5 IPN (Instant Payment Notification) 2.5.1 What is IPN? IPN is a utility of OnePAY payment gateway. It will provide all of the s data that was paid through payment gateway OnePAY. IPN technology works in server-to-server and your client will not be able to see through the screen. 2.5.2 Integration method The merchant have to build the URL and IPN will send GET data is same as data received on DR file to this URL. IPN processing model: INTRODUCTION MERCHANT INTEGRATION 10
Pic 3. IPN After received post data from IPN, you need get the value of vpc_txnresponsecode variable: vpc_txnresponsecode=0 and hash CORRECT: the succeed vpc_txnresponsecode#0: the failed If response from OnePAY is not received, we will keep retry three times on three minutes interval (1 time per 1 minute) If your received response from us, please response back to OnePAY in below fomat: responsecode=1&desc=confirm-success - Responsecode = 1: received - Responsecode = 0: received and invalid hash 2.6 QueryDR 2.6.1 URL URL Submit form in Test mode: https://mtf.onepay.vn/onecomm-pay/vpcdps.op URL Submit form in Production: https://onepay.vn/onecomm-pay/vpcdps.op Method: http request (POST) 2.6.2 Prameters Field Value type Description Example vpc_version String Static 1 vpc_command String Static querydr INTRODUCTION MERCHANT INTEGRATION 11
vpc_accesscode String Code of Merchant Account D67342C2 vpc_merchant String ID of Merchant Account ONEPAY vpc_merchtxnref String (40 chars) Key of payment Me_12321323232 vpc_user String Inquiry account op01 vpc_password String Password of inquiry account op123456 2.6.3 Example Request: https://mtf.onepay.vn/onecomm- pay/vpcdps.op?vpc_accesscode=d67342c2&vpc_command=querydr&vpc_merchtxnref=2259-1413779290&vpc_merchant=onepay&vpc_password=op123456&vpc_user=op01&vpc_version=1 Result: vpc_drexists=y&vpc_additiondata=686868&vpc_amount=129600000&vpc_command=pay&vpc_curr encycode=vnd&vpc_locale=vn&vpc_merchtxnref=2259-1413779290&vpc_merchant=onepay&vpc_message=transaction was successful&vpc_orderinfo=bao giay 2 nam - MSDH: 2259&vpc_TransactionNo=1472830&vpc_TxnResponseCode=0&vpc_Version=2 QueryDR function returns the result as a result of the original payment, plus 2 additional fields: - vpc_drexists: that there exist s to the value of the Merchant Transaction Reference. If the value of vpc_drexists equals Y that is existence. - vpc_txnresponsecode: status of payment INTRODUCTION MERCHANT INTEGRATION 12
2.7 Test case Cas e Content Steps Purpose Expected results Actual results Test Frontend (F) and Backend (B) Status (pass or not pass) 1 Test a successful 1. Enter card info (ATM card) below Checking the system to update a successful F: Show a success page. B: Update success status. Send a success mail to customer, sms, 2 Test a fail Response code <> 0 1. Cancel a or enter incorrect date. Checking the system to update a fail F: Show fail page. B: Update fail status 3 Check hash 1. Do a fail (vpc_txnrespons ecode <> 0 ) 2. Edit value of parameter vpc_txnresponse Code to 0 on return URL Checking the system to update a if parameters are modified on return URL F: Show fail page. B: Update status is pending 4 Return multiple times 1. Do a successful. 2. Refresh browser or re-press the return URL on browser s address bar B: Do not update again Check confirm backend system (IPN) INTRODUCTION MERCHANT INTEGRATION 13
5 Front-end and IPN both received data 1. Do a successful Checking the system to update a F: Show a success page. B: Update success status. Send a success mail to customer, sms, 6 Front-end not received data and IPN received data 1. Do a successful 2. Close the browser while redirecting from Onepay to website Checking the system to update a B: Update success status. Send a success mail to customer, sms, 7 Front-end received data and IPN not received data 1. Disable back-end url 2. Make a successful Checking the system to update a F: Show a success page. B: Update success status. Send a success mail to customer, sms, 2.8 Testing information Card type: Vietcombank Name: NGUYEN HONG NHUNG Number: 6868682607535021 Date: 12/08 OTP: 123456 ===== MERCHANT INFO TEST ======================== URL Payment: https://mtf.onepay.vn/onecomm-pay/vpc.op MerchantID: ONEPAY Accesscode: D67342C2 Hashcode (Tên khác là SECURE_SECRET): A3EFDFABA8653DF2342E8DAC29B51AF0 INTRODUCTION MERCHANT INTEGRATION 14