Web Payments. Integration Guide Version /04/2016

Transcription

1 Web Payments Integration Guide Version /04/2016 Table of Contents Introduction... 2 Getting Started... 2 Checking that Web Payments is enabled for your account... 2 How Web Payments works... 3 Integration Models... 3 Return Option, Integration Secret Hash Key and Customer Experience... 3 Customer Experience A - Return Option set to Display in Web Payments. 4 Customer Experience B - Return Option set to Post to Return URL... 4 Setup Integration Secret Hash Key in Merchant Console... 5 Merchant Notification Service (MNS)... 6 Web Payments Standard... 7 Input Variables... 7 Merchant Website Example (HTML example) Output Variables to Return_URL Only in Customer Experience B Web Payments Shopping Cart Input Variables Merchant Website Example (HTML example) Output Variables to Return_URL Only in Customer Experience B Web Payments Store Card Merchant Website Example (HTML example) Output Variables to Return_URL Only in Customer Experience B Merchant Notification Service (MNS) Implementing MNS MNS Handler Web Payments Standard and Shopping Cart Web Payments Store Card MNS Data Available Web Payments Standard Page 1 of 47

2 Web Payments Shopping Cart Web Payments Store Card Flo2Cash Action Response Merchant Console MNS Retry D Secure Customising the Flo2Cash Interface Overview Changes Available Appendix A: Flo2Cash Web Payments Error Codes Appendix B: CSS Templates, Samples, and Screenshots Appendix C: Merchant Verifier Examples Calculating the merchant_verifier input parameter value for Standard Payments Calculating the merchant_verifier input parameter value for Shopping Cart Payments Calculating the payment_provider_verifier output parameter value for Standard/Shopping Cart Payments Introduction Getting Started The Flo2Cash Web Payments is designed to take web-based card payments by integration with your website or ecommerce platform. The integration is based on standard HTTP POST model and supports a few integration variations, each designed for a specific purpose. Before you use any of the Flo2Cash Web Payments services, please check that you have subscribed to this payment channel. Checking that Web Payments is enabled for your account Before using any Web Payments service, you first need to make sure that Web Payments is enabled for your account. To do this, log in to the Flo2Cash Merchant Console available at using the Username and Password that you received from Flo2Cash when creating your account. Once you have successfully logged in to the Merchant Console, navigate to the Channel Settings section via the menu available on the left hand side of the screen. The Channel Settings page shows the Flo2Cash channels you currently subscribe and if they are configurable provides a link to the configuration page. You need to ensure the Web Payments channel is active before proceeding with any integration. Page 2 of 47

3 How Web Payments works Integration Models Flo2Cash Web Payments supports three different types of integration models. You can select the one that best suits your integration requirements. Web Payments Standard Payment - Simple ecommerce web payments with the payment page only displaying minimal payment information such as transaction amount and reference Web Payments Shopping Cart - ecommerce web payments with the payment page displaying additional payment information such as a table showing the shopping cart content and the option to collect and pass on customer details Web Payments Store Card - Designed for ecommerce transaction whose sole purpose is to validate the card details and convert the card into a Card Token. No amount will be deducted from the cardholder s card. This is ideal for websites or services that wish to collect the card details for recurring billing purposes in a secure manner. o Before using this integration method, please make sure you have subscribed to Card Token Management Return Option, Integration Secret Hash Key and Customer Experience Flo2Cash Web Payments supports two types of return option that determine what happen after a transaction is completed: Display in Web Payments: this is the default option selected. If this is selected, the transaction results are displayed on Flo2Cash Web Payments and customers will be presented with a Return to merchant button to go back to the merchant s website. Merchants are required to implement MNS to retrieve the transaction results. Post to Return URL: if this is selected, the transaction results along with a set of other parameters will be posted back to the merchant s return URL. The customer will be redirected at the same time back to the return URL. When data is posted back to the merchant s return URL, if there was a verifier present in the input parameter then there will be a output verifier returned as well. To get the verifier working you need to set-up a integration secret hash key in the merchant console. Merchants are recommended to implement MNS to retrieve and validate the transaction results and not rely on the return post variables received in the return URL for security and reliability reasons. Page 3 of 47

4 Customer Experience A - Return Option set to Display in Web Payments Step 1: Customer is on your website ready to make a purchase and is redirected to the Flo2Cash Web Payments where the customer will be prompted enter their card details. Step 2: Customer enters their card details on Flo2Cash Web Payments securely and processes the transaction. If the card information is valid, the payment will be processed. Step 3: The results of the transaction will be displayed on Flo2Cash Web Payments with a Return to Merchant button provided to return to your website. Step 4: If the customer clicks on the Return to Merchant button, the customer will be taken back to the return_url. Customer Experience B - Return Option set to Post to Return URL Step 2: Customer enters their card details on Flo2Cash Web Payments securely and processes the transaction. If the card information is valid, the payment will be processed. Page 4 of 47

5 Step 3: The transaction results will be posted immediately to the page indicated by the value of the return_url field. At the same time the customer will be redirected back to the return url. NOTE: if you choose to use this model, your return_url must have a valid SSL certificate to avoid the customer browsers prompting any security warning messages. Setup Integration Secret Hash Key in Merchant Console The secret key is a value known only to you and Flo2Cash. The secret hash key is combined with the data you send from your website to create a message verification value; this value allows Flo2Cash to verify that the data provided has not been tampered with and also that it is you sending the request. The same process is used when providing data back to your website after the payment has processed. To set-up the integration secret hash key you need to login in your Merchant Console and go to the web payments channel settings. Choose Integration Settings from the Quick Menu. If you have not previously generated a secret hash key it will be generated at this point. You can change the secret hash key at any stage by clicking on the Change button. Important: Changing the secret hash key can cause unforeseen issues if you have integrations currently working. Before changing this value please ensure that you have no current working integrations. For any questions around this please contact Flo2Cash. Page 5 of 47

