1.
Gharpay
REST
API
Documentation
The
Home
page
for
information
about
the
web
services
exposed
by
Gharpay
is:
http://services.gharpay.in
The
documentation
of
the
APIs
can
be
accessed
at
http://services.gharpay.in/resources/Gharpay_REST_API_Documentation.pdf
Please
keep
in
mind
that
this
is
the
pre-­‐production
environment
or
staging
environment.
The
API
methods
currently
exposed
by
Gharpay
are:
• createOrder
• addProductsToOrder
• cancelOrder
• cancelProductsFromOrder
• viewOrderStatus
• viewOrderDetails
• getCityList
• getPincodesInCity
• isCityPresent
• isPincodePresent
• getAllPincodes
Authentication:
Each
request
is
authenticated
by
a
special
username
and
password
provided
to
each
client
by
Gharpay.
These
credentials
must
be
provided
in
the
HTTP
Header
for
each
request.
Sample
Input:
Key:
username
Value:
<username>
Key:
password
Value:<password>
createOrder:
This
service
is
invoked
when
the
client
wishes
to
push
a
new
transaction
order
into
Gharpay's
system.
The
client
needs
to
input
the
following
information
and
Gharpay
returns
with
the
OrderID
created
at
Gharpay's
end
and
(if
provided)
the
Client
Order
ID.
Allowed
Methods:
POST
URL:
http://services.gharpay.in/rest/GharpayService/createOrder
Inputs:
Transaction
Details:
Customer
Details:
• Prefix
(Optional)
–
The
Prefix
to
be
used
when
addressing
the
client.
This
defaults
to
“Mr.”
The
other
allowed
values
are:
Mr.
,
Ms.,
Miss,
Mrs.,
Dr.,
Prof.

2. • FirstName
(Mandatory)-­‐
This
is
the
first
name
of
the
customer.
This
is
a
String
value
with
a
maximum
length
of
255
characters.
• LastName
(Optional)
–
This
is
the
last
name
of
the
customer.
This
is
a
String
value
with
a
maximum
length
of
255
characters.
• ContactNo
(Mandatory)
–
This
is
the
customer's
contact
no.
(
preferably
a
mobile
number).
Gharpay's
payment
executives
shall
call
up
this
number
to
confirm
the
availability
of
the
customer
at
the
given
address.
This
is
a
String
value
with
a
maximum
length
of
255
characters.
• Email
(Optional)
–
If
provided,
the
payment
confirmation
is
sent
to
this
email
ID.
• Address
(Mandatory)
–
This
is
the
complete
billing
address
of
the
customer.
This
is
the
address
which
Gharypay's
payment
executives
will
visit
to
collect
the
cash
payment.
This
is
a
String
value.
Order
Details:
• ProductDetails(Optional,
Repeatable):
o Product
ID:
This
is
the
ID
of
the
product
bought
by
the
customer
for
which
Gharpay
shall
collect
the
payment.
This
is
a
String
value
with
a
maximum
length
of
64
characters.
o Product
Quantity:
This
is
the
quantity
of
the
product
being
booked.
This
is
an
Integer
value.
o Unit
Cost:
This
is
the
cost
per
unit
of
the
product.
This
is
a
Float
value.
• Delivery
Date
(Mandatory):
This
is
the
date
on
which
delivery
is
required.
This
is
a
String
of
the
form
“dd-­‐MM-­‐yyyy”.
For
example,
20th
July
2011
would
be
represented
as
20-­‐07-­‐2011.
• City
Pincode
(Mandatory):
This
is
the
pincode
in
which
the
customer’s
address
is
present.
This
is
a
Long
value
of
6
digits
in
length.
• Order
Amount(Mandatory):
This
is
the
final
value
of
the
product(s)
being
sold.
This
amount
is
inclusive
of
all
commissions
and
charges(if
any).
This
is
the
amount
that
shall
be
collected
from
the
customer.
This
is
a
float
value.
•
Template
ID(Optional):
This
is
the
ID
of
the
template
of
the
receipt
to
be
printed.
If
not
provided,
the
default
template
for
the
client
is
used.
• Client
Order
ID(Mandatory):
This
is
the
ID
used
by
the
client
to
create
the
order
on
their
systems.
This
is
only
for
reference
purposes
to
ensure
that
Gharpay’s
systems
are
in
sync
with
the
client’s
systems.
This
is
a
String
value
with
a
maximum
length
of
64
characters.
Additional
Information
(Optional):
This
tag
is
used
to
convey
any
client
specific
information
that
needs
to
be
pushed
to
Gharpay’s
systems.
• Parameter(Optional,
Repeatable):
o Name:
Name
of
the
parameter.
For
example,
TravelDate.
o Value:
The
value
of
the
parameter
being
defined.
This
is
a
String
value
with
a
maximum
length
of
45
characters.
N.B:
All
Name
tags
need
to
be
registered
with
Gharpay
prior
to
using
this
tag.
Sample
Input:
<transaction>
<customerDetails>
<address>{Customer
Address}</address>
<contactNo>{Customer
Contact
No.}</contactNo>
<!-­‐-­‐Optional:-­‐-­‐>
<email>{Customer
Email}</email>
<firstName>{Customer
First
Name}</firstName>

