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
1. Version Control
Version Date Remarks
1.0.0 March 12th, 2015 First version.
1.0.1 March 12th, 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
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. “[email protected]”
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. 50 characters. “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. “Nikon N2748;”, or “Nikon N2746;Nikon N3001;”
v_productqty Product quantity Optional Decimal. Leave blank if no
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.
50 characters.
V_Routing Bank Routing Number Required Alphanumeric.
50 characters. “0123456789”
v_AccountNo Account Number Required Alphanumeric.
50 characters. “0123456789”
V_AccountType Account Type Required Alphanumeric.
50 characters. “Checking” or “Saving”
v_BankName Bank Name Required Alphanumeric.
50 characters. “Bank of America”
v_CheckNo Check Number Required Alphanumeric.
50 characters. “123456”
V_CheckName Check Name Required Alphanumeric.
50 characters. “John Smith”
V_CheckType Check Type Required Alphanumeric.
50 characters. “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.
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
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 :
12. Appendix B – Currency Codes
USD United States – Dollar
CNY China – Renminbi
MYR Malaysia – Ringgit
SGD Singapore – Dollar
IDR Indonesia – Rupiah
THB Thailand – Baht
EUR Europe – Euro dollar
GBP United Kingdom – Sterling pound
JPY Japan – Yen
AUD Australia – Dollar
NOK Norwegian – Krone
CAD Canada – Dollar
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 validateResult = “Invalid Signature “ End
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