6 Merchant Notification Service (MNS) The Merchant Notification Service (MNS) provides details of a processed transaction so that merchants can update their own systems accordingly. It utilises a handshake verification procedure to avoid the spoofing aspect that could occur if using the fields posted back to the return_url. Below is the MNS data flow with the assumption that the return option is set to display results in Flo2Cash Web Payments. The order of events is as follows: 1. After a transaction is processed, Flo2Cash sends transaction data to the notification URL. 2. The merchant s website is required to send the received data back to Flo2Cash MNS handler (see section 6.2 for MNS handler end points). At this point, you should store the transaction data in your online shop, but marking the transaction as pending verification. Page 6 of 47

7 3. Flo2Cash sends VERIFIED / REJECTED response to merchant notification URL depending on the verification status of the transaction (see section 6.4 for Flo2Cash Action Response). 4. Merchant website handles the payment verification response from Flo2Cash appropriately. Once a VERIFIED message is received, you should then mark your previously stored transaction as Verified and action the next step in your website logic, following a payment having been accepted successfully, for example, triggering the shipping process or activating the service requested. Please note these are the important steps that ensure nobody attempts to spoof the post at step 1. MNS is highly recommended as a way of verifying transaction results versus relying on data received at your return URL. For implementation details of MNS, please refer to Section 6. Web Payments Standard Input Variables Flo2Cash Web Payments validates all the data posted to it, and in the case of an invalid field, the browser (Customer) is redirected to the Return URL along with a HTTP POST containing an appropriate error message, found in the response_text field. The following table shows the input fields that can be posted to Flo2Cash Web Payments. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional. Name Description Required Type Length cmd Defines the Web Payments integration service. Always use _xclick for Web Payments Standard Payment. Required N/A account_id Flo2Cash issued Account ID Required Integer N/A amount The transaction amount in NZ dollars. Must be a positive value. Required Decimal N/A item_name Description of item, not stored by Flo2Cash. Required 50 reference particular return_url Merchant defined value stored with the transaction. Merchant defined value stored with the transaction. The URL that the customer will be sent to on completion of the payment. Optional 50 Optional 50 Required 1024 notification_url This must be a publicly accessible URL. If provided, this URL will be used in conjunction with Flo2Cashs Merchant Notification Service (MNS). (See MNS for details) This must be a publicly accessible URL. Optional 1024 Page 7 of 47

8 header_image header_bottom_border header_background_col our custom_data The URL to an image. Sets the image at the top of the payment page. The image can be of any height but must be a maximum of 600px wide and must be URLencoded. The URL must end with one of the following image extensions.jpg,.jpeg,.png,.bmp,.gif. Flo2Cash recommends that you provide an image that is stored only on a secure (HTTPS) server. (See Customising the Flo2Cash Interface). Sets the colour of the border underneath the header on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6-character hexadecimal value for the colour required. Sets the background colour of the header section on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6-character hexadecimal value for the colour required. Merchant defined value that you can use to identify your transaction. Any value passed in will be posted Optional 1024 Optional 6 Optional 6 Optional 1024 store_card display_customer_ back to the notification_url (See MNS). This is a pass-through field that is never presented to your customer. Flo2Cash will not store this value. 0 or 1 as to whether Web Payments should display the option for storing the card details upon a successful payment. 0 = do not show (default) 1 = show 0 or 1 as to whether Web Payments should display customer receipt field. 1=display (default) 0 = hide Optional Integer N/A optional Integer N/A Page 8 of 47

9 payment_method This parameter is optional. If not set and the merchant is configured to accept more than one card payment types, the customer will be presented with a payment method selection page before completing the card payment. For example, if the merchant accepts Visa, MasterCard and UnionPay, the customers will be presented with a payment method selection page presenting the two options of either paying with Visa/MasterCard or UnionPay card. optional 50 Merchants can, however, pre-select the preferred payment method using this parameter. The following strings are supported values (both in lower case): - standard - unionpay - masterpass If the value standard is passed, the customer will be directed to the standard Visa/MasterCard entry page, skipping the payment method selection page. If the value masterpass is passed, the customer will be directed to the masterpass wallet processing flow, skipping the payment method selection page. Similarly, if the value unionpay is passed, the customer will be directed to the UnionPay card transaction processing flow, skipping the payment method selection page. merchant_verifier This is a SHA1 hash of the data that you are passing plus your secret hash key (explained above). Please see the appendix (Flo2Cash Calculating the merchant_verifier input parameter value for Standard Payments) for sample code on how to calculate this field. Required N/A Page 9 of 47

10 Merchant Website Example (HTML example) <form action=" method="post"> <input type="hidden" name="cmd" value="_xclick"/> <input type="hidden" name="account_id" value="10000"/> <input type="hidden" name="return_url" value=" <input type="hidden" name="notification_url" value=" <input type="hidden" name="header_image" value=" <input type="hidden" name="header_bottom_border" value="22ffdd"/> <input type="hidden" name="header_background_colour" value="22ffdd"/> <input type="hidden" name="store_card" value="0"/> <input type="hidden" name="display_customer_ " value="0"/> <input type="hidden" name="merchant_verifier" value="jhgvjhvgkjh+dfhg^dgvd"/> amount <input type="text" name="amount" value="10.00"/> Item name <input type="text" name="item_name" value="optical mouse"/> reference <input type="text" name="reference" value="iv "/> particular <input type="text" name="particular" value="item No 123"/> <input type="submit" value="submit" /> </form> The input type can be anything you like (e.g. textfields, drop-down box, hidden fields, etc) as long as you post the correct field names to the server. If the posted fields are successfully validated, the customer is presented with a secure page where they can enter their credit card details and complete the transaction. Output Variables to Return_URL Only in Customer Experience B *NB: Please note that the output variables only apply if the Return Option is set to Post to Return URL The following table shows the output fields to be posted back to the Return URL, along with a brief description of each. Name Description Type txn_id Flo2Cash defined unique transaction ID. receipt_no Flo2Cash unique transaction receipt number. Integer txn_status 0 = Unknown Transaction result cannot be confirmed i.e. lost connection with the payment switch 1 = Processing An old status left in for legacy integrations (Ignore) 2 = Successful Transaction processed successfully and monies were taken from the card 3 = Failed Transaction has failed to process 4 = Blocked Transaction was blocked from taking place due to merchant specific rules 11 = Declined Transaction was processed but declined Integer Page 10 of 47