3. <!-­‐-­‐Optional:-­‐-­‐>
<lastName>{Customer
Last
Name}</lastName>
<!-­‐-­‐Optional:-­‐-­‐>
<prefix>Mr.</prefix>
</customerDetails>
<orderDetails>
<pincode>{Customer
Address
Pincode}</pincode>
<clientOrderID>{Client
Order
ID}</clientOrderID>
<deliveryDate>{Order
Delivery
Date}</deliveryDate>
<orderAmount>{Order
Amount}</orderAmount>
<!-­‐-­‐Zero
or
more
repetitions:-­‐-­‐>
<productDetails>
<productID>{Product
ID}</productID>
<productQuantity>{Product
Quantity}</productQuantity>
<unitCost>{Product
Unit
Cost}</unitCost>
<productDescription>{Description
of
the
product}</productDescription>
</productDetails>
<templateID>{ID
of
the
template
to
be
used
while
printing
receipts}</templateID>
</orderDetails>
<!-­‐-­‐Optional:-­‐-­‐>
<additionalInformation>
<!-­‐-­‐1
or
more
repetitions:-­‐-­‐>
<parameters>
<name>{Parameter
Name}</name>
<value>{Parameter
Value}</value>
</parameters>
<parameters>
<name>{Parameter
Name}</name>
<value>{Parameter
Value}</value>
</parameters>
</additionalInformation>
</transaction>
Output:
• OrderID
generated
by
Gharpay.
This
is
a
String
value.
• Client
Order
ID:
If
the
client
has
provided
the
order
ID
from
their
end,
this
is
also
returned.
This
is
only
for
verification
purposes
to
ensure
that
the
right
Gharpay
ID
is
associated
with
the
order
on
the
client’s
end.
Sample
Output:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<createOrderResponse>
<clientOrderID>{Order
ID
provided
by
the
client}</clientOrderID>
<orderID>{Order
ID
generated
by
Gharpay}</orderID>
</createOrderResponse>
addProductsToOrder:
The
client
can
also
add
multiple
tickets/transaction
requests
to
the
same
order
if
the
order
has
been
created
for
the
customer
earlier
and
the
order
has
not
been
delivered
yet.

4. Allowed
Methods:
POST
URL:
http://services.gharpay.in/rest/GharpayService/addProductsToOrder
Inputs:
Add
Product
Details:
• orderID(Mandatory):
This
is
the
orderID
(generated
earlier
by
Gharpay)
to
which
the
current
product
has
to
be
added.
• orderAmount(Mandatory):
This
is
the
new
order
amount
that
needs
to
be
collected
from
the
customer.
This
is
to
ensure
that
Gharpay’s
systems
are
in
sync
with
the
client’s
systems.
Product
Details
(Mandatory,
Repeatable):
• ProductId(Mandatory):
This
is
the
ID
of
the
product
bought
by
the
customer
for
which
Gharpay
shall
collect
payment.
This
is
a
String
value
with
a
maximum
length
of
64
characters.
• Product
Quantity(Mandatory):
This
is
the
quantity
of
the
particular
being
booked.
This
is
an
Integer
value.
• Unit
Cost(Mandatory):
This
is
the
cost
per
unit
of
the
product.
This
is
a
Float
value.
Sample
Input:
<addProductsToOrder>
<orderAmount>{Final
amount
payable
by
customer
now}</orderAmount>
<orderID>{Order
ID
to
which
the
product
shall
be
added}</orderID>
<!-­‐-­‐1
or
more
repetitions:-­‐-­‐>
<productDetails>
<productID>{ID
of
the
product
to
be
added}</productID>
<productQuantity>{Quantity
of
the
product
to
be
added}</productQuantity>
<unitCost>{Cost
per
unit
of
the
product
being
added}</unitCost>
</productDetails>
</addProductsToOrder>
Output:
Boolean
value
returned
indicating
the
success
or
failure
of
the
operation.
Sample
Output:
Success
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<addProductsToOrderResponse>
<result>true</result>
<orderID>{Gharpay
Order
ID}</orderID>
</addProductsToOrderResponse>
Failure
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<addProductsToOrderResponse>
<result>false</result>
<orderID>{Gharpay
Order
ID}</orderID>
</addProductsToOrderResponse>
cancelOrder:
This
is
the
invoked
when
the
complete
order
needs
to
be
cancelled.
All
products
associated
with
the
order
shall
also
be
cancelled.

