web payments integration guide version 1.0 – 19/04/2016 · web payments integration guide version...

Web Payments Integration Guide Version 1.0 – 19/04/2016 | Flo2Cash Limited

of 47

Web Payments Integration Guide Version 1.2

21/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) .............................................................. 10

Output Variables to Return_URL – Only in Customer Experience B ................. 10

Web Payments Shopping Cart................................................................................................. 11

Input Variables .......................................................................................................................... 11



Web Payments – Store Card ..................................................................................................... 18



Merchant Notification Service (MNS) .................................................................................. 20

Implementing MNS ................................................................................................................... 20

MNS Handler ............................................................................................................................... 21

Web Payments Standard and Shopping Cart ........................................................... 21

Web Payments Store Card ................................................................................................ 21

MNS Data Available .................................................................................................................. 21

Web Payments Standard .................................................................................................... 21


of 47

Web Payments Shopping Cart ......................................................................................... 22

Web Payments Store Card ................................................................................................ 23

Flo2Cash Action Response ................................................................................................... 23

Merchant Console MNS Retry ............................................................................................. 24

3D Secure ......................................................................................................................................... 24

Customising the Flo2Cash Interface ................................................................................... 24

Overview ....................................................................................................................................... 24

Changes Available .................................................................................................................... 24

Appendix A: Flo2Cash Web Payments Error Codes ...................................................... 25

Appendix B: CSS Templates, Samples, and Screenshots ............................................ 27

Appendix C: Merchant Verifier Examples ......................................................................... 42

Calculating the merchant_verifier input parameter value for Standard

Payments ...................................................................................................................................... 42

Calculating the merchant_verifier input parameter value for Shopping Cart

Payments ...................................................................................................................................... 43

Calculating the payment_provider_verifier output parameter value for

Standard/Shopping Cart Payments .................................................................................. 45

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 https://secure.flo2cash.co.nz/client/ 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.

https://secure.flo2cash.co.nz/client/Default/MemberLogin.aspx


of 47

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.


of 47

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.


of 47

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.


of 47

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.


of 47

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 String 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 String 50

reference Merchant defined value stored with the

transaction.

Optional String 50

particular Merchant defined value stored with the

transaction.

Optional String 50

return_url The URL that the customer will be sent to on

completion of the payment.

This must be a publicly accessible URL.

Required String 1024

notification_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 String 1024


of 47

header_image 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).


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.

Optional String 6

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.

Optional String 6

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 pass-through field that is never

presented to your customer. Flo2Cash will

not store this value.

store_card 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

Optional Integer N/A

display_customer_email 0 or 1 as to whether Web Payments should

display customer email receipt field.

1=display (default) 0 = hide

optional Integer N/A


of 47

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.

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


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.

optional String 50

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 String N/A


of 47

Merchant Website Example (HTML example)

<form action="https://secure.flo2cash.co.nz/web2pay/default.aspx" method="post">

<input type="hidden" name="cmd" value="_xclick"/>

<input type="hidden" name="account_id" value="10000"/>

<input type="hidden" name="return_url" value="http://<your-

site>/ReturnURL.php"/>

<input type="hidden" name="notification_url" value="http://<your-

site>/NotifyURL.php"/> <input type="hidden" name="header_image"

value="https://<your-site>/images/logo.gif"/>

<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_email" 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="IV20061031001"/>

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. String

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


of 47

account_id The Flo2Cash Account ID used for processing the

transaction.

Integer

reference Reference used for the transaction - defined by the

merchant

String

particular Particular used for the transaction – defined by the

merchant

String

card_type The credit card type used for this transaction:

1 = American Express

3 = Diners Club

4 = MasterCard

5 = Visa Card

6 = China Union Pay

Integer

response_text If an error occurred, then the error message will be

stored here

String

response_code 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

String

amount Total amount of the transaction. Decimal

authorisation_code Authorisation code returned by the bank for this

transaction

String

error_code The error code indicating the type of error that

occurred. See Appendix for a full listing of Error

Codes

String

error_message The error message explaining what the error means.

See Appendix for a full listing of Error Codes

String

custom_data Value of the custom_data input variable that you

passed to identify your transaction.

String

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

String

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 (Flo2Cash Calculating the

payment_provider_verifier output parameter value

for Standard/Shopping Cart Payments) for sample

code on how to calculate this field.

String

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.


of 47


cmd Defines the Web Payments

integration service. Always use

“_xcart” for Web Payments

Shopping Cart.

Required String N/A

account_id Flo2Cash issued Account ID Required Integer N/A

reference Merchant defined value stored

with the transaction.

Optional String 50

particular Merchant defined value stored

with the transaction.

Optional String 50

return_url The URL that the customer will be

sent to on completion of the

payment.

This must be a publicly accessible

URL.


notification_url If provided, this URL will be used

in conjunction with Flo2Cash

Merchant Notification Service

(MNS).

This must be a publicly accessible

URL.


Item_nameX 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.)

Required String 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 String 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


of 47

Item_qtyX You can pass through multiple

items for one transaction.

The item_qty elements must be

formatted as follows: item_qty1,

item_qty2, item_qty3, etc...