11 account_id reference particular card_type response_text response_code The Flo2Cash Account ID used for processing the transaction. Reference used for the transaction - defined by the merchant Particular used for the transaction defined by the merchant The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card 6 = China Union Pay If an error occurred, then the error message will be stored here The response code is a legacy field and is now superseded by the txn_status field as above. The values for the response_code are: 0 = Successful 1 = Failed Integer Integer amount Total amount of the transaction. Decimal authorisation_code error_code error_message custom_data card_token payment_provider_verifier Authorisation code returned by the bank for this transaction The error code indicating the type of error that occurred. See Appendix for a full listing of Error Codes The error message explaining what the error means. See Appendix for a full listing of Error Codes Value of the custom_data input variable that you passed to identify your transaction. The token of the newly stored card, only available if the store_card variable was set to 1 and the customer chose to store their card details This is a SHA1 hash of the data that we pass back to you plus your secret hash key. Please see the appendix (Flo2Cash Calculating the payment_provider_verifier output parameter value for Standard/Shopping Cart Payments) for sample code on how to calculate this field. Web Payments Shopping Cart Input Variables Flo2Cash Web Payments validates all the data posted to it, and in the case of an invalid field, the browser (Customer) is redirected to your Return URL along with a HTTP POST containing an appropriate error message, found in the response_text field. The following table shows the input fields that can be posted to Web Payments Shopping Cart. A brief description of each field is provided, as well as the accepted data format and whether it is required or optional. Page 11 of 47

12 Name Description Required Type Length cmd Defines the Web Payments integration service. Always use _xcart for Web Payments Shopping Cart. Required N/A account_id Flo2Cash issued Account ID Required Integer N/A reference particular return_url Merchant defined value stored with the transaction. Merchant defined value stored with the transaction. The URL that the customer will be sent to on completion of the payment. Optional 50 Optional 50 Required 1024 notification_url Item_nameX This must be a publicly accessible URL. If provided, this URL will be used in conjunction with Flo2Cash Merchant Notification Service (MNS). This must be a publicly accessible URL. You can post multiple items for one transaction. The item_name elements must be formatted as follows: item_name1, item_name2, item_name3, etc. (For example, item_name1, item_code1, item_price1 and item_qty1 describe the first item in your shopping cart.) Optional 1024 Required 50 Item_codeX You can post multiple item codes for one transaction. The item_code elements must be formatted as follow: item_code1, item_code2, item_code3, etc... Required 50 Item_priceX You can pass through multiple items for one transaction. Must be a positive value. The item_price elements must be formatted as follows: item_price1, item_price2, item_price3, etc... Required Decimal N/A Page 12 of 47

13 Item_qtyX You can pass through multiple items for one transaction. Required Integer N/A The item_qty elements must be formatted as follows: item_qty1, item_qty2, item_qty3, etc... header_image header_bottom_border The URL to an image. Sets the image at the top of the payment page. The image can be of any height but must be a maximum of 600px wide and must be URLencoded. The URL must end with one of the following image extensions.jpg,.jpeg,.png,.bmp,.gif. Flo2Cash recommends that you provide an image that is stored only on a secure (HTTPS) server. (See Customising the Flo2Cash Interface). Sets the colour of the border underneath the header on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6- character hexadecimal value for the colour required. header_background_colour Sets the background colour of the header section on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6- character hexadecimal value for the colour required. custom_data customer_info_required Merchant defined value that you can use to identify your transaction. Any value passed in will be posted back to the notification_url (See MNS). This is a pass-through field that is never presented to your customer. Flo2Cash will not store this value. Passing this variable (value must be 1 ) will allow you to collect customer information from the Flo2Cash Web Payments shopping cart page. The customer information will then be posted back to your notification URL (See MNS). Optional 1024 Optional 6 Optional 6 Optional 1024 Optional Integer N/A Page 13 of 47

14 store_card display_customer_ payment_method 0 or 1 as to whether Web Payments should display the option for storing the card details upon a successful payment. 0 = do not show (default) 1 = show 0 or 1 as to whether Web Payments should display customer receipt field. 1=display (default) 0 = hide This parameter is optional. If not set and the merchant is configured to accept more than one card payment types, the customer will be presented with a payment method selection page before completing the card payment. Optional Integer N/A optional Integer N/A optional 50 For example, if the merchant accepts Visa, MasterCard and UnionPay, the customers will be presented with a payment method selection page presenting the two options of either paying with Visa/MasterCard or UnionPay card. Merchants can, however, preselect the preferred payment method using this parameter. The following strings are supported values (both in lower case): - standard - unionpay - masterpass If the value standard is passed, the customer will be directed to the standard Visa/MasterCard entry page, skipping the payment method selection page. If the value masterpass is passed, the customer will be directed to the masterpass wallet processing flow, skipping the payment method selection page. Similarly, if the value unionpay is passed, the customer will be Page 14 of 47

