UseCash
is an innovative new system
to allow people to purchase
items online using cash. It
works as follows. A potential
customer selects their required
items on a merchants web site.
When they go to pay for their
items they are offered an option
to pay with 'UseCash'. When
the customer selects UseCash
they are presented with an order
page similar to that in figure
1. They then print out the invoice
and take it to one of 2000 PayZone
terminals (there are 50 terminals
for the initial December release,
increasing to 2000+ thereafter),
the terminals are located in
local shops all over the country
and can be found using this
link http://www.usecash.net/payzone.htm
. The customer presents the
order at the shop and pays the
amount shown on it. UseCash
receives notification of the
payment and informs the merchant
web site to send the goods on
to the customer.
The
merchant informs UseCash the
goods have been dispatched and
then each week UseCash transfers
the relevant funds to the merchant
using the Electronic Money Transfer
System.
This
document details the required
steps required by a merchant
to integrate their website with
UseCash using our integration
options. These are:
Email
Notifications, our
simplest integration option,
which is meant for small shops
and merchants who want to get
active on the UseCash system
as quickly and easily as possible.
Callback
Notifications, for
merchants who require automatic
callbacks to their system on
order status.
Web
Service Integration,
our most complex option for
very large shops, which allows
for extra functionality and
is set-up on a merchant by merchant
basis.
All
communication to the UseCash
servers is encrypted and password
protected. Please have a look
at the Email Notifications first,
if your web site requires callback
functionality then take a look
at UseCash Callback Notifications
section which provides automated
processing. Larger websites
which use web services should
contact us for more detailed
options for integration via
WSDL
UseCash Sign-Up
Once
a merchant has decided to
the avail of the UseCash
service, they will sign a
contract with us and provide
us with the following information:
Merchant
Full Name
The merchants name (e.g. the website
name).
Merchant
Address
The merchants
physical address.
Contact Name
The contact person for the merchant.
Contact Email
The contact persons email address.
Notification
Email
The email address that UseCash will use to notify a merchant of new orders/payments
etc.
Bank Sort
Code
The merchants
bank account sort code.
Bank Account
Number
The merchants bank account number
Bank Account
Name
The name on the merchants bank account
Order Validity
The amount of time an order is valid
for, after which it
cannot be paid
measured in days or
any part thereof.
Email Notifications
Required
Whether the merchant would like to
be informed of their
order's status via email
(this document assumes
this is the expected
option).
Merchant
Image
A link to a small image that the
merchant can specify
to appear on the order
(Optional).
Secret Key
An initial secret text known only
to the merchant and
UseCash
that will allow, if
it is used, the communication
between the UseCash
and the merchants servers
to be signed (Optional).
Once
UseCash
has validated these details
we will contact the merchant
via telephone and provide
them with the following information:
Vendor Name
This is the secret name that the
merchant will use to
access the UseCash
system. It should be
kept secret and not
disclosed to anyone.
VendorPassword
The password the merchant must use
to access the UseCash
servers.
The
merchant is now ready to integrate
their website with the UseCash
system.
Merchant
Website Integration
This
sections
details how the merchant website
can connect to the UseCash
servers to create a customer
order. As there a many ways
that a merchant can have setup
their website we have given
instructions below that cover
the most common integration
tasks, from self-developed
websites to those using sophisticated
shopping cart software and
systems.
Technical
Details
At
it's
simplest, creating a UseCash
order consists of sending
a HTML POST directive
to the UseCash
servers. An example of
the most basic order is
shown below, followed
by an explanation of each
field.
(You
can click here to follow the above link and generate an example
order).
This
contains the minimum information
required to create a UseCash
order.
The following
fields are required
VENDOR NAME
This is the merchants UseCash user name which was provided to them at sign up.
VALUE
The total value of the order to a
maximum value
of €9999.99
CUSTOMER
EMAIL
The email address of the customer,
used to notify
the customer
of the order
status.
VENDOR ORDER
ID
The transaction id for the order
used by the
merchant. The
merchant will
use this id
to identify
the order on
their own system.
Other commonly used optional fields are
CUST NAME
This is the merchants UseCash user name which was provided to them at sign up.
ADDR1
First line of the customers address.
ADDR2
2nd line of the customers address.
ADDR3
3rd line of the customers address.
ADDR4
4th line of the customers address.
ADDR5
5th line of the customers address.
REPLY_URL
A merchant supplied HTML link that we will forward the customer on to when they click the 'Return to Merchant Website' link on the order. Useful for informing your shopping cart software that the an order has been completed to remove purchased items from cart..
CANCEL_URL
A merchant supplied HTML link that we will forward the customer on to if there is a problem with their order.
Optional Signature field
SIGN
This is the sha-1 hash function for
the Order. It
allows UseCash
to verify that
the order is
from the merchant.
Please see the
Order signature
section below
for detail on
how this signature
is generated.
Fields
for future use
COUNTRY
The customers country (default is
Ireland).
TIMEZONE
The customers timezone
(default is
Ireland).
CURRENCY
The customers currency (default is
Euro).
(These
parameters will in
future allow customers
from all over Europe
to buy from the merchants
web site via the UseCash payment network.
Signature
To
increase the security
of the system and remove
any chance of a
un-authorised
person pretending to be
a merchant and creating
bogus orders, the merchant
may opt to use the SIGN
field on the Order creation
message.
This
SIGN field is generated
like this: The values
for the four compulsory
fields are appended, VENDOR_NAME,
VALUE, CUST_EMAIL, VENDOR_ORDER_ID
to a string. Then the
Secret Key for that merchant
is added to the string
and it is processed by
a SHA1 hash function.
(US
Secure Hash Algorithm
1). The result of this hash is then added to the create
order message as the SIGN
parameter.
For
the basic example we used
above, this can be worked
out as so (where “secret”
is the secret key in this
case):
(Click here
to follow the link
to generate an order).
When
the UseCash
servers receive this message
they will also generate
the Sha-1 hash function
using the four parameters
plus the secret key. Then
if the two sha-1 hash
keys match we know that
the order came from that
merchant as only they
and UseCash know the secret key.
All
modern programming languages
provide either an inbuilt
function for generating
the sha1 hash, or have
publicly available libraries
for doing so. Here is
a list of links for the
most common web languages
(Please contact us at
support@usecash.ie if you require assistance):
The
Secret Key can be changed
anytime via the UseCash
Merchant Administration
Website.
Custom
Websites
For
the simplest websites,
UseCash can provide a HTML page that a merchant can drop into
their website. This page
includes a form that the
customer fills in with
their details, name, email
address, physical address
etc..and
includes the order amount
as provide by the merchant.
Once the customer has
entered all their details
they click on the 'Buy
WithUseCash'
Button and they will be
taken to their new order
screen as above in Figure
1.
For
websites that already
gather the required customer
information then they
can simply forward the
details using the UseCash
Order Creation URL above.Including the optional
SIGN parameter as required.
Off-the-shelf/Shopping
Cart Websites
This
section details how to
integrate UseCash
with some of the commonest
website shopping solutions
available. Usually the
integration will be done
by UseCash providing the merchant with a drop-in module for their
shopping cart of choice.
These
modules were developed
either solely by UseCash or in conjunction with the shopping cart developers.
If your website uses a
cart solution that isn't
listed here, please inform
us and we will develop
a plug-in module for it
as soon as possible. These
modules include the SIGN
generation code required
to allow for message signing.
OsCommerce
We
provide a plug-in module
for OsCommerce
based websites. When
you sign up we will
provide a drop-in module
and instructions for
it's
installation. Just follow
the instructions and
UseCash!
VirtuaMart
UseCash also provides a module for Virtua
Mart.
Others
UseCash modules for other shopping carts will be developed
by request.
Email
Notifications
This
sections details the various
notification emails that both
the customer and the merchant
will receive from the UseCash
servers as an order works
it's way through the system.
The
customer will always receive
the email notifications on
the status of their order.
The
merchant will only receive
these emails if they have
defined a valid email address
on the Account Settings page
of the Merchant Administration
Area: https://servers.usecash.ie/merchants.
Merchant
Email Notifications
The
first stage of processing
a UseCash
order is the Order creation
which has been covered
earlier in this document..
Order Creation
When
a new Order is created
on your system and
UseCash
is chosen as a payment
option you will receive
an email similar to
the one in Figure
3 below:
from"system@usecash.ie"
tousecash.vendor@gmail.com
dateNov 1,
2007 3:29 PM
subjectA New Order has been created
with UseCash!
Dear UseCash Ltd,
We have received a New Order on our system of €10.76
from rory@yoda
on 15:29, 1 Nov, 2007 for your order ref: 123456789,
UseCash
order No: 60500
2491 11300 1076
11041 5297
We will notify you when payment is made, or when the
order expires
as per your
settings.
Thank you for using UseCash!
Regards,
The UseCash Team
Payment Received
Once
payment is received
the merchant will
receive an email similar
to that shown in Figure
3 below:
from"system@usecash.ie"
<system@usecash.ie>
tousecash.vendor@gmail.com
dateOct 29,
2007 5:40 PM
subjectPayment for your goods has
been received
by UseCash.
Dear UseCash Demo Shop,
We have received payment of $10.76 from usecash.customer@gmail.com
on 17:40, 29 Oct, 2007 for your order No: 123456789,
UseCash
order No: 60500
2264 49200 1076
10291 8376
We have sent a receipt of payment to the customer and
you should now
forward on the
relevant merchandise.
UseCash will now
transfer the
funds to your
account as per
the terms of
our contract.
Thank you for using UseCash!
Regards,
The UseCash Team
Figure 3: Merchant Payment Notification
Email
As
payment has been received
we now notify the
Customer that we have
received their payment
and we now include
the value of that
order in out payment
processing for the
merchant.
Order
Expired
If
the Customer doesn't
pay the order at a
PayZone
terminal within the
expiration time set
by the merchant then
the order is marked
as expired and a confirmation
email is sent to merchant
as shown in Figure
5 below:
from"system@usecash.ie"
tousecash.vendor@gmail.com
dateOct 30,
2007 1:11 PM
subjectThe Order made through UseCash has Expired without payment.
Dear UseCash Demo Shop ,
The order placed on your website by usecash.customer@gmail.com
valued at €10.76
has now expired
(since Oct 30,
2007 1:00 PM)
and we will
not be accepting
payment for
it.
Your reference number for the Order is '123456789'.
Ours is '60500
2508 71700 1076
10301 3090'.