Required Integer N/A

header_image 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 URL-

encoded. 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).


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.

Optional String 6

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.

Optional String 6

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 pass-through field that is never

presented to your customer.

Flo2Cash will not store this

value.


customer_info_required 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).



of 47

store_card 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


display_customer_email 0 or 1 as to whether Web

Payments should display

customer email receipt field.

1=display (default) 0 = hide

optional Integer N/A

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.

optional String 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, 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


Similarly, if the value “unionpay”

is passed, the customer will be


of 47

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 String N/A


<form action=”https://secure.flo2cash.co.nz/web2pay/default.aspx” method=”post”>

<input type=”hidden” name=”cmd” value=”_xcart”/>

<input type=”hidden” name=”account_id” value=”10000”/>

<input type=”hidden” name=”return_url” value=”http://<your-

site>/ReturnURL.php”/>

<input type=”hidden” name=”notification_url” value=”http://<your-

site>/NotifyURL.php”/>

<input type=”hidden” name=”customer_info_required“

value=”1”/> <input type=”hidden” name=”store_card“

value=”0”/>

<input type="hidden" name="display_customer_email" value="0"/>

<input type="hidden" name="merchant_verifier"

value="JHGgdfgGKJH+dfHG^dgvd"/>

reference


of 47

<input type=”text” name=”reference” value=”IV20061031001”/>

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=”10.65”/> 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=”22.50”/> 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=”https://<your-

site>/images/logo.gif”/>

<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.


*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.


txn_id Flo2Cash defined unique transaction ID. String

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


of 47

account_id The Flo2Cash Account ID used for processing

the transaction.

Integer

Reference Reference used for the transaction - defined by

the merchant

String

Particular Particular used for the transaction – defined by

the merchant

String



3 = Diners Club

4 = MasterCard

Integer

5 = Visa Card

response_text If an error occurred, then the error message will

be stored here

String

response_code 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

String

amount Total amount of the transaction. Decimal

authorisation_code Authorisation code returned by the bank for the

transaction.

String



Codes

String

error_message The error message explaining what the error

means. See Appendix for a full listing of Error

Codes

String

custom_data Value of the custom_data input field that was

passed to identify the transaction.

String

The following fields will be posted back only if the “customer_info_required”

field was set to “1”

first_name Customer First Name String

last_name Customer Last Name String

Phone Customer Phone String

Email Customer Email Address String

address1 Customer address String

address2 Customer address String

City Customer City String

Country Customer Country String

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

String

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

String


of 47

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.


cmd Defines the Web

Payments integration

service. Always use

“_xstorecc”” for Web

Payments Store Card.

Required String 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.

Required String 50

return_url The URL that the

customer will be sent to

on completion of the

payment.

This must be a publicly

accessible URL.


notification_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.


header_image 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”.



of 47

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.

Optional String 6

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.

Optional String 6

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.



<form action=”https://secure.flo2cash.co.nz/web2pay/default.aspx” method=”post”> <input type=”hidden” name=”cmd” value=”_xstorecc”/> <input type=”hidden” name=”client_id” value=”10000”/> <input type=”hidden” name=”return_url” value=”http://<your-

site>/ReturnURL.php”/> <input type=”hidden” name=”notification_url” value=”http://<your-

site>/NotifyURL.php”/> <input type=”hidden” name=”header_image” value=”https://<your-

site>/images/logo.gif”/> <input type=”hidden” name=”header_bottom_border” value =”22FFDD”/> <input type=”hidden” name=”header_background_colour”

value=”22FFDD”/> <input type=”submit” value=”submit” />


of 47

</form>


*NB: Please note that the output variables only apply if the Return Option is set to post

back to the merchant


response_code The values for the response_code are:

0 = Successful

1 = Failed

String

response_message The error text accompanied with the response

code

String

card_token The card token representing this card will be

available here.

String

card_number Masked card number for the stored card token String



3 = Diners Club

4 = MasterCard

5 = Visa Card

Integer

card_expiry Provided in the format of MMYY String

card_holder_name The cardholder name collected from the secure

page

String

unique_reference A unique identifier you can use to match the

card owner’s details to the token created

String

custom_data 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.

String



Codes

String

error_message The error message explaining what the error

means. See Appendix for a full listing of Error

Codes

String

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’.