5. Allowed
Methods:
POST
URL:
http://services.gharpay.in/rest/GharpayService/cancelOrder
Inputs:
• Order
ID(Mandatory):
This
is
the
ID
of
the
order
(generated
and
returned
earlier
by
Gharpay)
that
needs
to
be
cancelled.
This
is
a
String
value.
Sample
Input:
<cancelOrder>
<orderID>{ID
of
the
order
to
be
cancelled}</orderID>
<cancelOrder>
Output:
Gharpay's
systems
shall
return
a
boolean
result
of
the
operation.
Sample
Output:
Success
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<cancelOrderResponse>
<result>true</result>
<orderID>{Gharpay
Order
ID}</orderID>
</cancelOrderResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<cancelOrderResponse>
<result>false</result>
<orderID>{Gharpay
Order
ID}</orderID>
</cancelOrderResponse>
CancelProductsFromOrder:
This
service
is
invoked
when
only
some
of
the
products
have
to
be
cancelled
from
the
order.
Allowed
Methods:
POST
URL:
http://services.gharpay.in/rest/GharpayService/cancelProductsFromOrder
Inputs:
• Order
ID
(Mandatory):
This
is
the
ID
of
the
order
(generated
and
returned
earlier
by
Gharpay)
from
which
the
product(s
)
have
to
be
cancelled.
This
is
a
String
value.
• Product
ID(Mandatory,Repeatable):
This
is
the
ID
of
the
product
that
needs
to
be
cancelled.
This
is
a
String
value
of
maximum
length
of
64
characters.
Sample
Input:
<cancelProductsFromOrder>
<orderAmount>{Final
amount
payable
by
customer
now}</orderAmount>
<orderID>{Order
ID
to
which
the
product
shall
be
added}</orderID>
<!-­‐-­‐1
or
more
repetitions:-­‐-­‐>
<productId>{ID
of
the
product
being
cancelled}</productId>
</cancelProductsFromOrder>
Output:

6. Gharpay's
system
shall
return
a
boolean
result
of
the
operation.
Sample
Output:
Success
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<cancelProductsFromOrderResponse>
<result>true</result>
<orderID>{Gharpay
Order
ID}</orderID>
</cancelProductsFromOrderResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<cancelProductsFromOrderResponse>
<orderID>{Gharpay
Order
ID}</orderID>
<result>false</result>
</cancelProductsFromOrderResponse>
viewOrderDetails:
This
service
is
invoked
in
order
to
get
details
of
the
order.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/viewOrderDetails
Inputs:
• Order
ID(Mandatory):
The
order
ID
(generated
earlier
by
Gharpay)
for
which
details
are
required.
This
is
a
String
value.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/viewOrderDetails?orderID={Order
ID
provided
by
Gharpay}
Outputs:
viewOrderDetailsResponse:
• Commission:
This
is
the
commission
charged
by
Gharpay
to
collect
payment
for
this
order.
This
is
a
Float
value.
Customer
Details:
• Address:
This
is
the
address
of
the
customer.
This
is
returned
as
a
String
value.
• Contact
No:
This
is
the
contact
number
of
the
customer.
This
is
returned
as
a
String
value.
• Email:
This
is
the
email
of
the
customer.
This
is
returned
as
a
String
value.
• First
Name:
This
is
the
first
name
of
the
customer.
This
is
returned
as
a
String
value.
• Last
Name:
This
is
the
last
name
of
the
customer.
This
is
returned
as
a
String
value.
• Prefix:
This
is
the
prefix
of
the
customer.
This
is
returned
as
a
String
value.
• Delivery
Date:
This
is
the
date
on
which
the
payment
shall
be
collected.
This
is
a
String
value
of
the
format
“dd-­‐MM-­‐yyyy”.
• Executive
Name:
If
the
order
has
been
assigned
to
an
executive,
this
tag
represents
the
name
of
Gharpay’s
executive
who
shall
collect
payment
for
the
customer.
This
is
returned
as
a
String
value.

