1. Introduction to CardPay

Transcription

1

2 1. Introduction to CardPay The introduction manual describes the technical aspects of payments processing using CardPay's hosted payment page. CardPay is an online payment processor for e-commerce transactions and provides the following functions: Payment processing Merchant account Security of payment data Fraud management and screening Customer support CardPay helps turn a web site into a well working, real-time sales channel with automated card payment processes. Integrated into your web site, catalogue, call centre or other application, it offers a secure method for managing on-line payment transactions. 1.1 What is CardPay? CardPay is a secure online payment service, enabling merchants to accept a wide range of payment cards for their goods and services, whilst benefiting from increased levels of efficiency in their order handling process and improved cash flow. CardPay removes the need for re-keying card details by providing real-time card authentication and authorisation and reducing the timescales for merchant payment. A block diagram is given below, showing the relationship between CardPay, a merchant and the banking network. Page 2 of 14

3 1. The customer forms a basket of goods / services navigating through the merchant's web-site. 2. The customer fills in an online form on the merchant's web-site and sends a request to the CardPay Server. The CardPay Server processes the request. If the request contains no payment card details the CardPay payment page will be displayed for the customer where he has to fill in his payment card details as well as his billing address details. The CardPay Server validates the request and checks its integrity using fraud prevention tools. 3. If the request is ok it is forwarded to the Acquirer Bank. 4. The Acquirer Bank makes the authorise request to the Card Issuer Bank. 5. The Card Issuer Bank makes a response for the Acquirer Bank. 6. The Acquirer Bank processes the response and sends the results to the CardPay Server. 7. The CardPay Server redirects customer's web-browser to the merchant's web-site. 8. Merchant shows the payment results to the customer. 1.2 Advantages of Cardpay Makes profit and produces growth of capital at a maximum implementable rate, takes into account market risks and formidable challenges concerning the international credit card payments processing Accepts and observes high standards of trading honour and principles of equity for the purpose of its business Enforces the legislative requirements fixed by Financial Services Authorities and other appropriate regulating authorities Cardpay's reliability and integrity, remarkable service just as well as the professional service provided to its client base, make CardPay Inc. a leading payment service provider. 24-hours support Advance technology solutions Competitive price Regulated by FSA of Mauritius User friendly client interface As well as the client-side software CardPay provides a secure merchant services website which allows the merchant to carry out customer service functions such as enquires on transactions. Access is granted once merchants are registered with the CardPay service. 1.3 Payment Manager Cardpay Payment Manager gives ability to monitor the transactions and perform other merchant operations. In order to get the access please contact your Cardpay manager and provide for the account registration and cell phone number or Skype account. Registration contains the archive Page 3 of 14

4 with the password for the Payment Manager. In order to open the archive separate password must be used, which will be provided as SMS or by Skype separately. Each 3 months new password is creating and sending to the merchant using the same way ( with the archive and password by SMS or Skype). 2. Integrating CardPay with your system When your customer is ready to pay for the goods or services, your site should present a "Pay Now" button that, when clicked, sends a complete purchase request to the CardPay payment network. The purchase request is sent as a HTML FORM containing a description of the goods/services purchased, total cost, and details of your merchant account. To construct a valid request you have to pass 4 simple steps. Step 1 - Creating order XML message Our team prefers working with an XML text message format. That's why you'll have to form a typical xml message as soon as you want to integrate CardPay with your system. But don't worry, it's quite easy if you read carefully this manual. First of all, you have to collect all the required values that are listed in the table below. Please pay attention to the red attributes. They are mandatory whereas others may be omitted. As well as red tags. If the tag in the table is black and the attribute is red, it means that the tag is not required, but if it is used - the red attributes have to be sent also. # TAG ATTRIBUTE DESCRIPTION POSSIBLE VALUES EXAMPLE 1 ORDER WALLET_ID Unique merchant's shop ID in CardPay payment system Any numeric 21 Page 4 of 14

