Penthouse, Unit 12 th Floor, API For PaySec Merchants Configuration: Automated Clearing House (ACH) Version: 1.0.1 Status: Published Contents 1. Version Control... 1 2. Introduction... 1 3. Prerequisites... 1 4. Payment Submission Workflow... 1 5. Return Parameter for CallbackURL... 4 6. Check Payment Status by CartID... 4. 7. Check transaction status in Merchant Site... 4 8. Request for refunds... 4 9. Merchant Notify Email Setup... 5 10. Frequently Asked Questions... 5 11. Appendix A - Country Codes... 5 12. Appendix B - Currency Codes... 6 13. Appendix C - Sample code to compare signature... 7 14. Appendix D - Payment Status Code... 8 Page 2
Penthouse, Unit 12 th Floor, 1. Version Control Version Date Remarks 1.0.0 March 12 th, 2015 First version. 1.0.1 March 12 th, 2015 Added parameter v_accounttype 2. Introduction This documentation is meant for merchants of PaySec. It describes how to integrate merchant system with PaySec, in order to, submit payment information, receive payment status and check payment status. A merchant account may be configured differently for different type of processor and workflow. This documentation is meant for the ACH configuration. 3. Prerequisites Merchant When a merchant is registered with PaySec, the merchant is provided with a Merchant ID. Whitelisting PaySec Server IP PaySec payment processing server IP is 203.223.135.105. Before beginning integration with PaySec, please ensure this IP address is whitelisted in the firewall, for inbound and outbound traffic. 4. Payment Submission Workflow 1. Buyer visits payment form and fill the form detail in merchant website. 2. That information is saved by merchant system. Buyer s browser is redirected to a waiting page (in merchant site). But the payment parameters are posted to PaySec in the background. 3. PaySec server will send payment status to merchant system in the background via HTTP Request method. The URL of the HTTP Request is called CallbackURL. 4. Receiving the payment status in the backend, the waiting page (in the merchant site) will jump out of its refreshing loop and displays the payment status to the buyer. In step 2 above, the payment information is submitted to https://merchant.paysec.com/int/cpach.asp Page 3
The following parameters are submitted to the above URL. Parameter Description Requirement Specification Example v_currency Currency code Refer to Appendix B Currency Codes. Required Alphanumeric. 3 characters. All uppercase. CNY v_amount Amount to pay Required Numeric only. 2 decimal. 123.45 v_firstname Buyer s first name Required Alphanumeric. 18 characters. John v_lastname Buyer s last name Required Alphanumeric. 18 characters. Sayor V_dob Buyer s date of birth Required Format yyyymmdd 20021231 V_SSN Buyer s Social Security Number (for United States buyers only) Required Alphanumeric. 4 characters. 1234 v_billemail Email address Required Alphanumeric. 40 characters. john.stuart@gmail.com v_shipstreet Street Optional Alphanumeric. 40 characters. No. 1 Stuart Road v_shipcity City Optional Alphanumeric. 40 characters. Kuala Lumpur v_shipstate State Optional Alphanumeric. 40 characters. Wilayah Persekutuan v_shippost Post code or Zip code Optional Alphanumeric. 40 characters. 50000 v_shipcountry Country name Optional Refer to Appendix A. MY (ISO 1366 Standard Country Code) v_shipphone Phone number Optional Alphanumeric. 18 characters. 60388887777 v_billstreet Street Required Alphanumeric. 40 characters. No. 1 Stuart Road v_billcity City Required Alphanumeric. 40 characters. Kuala Lumpur v_billstate State Required Alphanumeric. 40 characters. Wilayah Persekutuan v_billpost Post code Required Alphanumeric. 40 characters. 50000 v_billcountry Country name Required Refer to Appendix A. MY (ISO 1366 Standard Country Code) v_billphone Phone number Required Alphanumeric. 18 characters. 60388887777 CID Merchant ID* Required Alphanumeric. M104- C- 196 merchantkey Company merchantkey* Required Alphanumeric. 10 characters. UiCFdmLp v_cartid Cart ID Required Alphanumeric. 255 characters. 0029471JKWN823 v_productno Product numbers Numbering of single or multiple products in cart Optional Alphanumeric. 255 characters. Leave blank if no product. 1;, or 1;2;3;, or 1; 2a; 2b; 3;, or A;B;C; or 1.1;1.2;2;3; v_productcode Product codes Optional Alphanumeric. 255 characters. Leave blank if no product. PKG1028;, or P1028;P2019; v_productdesc Product description Optional Alphanumeric. 255 characters. Leave blank if no product. v_productqty Product quantity Optional Decimal. Leave blank if no product. Nikon N2748;, or Nikon N2746;Nikon N3001; 1; or 1;1;2; Page 4
Parameter Description Requirement Specification Example v_productunitpr ice Product prices Optional Decimal. Leave blank if no product. 400; or 1200;20.30; v_productprice Currency Product prices currency Optional Alphanumeric. 3 characters. USD v_subamount Product sub- amounts Optional Decimal. Leave blank if no product. 400; or 1200; 20.30; * provided to merchant who successfully registered with PaySec. Parameter Description Requirement Specification Example v_checkmemo Reason of the payment Required Alphanumeric. 500 characters. Product purchase v_micr Magnetic Ink Check Reader data line Required Alphanumeric. 500 characters. V_DrivingLicens e Buyer s Driving License Number Required Alphanumeric. V_Routing Bank Routing Number Required Alphanumeric. 0123456789 v_accountno Account Number Required Alphanumeric. 0123456789 V_AccountType Account Type Required Alphanumeric. v_bankname Bank Name Required Alphanumeric. Checking or Saving Bank of America v_checkno Check Number Required Alphanumeric. 123456 V_CheckName Check Name Required Alphanumeric. John Smith V_CheckType Check Type Required Alphanumeric. Personal or Corporate or Government Parameter Description Requirement Specification Example callbackurl transaction result will send to this URL Required Alphanumeric. 255 characters. https://merchant.paysec.co m/samples/callbackurl.asp returnurl Buyer s browser will be redirected back to this URL when the transaction is complete. This overrides the returnurl setting in the PaySec backoffice. Optional Alphanumeric. 255 characters. https://merchant.paysec.co m/samples/returnurl.asp v_ip The buyer s IP address Required Alphanumeric. 201.45.123.34 Page 5
5. Return Parameter for CallbackURL Parameter name Title Description Example of data mid Merchant ID This is the merchant ID of this transaction. This is useful for our log files to detect anomalies when we try to debug the problem. text M104- C- 196 oid Order ID This is the unique order ID that identifies the transaction. text M104- PO- 1234 cur Currency This is a 3 letter code of the currency. Example: USD amt Amount This is a numeric value of the transaction amount. numeric 10000.00 status Status 88 - Transferred means this transaction has been successfully completed. Other results mean Declined or Failed transaction status. Refer to Appendix D. text 88 - Transferred cartid Cart ID This is the merchant generated reference number text 12345678 signature signature This is SHA1 signature that generate by our gateway text To ensure the signature generated was correct, compare the link below for signature comparison. https://merchant.paysec.com/api/validatesign.asp?oid="<your return OrderID here>" When PaySec receives the request or transaction order from the merchant, it will check the hash value it generates to match with the value you as a merchant have included. When your script receives the results of the transaction, you can send your order ID to us, and we will send back a set of Hash code and you need be sure that the return signature matches ours. Do take note that the signature in the response will only be present if the transaction is not in error, that is, for approved and declined transactions. 6. Check Payment Status by CartID Merchant can get Payment Status by CartID in some cases if some transaction are not confirm To check transaction https://merchant.paysec.com/api/getpaymentstatus.asp?cartid=cart12345&companyid=m104- C- 277&merchantKey=DSAS213 Example return result : mid=m104- C- 277&oid=M104- PO- 4890&cur=&amt=1&status=Cancelled&cartid=6407333&createdDateTime=2013-03- 20 14:36:13 Noted that if duplicated cartid payment, it will display mutliple row of result. 7. Check transaction status in Merchant Site Login at http://paysec.com and login using the Login ID and Password provided by PaySec. After you have logged in, go to function Transaction History Page. 8. Request for refunds 1. Login to Merchant Site (http://paysec.com) 2. Open Transaction History Page 6
3. Click on Request refund in the Refund Status column. 4. Enter reason of refund. This is required. 5. Enter merchant password for confirmation. 6. Click on Request button. 7. The status of the refund will change to Pending. 8. When the request for refund process has been completed, the status will change to Completed. 9. Merchant Notify Email Setup This notify email settings is for every time any transaction from your customer end, it will send another copy of transaction receipt to your email. Way to setup: 1. Login to Merchant Site (http://paysec.com) 2. Open Merchant Notify Email Settings 3. Enter the email address for receive notification if any customer done transaction. 4. Check on Enable checkbox 5. Click Submit 10. Frequently Asked Questions If I have two accounts from PaySec. One Visa and one Mastercard, how do I do the integration? Each merchant account from PaySec has a unique Company ID and Merchant Key. When the buyer uses a Visa card, then use the Company ID of the Visa assigned account. If the buyer uses a Mastercard, then use the Company ID of the Mastercard assigned account. This applies to situation for mult- currencies and multi- product categories (descriptor code). 11. Appendix A Country Codes ISO 3166 Country Code PaySec uses the standard ISO 3166 Two alphabet country code Example : 1. AF is same equal to AFGHANISTAN Country 2. AL is same equal to ALBANIA Country For full listing, please refer to : http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements.htm Page 7
12. Appendix B Currency Codes USD CNY MYR SGD IDR THB EUR GBP JPY AUD NOK CAD SEK United States Dollar China Renminbi Malaysia Ringgit Singapore Dollar Indonesia Rupiah Thailand Baht Europe Euro dollar United Kingdom Sterling pound Japan Yen Australia Dollar Norwegian Krone Canada Dollar Sweden Krona Page 8
Penthouse, Unit 12 th Floor, 13. Appendix C Sample code to compare signature ASP sample code v_signature = trim(request( signature )) signatureserver = GetTextFromUrl( https://merchant.paysec.com/api/validatesign.asp?oid= & request( oid )) Function GetTextFromUrl(url) Dim oxmlhttp Dim strstatustest Set oxmlhttp = CreateObject( MSXML2.ServerXMLHTTP.3.0 ) oxmlhttp.open GET, url, False oxmlhttp.send If oxmlhttp.status = 200 Then GetTextFromUrl = oxmlhttp.responsetext End If End Function if v_signature = signatureserver Then validateresult = Valid Signature ElseIf v_signature <> signatureserver Then End validateresult = Invalid Signature
Penthouse, Unit 12 th Floor, V Corporate Centre, L.P. Leviste St. Salcedo Village, Makati City, Philippines, 1227 14. Appendix D Payment Status Code Code Status Description 0 Payment Declined 2 Card IP EMAIL- BLACK LIST 3 Transaction amount limit 5 IP Duplicate 6 Email Duplicate 7 Card Duplicate 8 Browser Duplicate 9 High risk transaction 10 MID haven register 12 Invalid Currency code 13 Invalid Md5info 15 MID not open 16 MID channel not open 17 Card bin blacklisted 18 Browser Duplicate 19 Transaction processing, please check status in later 25 Message error 26 Amount over limit 30 Phone more than 1 times. Daily limit reached 66 Failed 67 Rejected. High risk / fraud 88 Transferred - - - End of document - - -