15 directed to the UnionPay card transaction processing flow, skipping the payment method selection page. merchant_verifier This is a SHA1 hash of the data that you are passing plus your secret hash key (explained above). Please see the appendix (Flo2Cash Calculating the merchant_verifier input parameter value for Shopping Cart Payments) for sample code on how to calculate this field. Required N/A Merchant Website Example (HTML example) <form action= method= post > <input type= hidden name= cmd value= _xcart /> <input type= hidden name= account_id value= /> <input type= hidden name= return_url value= /> <input type= hidden name= notification_url value= /> <input type= hidden name= customer_info_required value= 1 /> <input type= hidden name= store_card value= 0 /> <input type="hidden" name="display_customer_ " value="0"/> <input type="hidden" name="merchant_verifier" value="jhggdfggkjh+dfhg^dgvd"/> reference Page 15 of 47

16 <input type= text name= reference value= IV /> particular: <input type= text name= particular value= Order_Par_123 /> first item name: <input type= text name= item_name1 value= Product 1 /> first item price: <input type= text name= item_price1 value= /> first item code: <input type= text name= item_code1 value= P00001 /> first item qty: <input type= text name= item_qty1 value= 10 /> second item name: <input type= text name= item_name2 value= Product 2 /> second item price: <input type= text name= item_price2 value= /> second item code: <input type= text name= item_code2 value= P00017 /> second item qty: <input type= text name= item_qty2 value= 7 /> <input type= hidden name= header_image value= /> <input type= hidden name= header_bottom_border value = 22FFDD /> <input type= hidden name= header_background_colour value= 22FFDD /> <input type= submit value= submit /> </form> The input type can be anything you like (e.g. textfields, drop-down box, hidden fields, etc.) as long as you post the correct field names to the server. If the posted variables are successfully validated, the customer is presented with a secure page where they can enter their credit card details and complete the transaction. Output Variables to Return_URL Only in Customer Experience B *NB: Please note that the output variables only apply if the Return Option is set to post back to the merchant The following table shows the output fields to be posted back to the Return URL, along with a brief description of each. Name Description Type txn_id Flo2Cash defined unique transaction ID. receipt_no Flo2Cash unique transaction receipt number. Integer txn_status 0 = Unknown Transaction result cannot be confirmed i.e. lost connection with the payment switch 1 = Processing An old status left in for legacy integrations (Ignore) 2 = Successful Transaction processed successfully and monies were taken from the card 3 = Failed Transaction has failed to process 4 = Blocked Transaction was blocked from taking place due to merchant specific rules 11 = Declined Transaction was processed but declined Integer Page 16 of 47

17 account_id Reference Particular card_type response_text response_code The Flo2Cash Account ID used for processing the transaction. Reference used for the transaction - defined by the merchant Particular used for the transaction defined by the merchant The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card If an error occurred, then the error message will be stored here The response code is a legacy field and is now superseded by the txn_status field as above. The values for the response_code are: 0 = Successful 1 = Failed Integer Integer amount Total amount of the transaction. Decimal authorisation_code error_code error_message custom_data Authorisation code returned by the bank for the transaction. The error code indicating the type of error that occurred. See Appendix for a full listing of Error Codes The error message explaining what the error means. See Appendix for a full listing of Error Codes Value of the custom_data input field that was passed to identify the transaction. The following fields will be posted back only if the customer_info_required field was set to 1 first_name Customer First Name last_name Customer Last Name Phone Customer Phone Customer Address address1 Customer address address2 Customer address City Customer City Country Customer Country card_token The token of the newly stored card, only available if the store_card variable was set to 1 and the customer chose to store their card details payment_provider_verifier This is a SHA1 hash of the data that we pass back to you plus your secret hash key. Please see the appendix sample (Flo2Cash Calculating the payment_provider_verifier output parameter value for Standard/Shopping Cart Page 17 of 47

18 Payments) for sample code on how to calculate this field. Web Payments Store Card Before using this integration method, please make sure you have subscribed to Card Token Management. This only applies to standard card types Visa, MasterCard, American Express and Diners cards. UnionPay cards cannot be tokenised due to the 3party authentication model used by UnionPay ecommerce transactions. Name Description Required Type Length cmd Defines the Web Payments integration service. Always use _xstorecc for Web Payments Store Card. Required N/A client_id Flo2Cash issued Client ID Required Integer N/A unique_reference A unique identifier you can use to match the card owner s details to the token created. return_url The URL that the customer will be sent to on completion of the payment. Required 50 Required 1024 notification_url header_image This must be a publicly accessible URL. If provided, this URL will be used in conjunction with Flo2Cashs Merchant Notification Service (MNS). (See MNS for details) This must be a publicly accessible URL. The URL to an image. Sets the image at the top of the payment page. The image can be of any height but must be a maximum of 600px wide and must be URLencoded. The URL must end with one of the following image extensions.jpg,.jpeg,.png,.bmp,.gif. Optional 1024 Optional 1024 Page 18 of 47

19 Flo2Cash recommends that you provide an image that is stored only on a secure (HTTPS) server. (See Customising the Flo2Cash Interface). header_bottom_border Sets the colour of the border underneath the header on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6-character hexadecimal value for the colour required. header_background_col our Sets the background colour of the header section on the Flo2Cash hosted payment page. (See Customising the Flo2Cash Interface). Value must be a 6- character hexadecimal value for the colour required. custom_data Merchant defined value that you can use to identify your transaction. Any value passed in will be posted back to the notification_url (See MNS). This is a passthrough field that is never presented to your customer. Flo2Cash will not store this value. Optional 6 Optional 6 Optional 1024 Merchant Website Example (HTML example) <form action= method= post > <input type= hidden name= cmd value= _xstorecc /> <input type= hidden name= client_id value= /> <input type= hidden name= return_url value= /> <input type= hidden name= notification_url value= /> <input type= hidden name= header_image value= /> <input type= hidden name= header_bottom_border value = 22FFDD /> <input type= hidden name= header_background_colour value= 22FFDD /> <input type= submit value= submit /> Page 19 of 47