5 2 ORDER_NUMBER 3 NAME Unique order id in merchant shop engine Name of service / product, provided for the customer Any 17 Any T-Shirt 4 DESCRIPTION 5 AMOUNT Description of service / product, provided to the customer Order total amount in your account currency Any Any positive numeric below Best ever T-Shirt 6 Customer Any valid customer@example.com 7 IS_TWO_PHASE Hold only transaction? (No if omitted) 8 CURRENCY ISO3 currency code 9 IS_GATEWAY 10 LOCALE Is Gateway behaviour required? Preferred locale of payment page. Default applied if received is not supported. Default locale EN yes/no true/false 1/0 Any valid ISO3 currency code yes (no) true (false) 1 (0) ISO language code yes USD, GBP etc. 1 ru 11 RECURRING PRICE Price of a prolongation of the membership access service Any positive below USD PERIOD Period in days of prolongation of the membership access service. Any positive number BEGIN The date when you want the transaction to be repeated at first time. dd.mm.yyyy d.m.yyyy d.m.yy dd/mm/yyyy d/m/yyyy d/m/yy COUNT Quantity of repeated transactions in every given REC_PERIOD. Any positive number ORDER_ITEM NAME Name of service / product, provided to the customer Any Video S 16 DESCRIPTION Description of service / product, provided to the customer Any Sport Video Subscribtion 17 COUNT Service / product quantity Any 1 18 PRICE 19 ADDRESS COUNTRY Price of each service / product Delivery country (ISO3 code) Any latin letter code USA 20 STATE Delivery State / Province Any NY Page 5 of 14

6 21 CITY Delivery city Any New York 22 ZIP Delivery post code Alphanumeric sequence STREET Delivery street address Any 450 W. 33 Street 24 PHONE Customer phone number Any valid phone +1 (212) CARD NUM Customer's card number (PAN) Any valid card number HOLDER Customer's cardholder name Any valid cardholder name John Silver 27 CVV Customer's CVV2 / CVC2 3 / 4 positive digits EXPIRES Customer's card expiration date mm.yyyy m/yy m/yyyy mm/yyyy m.yy m.yyyy Basic Order XML The minimal order XML string normally looks like this one: <ORDER WALLET_ID="21" ORDER_NUMBER="458210" AMOUNT="291.86" ="customer@example.com"/> The order xml is not case sensitive. So the next example is equivalent to previous one. <order wallet_id="21" order_number="458210" amount="291.86" ="customer@example.com"/> You don't have to worry about attribute value length: if it is too long it will be cut automatically. You also can use either double or single quotes, but all the quotes have to be the same. The example below is equal to both previous ones. <ORDER WALLET_ID='21' ORDER_NUMBER='458210' AMOUNT='291.86' ='customer@example.com'/> Usually the order XML includes two more attributes NAME and DESCRIPTION. ="customer@example.com"/> If you want a transaction to be HOLD ONLY (to use two phases of payment) you have to use one more ORDER attribute. This is the IS_TWO_PHASE attribute. A HOLD ONLY transaction type lets you manually choose the transactions (using CardPay Admin Web Interface) to be processed. Kindly contact CardPay customer support service for details. ="customer@example.com" IS_TWO_PHASE="true"/> Page 6 of 14

