API For Chopstickpay Merchants Configuration: Server-to-server Version: 3.4 Status: Published

Transcription

1 API For Chopstickpay Merchants Configuration: Server-to-server Version: 3.4 Status: Published Contents 1. Version Control Introduction Prerequisites Payment Submission Workflow Return Parameter for CallbackURL Check Payment Status by CartID Check transaction status in Merchant Site Request for refunds Merchant Notify Setup Frequently Asked Questions Appendix A - Country Codes Appendix B - Currency Codes Appendix C - Sample code to compare signature Appendix D - Payment Status Code 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 letter country code only. Full country name is removed for standardization. Page 1

2 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 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 Page 2

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 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 V_SSN Last 4 digits of buyer s Social Security Number (for United States buyers only) Required Alphanumeric. 4 characters v_bill 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 v_shipcountry Country name Optional Refer to Appendix A. MY (ISO 1366 Standard Country Code) v_shipphone Phone number Optional Alphanumeric. 18 characters 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 v_billcountry Country name Required Refer to Appendix A. MY (ISO 1366 Standard Country Code) v_billphone Phone number Required Alphanumeric. 18 characters 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 JKWN823 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

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 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 , Parameter Description Requirement Specification Example callbackurl transaction result will send to this URL Required Alphanumeric. 255 characters. 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. m/samples/returnurl.asp v_ip The buyer s IP address Required Alphanumeric. 50 characters Page 4

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 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 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. 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 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 Example return result : mid=m104-c-277&oid=m104-po-4890&cur=&amt=1&status=cancelled&cartid= &createddatetime= :36:13 Noted that if duplicated cartid payment, it will display mutliple row of result. 7. Check transaction status in Merchant Site Login at 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 ( 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

7 9. Merchant Notify Setup This notify settings is for every time any transaction from your customer end, it will send another copy of transaction receipt to your . Way to setup: 1. Login to Merchant Site ( 2. Open Merchant Notify Settings 3. Enter the 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

8 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 : Page 8

9 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

10 13. Appendix C Sample code to compare signature ASP sample code v_signature = trim(request( signature )) signatureserver = GetTextFromUrl( & 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

11 14. Appendix D Payment Status Code Code Status Description 0 Payment Declined 2 Card IP -BLACK LIST 3 Transaction amount limit 5 IP Duplicate 6 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