7. • Executive
Contact
No:
If
the
order
has
been
assigned
to
an
executive,
this
tag
represents
the
contact
details
of
Gharpay’s
executive
who
shall
collect
payment
for
the
customer.
• Order
Status:
This
is
the
status
of
the
order.
Possible
values
are:
Pending,
On-­‐The-­‐Way,
Delivered,
Cancelled
by
Client,
Cancelled
by
Customer,
Failed,
Deferred
By
Customer,
Invalid
Sample
Output:
Success
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<viewOrderDetailsResponse>
<commission>{Commission
being
charged
by
Gharpay}</commission>
<customerDetails>
<address>{Address
of
the
customer}</address>
<contactNo>{Contact
number
of
the
customer}</contactNo>
<email>{Email
ID
of
the
customer}</email>
<firstName>{First
name
of
the
customer}</firstName>
<lastName>{Last
name
of
the
customer}</lastName>
<prefix>{Prefix
of
the
customer}</prefix>
</customerDetails>
<deliveryDate>{Date
on
which
the
order
shall
be
delivered}</deliveryDate>
<executiveContactNo>{Executive’s
contact
number}</executiveContactNo>
<executiveName>{Executive’s
name}</executiveName>
<orderStatus>{Status
of
the
order}</orderStatus>
</viewOrderDetailsResponse>
Failure
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<viewOrderDetailsResponse>
<return/>
</viewOrderDetailsResponse>
viewOrderStatus:
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/viewOrderStatus
This
service
is
invoked
to
get
only
the
status
of
the
order.
Inputs:
• Order
ID(Mandatory):
The
order
ID
(generated
and
returned
earlier
by
Gharpay)
for
which
the
status
needs
to
be
known.
This
is
a
String
value.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/viewOrderStatus?orderID={Order
ID
provided
by
Gharpay}
Output:
• The
status
of
the
order.
Possible
values
are:
o Pending
–
The
order
has
been
received
by
Gharpay’s
systems.
o On
the
way
–
The
order
has
been
assigned
to
our
payment
executive
and
is
on
the
field.
o Delivered
–
The
order
has
been
delivered
successfully
and
Gharpay
has
collected
the
payment.
o Failed
–
The
customer
has
failed
to
respond
despite
repeated
attempts
made
by
Gharpay’s
executives.
In
this
case,
the
exact
reason
is
mentioned
in
the
order’s
comments
section.
o Cancelled
by
Client
–
The
order
has
been
cancelled
by
the
client/merchant.

8. o Cancelled
by
Customer
–
The
customer,
when
contacted
by
Gharpay’s
executive,
expressed
the
intent
to
cancel
the
order.
o Deferred
by
Customer
–
The
end
customer,
when
contacted
by
Gharpay’s
executive,
asked
for
the
delivery/pickup
to
be
deferred
by
a
few
days.
o Invalid
–
The
customer
contact
details
provided
are
invalid
or
the
area
is
not
serviceable
by
Gharpay.
Sample
Output:
Success
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<viewOrderStatusResponse>
<orderStatus>Pending</orderStatus>
<orderID>{Gharpay’s
Order
ID}</orderID>
</viewOrderStatusResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<viewOrderStatusResponse>
<orderID>{Gharpay’s
Order
ID}</orderID>
<orderStatus
/>
</viewOrderStatusResponse>
getCityList:
This
is
invoked
in
order
to
get
a
list
of
the
cities
that
are
currently
being
served
by
Gharpay.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/getCityList
Input:
There
are
no
inputs
that
need
to
be
provided
to
this
service.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/getCityListOutput:
List
of
the
cities
being
served
by
Gharpay.
Sample
Output:
<getCityListResponse>
<city>Hyderabad</city>
<
city
>Chennai</
city
>
<
city
>Mumbai</
city
>
</getCityListResponse>
getPincodesInCity:
This
is
invoked
in
order
to
get
a
list
of
pincodes
in
a
particular
city.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/getPincodesInCity
Input:
• City
Name(Mandatory):
This
is
the
name
of
the
city
for
which
a
list
of
pincodes
is
required.
This
is
a
String
value.

9.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/getPincodesInCity?cityName={Name
of
the
city}
Output:
Successful
output:
List
of
pincodes
being
served
in
the
city.
All
values
are
6
digit
Long
values.
Unsuccessful
output:
Error
Response
detailing
the
reason
for
failure.
Sample
Output:
Success
Scenario:
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<getPincodesInCityResponse>
<pincode>500008</pincode>
<pincode>500084</pincode>
</getPincodesInCityResponse>
Failure
Scenario:
<getPincodesInCityResponse>
<errorCode>3031</errorCode>
<errorMessage>Sorry,
we
currently
don't
serve
this
city.</errorMessage>
</getPincodesInCityResponse>
isCityPresent:
This
is
invoked
in
order
to
check
if
Gharpay's
operations
are
present
in
a
particular
city.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/isCityPresent
Input:
• City
Name(Mandatory):
This
is
the
name
of
the
city
that
needs
to
be
checked.
This
is
a
String
value
of
maximum
length
45
characters.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/isCityPresent?cityName={Name
of
the
city}
Output:
A
Boolean
result
is
returned.
True
if
the
city
is
present,
false
otherwise.
Sample
Output:
Success
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<isCityPresentResponse>
<result>true</result>
</isCityPresentResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<isCityPresentResponse>
<result>false</result>
</isCityPresentResponse>