7 Multiple currencies If you have multiple currencies support agreement with Cardpay Inc. you can switch between accounts using CURRENCY attribute (ISO3 currency code). <ORDER WALLET_ID="21" ORDER_NUMBER="458210" AMOUNT="291.86" CURRENCY="GBP"/> Recurring Billing There is also an ability to repeat the transaction every chosen period (to make it RECURRING). It can be useful when you want to subscribe a customer to any service (e.g. sending them fashion magazine every month). It that case you have no need to send the same order XML every month, just add one more tag RECURIING with an attribute PERIOD (period in days of prolongation of the membership access service). Recurring will be charged when possible after corresponding period of time until cancelled by customer. ="customer@example.com"> <RECURRING PERIOD="30"/> </ORDER> To make your recurring billing more flexible we've added some more attributes. These are PRICE (if the price differs from the ORDER AMOUNT value) COUNT (to specify the quantity of required transaction repetitions) and BEGIN (if you need to specify the date when recuring begins). If you did't specify the values for these attributes the system will use defaults. The default values are: for PRICE is ORDER AMOUNT value, for COUNT - untill customer stopped, for BEGIN - current date. ="customer@example.com"> <RECURRING PERIOD="10" BEGIN=" " COUNT="5"/> </ORDER> Order Items This order XML is good when a customer makes a service or a single product purchase. But when you need to describe the situation with multy-purchasing action you may use ORDER_ITEM tag (see the table above). <ORDER WALLET_ID="21" ORDER_NUMBER="458210" AMOUNT="270" ="customer@example.com"> <ORDER_ITEM NAME="T-Shirt-A" COUNT="2" PRICE="100" DESCRIPTION="Best ever seen T-Shirt" /> <ORDER_ITEM NAME="T-Shirt-B" COUNT="1" PRICE="70" DESCRIPTION="Yet another best ever seen T-Shirt" /> </ORDER> You can also combine ORDER_ITEM information with ORDER NAME and ORDER DESCRIPTION fields. <ORDER WALLET_ID="21" ORDER_NUMBER="458210" NAME="T-Shirts" DESCRIPTION="Best ever seen T-Shirts" AMOUNT="270" ="customer@example.com"> <ORDER_ITEM NAME="T-Shirt-A" COUNT="2" PRICE="100" DESCRIPTION="Best ever seen T-Shirt" /> <ORDER_ITEM NAME="T-Shirt-B" COUNT="1" PRICE="70" DESCRIPTION="Yet another best ever seen T-Shirt" /> </ORDER> Page 7 of 14

8 Shipping Address You can specify customer shipping address as well. Any of the address attribute fields can be omitted. <ORDER WALLET_ID="21" ORDER_NUMBER="458210" NAME="T-Shirts" DESCRIPTION="Best ever seen T-Shirts" AMOUNT="270" <ORDER_ITEM NAME="T-Shirt-A" COUNT="2" PRICE="100" DESCRIPTION="Best ever seen T-Shirt" /> <ORDER_ITEM NAME="T-Shirt-B" COUNT="1" PRICE="70" DESCRIPTION="Yet another best ever seen T-Shirt" /> <ADDRESS COUNTRY="USA" STATE="NY" ZIP="10001" CITY="New York" STREET="450 W. 33 Street" PHONE="+1 (212) "/> </ORDER> Importance of Details Though you can make a simple order XML without any descriptions or details (as in our first examle) we recommend that you provide us with as much details as you can, because details may be useful when resolving any payment problems. Besides such information will help you recognize the transactions in the Merchant Admin Web Interface, provided to you by the CardPay system. Payment Card Details, Gateway Behaviour Normally you have no need to provide us with any additional information. But if you already have a payment card data form integrated on your shop page, you can also send us customer payment card details. In this case the customer won't have to fill in their Billing Address information in our form as well as their payment card details. That makes a transaction faster and more user friedly. This is often called a Gateway behaviour. Please be informed that you should apply for this service directly (for further details contact our sales team). To use this ability one more root attribute should be included in your orderxml. This is the IS_GATEWAY attribute. Please pay attention that once you are using gateway behaviour you have to specify the type of address for every address you include in the order xml (shipping/billing). In this case the billing address is required while the shipping is optional. <ORDER WALLET_ID="21" ORDER_NUMBER="458210" NAME="T-Shirts" DESCRIPTION="Best ever seen T-Shirts" AMOUNT="270" ="customer@example.com" IS_GATEWAY="true"> <ORDER_ITEM NAME="T-Shirt-A" COUNT="2" PRICE="100" DESCRIPTION="Best ever seen T-Shirt" /> <ORDER_ITEM NAME="T-Shirt-B" COUNT="1" PRICE="70" DESCRIPTION="Yet another best ever seen T-Shirt" /> <ADDRESS COUNTRY="USA" STATE="NY" ZIP="10001" CITY="New York" STREET="450 W. 33 Street" PHONE="+1 (212) " TYPE="BILLING"/> <CARD NUM=" " HOLDER="John Silver" CVV="789" EXPIRES=" "/> </ORDER> You also may want to omit all address data for your transaction, in that case you should contact the CardPay integration manager to enable this feature. Page 8 of 14