of 47

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.GetString(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

https://secure.flo2cash.co.nz/web2pay/MNSHandler.aspx.

Web Payments Store Card

For Web Payments Store Card, the Flo2Cash URL to post the received data to is

https://secure.flo2cash.co.nz/web2pay/MNSHandlerStoreCard.aspx.

MNS Data Available

Web Payments Standard

The data sent to your notification handler for Web Payments Standard is as follows:

Name Description

verifier Flo2Cash defined encrypted string used for verification

cmd The command sent to Flo2Cash. In this case, the value must be

_xverify-transaction which means you are verifying a Flo2Cash

Transaction.

transaction_id Flo2Cash returned unique transaction ID.

https://secure.flo2cash.co.nz/web2pay/MNSHandler.aspx

https://secure.flo2cash.co.nz/web2pay/MNSHandlerStoreCard.aspx


of 47

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 The account ID used for processing the transaction.

reference Reference used for the transaction - defined by the merchant



3 = Diners Club

4 = MasterCard

5 = Visa Card

receipt_id Flo2Cash returned unique transaction receipt number.

response_text The error text accompanied with the response code.

amount Payment amount

custom_data 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.

card_token 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 Description



_xverify-transaction which means you are verifying a Flo2Cash

Transaction.

transaction_id 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

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 The account ID used for processing the transaction.

reference Reference used for the transaction - defined by the merchant


of 47



3 = Diners Club

4 = MasterCard

5 = Visa Card

receipt_id Flo2Cash returned unique transaction receipt number.

response_text The error text accompanied with the response code.

Item Data The data sent to Flo2Cash in step 1. (e.g. Items, amounts, codes

and qty’s. only apply for shopping cart)







here.

Web Payments Store Card

The data sent to your notification handler for Web Payments Store Card is as follows:

Name Description



_xstorecc_mns, which means you are verifying a Flo2Cash

Transaction.

response_code The values for the response_code are:

0 = Successful

1 = Failed

response_message The text accompanied with the response code



here.

card_number Masked card number for the stored card token



3 = Diners Club

4 = MasterCard

5 = Visa Card

card_expiry Provided in the format of MMYY

card_holder_name The cardholder name collected from the secure page

unique_reference A unique identifier you can use to match the card owner’s details

to the token created





Flo2Cash Action Response

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:


of 47

Action Response Description

VERIFIED The transaction was processed and initial post WAS from

Flo2Cash

REJECTED 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 Description

header_image 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”.


of 47

Flo2Cash recommends that you provide an image that is

stored only on a secure (HTTPS) server.

header_bottom_border 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.

header_background_colour 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="https://<your-

site>/images/logo.gif"/>

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 Error Message

W2P001 Invalid cmd field.

W2P002 Invalid account_id field.

W2P003 Invalid amount field.

W2P004 Invalid item_name field.

W2P005 Invalid reference field.

W2P006 Invalid particular field.

W2P007 Invalid return_url field.

W2P008 Invalid notification_url field.


of 47

W2P009 Invalid update_url field

W2P010 Invalid header_image field.

W2P011 Invalid header_bottom_border field.

W2P012 Invalid header_background_colour field.

W2P013 Invalid page_background_colour field.

W2P014 Invalid shopping cart items field.

W2P015 Invalid shopping cart item_price field or item_qty field.

W2P016 Invalid shopping cart item_name field.

W2P017 Invalid shopping cart item_code field.

W2P018 Invalid session_id field.

W2P019 Invalid checkout_id field.

W2P020 Invalid customer_email field.

W2P021 Invalid card_type field.

W2P022 Your IP address is not in our acceptable range.

W2P023 An error has occurred while processing your payment.

W2P024 The payment server is not available right now. Please try again later.

W2P025 3 party mode 2 is not enabled for your account.

W2P026 Transaction is blocked.

W2P027 Flo2Cash Web Payments is not enabled for your account.

W2P028 Payment gateway setup is not correct, please contact Flo2cash.

W2P029 Client account setup is not correct, please contact Flo2cash.

W2P030 Invalid custom_data field.

W2P031 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 (Monthly specific week) requires both number of week and day of week to be

provided

W2P034 (Monthly specific week) Start day does not match the Day of Week

W2P035 (Monthly specific week) Start day does not match the week of month

W2P036 (Monthly last weekday Frequency mode)- First payment day must be the last

weekday of the month

W2P038 Number of payments needs to be a positive integer value

W2P039 Last payment date is invalid, last payment day needs to be in the format

dd/mm/yyyy and must be in the future

W2P040 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


of 47

W2P046 Merchant is not active.

W2P047 Invalid csc_required field. Must be 0 or 1

W2P048 Invalid client_id field.

W2P049 Invalid unique_reference field.

W2P050 Card details are invalid or the one dollar authorisation has failed.

W2P051 Invalid register_return_url value.

W2P052 Recurring Payment plan creation failed. Please contact Flo2Cash.

W2P053 Invalid number_of_week value. Please consult integration guide

W2P054 Invalid day_of_week value. Please consult integration guide

W2P055 3DSecure Result - Card not enrolled

W2P056 3DSecure Result - Card Holder Not Registered

W2P057 3DSecure Result - Card Holder Registered but Verification not successful

W2P058 Invalid Merchant Transaction ID

W2P059 Invalid Mobile Device ID

W2P060 Invalid Mobile Device Description

W2P061 Invalid Latitude

W2P062 Invalid Longitude

W2P063 Invalid Customer Mobile Number

W2P064 Invalid Customer Data 1





W2P069 Error reading Web2Pay URI

W2P070 The value provided for payment method is invalid

W2P071 Merchant account is not configured for the selected payment method

W2P072 Invalid Mobile Request

W2P073 Mobile Request already has been processed

W2P074 Merchant verifier does not match with the details provided

W2P075 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" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-

transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head> <title></title> </head> <body> <div id="mainContainer"> <div id="headerContainer">


of 47

<div

id="header">

<h1> </h1> </div> </div> <div id="bodyContainer"> <div id="shoppingInfoBodyHeader"> <h2><span>Payment Details</span></h2> </div> <div id="shoppingInfoOuter"> <div id="shoppingInfoDivTop"><span> </span></div> <div id="shoppingInfoDivMain"> <div id="shoppingInfoContentHeader"> <h4><span>Payment Information</span></h4> </div> <div id="shoppingInfoContentMain"> <div class="divChildOne"> <span class="spanLabel1">Merchant:</span> <span class="spanData1">[Merchant Name]</span> </div> <div class="divChildTwo"> <span class="spanLabel2">Item:</span> <span class="spanData2">[Item to Pay For]</span> </div> <div class="divChildThree"> <span class="spanLabel3">Amount:</span> <span class="spanData3">[Amount]</span> </div> <div class="divChildFour"> <span class="spanLabel4">Reference:</span> <span class="spanData4">[Reference]</span> </div> </div> </div> <div id="shoppingInfoDivBtm"><span> </span></div> </div> <div id="creditCardInfoOuter"> <div id="creditCardInfoDivTop"><span> </span></div> <div id="creditCardInfoDivMain"> <div id="creditCardInfoContentHeader"> <h4><span>Credit Card Information</span></h4> </div> <div id="creditCardInfoContentMain"> <div class="divChildOne"> <span class="spanLabel1">Card Type:</span>


of 47

<span class="spanData1"> <span class="spanCardTypeContainer"> <select> <option value="MC">MasterCard</option> <option value="VISA">VISA</option> </select> </span><em>*</em> <span class="spanErrorMessage1">Error message</span> </span> </div> <div class="divChildTwo"> <span class="spanLabel2">Card No.:<span><sup>1</sup></span></span> <span class="spanData2"> <span class="spanCardNoContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage2">Error message</span> </span> </div> <div class="divChildThree"> <span class="spanLabel3">Card Security Code:<span><sup>2</sup></span></span> <span class="spanData3"> <span class="spanCardCscContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage3">Error message</span> <a href="#" class="lnkcsc">What is a Card Security Code?</a> </span> </div> <div class="divChildFour"> <span class="spanLabel4">Card Expiry:</span> <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> <span

class="spanCardMonthYrDivider">/</span> <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> </span><em>*</em> <span class="spanErrorMessage4">Error

message</span> </span> </div> <div class="divChildFive"> <span class="spanLabel5">Card Name:</span> <span class="spanData5"> <span class="spanCardNameContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage5">Error

message</span> </span> </div> <div class="divChildSix"> <span class="spanLabel6">Store Card:</span> <span class="spanData6"> <span class="spanCardStoreContainer"><input type="checkbox" /> </span>

of 47

</span> </div> <div id="creditCardNote"> <span><em>*</em> Required</span><br /> <span><b>1</b></span> <span>The card number should be entered with

<strong>no</strong> spaces or hyphens e.g. 1234567890123456</span><br /> <span><b>2</b></span> <span>The card security code is a 3 or 4 digit number

located on the back of your card ( Except Diners ).</span> </div> </div> </div> <div id="creditCardInfoDivBtm"><span> </span></div> </div> <div id="emailReceiptOuter"> <div

id="emailReceiptDivTop"><span> </span></div> <div id="emailReceiptDivMain"> <div id="emailReceiptContentHeader"> <span class="spanHeader">If you would like to receive a receipt for this payment by

email, please enter your email address below.</span> </div> <div id="emailReceiptContentMain"> <span class="spanLabel1">Email Address:</span> <span class="spanData1"> <span class="spanReceiptEmailContainer"><input type="text" /> </span> <span class="spanErrorMessage1">Error message here</span> </span> </div> </div> <div id="emailReceiptDivBtm"></div> </div> <div id="submitButtonOuter"> <div id="submitButton"> <span><input type="button" value="Submit" /></span><br /> </div> </div>

 <div id="extraDivOne"></div><div id="extraDivTwo"></div><div id="extraDivThree"></div> <div id="extraDivFour"></div><div id="extraDivFive"></div><div id="extraDivSix"></div> <div id="extraDivSeven"></div><div id="extraDivEight"></div><div

id="extraDivNine"></div> </div> <div id="footerContainer"> <p> </p> </div> <div id="f2cNote"> <p>Securely hosted by Flo2Cash<sup>TM</sup></p> </div> </div>


of 47

</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;

background-

color: #f9f8f8; } #headerContainer { width: 100%;

clear: both;

display: block;

padding: 0px; min-

height: 70px; height:

100px; background-

color: #000000;

background-image:

url(banner.gif);

background-repeat: no-

repeat; 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, #emailReceiptDivMain, #submitButton { width:

600px; margin-

left: 115px;

margin-top: 0px; border: none; } #shoppingInfoBodyHeader { background: url(paydetails.gif)