20 </form> Output Variables to Return_URL Only in Customer Experience B *NB: Please note that the output variables only apply if the Return Option is set to post back to the merchant Name Description Type response_code response_message card_token The values for the response_code are: 0 = Successful 1 = Failed The error text accompanied with the response code The card token representing this card will be available here. card_number Masked card number for the stored card token card_type The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card Integer card_expiry Provided in the format of MMYY card_holder_name unique_reference custom_data error_code error_message The cardholder name collected from the secure page A unique identifier you can use to match the card owner s details to the token created Pass through variable that you can use to identify your transaction. Value that passed in will be posted back to the notification_url. These are pass-through variables that are never presented to your customer. Flo2Cash will not store this variable. The error code indicating the type of error that occurred. See Appendix for a full listing of Error Codes The error message explaining what the error means. See Appendix for a full listing of Error Codes Merchant Notification Service (MNS) Implementing MNS To implement MNS with any of the Flo2Cash Web Payments Integration Services you must first setup your own merchant notification handler. The interface to this handler must be via a publically accessible URL. The URL to your notification handler must be passed to the Flo2Cash Web Payments service as the value of the notification_url. If no notification_url is passed or the URL is invalid, MNS will not be implemented for that transaction. Your notification handler is responsible for one part in the handshake verification procedure (step 4), other than that it is entirely merchant specific. When your notification handler receives an incoming request, its first job is to post back to Flo2Cash the data that it has just received, with the exception that you must change the cmd value to _xverify-transaction. Page 20 of 47