9 Payment Page Example Below you can find an example of the standard CardPay payment page. Step 2 - Creating SHA512 Digest Before posting a request to our server the customer can easily change the final order XML. To prevent price modifications (or other tricks) after the order XML is ready you have to make a SHA512 digest of the order XML plus your personal merchant secret word (secret key). That is why you'll be provided with a secret word after successful registration with CardPay payment system. The secret word can be easily changed using the Merchant Admin Web Interface. Ok. Let's consider you have made the folowing order XML: ="customer@example.com"/> Page 9 of 14

10 And your merchant secret word is: se1cr2et3w0r4d Now you have to make SHA512 digest (using your shop engine) from the string below. And this is the digest for the string above: dca de77af3c88cfb9a1586c49f13781e5c fab2139fc08a df335eade36f2e4388efe2ab1867b60b702854b94b42680f9010d3be1e Php examle: $order = "<ORDER WALLET_ID=\"21\" ORDER_NUMBER=\"458210\" "+ "NAME=\"T-Shirt-A\" DESCRIPTION=\"Best ever seen T-Shirt\" "+ " AMOUNT=\"291.86\" =\"customer@example.com\"/>"; $secret_key = "your_secret_here"; $sha512 = hash('sha512', $order. $secret_key); To get SHA512 signature you can use any SHA512 method implementation: Java examle: String order = "<ORDER WALLET_ID=\"21\" ORDER_NUMBER=\"458210\" NAME=\"T-Shirt-A\" DESCRIPTION=\"Best ever seen T-Shirt\" AMOUNT=\"291.86\" =\"customer@example.com\"/>"; String secretkey = "your_secret_here"; MessageDigest digest = java.security.messagedigest.getinstance("sha512" ); String message = order + secretkey digest.update(message.getbytes()); String sha512 = new BigInteger(1, digest.digest()).tostring(16); Step 3 - Creating BASE64 Coded Message Ok. Now we have an order XML message and its' SHA512 digest. Our order XML message contains tags and quotes. If we try to print them into a form input field without any screening method the page's HTML structure may be damaged. The problem can be easily solved by simple BASE64 order XML encoding. Order XML before BASE64 encoding: ="customer@example.com"/> Order XML after BASE64 encoding: PE9SREVSIFdBTExFVF9JRD0iMjEiIE9SREVSX05VTUJFUj0iNDU4MjEwIiBOQU1FPSJULVNoaXJ0 LUEiIERFU0NSSVBUSU9OPSJCZXN0IGV2ZXIgc2VlbiBULVNoaXJ0IiBBTU9VTlQ9IjI5MS44NiIg RU1BSUw9ImN1c3RvbWVyQGV4YW1wbGUuY29tIi8+Cg== Php examle: $order = " ="customer@example.com"/>"; $orderxml = base64_encode($order); Java examle: You can use any BASE64 impl library. String order = "<ORDER WALLET_ID="21" ORDER_NUMBER="458210" NAME="T-Shirt-A" DESCRIPTION="Best ever seen T-Shirt" AMOUNT="291.86" ="customer@example.com"/>"; Page 10 of 14