no-repeat top left; min-height: 30px; } #shoppingInfoContentHeader, #creditCardInfoContentHeader { min-height: 25px;


of 47

margin-top: 0px; } #shoppingInfoContentHeader { background: url(payinfo.gif)

no-repeat top left; } #creditCardInfoContentHeader { background: url(ccinfo.gif)

no-repeat top left; } #shoppingInfoContentMain, #creditCardInfoContentMain, #emailReceiptContentMain, #emailReceiptContentHeader

{ border: solid 1px #904747; min-height: 80px; } #creditCardInfoContentMain { border-bottom: none; } #emailReceiptContentHeader { min-

height: 15px;

padding: 15px 0

0 5px; border-

top: none; border-bottom: none; } #emailReceiptContentMain { 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;

margin-

bottom:

5px;

padding-

left:

5px;

color:

#534f4f;

font-

weight:

bold; font-size: 10px; } .spanData1, .spanData2, .spanData3, .spanData4, .spanData5, .spanData6 {

float: left;

width:

460px;

display:

inline-

block;


of 47

margin-

bottom: 5px; font-size: 10px; } input[type="text"], select { font-

size: 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; font-

size: 11px; font-

weight: bold; color:

#ffffff; cursor: pointer; } a, a:visited { color:

#000000; text-

decoration: 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, #emailReceiptDivTop,

#emailReceiptDivBtm, #footerContainer, #f2cNote { display: none;

Flo2Cash Web Payments Standard Payment CSS Sample Output with CSS applied


of 47

Flo2Cash Web Payments Shopping Cart Payment Page HTML Template


transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head> <title></title> </head> <body> <div id="mainContainer"> <div id="headerContainer"> <div

id="header">

<h1> </h1> </div> </div> <div id="bodyContainer"> <div id="shopCartBodyHeader"> <h2><span>Shopping Cart Payment Details</span></h2> </div> <div id="shopCartInfoOuter"> <div id="shopCartInfoDivTop"><span> </span></div> <div id="shopCartInfoDivMain"> <div id="shopCartInfoContentHeader"> <h4><span>Shopping Information</span></h4> </div> <div id="shopCartInfoContentMain">


of 47

<div class="divChildOne"> <span class="spanLabel1">Merchant:</span> <span class="spanData1">[Merchant Name]</span> </div> <div class="divChildTwo"> <span class="spanLabel2">Reference:</span> <span class="spanData2">[Reference]</span> </div> <div class="divChildThree"> <span class="spanLabel3">Particular:</span> <span class="spanData3">[Particular]</span> </div> <div class="divChildFour"> <table> <tr> <td> Shopping Cart data here.. </td> </tr> <tr> <td style="text-align: right;"><span>Total Amount for this transaction:

[Total Amount]</span></td> </tr> </table> </div> </div> </div> <div

id="shopCartInfoDivBtm"><span> </span></div> </div> <div id="customerInfoErrorOuter"> <div class="customerInfoError"> <span class="spanErrorMessage">Customer Information Error Message here</span> </div> </div> <div id="customerInfoOuter"> <div id="customerInfoDivTop"><span> </span></div> <div id="customerInfoDivMain"> <div id="customerInfoContentHeader"> <h4><span>Customer Information</span></h4> </div> <div id="customerInfoContentMain"> <div id="customerInfoSection1"> <div class="divChildOne"> <span class="spanLabel1">First Name:</span> <span class="spanData1"> <span class="spanFirstNameContainer"><input type="text"

/> </span><em>*</em> </span> </div> <div class="divChildTwo"> <span class="spanLabel2">Last Name:</span> <span class="spanData2"> <span class="spanLastNameContainer"><input type="text"

/> </span><em>*</em> </span> </div>


of 47

<div class="divChildThree"> <span class="spanLabel3">Email:</span> <span class="spanData3"> <span class="spanEmailContainer"><input type="text"

/> </span><em>*</em> </span> </div> <div class="divChildFour"> <span class="spanLabel4">Phone:</span> <span class="spanData4"> <span class="spanPhoneContainer"><input type="text" /> </span> </span> </div> </div> <div id="customerInfoSection2"> <div class="divChildFive"> <span class="spanLabel5">Address:</span> <span class="spanData5"> <span class="spanAddress1Container"><input type="text" /> </span> </span> </div> <div class="divChildSix"> <span class="spanLabel6"> </span> <span class="spanData6"> <span class="spanAddress2Container"><input type="text" /> </span> </span> </div> <div class="divChildSeven"> <span class="spanLabel7">City:</span> <span class="spanData7"> <span class="spanCityContainer"><input type="text" /> </span> </span> </div> <div class="divChildEight"> <span class="spanLabel8">Country:</span> <span class="spanData8"> <span class="spanCountryContainer"><select><option value="1">New

Zealand</option></select> </span> </span> </div> </div> </div> </div> <div

id="customerInfoDivBtm"><span> </span></div> </div> <div id="creditCardInfoOuter"> <div id="creditCardInfoDivTop"><span> </span></div> <div id="creditCardInfoDivMain"> <div id="creditCardInfoContentHeader"> <h4><span>Credit Card Information</span></h4> </div> <div id="creditCardInfoContentMain"> <div class="divChildOne"> <span class="spanLabel1">Card Type:</span> <span class="spanData1"> <span class="spanCardTypeContainer"> <select>


of 47

<option value="MC">MasterCard</option> <option value="VISA">VISA</option> </select> </span><em>*</em> <span class="spanErrorMessage1">Error message</span> </span> </div> <div class="divChildTwo"> <span class="spanLabel2">Card No.:<span><sup>1</sup></span></span> <span class="spanData2"> <span class="spanCardNoContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage2">Error message</span> </span> </div> <div class="divChildThree"> <span class="spanLabel3">Card Security Code:<span><sup>2</sup></span></span> <span class="spanData3"> <span class="spanCardCscContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage3">Error message</span> <a href="#" class="lnkcsc">What is a Card Security Code?</a> </span> </div> <div class="divChildFour"> <span class="spanLabel4">Card Expiry:</span> <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> <span class="spanCardMonthYrDivider">/</span> <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> </span><em>*</em> <span class="spanErrorMessage4">Error

message</span> </span> </div> <div class="divChildFive"> <span class="spanLabel5">Card Name:</span> <span class="spanData5"> <span class="spanCardNameContainer"><input type="text"

/> </span><em>*</em> <span class="spanErrorMessage5">Error message</span> </span> </div> <div class="divChildSix"> <span class="spanLabel6">Store Card:</span> <span class="spanData6"> <span class="spanCardStoreContainer"><input type="checkbox" /> </span>

of 47

</span> </div> <div id="creditCardNote"> <span><em>*</em> Required</span><br /> <span><b>1</b></span> <span>The card number should be entered with

<strong>no</strong> spaces or hyphens e.g. 1234567890123456</span><br /> <span><b>2</b></span> <span>The card security code is a 3 or 4 digit number

located on the back of your card ( Except Diners ).</span> </div> </div> </div> <div id="creditCardInfoDivBtm"><span> </span></div> </div> <div id="emailReceiptOuter"> <div

id="emailReceiptDivTop"><span> </span></div> <div id="emailReceiptDivMain"> <div id="emailReceiptContentHeader"> <span class="spanHeader">If you would like to receive a receipt for this payment by

email, please enter your email address below.</span> </div> <div id="emailReceiptContentMain"> <span class="spanLabel1">Email Address:</span> <span class="spanData1"> <span class="spanReceiptEmailContainer"><input type="text" /> </span> <span class="spanErrorMessage1">Error message here</span> </span> </div> </div> <div id="emailReceiptDivBtm"></div> </div> <div id="submitButtonOuter"> <div id="submitButton"> <span><input type="button" value="Submit" /></span><br /> </div> </div>

 <div id="extraDivOne"></div><div id="extraDivTwo"></div><div id="extraDivThree"></div> <div id="extraDivFour"></div><div id="extraDivFive"></div><div id="extraDivSix"></div> <div id="extraDivSeven"></div><div id="extraDivEight"></div><div

id="extraDivNine"></div> </div> <div id="footerContainer"> <p> </p> </div> <div id="f2cNote"> <p>Securely hosted by Flo2Cash<sup>TM</sup></p> </div> </div>


of 47

</body> </html>

Flo2Cash Web Payments Processing Page HTML Template


transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head> <title></title> </head> <body> <div id="mainContainer"> <div id="headerContainer"> <div

id="header">

<h1> </h1> </div> </div> <div id="bodyContainer"> <div id="processingBodyHeader"> <h2><span>Processing Payment</span></h2> </div> <div id="divProcessingOuter"> <div id="processingDivTop"><span> </span></div> <div id="divProcessingMain"> <span class="spanHeader">Please wait while your transaction is being processed.</span> <h3>Processing... <img src="progressbar.gif"

alternatetext="Progress Bar" alt="" /></h3> <div class="divProcessingNote"> <p><b>Please do not click the back button or navigate to another page while this is

in progress.</b></p> </div> </div> <div id="processingDivBtm"><span> </span></div> </div> </div> <div id="footerContainer">

<p> </p>

</div> <div id="f2cNote"> <p>Securely hosted by

Flo2Cash<sup>TM</sup></p> </div> </div> </body> </html>

Flo2Cash Web Payments Payment Result Page HTML Template


transitional.dtd"> <html

xmlns="http://www.w3.org/1999/xht

ml" > <head> <title></title> </head>


of 47

<body> <div id="mainContainer"> <div id="headerContainer"> <div id="header">

<h1> </h1> </div> </div> <div id="bodyContainer"> <div id="payResultBodyHeader"> <h2><span>Payment Result</span></h2> </div> <div class="errorInPayment"> <h4><span>An error has occured!</span></h4> <div class="divChildOne"> <span class="spanLabel1">Error Message:</span> <span class="spanData1">[Error Message]</span> </div> </div> <div id="payResultCuInfoOuter"> <div id="payResultCuInfoDivTop"><span> </span></div> <div id="payResultCuInfoDivMain"> <div id="payResultCuInfoContentHeader"> <h4><span>Customer Information</span></h4> </div> <div id="payResultCuInfoContentMain"> <div id="payResultCuInfoSection1"> <div class="divChildOne"> <span class="spanLabel1">First Name:</span> <span class="spanData1">[First Name]</span> </div> <div class="divChildTwo"> <span class="spanLabel2">Last Name:</span> <span class="spanData2">[Last Name]</span> </div> <div class="divChildThree"> <span class="spanLabel3">Email:</span> <span class="spanData3">[Email Address]</span> </div> <div class="divChildFour"> <span class="spanLabel4">Phone:</span> <span class="spanData4">[Phone Number]</span> </div> </div> <div id="payResultCuInfoSection2"> <div class="divChildFive"> <span class="spanLabel5">Address:</span> <span class="spanData5">[Address Line One]</span> </div> <div class="divChildSix"> <span class="spanLabel6"> </span> <span class="spanData6">[Address Line Two]</span>


of 47

</div> <div class="divChildSeven">

<span

class="spanLabel7">City:</span>

<span class="spanData7">[City]</span> </div> <div class="divChildEight">

<span

class="spanLabel8">Country:</span>

<span class="spanData8">[Country]</span> </div> </div> </div> </div> <div id="payResultCuInfoDivBtm"><span> </span></div> </div> <div id="payResultOuter"> <div id="payResultDivTop"><span> </span></div> <div id="payResultDivMain"> <div id="payResultContentHeader"> <h4><span>Payment Result Details</span></h4> </div> <div id="payResultContentMain"> <div class="divChildOne"> <span class="spanLabel1">Payment Status:</span> <span class="spanData1">[Transaction_Number]</span> </div> <div class="divChildTwo"> <span class="spanLabel2">Transaction

No.:</span> <span

class="spanData2">[Receipt_Number]</span> </div> <div class="divChildThree"> <span class="spanLabel3">Receipt No.:</span> <span class="spanData3">[Transaction_Status]</span> </div> <div class="divChildFour"> <span class="spanLabel4">Reference:</span> <span class="spanData4">[Reference]</span> </div> <div class="divChildFive"> <span class="spanLabel5">Particular:</span> <span class="spanData5">[Particular]</span> </div> <div class="divChildSix"> <span

class="spanLabel6">Amount</span>

<span class="spanData6">[Amount]</span> </div> <div class="divChildSeven"> <span class="spanLabel7">Optional

Email:</span> <span

of 47

class="spanData7">[Email Address]</span>

</div> </div> </div> <div id="payResultDivBtm"><span> </span></div> </div> <div id="returnToMerchantOuter"> <div id="returnToMerchantButton"> <span><a href="#">Return to

Merchant</a></span><br /> </div> </div>  <div id="extraDivOne"></div><div

id="extraDivTwo"></div><div id="extraDivThree"></div> <div id="extraDivFour"></div><div id="extraDivFive"></div><div id="extraDivSix"></div> <div id="extraDivSeven"></div><div id="extraDivEight"></div><div id="extraDivNine"></div> </div> <div id="footerContainer"> <p> </p> </div> <div id="f2cNote"> <p>Securely hosted by Flo2Cash<sup>TM</sup></p> </div> </div> </body> </html>

Appendix C: Merchant Verifier Examples

Calculating the merchant_verifier input parameter value for

Standard Payments

A merchant verifier is an SHA1 hash of the input parameters in your request with your

integration secret hash key (you can get your secret hash key in the merchant console –

see above). A merchant verifier ensures that the request originated from you and that the

data sent from you to us has not been altered in anyway.

To calculate the hash, you will need to order the data being passed and then concatenate

them with the secret hash key and finally hash them with the SHA-1 algorithm.

1. Convert the following data to strings and trim any whitespace (if the parameter is

optional and you are not providing it, it can be left out):

a) account_id