21 Note: Please ensure that all variables posted back to Flo2Cash are URL encoded. Also, during developing and testing of MNS, to achieve full functionality Flo2Cash Web Payments service needs to communicate with your testing website so beware of using localhost addresses or URLs inside your firewall that are unreachable by Flo2Cash. MNS gets triggered after a payment is processed, if the payment page shows errors before payment is processed then MNS is not triggered. Example (C#): WebClient WClient = new WebClient(); WClient.Headers.Add("Content-Type", "application/x-www-form-urlencoded"); string PostData = ""; for (int i = 0; i < Request.Form.AllKeys.Length; i++) string key = Request.Form.AllKeys[i]; string value = Request.Form[i]; PostData += key + "=" + Server.UrlEncode(value) + "&"; PostData += "cmd" + "=" + "_xverify-transaction"; byte [] PostBytes = Encoding.ASCII.GetBytes(PostData); byte[] ResponseBytes = WClient.UploadData(FLO2CASH_MNS_URL, "POST", PostBytes); string ActionResponse = Encoding.ASCII.Get(ResponseBytes); ActionResponse now holds the returned response string from the MNS Handler. It is now up to you to handle this response and process the data appropriately. MNS Handler The MNS handler is different for each of the integration methods. Please refer to Section 2.3 for what the MNS Handler is and how it is used. Web Payments Standard and Shopping Cart For Web Payments Standard and Shopping Cart, the Flo2Cash URL to post the received data to is Web Payments Store Card For Web Payments Store Card, the Flo2Cash URL to post the received data to is MNS Data Available Web Payments Standard The data sent to your notification handler for Web Payments Standard is as follows: Name Description verifier cmd transaction_id Flo2Cash defined encrypted string used for verification The command sent to Flo2Cash. In this case, the value must be _xverify-transaction which means you are verifying a Flo2Cash Transaction. Flo2Cash returned unique transaction ID. Page 21 of 47

22 transaction_status 0 = Unknown Transaction result cannot be confirmed i.e. lost connection with the payment switch 1 = Processing An old status left in for legacy integrations (Ignore) 2 = Successful Transaction processed successfully and monies were taken from the card 3 = Failed Transaction has failed to process 4 = Blocked Transaction was blocked from taking place due to merchant specific rules 11 = Declined Transaction was processed but declined account_id reference card_type receipt_id response_text amount custom_data card_token The account ID used for processing the transaction. Reference used for the transaction - defined by the merchant The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card Flo2Cash returned unique transaction receipt number. The error text accompanied with the response code. Payment amount Pass through variable that you can use to identify your transaction. Value that passed in will be posted back to the notification_url. These are pass-through variables that are never presented to your customer. Flo2Cash will not store this variable. If the store_card option was used and the customer chose to store their card data, the token representing this card will be available here. Web Payments Shopping Cart The data sent to your notification handler for Web Payments Shopping Cart is as follows: Name verifier cmd transaction_id Description Flo2Cash defined encrypted string used for verification The command sent to Flo2Cash. In this case, the value must be _xverify-transaction which means you are verifying a Flo2Cash Transaction. Flo2Cash returned unique transaction ID. transaction_status 0 = Unknown Transaction result cannot be confirmed i.e. lost connection with the payment switch 1 = Processing An old status left in for legacy integrations (Ignore) 2 = Successful Transaction processed successfully and monies were taken from the card account_id reference 3 = Failed Transaction has failed to process 4 = Blocked Transaction was blocked from taking place due to merchant specific rules 11 = Declined Transaction was processed but declined The account ID used for processing the transaction. Reference used for the transaction - defined by the merchant Page 22 of 47

23 card_type receipt_id response_text Item Data custom_data card_token The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card Flo2Cash returned unique transaction receipt number. The error text accompanied with the response code. The data sent to Flo2Cash in step 1. (e.g. Items, amounts, codes and qty s. only apply for shopping cart) Pass through variable that you can use to identify your transaction. Value that passed in will be posted back to the notification_url. These are pass-through variables that are never presented to your customer. Flo2Cash will not store this variable. If the store_card option was used and the customer chose to store their card data, the token representing this card will be available here. Web Payments Store Card The data sent to your notification handler for Web Payments Store Card is as follows: Name Description verifier cmd response_code Flo2Cash defined encrypted string used for verification The command sent to Flo2Cash. In this case, the value must be _xstorecc_mns, which means you are verifying a Flo2Cash Transaction. The values for the response_code are: 0 = Successful 1 = Failed response_message The text accompanied with the response code card_token card_number card_type card_expiry card_holder_name unique_reference custom_data Flo2Cash Action Response If the store_card option was used and the customer chose to store their card data, the token representing this card will be available here. Masked card number for the stored card token The credit card type used for this transaction: 1 = American Express 3 = Diners Club 4 = MasterCard 5 = Visa Card Provided in the format of MMYY The cardholder name collected from the secure page A unique identifier you can use to match the card owner s details to the token created Pass through variable that you can use to identify your transaction. Value that passed in will be posted back to the notification_url. These are pass-through variables that are never presented to your customer. Flo2Cash will not store this variable. Once Flo2Cash receives the data from your notification handler we will verify that the transaction was processed by us and that the initial post came from our server. A response action will then be sent back to your notification handler: Page 23 of 47

24 Action Response VERIFIED REJECTED Description The transaction was processed and initial post WAS from Flo2Cash The transaction never occurred and initial post WAS NOT from Flo2Cash In the case of a REJECTED action response you may wish to investigate further into possible fraud. Merchant Console MNS Retry If you have implemented MNS on your Flo2Cash Web Payments integration, you will be able to see the MNS handshake status in the transaction details on Merchant Console. For MNS messages that were not verified (for reasons such as network error or Notification URL unavailable at the time), you can re-send the MNS for the selected transaction from the Merchant Console manually. 3D Secure 3D Secure is a card payment industry standard for authenticating cardholders performing Internet purchases and designed to provide greater on-line transaction security for both cardholders and merchants. It is marketed by MasterCard as MasterCard SecureCode and Visa as Verified by Visa (VbV). With 3D Secure transactions, cardholders authenticate themselves during an online transaction by entering a password, or one-time password, which is authenticated by the cardholder s Issuing Bank. It provides level of chargeback protection for participating merchants under certain conditions. If you wish to enable 3D Secure on your Web Payment, please contact Flo2Cash. Please note in order to use 3D Secure, your website and integration method must support the use of Sessions and Cookies. For some newer web browsers, this means you may not be able to host the Web Payments page in an IFrame. Customising the Flo2Cash Interface Overview Flo2Cash provides a way for you to customise the Flo2Cash Hosted Payment page that your customers see in order to make it look and feel more like your own website. You can change the logo, header background and the header border. This is all easily achieved by appending a few extra input values in the data posted to Flo2Cash Web Payments Services. (See form code examples in each Web Payments Service section above) Changes Available Name header_image Description A URL to an accessible image. Sets the image at the top of the payment page. The image can be of any height but must be a maximum of 600px wide and must be URL-encoded. The URL must end with one of the following image extensions.jpg,.jpeg,.png,.bmp,.gif. Page 24 of 47

25 Flo2Cash recommends that you provide an image that is stored only on a secure (HTTPS) server. header_bottom_border header_background_colour Allows you to set the colour of the border underneath the header on the Flo2Cash hosted payment page. Value must be a 6-character hexadecimal value for the colour required. Allows you to set the background colour of the header on the Flo2Cash hosted payment page. Value must be a 6-character hexadecimal value for the colour required. Example of what to append to your posted form: Header Image: <input type="text" name="header_image" value=" header bottom border: <input type="text" name="header_bottom_border" value ="22FFDD"/> header background colour: <input type="text" name="header_background_colour" value="22ffdd"/> On the other hand, you can also set these values in your Flo2Cash Merchant Console in the Web Payments section in Channel Settings. If this customisation is not enough to really portray your brand, Flo2Cash offers a way to use Cascading Style Sheets (CSS) to customise the hosted payment page. You can switch this option on in the Web Payments section in Channel Settings in the Merchant Console. See Appendix for some CSS samples, HTML template codes and screenshots of the template s structure. Appendix A: Flo2Cash Web Payments Error Codes The following is a list of the possible Flo2Cash Web Payments Error Codes and Error Messages, returned to your specified return URL in the case of an error. Error Code W2P001 W2P002 W2P003 W2P004 W2P005 W2P006 W2P007 W2P008 Error Message Invalid cmd field. Invalid account_id field. Invalid amount field. Invalid item_name field. Invalid reference field. Invalid particular field. Invalid return_url field. Invalid notification_url field. Page 25 of 47

26 W2P009 W2P010 W2P011 W2P012 W2P013 W2P014 W2P015 W2P016 W2P017 W2P018 W2P019 W2P020 W2P021 W2P022 W2P023 W2P024 W2P025 W2P026 W2P027 W2P028 W2P029 W2P030 W2P031 Invalid update_url field Invalid header_image field. Invalid header_bottom_border field. Invalid header_background_colour field. Invalid page_background_colour field. Invalid shopping cart items field. Invalid shopping cart item_price field or item_qty field. Invalid shopping cart item_name field. Invalid shopping cart item_code field. Invalid session_id field. Invalid checkout_id field. Invalid customer_ field. Invalid card_type field. Your IP address is not in our acceptable range. An error has occurred while processing your payment. The payment server is not available right now. Please try again later. 3 party mode 2 is not enabled for your account. Transaction is blocked. Flo2Cash Web Payments is not enabled for your account. Payment gateway setup is not correct, please contact Flo2cash. Client account setup is not correct, please contact Flo2cash. Invalid custom_data field. First payment date must be in the format of dd/mm/yyyy, and must be in the future W2P032 Frequency mode must be an integer that is greater than 0 and less than 13 W2P033 W2P034 W2P035 W2P036 W2P038 W2P039 W2P040 (Monthly specific week) requires both number of week and day of week to be provided (Monthly specific week) Start day does not match the Day of Week (Monthly specific week) Start day does not match the week of month (Monthly last weekday Frequency mode)- First payment day must be the last weekday of the month Number of payments needs to be a positive integer value Last payment date is invalid, last payment day needs to be in the format dd/mm/yyyy and must be in the future Last payment date is invalid, last payment day does not match the selected frequency mode W2P041 Termination mode invalid, termination mode can only be 1,2 or 3 W2P042 Service is not Enabled W2P043 Invalid store_card field. Must be 0 or 1 W2P044 CSS file not found W2P045 Page display type undetermined. Must be 1 or 2 Page 26 of 47

27 W2P046 Merchant is not active. W2P047 Invalid csc_required field. Must be 0 or 1 W2P048 W2P049 W2P050 W2P051 W2P052 W2P053 W2P054 W2P055 W2P056 W2P057 W2P058 W2P059 W2P060 W2P061 W2P062 W2P063 Invalid client_id field. Invalid unique_reference field. Card details are invalid or the one dollar authorisation has failed. Invalid register_return_url value. Recurring Payment plan creation failed. Please contact Flo2Cash. Invalid number_of_week value. Please consult integration guide Invalid day_of_week value. Please consult integration guide 3DSecure Result - Card not enrolled 3DSecure Result - Card Holder Not Registered 3DSecure Result - Card Holder Registered but Verification not successful Invalid Merchant Transaction ID Invalid Mobile Device ID Invalid Mobile Device Description Invalid Latitude Invalid Longitude Invalid Customer Mobile Number W2P064 Invalid Customer Data 1 W2P065 Invalid Customer Data 2 W2P066 Invalid Customer Data 3 W2P067 Invalid Customer Data 4 W2P068 Invalid Customer Data 5 W2P069 W2P070 W2P071 W2P072 W2P073 W2P074 W2P075 Error reading Web2Pay URI The value provided for payment method is invalid Merchant account is not configured for the selected payment method Invalid Mobile Request Mobile Request already has been processed Merchant verifier does not match with the details provided Xero integration disconnected by the merchant Appendix B: CSS Templates, Samples, and Screenshots Flo2Cash Web Payments Standard Payment Page HTML Template <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " transitional.dtd"> <html xmlns=" > <head> <title></title> </head> <body> <div id="maincontainer"> <div id="headercontainer"> Page 27 of 47

28 <div id="header"> <h1> </h1> <div id="bodycontainer"> <div id="shoppinginfobodyheader"> <h2><span>payment Details</h2> <div id="shoppinginfoouter"> <div id="shoppinginfodivtop"><span> <div id="shoppinginfodivmain"> <div id="shoppinginfocontentheader"> <h4><span>payment Information</h4> <div id="shoppinginfocontentmain"> <div class="divchildone"> <span class="spanlabel1">merchant: <span class="spandata1">[merchant Name] <div class="divchildtwo"> <span class="spanlabel2">item: <span class="spandata2">[item to Pay For] <div class="divchildthree"> <span class="spanlabel3">amount: <span class="spandata3">[amount] <div class="divchildfour"> <span class="spanlabel4">reference: <span class="spandata4">[reference] <div id="shoppinginfodivbtm"><span> <div id="creditcardinfoouter"> <div id="creditcardinfodivtop"><span> <div id="creditcardinfodivmain"> <div id="creditcardinfocontentheader"> <h4><span>credit Card Information</h4> <div id="creditcardinfocontentmain"> <div class="divchildone"> <span class="spanlabel1">card Type: Page 28 of 47

29 <span class="spandata1"> <span class="spancardtypecontainer"> <select> <option value="mc">mastercard</option> <option value="visa">visa</option> </select> <em>*</em> <span class="spanerrormessage1">error message <div class="divchildtwo"> <span class="spanlabel2">card No.:<span>¹ <span class="spandata2"> <span class="spancardnocontainer"><input type="text" /> <em>*</em> <span class="spanerrormessage2">error message <div class="divchildthree"> <span class="spanlabel3">card Security Code:<span>² <span class="spandata3"> <span class="spancardcsccontainer"><input type="text" /> <em>*</em> <span class="spanerrormessage3">error message <a href="#" class="lnkcsc">what is a Card Security Code?</a> <div class="divchildfour"> <span class="spanlabel4">card Expiry: <span class="spandata4"> <span class="spancardmonthcontainer"> <select> <option value="1">01</option> <option value="2">02</option> <option value="3">03</option> <option value="4">04</option> <option value="5">05</option> <option value="6">06</option> <option value="7">07</option> <option value="8">08</option> <option value="9">09</option> <option value="10">10</option> <option value="11">11</option> <option value="12">12</option> </select> <span class="spancardmonthyrdivider">/ <span class="spancardyearcontainer"> <select> <option value="9">09</option> <option value="10">10</option> <option value="11">11</option> <option value="12">12</option> <option value="13">13</option> <option value="14">14</option> </select> <em>*</em> <span class="spanerrormessage4">error message <div class="divchildfive"> <span class="spanlabel5">card Name: <span class="spandata5"> <span class="spancardnamecontainer"><input type="text" /> <em>*</em> <span class="spanerrormessage5">error message <div class="divchildsix"> <span class="spanlabel6">store Card: <span class="spandata6"> <span class="spancardstorecontainer"><input type="checkbox" /> Page 29 of 47

30 <div id="creditcardnote"> <span><em>*</em> Required<br /> <span><b>1</b> <span>the card number should be entered with <strong>no</strong> spaces or hyphens e.g <br /> <span><b>2</b> <span>the card security code is a 3 or 4 digit number located on the back of your card ( Except Diners ). <div id="creditcardinfodivbtm"><span> <div id=" receiptouter"> <div id=" receiptdivtop"><span> <div id=" receiptdivmain"> <div id=" receiptcontentheader"> <span class="spanheader">if you would like to receive a receipt for this payment by , please enter your address below. <div id=" receiptcontentmain"> <span class="spanlabel1"> Address: <span class="spandata1"> <span class="spanreceipt container"><input type="text" /> <span class="spanerrormessage1">error message here <div id=" receiptdivbtm"> <div id="submitbuttonouter"> <div id="submitbutton"> <span><input type="button" value="submit" /><br /> <!-- you can use these extra divs for pictures, other data you would like to put on the page then just specify the absolute position if you decide to use it. --> <div id="extradivone"><div id="extradivtwo"><div id="extradivthree"> <div id="extradivfour"><div id="extradivfive"><div id="extradivsix"> <div id="extradivseven"><div id="extradiveight"><div id="extradivnine"> <div id="footercontainer"> <p> </p> <div id="f2cnote"> <p>securely hosted by Flo2Cash^TM</p> Page 30 of 47

31 </body> </html> Flo2Cash Web Payments Standard Payment CSS Sample Code body font-size: 10px; font-family: Verdana, Arial, Sans-Serif; background-color: #6e0b0b; #maincontainer width: 832px; margin: 0px auto 0px auto; backgroundcolor: #f9f8f8; #headercontainer width: 100%; clear: both; display: block; padding: 0px; minheight: 70px; height: 100px; backgroundcolor: #000000; background-image: url(banner.gif); background-repeat: norepeat; background-position: top; #header h1 display: none; #bodycontainer min-height: 680px; width: 832px; background: url(displaypic.gif) no-repeat bottom; border: solid 1px #6e0b0b; border-top-color: #ffffff; border-bottom-color: #000000;.spanErrorMsg color: #000000; margin-top: 5px; #shoppinginfobodyheader, #shoppinginfodivmain, #creditcardinfodivmain, # receiptdivmain, #submitbutton width: 600px; marginleft: 115px; margin-top: 0px; border: none; #shoppinginfobodyheader background: url(paydetails.gif) no-repeat top left; min-height: 30px; #shoppinginfocontentheader, #creditcardinfocontentheader min-height: 25px; Page 31 of 47

32 margin-top: 0px; #shoppinginfocontentheader background: url(payinfo.gif) no-repeat top left; #creditcardinfocontentheader background: url(ccinfo.gif) no-repeat top left; #shoppinginfocontentmain, #creditcardinfocontentmain, # receiptcontentmain, # receiptcontentheader border: solid 1px #904747; min-height: 80px; #creditcardinfocontentmain border-bottom: none; # receiptcontentheader minheight: 15px; padding: 15px 0 0 5px; bordertop: none; border-bottom: none; # receiptcontentmain min-height: 30px; border-top: none; #shoppinginfocontentmain.divchildone, #creditcardinfocontentmain.divchildone margin-top: 8px;.spanLabel1,.spanLabel2,.spanLabel3,.spanLabel4,.spanLabel5,.spanLabel6 float: left; width: 130px; display: block; marginbottom: 5px; paddingleft: 5px; color: #534f4f; fontweight: bold; font-size: 10px;.spanData1,.spanData2,.spanData3,.spanData4,.spanData5,.spanData6 float: left; width: 460px; display: inlineblock; Page 32 of 47

33 marginbottom: 5px; font-size: 10px; input[type="text"], select fontsize: 10px; color: #534f4f; padding-left: 3px; #creditcardnote margin-left: 5px; #submitbutton text-align: right; padding-top: 5px; #submitbutton input[type="button"] width: 70px; height: 25px; text-align:center; vertical-align: middle; background: url(btnsubmitbg.gif) no-repeat top right; border: solid 1px #904747; fontsize: 11px; fontweight: bold; color: #ffffff; cursor: pointer; a, a:visited color: #000000; textdecoration: none; font-weight: bold; a : h o v e r text-decoration: underline; em, span sup, span b,.spanerrormessage1,.spanerrormessage2,.spanerrormessage3,.spanerrormessage4,.spanerrormessage5 color: #6e0b0b; #shoppinginfobodyheader h2 span, #shoppinginfocontentheader h4 span, #creditcardinfocontentheader h4 span, #shoppinginfodivtop, #shoppinginfodivbtm, #creditcardinfodivtop, #creditcardinfodivbtm, # receiptdivtop, # receiptdivbtm, #footercontainer, #f2cnote display: none; Flo2Cash Web Payments Standard Payment CSS Sample Output with CSS applied Page 33 of 47

34 Flo2Cash Web Payments Shopping Cart Payment Page HTML Template <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " transitional.dtd"> <html xmlns=" > <head> <title></title> </head> <body> <div id="maincontainer"> <div id="headercontainer"> <div id="header"> <h1> </h1> <div id="bodycontainer"> <div id="shopcartbodyheader"> <h2><span>shopping Cart Payment Details</h2> <div id="shopcartinfoouter"> <div id="shopcartinfodivtop"><span> <div id="shopcartinfodivmain"> <div id="shopcartinfocontentheader"> <h4><span>shopping Information</h4> <div id="shopcartinfocontentmain"> Page 34 of 47