INTRODUCTION MERCHANT INTEGRATION. Ha noi, 10/7/2012

Transcription

1 INTRODUCTION MERCHANT INTEGRATION Ha noi, 10/7/2012 0

2 Index Index Purpose Content Integrate payment gateway Edit the specifications of international payment gateway Response Code from OnePAY Domestic Payment Gateway... 9 No: 01/QT-KT Trang 1/5

3 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. 2. Content 2.1 Integrate payment gateway - Step 0: Register one account in the url: Login to your account and download source code, documents from this site. URL to view MERCHANT ACCOUNT TEST, CARD CREDIT TEST: URL to download jsp source code: URL to download php source code: URL to download C#.net: URL to download Vb.net: URL to download ASP Classic: - 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 The file is called payment form. Parameter Requited Optional Field type Length Example Value vpc_version The version of the Virtual Payment Client being used. No: 01/QT-KT Trang 2/5

4 The current version is 2. Required ic 1,8 2 virtualpaymentclienturl http address of payment gateway alphabet vpc_command Indicates the transaction type. This must be equal to pay Required ic 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 ic 8 d03due3 vpc_merchtxnref A unique value created by the merchant to identify the DO. It is used to track the progess of a transaction 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 transaction attempt. For example, if a cardholder has insufficient funds on their card and you allow them to repeat the transaction 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 ic 1,40 Test1234/1 vpc_merchant The unique merchant Id assigned to you by your Payment Provider. Required ic 1,16 TESTMERCHA NT01 vpc_orderinfo Your own identifier used to identify the transaction with the cardholder. For example, a shopping cart number, an order number, or an invoice number. Required ic 1,34 Test1234 No: 01/QT-KT Trang 3/5

5 vpc_amount The amount of the transaction in the smallest currency unit expressed as an integer. For example, if the transaction amount is VND then the amount is Required ic 1, 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 or 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 ic 1,255 rl/receipt.asp vpc_locale Used in SSL type transactions for specifying the language that is used on the Payment Server pages that are displayed to the cardholder. If the locale is not supplied the Payment Server defined default of vn is used. Required ic 2,5 vn vpc_ticketno Ticket No is IP address of the computer of the cardholder do the transaction. Required ic 1, vpc_securehash Required ic DB8 B D14E070 A5121DA926 B6D738436C ED590FB9DE E Title Required alphabet Onepay gateway AgainLink Required alphabet No: 01/QT-KT Trang 4/5