b) amount

c) reference

d) particular

e) return_url

f) notification_url

g) custom_data


of 47

h) payment_method

i) Integration Secret Hash Key (which was defined in the merchant console)

2. Concatenate the data as follows (the order is important here):

a. account_id + amount + reference + particular + return_url + notification_url +

custom_data + payment_method + Integration Secret Hash Key

3. Encode the concatenated string to UTF-8

4. Hash the concatenated string using the SHA-1 algorithm

5. Base 64 encode your result and provide this string as your merchant_verifier

Here is a .net C# version of the implementation:

public string CalculateMerchantVerifier(int accountId, string amount, string reference, string particular, string returnUrl, string notificationUrl, string customData, string paymentMethod, string integrationSecretHashKey) { byte[] result; string concatenatedValue = String.Format("{0}{1}{2}{3}{4}{5}{6}{7}{8}", accountId.ToString().Trim(), amount.Trim(), (reference ?? String.Empty).Trim(), (particular ?? String.Empty).Trim(), returnUrl.Trim(), (notificationUrl ?? String.Empty).Trim(), (customData ?? String.Empty).Trim(), (paymentMethod ?? String.Empty).Trim(), integrationSecretHashKey.Trim() ); byte[] valueToHash = Encoding.UTF8.GetBytes(concatenatedValue); using (var sha = new SHA1Managed()) { result = sha.ComputeHash(valueToHash); } return Convert.ToBase64String(result); }