11 String orderxml = BASE64.encodeString(order); Step 4 - Printing The Form Now all of our components are ready. It is the time to print the form using single button by which the customer sends all the required parameters to CardPay payment server. You are to send: orderxml parameter (with BASE64 coded order XML message) SHA512 parameter (with order XML plus Merchant Secret Word SHA512 digest) It is important to note that both parameters names are case sensitive and have to be printed only in the way they are given above. Use the following url for your integration and testing purposes: <HTML> <BODY> <FORM ACTION=" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="orderXML" VALUE=" PE9SREVSIFdBTExFVF9JRD0iMjEiIE9SREVSX05VTUJFUj0iNDU4MjEwIiBOQU1FPSJULVNoaXJ0 LUEiIERFU0NSSVBUSU9OPSJCZXN0IGV2ZXIgc2VlbiBULVNoaXJ0IiBBTU9VTlQ9IjI5MS44NiIg RU1BSUw9ImN1c3RvbWVyQGV4YW1wbGUuY29tIi8+Cg=="/> <INPUT TYPE="HIDDEN" NAME="sha512" VALUE=" 6eb110152cf663d7b521d f3f6c3bd5de46bd061d19d f d d f7626cceed2a9f1620bc2747a3b3c03ab9e0d1321e5f78a635c1 840f348e"/> <INPUT TYPE="SUBMIT" VALUE="PAY BY CARDPAY"/> </FORM> </BODY> </HTML> You can also use CardPay logo instead of a regular submit button. <HTML> <BODY> <FORM ACTION=" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="orderXML" VALUE=" PE9SREVSIFdBTExFVF9JRD0iMjEiIE9SREVSX05VTUJFUj0iNDU4MjEwIiBOQU1FPSJULVNoaXJ0 LUEiIERFU0NSSVBUSU9OPSJCZXN0IGV2ZXIgc2VlbiBULVNoaXJ0IiBBTU9VTlQ9IjI5MS44NiIg RU1BSUw9ImN1c3RvbWVyQGV4YW1wbGUuY29tIi8+Cg=="/> <INPUT TYPE="HIDDEN" NAME="sha512" VALUE=" 6eb110152cf663d7b521d f3f6c3bd5de46bd061d19d f d d f7626cceed2a9f1620bc2747a3b3c03ab9e0d1321e5f78a635c1"/> <INPUT TYPE="IMAGE" WIDTH="170" HEIGHT="30" SRC=" ALT="Pay Now With CardPay!"/> </FORM> </BODY> </HTML> Page 11 of 14

12 Redirect pages Based on the transaction status you may want to specify different URLs for redirecting user. There is three types of URL for redirecting user: SUCCESS PAGE - User will be redirected to this URL in case of successful transaction. ERROR PAGE - User will be redirected to this URL in case if transaction finished with error ( insufficient funds on users bank account ) CANCEL PAGE - User will be redirected to this URL if he will press cancellation button of CardPay Payment Page form. In order to set-up this URLs you need to contact your CardPay integration manager. If URL was not specified for some particular case, user will be redirected on shops main page. Callback After you prepared your order XML.. e.g. ="customer@example.com"/> Printed an HTML containing required form e.g. <HTML> <BODY> <FORM ACTION=" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="orderXML" VALUE="PE9SREVSIFdBTExFVF9JRD0iMjEiI E9SREVSX05VTUJFUj0iNDU4MjEwIiBOQU1FPSJULVNoaXJ0LUEiIERFU0NSSVB USU9OPSJCZXN0IGV2ZXIgc2VlbiBULVNoaXJ0IiBBTU9VTlQ9IjI5MS44NiINC kvnqulmpsjjdxn0b21lckblegftcgxllmnvbsivpg=="/> <INPUT TYPE="HIDDEN" NAME="sha512" VALUE="65ddb6b840bbfeb749178ab96424a06a9 de79fdcb3aebe0eb0acfcbd7cbd57167dd61435a91038de9bc ff44f30fc44aba32 840f348e"/> <INPUT TYPE="IMAGE" WIDTH="170" HEIGHT="30" SRC=" ALT="Pay Now With CardPay!"/> </FORM> </BODY> </HTML> The customer submitted the form. CardPay processes the request and sends the callback parameters to the callback page specified by merchant. The page is called with two parameters: orderxml parameter (with BASE64 coded order XML callback message) sha512 parameter (with order XML callback message plus Merchant Secret Word sha512 digest) Page 12 of 14