10.
isPincodePresent:
This
service
is
invoked
to
check
if
Gharpay
serves
a
particular
pincode.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/isPincodePresent
Inputs:
• City
Pincode(Mandatory):
This
is
the
pincode
that
needs
to
be
checked.
This
is
a
6
digit
Long
value.
Sample
Input:
http://services.gharpay.in/rest/GharpayService/isPincodePresent?pincode={City
Pincode}
Output:
The
service
returns
a
Boolean
value
stating
if
Gharpay
serves
the
pincode
or
not.
Sample
Output:
Success
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<isPincodePresentPresentResponse>
<result>true</result>
</isPincodePresentPresentResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<isPincodePresentPresentResponse>
<result>false</result>
</isPincodePresentPresentResponse>
getAllPincodes:
This
is
invoked
to
retrieve
a
complete
list
of
pincodes
that
are
currently
serviced
by
Gharpay.
Allowed
Methods:
GET
URL:
http://services.gharpay.in/rest/GharpayService/getAllPincodes
Sample
Input:
http://services.gharpay.in/rest/GharpayService/getAllPincodes
Output:
A
list
of
all
pincodes
will
be
returned
Sample
Output:
Success
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<getAllPincodesResponse>
<pincode>500008</pincode>

11. <pincode<560001</pincode>
</getAllPincodesResponse>
Failure
Scenario
<?xml
version="1.0"
encoding="UTF-­‐8"
standalone="yes"?>
<getAllPincodesResponse>
<errorCode>4002</errorCode>
<errorMessage>Invalid
client
credentials</errorMessage>
</getAllPincodesResponse>
Push
Notifications
In
case
real
time
updates
of
order
status
is
required,
the
facility
of
push
notifications
can
be
utilized.
A
notification
is
sent
to
the
client
server
every
time
the
status
of
any
order
is
updated.
The
client
can
then
hit
the
viewOrderStatus
API
or
the
viewOrderDetails
API
to
retrieve
the
latest
status
associated
with
this
order.
The
possible
statuses
of
an
order
on
Gharpay’s
servers
are:
o Pending
–
The
order
has
been
received
by
Gharpay’s
systems.
o On
the
way
–
The
order
has
been
assigned
to
our
payment
executive
and
is
on
the
field.
o Delivered
–
The
order
has
been
delivered
successfully
and
Gharpay
has
collected
the
payment.
o Failed
–
The
customer
has
failed
to
respond
despite
repeated
attempts
made
by
Gharpay’s
executives.
In
this
case,
the
exact
reason
is
mentioned
in
the
order’s
comments
section.
o Cancelled
by
Client
–
The
order
has
been
cancelled
by
the
client/merchant.
o Cancelled
by
Customer
–
The
customer,
when
contacted
by
Gharpay’s
executive,
expressed
the
intent
to
cancel
the
order.
o Deferred
by
Customer
–
The
end
customer,
when
contacted
by
Gharpay’s
executive,
asked
for
the
delivery/pickup
to
be
deferred
by
a
few
days.
o Invalid
–
The
customer
contact
details
provided
are
invalid
or
the
area
is
not
serviceable
by
Gharpay.
In
case
such
a
notification
is
required,
please
expose
a
URL
of
the
form
–
http://some/url/notification.xyz?order_id=<order
id>&time=<time>
where
• <order
id>
is
the
Gharpay
order
ID
returned
while
creating
the
order
id
• <time>
is
in
the
format
YYYY-­‐MM-­‐DD
HH:MM:SS
For
example,
http://some/url/notification.xyz?order_id=GW-­‐xxx-­‐0000xxx-­‐xxx&time=2011-­‐09-­‐08+13%3A59%3A20
Gharpay’s
servers
will
make
HTTP
GET
requests
to
this
URL.
Please
note
that
we
currently
do
not
support
any
form
of
authentication
for
this.
In
case
there
is
a
need
to
secure
this
URL,
Gharpay
can
provide
possible
whitelisted
IPs
from
where
Gharpay
shall
make
the
requests.