Calculating the merchant_verifier input parameter value for

Shopping Cart Payments

A merchant verifier is an SHA1 hash of the input parameters in your request with your

integration secret hash key (you can get your secret hash key in the merchant console –

see above). A merchant verifier ensures that the request originated from you and that the

data sent from you to us has not been altered in anyway.

To calculate the hash, you will need to order the data being passed and then concatenate

them with the secret hash key and finally hash them with the SHA-1 algorithm.

Below are the steps required to create the hash for shopping cart payment integration:


of 47



a) account_id

b) item_price[X*]

c) item_qty[X*]

d) customer_info_required

e) reference

f) particular

g) return_url

h) notification_url

i) custom_data

j) payment_method

k) Integration Secret Hash Key

2. Concatenate the data as follows (the order is important here):

a. account_id + REPEAT([item_priceX] + [item_qtyX] )

customer_info_requiredreference + particular + return_url +

notification_url + custom_data + payment_method + Integration Secret

Hash Key



3. Base 64 encode your result and provide this string as your merchant_verifier

* X would be the cart item number of the shopping cart items; all cart items provided

must be part of the hash.


public string CalculateMerchantVerifierForShoppingCart(int accountId, string itemPrice1, int itemQty1, string itemPrice2, int itemQty2, string displayCustomerInfo, string reference, string particular, string returnUrl, string notificationUrl, string customData, string paymentMethod, string integrationSecretHashKey) { byte[] result; string concatenatedValue = String.Format("{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}{10}{11}{12}", accountId, itemPrice1, itemQty1, itemPrice2, itemQty2, (displayCustomerInfo ?? String.Empty).Trim(), (reference ?? String.Empty).Trim(), (particular ?? String.Empty).Trim(), returnUrl.Trim(), (notificationUrl ?? String.Empty).Trim(), (customData ?? String.Empty).Trim(),


of 47

(paymentMethod ?? String.Empty).Trim(), integrationSecretHashKey.Trim()); byte[] valueToHash = Encoding.UTF8.GetBytes(concatenatedValue); using (var sha = new SHA1Managed()) { result = sha.ComputeHash(valueToHash); } return Convert.ToBase64String(result); }

