API For Chopstickpay Merchants Configuration: Server-to-server Version: 3.4 Status: Published Contents 1. Version Control... 1 2. Introduction... 2 3. Prerequisites... 2 4. Payment Submission Workflow... 2 5. Return Parameter for CallbackURL... 5 6. Check Payment Status by CartID... 6 7. Check transaction status in Merchant Site... 6 8. Request for refunds... 6 9. Merchant Notify Email Setup... 7 10. Frequently Asked Questions... 7 11. Appendix A - Country Codes... 8 12. Appendix B - Currency Codes... 9 13. Appendix C - Sample code to compare signature... 10 14. Appendix D - Payment Status Code... 11 1. Version Control Version Date Remarks 1.0 June 11 th, 2013 First version. 2.0 March 30 th, 2014 Posting URL has been updated. 3.0 June 9 th, 2014 Added v_dob parameter. Changed v_billstate, vbillpost and vbillcountry from Optional to Required. Replaced URL with IP address to merchant.chopstickpay.com. Added Frequently Asked Questions. 3.1 June 13 th, 2014 Indicated v_currency parameter values should always be uppercase. 3.2 August 24 th, 2014 Added returnurl and v_ip parameters. Added Whitelisting Chopstickpay IP. 3.3 September 13 th, 2014 Added Social Security Number parameter, v_ssn 3.4 September 16 th, 2014 Use ISO 3166 2-letter country code only. Full country name is removed for standardization. Page 1
2. Introduction This documentation is meant for merchants of Chopstickpay. It describes how to integrate merchant system with Chopstickpay, 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 webto-web configuration. 3. Prerequisites Merchant ID When a merchant is registered with Chopstickpay, the merchant is provided with a Merchant ID. Whitelisting Chopstickpay Server IP Chopstickpay payment processing server IP is 203.223.135.105. Before beginning integration with Chopstickpay, please ensure this IP address is 2hitelisted 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 Chopstickpay in the background. 3. Chopstickpay 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.chopstickpay.com/int/ccss-process.asp Page 2
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 Last 4 digits of 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. 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. v_productdesc Product description Optional Alphanumeric. 255 characters. Leave blank if no product. v_productqty Product quantity Optional Decimal. Leave blank if no product. PKG1028;, or P1028;P2019; Nikon N2748;, or Nikon N2746;Nikon N3001; 1; or 1;1;2; Page 3
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 Chopstickpay. Parameter Description Svr-to-svr requirement Specification Example v_pmode Credit card type Optional Numeric only VISA = visa MASTER = master AE = ae JCB = jcb v_card_holder Card holder first name Required Alphanumeric. 50 characters. John v_card_holder_l ast Card holder last name Required Alphanumeric. 50 characters. Sayor v_cardnum Card number Required Alphanumeric. 16 characters. No spaces. v_month Card expiration month Required Alphanumeric. 2 characters. v_year Card expiration year Required Alphanumeric. 4 characters. v_cvv2 Card CVV number Required Alphanumeric. 4 characters. 1111222233334444 01, 02.. 12 2010 577 Parameter Description Requirement Specification Example callbackurl transaction result will send to this URL Required Alphanumeric. 255 characters. https://merchant.chopstickpay.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 ChopstickPay backoffice. Optional Alphanumeric. 255 characters. https://merchant.chopstickpay.co m/samples/returnurl.asp v_ip The buyer s IP address Required Alphanumeric. 50 characters. 201.45.123.34 Page 4
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.chopstickpay.com/api/validatesign.asp?oid="<your return OrderID here>" When Chopstickpay 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. Page 5
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.chopstickpay.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://chopstickpay.com and login using the Login ID and Password provided by Chopstickpay. After you have logged in, go to function Transaction History Page. 8. Request for refunds 1. Login to Merchant Site (http://chopstickpay.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. Page 6
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://chopstickpay.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 Chopstickpay. One Visa and one Mastercard, how do I do the integration? Each merchant account from Chopstickpay 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). Page 7
11. Appendix A Country Codes ISO 3166 Country Code Chopstickpay 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 8
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 9
13. Appendix C Sample code to compare signature ASP sample code v_signature = trim(request( signature )) signatureserver = GetTextFromUrl( https://merchant.chopstickpay.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 if validateresult = Invalid Signature Page 10
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 --- Page 11