6 com Note: Parameter name can be changed following merchant advice during integration. - Step 2: Copy MerchantID, Accesscode (from url address: and paste vpc_merchant và vpc_accesscode into payment form opened in step 1. - Step 3: If the module payment gateway is: o PHP then open do.php file and dr.php file o JSP then open VPC_JSP_3P_DO.jsp file and VPC_JSP_3P_DR.jsp file o ASP then open VPC_ASP_3P_DO.asp file and VPC_ASP_3P_DR.asp file o C#.net then open vpc_do.aspx.cs file and vpc_dr.aspx.cs file 2 files are calld file DO và file DR. - Step 4: Copy Hash code (or SECURE_SECRETfrom url address: and paste the values to SECURE_SECRET fields in DO file and DR file opened in step 3. - Step 5: Fix Purchase Amount in payment form opened in step 1 equal Step 6: Open payment form, finding Merchant Transaction Reference field has vpc_merchtxnref variable. Vpc_MerchTxnRef is varchar type and unique value per even transaction, maxlength is 34 degits. Vpc_MerchTxnRef is called key of transaction. You can write a function that automatically increases (sequence) or take the time to assign values to vpc_merchtxnref variables. Such as vpc_merchtxnref = Step 7: 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: + Type of card: visa + Card Number: No: 01/QT-KT Trang 5/5

7 + Issue date: 05/13 + CVV/CSC: Step 8: Check information in return for a DR file transactions are successful, pendding - unknown results or failed payment. Specifically: 1. Payment transaction successfully: vpc_txnresponsecode = 0 Hash Validated Correctly: CORRECT 2. Pending payment transactions: Hash Validated Correctly: INVALID HASH 3. Other cases vpc_txnressponsecode <>0 Hash Validated Correctly: CORRECT The payment transaction fails. Parameters in DR file. Parameter Required Optional Field Type Length Comment vpc_version The value of the vpc_version DO input field that is returned in the DR. input ic 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_add Addtion infor 255 [6 digits Card Bin] vpc_transactionno Payment server transaction id vpc_merchtxnref The value of the vpc_merchanttxnref DO input field that is returned in the DR. Input ic - Special 1,40 Test1234/1 vpc_merchant The value of the vpc_merchant DO input field that is returned in the DR. No: 01/QT-KT Trang 6/5

8 Input ic - Special 1,16 TESTMERCHANT01 vpc_orderinfo The value of the vpc_orderinfo DO input field that is returned in the DR. Input ic Special characters 1,34 Test1234 vpc_amount The value of the vpc_amount DO input field that is returned the DR. Input Numeric 1, vpc_currency Currency type of amount in transaction 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 ic 2,5 vn vpc_responsecode A response code that is generated by the Payment Server to indicate the status of the transaction. A vpc_responsecode of 0 indicates that the transaction was processed successfully and approved by the Acquiring Bank. Any other value indicates the transaction was declined Required Numeric 1 0 vpc_message Indicates any errors the transaction may have encountered Optional ic 10,200 No reply from Bank vpc_securehash Optional ic 64 DDDF9FC7E67B7 0743E A2 31BD4B3D B235DBEC632C A88058DFC No: 01/QT-KT Trang 7/5

9 2.2 Edit the specifications of international payment gateway - Step 9: Open payment form file opened in step 1, look to the Ticket Number is vpc_ticketno variable. Vpc_TicketNo variable is assigned an IP address Remote address of the client computer, for example You need to write a function to get Remote IP Address from the client machine and assigned to the vpc_ticketno variable. - Step 10: Open form of payment file opened in step 1, find the Purchase Amount has vpc_amount variable. Last two units of the vpc_amount is odds provisions for payment of money should you need to make payment of the value with 100 before assigning values to variables vpc_amount, such payment: o VND is vpc_amount: o 100 USD is vpc_amount: o USD is vpc_amount: Step 11 : Coding insert, update functions in Database You create a table with fields such as TB_TRAN_LOG (or you can still save data into log file). Table TB_TRAN_OP STT Name Data type Null Default Primary Key 1 vpc_merchtxnref VARCHAR2(34) N Y Key Description 3 vpc_do VARCHAR2(1500) N N URL request 2 vpc_dr VARCHAR2(1500) Y Null N URL response Example: vpc_merchref: Table 1. Table TB_TRAN_LOG stored payment data vpc_do: /onecommpay/vpc.op?vpc_accesscode=d67342c2&&vpc_command=pay&vpc_orderinfo=test_ &&&vpc_ReturnURL=http%3A%2F%2Fmtf.onepay.vn%2Fopdev%2F%3Fpage%3Dde mo_noidia&&title=onepay+paygate&&vpc_version=2&vpc_locale=vn&vpc_ticketno= &vpc_Merchant=ONEPAY&vpc_Amount= &vpc_SecureHash= DB8B D14E070A5121DA926B6D738436CED590FB9DEE&&vpc_Currency=VND&vpc_MerchTxn Ref=TEST_ vpc_dr: &vpc_command=pay&vpc_currencycode=vnd&vpc_locale=vn&vpc_merchtxnref=test_ &vpc_Merchant=ONEPAY&vpc_OrderInfo=TEST_ & vpc_transactionno= &vpc_txnresponsecode=0&vpc_version=2&vpc_securehash=dddf9 FC7E67B70743E A231BD4B3D B235DBEC632CA88058DFC No: 01/QT-KT Trang 8/5

10 2.3 Response Code from OnePAY international Payment Gateway List of value for vpc_responsecode field Introduction Merchant Integration Response Code Desc 0 Approved 1 Transaction Declined - Bank Error 2 Bank Declined Transaction 3 Transaction Declined - No Reply from Bank 4 Transaction Declined - Expired Card 5 Transaction Declined - Insufficient funds 6 Transaction Declined - Error Communicating with Bank 7 Payment Server Processing Error - Typically caused by invalid input data such as an invalid credit card number. Processing errors can also occur 8 Transaction Declined - Transaction Type Not Supported 9 Bank Declined Transaction (Do not contact Bank) A C D E F I L N P Transaction Aborted Transaction Cancelled Deferred Transaction Issuer Returned a Referral Response 3D Secure Authentication Failed Card Security Code Failed Shopping Transaction Locked (This indicates that there is another transaction taking place using the same shopping transaction number) Cardholder is not enrolled in 3D Secure (Authentication Only) Transaction is Pending No: 01/QT-KT Trang 9/5

11 R S U Retry Limits Exceeded, Transaction Not Processed Duplicate OrderInfo used. (This is only relevant for Payment Servers that enforce the uniqueness of this field) Card Security Code Failed No: 01/QT-KT Trang 10/5