Calculating the payment_provider_verifier output parameter

value for Standard/Shopping Cart Payments

Once a payment is processed and if you had set your return option to post the result data

back to you, we will include a field in the result data set called payment_provider_verifier.

This will be a SHA1 hashed value to verify that the data we are sending to you originated

from Flo2Cash and has not been altered in transit.

To verify the hash, you will need to order the data being passed and then concatenate

them with the secret hash key, hash the data with the SHA-1 algorithm and finally compare

your result with the hash provided by Flo2Cash in the payment_provider_verifier field.

Below are the steps required to verify the hash for your integration:



a. txn_id

b. receipt_no

c. txn_status

d. account_id

e. reference

f. particular

g. card_type

h. amount

i. response_code

j. response_text

k. customer_email

l. authorisation_code

m. error_message

n. error_code

o. custom_data

p. card_token

q. date

r. checkout_id

s. session_id

t. blocked_reason


of 47

u. Integration Secret Hash Key

2. Concatenate the string as follows:

txn_id + receipt_no + txn_status + account_id + reference + particular + card_type

+ amount + response_code + response_text + customer_email + authorisation_code

+ error_message + error_code + custom_data + card_token + date + checkout_id +

session_id + blocked_reason + Integration Secret Hash Key



5. Base 64 encode your result and compare this value to that provided in the