13 Now consider you have received a callback containing these parameters. Parameter name orderxml Parameter value PE9SREVSIElEPSIxMTExMTgiIE5VTUJFUj0iMjUiIFN UQVRVUz0iQVBQUk9WRUQiIERFU0NSSVBUSU9OPSJDT05GSVJNRUQiCkRBVEU9IjI1LTAyLTIwMTM gmdk6nti6mjeiienbukrftlvnpsiuli43mta3iibdqvjex0hpterful9oqu1fpsjkb2huifnpbhz lciikq0fsrf9uwvbfpsj2axnhiibcsuxmsu5hx1pjud0imtawmdeiiejjtexjtkdfu1rsruvupsi 0NTAgdy4gMzMgc3RyZWV0IiBCSUxMSU5HX1NUQVRFPSJueSIKQklMTElOR19DSVRZPSJuZXcgeW9 yayigqklmtelor19dt1vovfjzpsjvuyiglz4k sha512 7be66e638cd66f936c ce4b6f483cb549d716 5c48a0ace80789b9ec6bc7e71dab9d190720f28c009 a0ca519f1c05fc882dca746e607386a738c8cb64b7 To process the callback you have to: 1. Decode the orderxml parameter value using BASE64 decoding algorithm. The result of decoding typically looks like the below. <ORDER ID="111118" NUMBER="25" STATUS="APPROVED" DESCRIPTION="CONFIRMED" DATE=" :52:21"/> 2. Get your personal Merchant Secret Word. You can find your Merchant Secret Word using the CardPay Merchant Web-Interface and store it to a secure place for instant access (database, protected file etc). merhcant secret word se1cr2et3w0r4d 3. Get the SHA512 digest from the string that contains decoded order XML parameter value plus your Merchant Secret Word. combined string sha512 <ORDER ID="111118" NUMBER="25" STATUS="APPROVED" DESCRIPTION="CONFIRMED" DATE=" :52:21"/>se1cr2et3w0r4d 3e fdc73a fd87a8db8c74f40285c8c6b8b93cd911c61817bfcec675a1014e2f7a30ed6dc9b902e9 ea2a30c2f11f35ea81f3a a24e51 4. Compare SHA512 digest that you have just made and the received the SHA512 parameter value. They must be identical. If they are not - you have likely received the parameters from unauthorized source or you did something wrong. 5. Parse the callback order xml. The order xml callback incloses a list of attributes for your usage. These are: ID - CardPay's system order unique identificator NUMBER - Merchant's system order unique identificator STATUS - Order status DESCRIPTION - Order status description (if any) DATE - Date of purchase Take a note: if your callback page supports HTTPS protocol you can omit steps 2-4. In order to set-up callback URL you need to contact your CardPay integration manager. If callback URL is not specified parameters will be sent to success page. Page 13 of 14

14 Gateway behaviour callback If you use the gateway behaviour mode you will receive an orderxml the same as described above. The main difference is that it will be sent as plain text in the body of the response to your request. Another difference is that SHA512 digest is not sent either. <ORDER ID="111118" NUMBER="25" STATUS="APPROVED" DESCRIPTION="CONFIRMED" DATE=" :52:21"/> The following table provides a list of options for server responses for STATUS property values: APPROVED transaction succeeded, amount was captured DECLINED transaction denied PENDING transaction needs time to be verified, amount was held Page 14 of 14