payment_provider_verifier field.


public string CalculateProviderHash(string txn_id, string receipt_no, string txn_status, string account_id, string reference, string particular, string card_type, string amount, string response_code, string response_text, string customer_email, string authorisation_code, string error_message, string error_code, string custom_data, string card_token, string date, string checkout_id, string session_id, string blocked_reason, string integrationSecretHashKey) { byte[] result; string concatenatedValue = String.Format(

"{0}{1}{2}{3}{4}{5}{6}{7}{8}{9}{10}{11}{12}{13}{14}{15}{16}{17}{18}{19}{20}", (txn_id ?? String.Empty).Trim(), (receipt_no ?? String.Empty).Trim(), (txn_status ?? String.Empty).Trim(), account_id.ToString().Trim(), (reference ?? String.Empty).Trim(), (particular ?? String.Empty).Trim(), (card_type ?? String.Empty).Trim(), (amount ?? String.Empty).Trim(), (response_code ?? String.Empty).Trim(), (response_text ?? String.Empty).Trim(), (customer_email ?? String.Empty).Trim(), (authorisation_code ?? String.Empty).Trim(), (error_message ?? String.Empty).Trim(),


of 47

(error_code ?? String.Empty).Trim(), (custom_data ?? String.Empty).Trim(), (card_token ?? String.Empty).Trim(), (date ?? String.Empty).Trim(), (checkout_id ?? String.Empty).Trim(), (session_id ?? String.Empty).Trim(), (blocked_reason ?? String.Empty).Trim(), integrationSecretHashKey.Trim() ); byte[] valueToHash = Encoding.UTF8.GetBytes(concatenatedValue); using (var sha = new System.Security.Cryptography.SHA1Managed()) { result = sha.ComputeHash(valueToHash); } return Convert.ToBase64String(result); }

web payments integration guide version 1.0 – 19/04/2016 · web payments integration guide version...

Documents