Developer Starter Guide
Developer Starter Guide
Version 1.1.3
1
Table of contents
Introduction ......................................................................................................................... 4
Static Payment iFrame ........................................................................................................ 5
Overview............................................................................................................................ 5
Getting started, a step-by-step walkthrough ....................................................................... 6
Merchant account registration ........................................................................................ 6
Define your site .............................................................................................................. 7
URL Settings .................................................................................................................. 8
Set-up products on the HiPay Mobile merchant back-office ............................................... 9
Add a product ................................................................................................................. 9
Geographies, payment methods, prices ........................................................................10
Edit a product ................................................................................................................11
Install your product ........................................................................................................12
Full UI integration ...............................................................................................................15
Overview...........................................................................................................................15
Getting started ..................................................................................................................15
Building the purchase experience .....................................................................................15
Retrieve the billing information applicable to the end-user .............................................16
Access Code redemption ..............................................................................................16
Process Payments received ..............................................................................................17
Overview...........................................................................................................................17
Unlock your protected content ..........................................................................................17
Call HiPay Mobile from the Product Access URL to verify transactions .............................18
Receive a call from HiPay Mobile to your Notification URL ............................................19
API Basic implementation..................................................................................................22
Overview...........................................................................................................................22
What is an API?.............................................................................................................22
Who may use this API? .................................................................................................22
Knowledge and skills .....................................................................................................22
Method "GET onetime/pricing" ..........................................................................................22
Method “Post onetime/validate-codes” ..............................................................................25
2
Response ......................................................................................................................26
Signature verification .........................................................................................................28
Check the signature of a notification .................................................................................28
Signature verification example.......................................................................................29
Testing ................................................................................................................................30
Virtual bank card (only for One-Time Dynamic products) .................................................30
Test codes ........................................................................................................................30
Free codes (only for One-Time Fixed products) ................................................................31
More questions?.................................................................................................................31
3
Introduction
Description
In this document, we outline several different approaches to integrating
HiPay Mobile payments on your website.
Parts of an HiPay
Mobile integration
There are two main parts to an HiPay Mobile integration:

The Purchase Page: The web interface by which your end-users
pay you

Transaction processing of a successful payment: The confirmation
that you receive from HiPay Mobile that a purchase transaction has
succeeded.
You have a lot of flexibility in deciding how to integrate HiPay Mobile.
Diagram
There are three different ways to integrate HiPay Mobile into your
purchase page, and three different ways to process received payments.
Possible associations between types of integration and ways of
processing successful payments (sorted by complexity)
Finding
Making the best choice of integration for your business will highly impact
the success of your payment strategy.
Recommendation
It is strongly recommended to read this document before diving into
the details of the HiPay Mobile API.
Aim of the
document
Here you will learn how to make a Static iframe and Full UI integration, to
know how to integrate a dynamic iframe using our SDK and the advanced
HiPay Mobile API please refer to the HiPay Mobile API Developer
Reference Manual.
4
Static Payment iFrame
Overview
Features



Prerequisites

The easiest way to offer any or all payment methods, with no
coding effort
Supports a wide number of payment methods in an integrated
user experience
End-users are only presented with the payment methods
available in their country
Ability to edit your website's HTML source code
User
Experience
Image 1: Example of an HiPay Mobile purchase iframe
5
Getting started, a step-by-step walkthrough
Merchant account registration
Introduction
In order to use HiPay Mobile, you will need to set up an HiPay Mobile
account.
It’s a simple process which can be completed online.
Procedure
To set up an HiPay Mobile account, proceed as follow:
Steps
Action
1
Go to www.hipaymobile.com,
2
Click “START NOW”, and follow the instructions.
3
Once you’ve set up your HiPay
https://merchant.hipaymobile.com and login.
Mobile
account,
go
to
Once you’re logged in, you’ll see the “Dashboard” screen below.
4
6
Define your site
Procedure
(continuation)
Steps
Action
Go to “Products -> New site” to define your site
5
Fill all required information and click “Save”.
6
 The “Site” information is used to distinguish between multiple
websites in your HiPay Mobile account.
7
Steps
Action
Note: The IDSITE is under your site name on the "Sites & Products"
page.
You will need it later during your integration.
7
URL Settings
Description
HiPay Mobile needs to be able to redirect to some of your pages for events
such as payment success, payment errors or to send call-back
notifications. If you set your URLs in your site configuration they will be
pre-filled by default on all new product created inside the site.
URL list
URL
Description
Purchase URL
The purchase page where you intend to embed the
HiPay Mobile iframe or display a payment button.
Product
access URL
HiPay Mobile will redirect to this page after a
successful purchase.
Error URL
HiPay Mobile will redirect to this page when an error
occurs. If you leave this blank, the default HiPay
Mobile error page will be used.
Notification
URL
HiPay Mobile will call this URL upon successful
purchase (see “Call HiPay Mobile from the Product
Access URL to verify transactions” section)
8
Set-up products on the HiPay Mobile merchant backoffice
Add a product
Procedure
To set up products on HiPay Mobile merchant back office, proceed follow:
Steps
Action
From the "Sites & Products" page, click on "Add Product" on the right of
your site information line.
1
Select the product type based on the following table:




2



Recommend (One-Time Fixed): HiPay Mobile will select for you
the best price points in each country for any one-time purchase
based on a price range.
Manual (One-Time Fixed): You will be able to choose among a
wide range of different price points and filter them for any one-time
purchase.
One-Time Dynamic: Fix by yourself the price you want to display to
your customers. HiPay Mobile provides a wide choice of payment
solutions in each country for any one-time purchase (except
Premium Text Message and IVR).
Subscription: Set up the amount and the frequency of billings
made by your customers. All our subscriptions are automatically
renewed. Available for Mobile Payment and ISP Billing.
Old Subscription: Decide the frequency and the amount charged
to your customers by using credit card and prepaid card. You will be
redirected to the previous version of the interface.
Virtual Currency: Create your virtual currency with our payment
scripts. Enter the exchange rate of your virtual currency and
customise the script with your own style. You will be redirected to
the previous version of the interface.
Pay-Per-Minute: Your customer is on the phone with a vocal server
for the whole duration of his call. Once he hangs up, he has no
longer access to content. You will be redirected to the previous
version of the interface.
9
Steps
Action
Choose the desired price points and fill your product information:
3
Note: URL Settings will be pre-filled if you have already specified them
in your site configuration.
Geographies, payment methods, prices
Description
HiPay Mobile is designed to ease the pricing of your products in multiple
geographies. When you set up a product on the HiPay Mobile platform,
you choose the payment methods you want and set the prices in each
country.
The end user in any given country will automatically be presented (using
10
IP-based geolocation) with those payment methods at the prices you have
selected.
Edit a product
Procedure
To edit products on HiPay Mobile merchant back office, proceed as follow:
Steps
Action
1
From the "Sites & Products" screen, click on your site name and then on
“Edit product” at the right of your product.
11
Steps
Action
Select the desired payment methods and price-points in the list on your left,
change product name, filter price points or change URL Settings.
2
3
Click “Next”.
As explained on the website, some payment methods/geographies may
only be available on request after our Customer Support team confirms
that your service complies with the relevant Terms of Use. After selecting
this price point, please contact us by email at contact.mobile@hipay.com
so that we can activate it on your site.
Note
Install your product
Procedure
To obtain the html code to install your product, proceed as follow:
Steps
Action
1
From the "Sites & Products" screen, click on your site name and then on
“Install product” at the right of your product.
12
Steps
Action
Choose between



The Checkout script URL if you want to call directly the payment
page.
The iframe script if you want to show the HiPay Mobile payment
script in an internal iframe in your page.
The ready-made html code for a payment button (Checkout button)
that pops-up a modal box.
2
Payment
parameters
The payment URL accepts the following GET parameters
Status
Parameter
Description
Example
mandator
y
ids
Your site ID as set up in your 12345
HiPay
Mobile
merchant
account
13
Status
Parameter
Description
Example
mandator
y
idd
Your product ID as set up in 67890
your HiPay Mobile merchant
account
optional
data
Custom merchant data.
optional
merchant_transaction_id
The transaction ID used by IN1237123
the merchant.
optional
country
ISO country code so that you FR
can set the iframe to a
specific country (ignoring
geolocation).
optional
carousel
Can be set to row or col row
depending on whether you
want to show the list of
payment methods in rows or
in columns. Default is row.
optional
forward_target
Window target for the forward parent
to the product page at the
end of the transaction.
MyClientId
Can be set to parent or
current
optional
bundle_purchase
Hide the drop-down menu to 0
buy bundle of codes, if 0 the
script will always let the user
buy only one code at a time.
optional
access_form
Hide the validate code form 0
in the HiPay Mobile payment
window. If used, you must
create your own validate
code form in your site.
Refer
to
Method“POST
onetime/validate-codes”
optional
Note
button_url
You can enter your own
image for your payment
button, only specifies the
complete URL to the image in
this field.
http://www.
mysite.com/
mypayment
button.png
HiPay Mobile handles availability of payment methods in the
end-user's country of origin (IP geolocation) and provides an
integrated UI accordingly.
14
Full UI integration
Overview
Introduction
The fully integrated UI approach is based on access code redemption and
currently supports only SMS and Home phone billing.
Features


Full control over the UI (no iframe)
Moves the purchase experience away from the browser (e.g. ingame payments)
Prerequisites

Server-side coding with ability to make GET and POST http calls
(for example, PHP with curl extension)
Available for SMS and Home phone payment methods only

Getting started
Introduction
The set-up for this integration is the same as for the static iframe
integration.
Procedure
Namely, you need to:


Reference
open an HiPay Mobile merchant account and
create your products.
Please refer to the section Static payment iframe for detailed information
about these items.
Building the purchase experience
Introduction
The end-user is presented with a purchase page containing the following
information:



Product description and price
Phone billing instructions (SMS and/or Home phone). An Access
Code is provided offline by HiPay Mobile on successful purchase
A text field for Access Code redemption
15
Below are the steps to achieving this full integration:
Retrieve the billing information applicable to the end-user
Question
How may I bill my end-user, based on IP geolocation and based on my
target price?
Method used
As SMS and Home phone billing are based on static price points, this is
done using the onetime/pricing API method.

This API outputs the list of prices available to bill the end-user.
It is up to you to make an automatic price point selection.
This usually requires that the website operates a database of products with
relevant pricing information.

The API also outputs the end-user instructions, in compliance with
requirements of local authorities, in each of the markets that we
cover.
Recommandation
For compliance reasons, it is mandatory that you display these enduser instructions on your payment page.
Failure to do so may result in service interruption. These instructions
may be updated without prior notice.
Conclusion
These instructions allow the end-user to buy an Access Code offline over
the phone, making this integration especially suitable for in-game
purchases.
Access Code redemption
Description
End-users need to be able to redeem their Access Code on your website.
Process
The HiPay Mobile API enables you to validate Access Codes with the
onetime/validate-codes method.
This API method outputs the status of the code.
When the Access Code is validated, the merchant account is credited and
the product can be safely delivered to the end-user.
Reference
To learn more about these API methods, please refer to the API Basic
implementation section.
16
Process Payments received
Overview
Introduction
The HiPay Mobile platform offers 3 different ways of processing payments
received.
Unlock your protected content

Features
Benefits
Procedure

Upon payment success, users are redirected to a JavaScriptprotected URL that they were previously unable to access.
Suitable for content monetization only.



No coding involved. Fast and easy.
Casual protection.
Access to content is granted instantaneously after purchase.
To obtain securisation html code, proceed as follow:
Steps
Action
You define the Product Access URL when you create a Product in your
HiPay Mobile account.
1
This is where your protected content is located.
Please refer to the URL Settings paragraph in the “Getting started, a stepby-step walkthrough” section.
2
To limit the access of this page to paying users, add some JavaScript to
your page and to any linked page that needs to be protected.
From the "Sites & Products" screen, click on your site name and then on
“Install product” at the right of your product.
3
5
The script that you need to use is located in Step 2: Securing your product
page.
Copy and paste it to your html page(s) right after the <head> tag.
17
Steps
Action
Call HiPay Mobile from the Product Access URL to
verify transactions
Features

Paying users are redirected to the Access URL where you call
HiPay Mobile to verify the transaction
Benefits

Payment is credited synchronously. You can deliver your
product/service instantaneously
Robust multi-purpose integration

Step-by-step
walkthrough
After a successful purchase, the end-user is redirected to a Product
Access URL confirming proper payment.
HiPay Mobile passes to that page some GET parameters described as
follows:
Parameter
Description
data
Custom data that was initially passed to the
payment iframe.
code
HiPay Mobile access code.
trxid
HiPay Mobile ID of the transaction
merchant_transaction_id Optional merchant transaction ID initially
passed to the payment iframe.
codes
same as code [deprecated and only intended
for backward compatibility]
DATAS
same as data [deprecated and only intended
for backward compatibility]
With this information you can call the transaction API method and obtain
detailed information about the transaction, please refer to the HiPay Mobile
- API Reference documentation for more information.
18
Receive a call from HiPay Mobile to
your Notification URL
Features

HiPay Mobile sends a call back to a Notification URL set-up by the
merchant to process transaction details
Benefits

Payment is credited asynchronously. You can deliver your
product/service in the background without disrupting the user
experience.
Robust multi-purpose integration

Step-by-step
walkthrough
If your products are managed on the HiPay Mobile merchant account, the
notification URL is defined when you create a Product in the HiPay Mobile
merchant account. Please refer to the Payment URLs paragraph in the
Static payment iframe section.
After a successful purchase, HiPay Mobile immediately calls your
Notification URL in the background with comprehensive information about
the payment passed through GET parameters.
A signature verification mechanism ensures that the notification comes
from the HiPay Mobile server. The list of parameters and the signature
validation process are documented in the Signature Verification section.
Response
The following table lists the parameters returned to the merchant URL.
Parameter
Description
Example
action
Describes the type of event
for which we notify.
payment-confirm
test
Allows merchant to identify
test transactions.
true or false
transaction_id
Unique ID for the HiPay
Mobile transaction.
0c92578d-3143-4bd8aeae-72f2455e2499
status
Status of the transaction.
0
Please refer to actions
table below.
Please refer to status
table below.
status_description
Description of the status of
the transaction.
Success
access_type
Product type
onetime
19
Parameter
Description
Example
date
Transaction date
2010-1215T16:09:57+00:00
code
HiPay Mobile code used
XXXXXXXX
pricepoint_id
Pricepoint Id used
206
type
Payment method
premium-sms
data
Custom merchant data
provided when making
payment request.
Widget592
merchant_
IN1237123
transaction_id
The transaction ID used by
the merchant.
amount
Amount of the transaction.
10.00
The currency is determined
by the price point identifier.
paid
Amount actually paid by the
customer in currency.
10.00
currency
Local currency for the
transaction.
EUR
payout_amount
Amount of the merchant
payout in payout currency
6.18
payout_currency
Payout currency for the
transaction
EUR
reference_currency
Base currency (EUR is
default).
USD
reference_amount
Amount of the transaction in
base currency
14.79
reference_paid
Amount actually paid by the
customer in base currency
14.79
reference_payout
Amount of the merchant
payout in base currency
9.14
customer_country
Country code of the
customer.
FR
This two-letter code complies
with ISO-3166.
site_id
Identifier of the merchant site.
123456
20
Parameter
Description
Example
product_name
The name of the product
where the code was used
My New Product
carrier
Optional: Carrier information
if available
Orange
msisdn
Optional: MSISDN
information if available
0612345678
code_creation_date
Optional: Code creation date
if available.
2013-0718T13:05:38+00:00
api_key
Merchant API key
cfd3b9a6b7b309c06aa5
3f5527c96e67
api_ts
UNIX Timestamp (GMT)
1258691527
api_hash
Hash function to use for
signing: md5 or sha1. (SHA-1
is default)
sha1
Signature
fb1bab50fd2c3751dab07
b35…
api_sig
md5
Example
URL
notification
Example
http://your-domain.com/hipay_notification.php?action=paymentconfirm&test=true&transaction_id=2ae1116c-57b2-4707-9d237aba0211050b&status=0&status_description=success&access_type=onetimedynamic&date=2010-1215T16%3A09%3A57%2B00%3A00&code=XXXXXX&pricepoint_id=206&data=&merchant_transacti
on_id=&amount=3&paid=0&currency=EUR&payout_amount=0&payout_currency=EUR&referenc
e_currency=EUR&reference_amount=3&reference_paid=0&reference_payout=0&customer_c
ountry=IL&site_id=127042&api_key=9696ba35ebb3dc6c11c964c269f262a6&api_ts=1292429
411&api_hash=md5&api_sig=8217c0e1bb35eb6a51df5a5b150b1d0f
Action
Code
Description
payment-confirm
Success transaction
payment-renewal
Subscription success renewal
payment-error
Payment error
payment-chargeback
Chargeback on payment
subscription-cancellation
Subscription cancellation
Status codes
Code
Description
Example
21
0
Success
Payment accepted
1
Error
Insufficient funds
5
Charged back transaction
Chargebacked
API Basic implementation
Overview
Introduction
HiPay Mobile provides access to key features of its payment engine
through an API or Web Service.
What is an API?
Description
An API (Application Programming Interface) is a library of functions or
procedures to develop applications.
Who may use this API?
Description
This API is opened to all merchants who wish to dynamically integrate the
HiPay Mobile payment solution in their sites or applications.
This document is specifically aimed to developers.
Knowledge and skills
The HiPay Mobile API requires that the user is familiar with the following:



Basic understanding of Web Services (http://www.w3schools.com/webservices),
Manipulating an XML document (http://www.w3schools.com/xml)
Mastery of a programming language allowing the use of Web Services.
Note
To learn more about these API methods, or for an advanced
implementation, please refer to the HiPay Mobile API Developer
Reference Manual.
Method "GET onetime/pricing"
22
Description
Returns the list of static price points available for a product or a website in
XML format.
Goal of this
method
This method is used to obtain the list of price points supported by the
HiPay Mobile API, each price point being set for a payment method, a
country and a user price.
It returns a list of supported countries and detailed information for each
available price point.
URL
https://payment.allopass.com/api/onetime/pricing.apu
HTTP Method
GET
Parameters
Status
Parameter
Type
Description
mandatory
site_id
integer
Identifier of the merchant site.
optional
product_id
integer
Product identifier (for one-shot
micropayment).
optional
country
string
Filters the list of price points by
country (expecting ISO-3166compliant
two-letter
country
codes).
optional
type
string[]
Filters the list of price points by
payment type.
For a list of payment types, see
Appendix 1 "Payment types"
optional
customer_ip
inet
If the customer IP address is
specified, the country of the
customer
is
identified
via
geolocation.
optional
only4ip
boolean
Geolocates the customer_ip and
filters the list of price points for the
identified country.
optional
reference_currency
string
Base currency (EUR is default).
Example request
Request URL
Example
https://payment.allopass.com/api/onetime/pricing.apu?site_id=123456&product_id=6
54321
23
Response
Parameter
Description
Example
creation_date
Date of server reply (GMT).
2009-0830T12:04:21+00:00
customer_ip
If the customer IP address is 83.167.62.196
specified, the country of the
customer is identified via
geolocation.
customer_country
Country code of the customer.
US
The country is automatically
detected from the IP address
of the customer (if provided).
This two-letter code complies
with ISO-3166.
countries
List of supported countries.
markets
List of price points available
per country.
Sample response
Code Example
<?xml version="1.0" encoding="utf-8" ?>
<response xmlns="https://api.allopass.com/rest"code="O" message="OK">
<creation_date timestamp="1251633861" date="2009-08-30T12:04:21+00:00" />
<customer_ip>83.167.62.196</customer_ip>
<customer_country>FR</customer_country>
<countries>
<region name="Europe">
<country code="FR" name="France"/>
</region>
<region name="NorthAmerica">
<country code="US" name="UnitedStates"/>
</region>
</countries>
<markets>
<market country_code="FR" country="France">
<pricepoint id="2"code="FR" type="premium-calling">
<price currency="EUR" amount="1.80"
exchange="1.0000000" reference_currency="EUR" reference_amount="1.80"/>
<buy_url>
<![CDATA[https://payment.allopass.com/acte/audiotel/purchase.apu?ids=123456&idd=
654321]]>
</buy_url>
<phone_numbers>
<phone_number value="08 99 19 01 13">
<description>
<![CDATA[
Pour recevoir votre code, appelez le :<br />
<span class="phone-number">08 99 19 01 13</span>
]]>
</description>
</phone_number>
</phone_numbers>
<description>
<![CDATA[
La communication vous sera facturée :<br /> 1,34€/appel + 0,34€/min.
depuis
une ligne fixe.<br />Obtention du code en < 1,30 min. - coût : 1,80€
]]>
</description>
</pricepoint>
</market>
<market country_code="US" country="UnitedStates">
<pricepoint id="166" code="US" type="premium-sms">
<price currency="USD" amount="3.99"
24
exchange="1.4788000" reference_currency="EUR"reference_amount="2.70"/>
<buy_url>
<![CDATA[https://payment.allopass.com/acte/sms/purchase.apu?ids=123456&idd=65432
1]]>
</buy_url>
<keywords>
<keyword name="ALL" shortcode="44536" operators="*"number_billed_messages="1">
<description>
<![CDATA[
To receive an access code<br />on your mobile phone, send<br />
<span class="keyword">ALL</span> to <span class="shortcode">44536</span>
]]>
</description>
</keyword>
</keywords>
<description>
<![CDATA[
$ 3.99/SMS – Standard text messaging rates apply<br />
Info at 1-877-524-8532
]]>
</description>
</pricepoint>
</market>
</markets>
</response>
Structure of a “pricepoint”
Parameter
Description
price
End-user price
currency : local currency in which the end-user is billed
amount : amount of the transaction
exchange : exchange rate of the day
reference_currency : base currency (euro is default)
reference_amount : amount of the transaction in base
currency
buy_url
Buy URL for the customer (Not Applicable when not
utilizing a product_id along with the following payment
methods: MPME, Mikro-Odeme and SMS US WO)
description
Pricepoint description
Method “Post onetime/validate-codes”
Description
Validate access codes.
Goal of this
method
This method is used to validate “manually” the HiPay Mobile codes
generated after a payment.
The codes will be validated and destroyed after using this method. You will
receive an XML response with the details of the transaction, you have
then, to treat this response and redirect the user to the page/content he
paid for.
URL
https://payment.allopass.com/api/onetime/validate-codes.apu
25
HTTP Method
POST
Parameters
Status
Parameter
Type
Description
mandatory
site_id
integer
Identifier of the merchant site.
mandatory
product_id
integer
Identifier of a product.
mandatory
code
string[]
Access code(s)
optional
merchant_transaction
_id
string
Transaction ID used by the
merchant.
optional
data
string
Custom data.
optional
ap_ca
string
Partner code.
optional
ap_ca_idc
integer[]
Partner ID.
optional
ap_ca_mnt
string[]
Partner revenue share (in %).
optional
ap_ca_map
integer[]
Affiliate program ID.
optional
customer_ip
inet
Customer IP address.
optional
reference_currency
string
Base currency
default).
(EUR
is
Example request
Code Example
<form action="https://payment.allopass.com/api/onetime/validate-codes.apu"
method="post">
<input type="hidden" value="xxxxxx" name="site_id">
<input type="hidden" value="yyyyyy" name="product_id">
<input type="text" name="code[]" value="zzzzzzzz">
<input type="text" name="merchant_transaction_id" value="MyTransactionId">
<input type="text" name="data" value="MyPersonalData">
<input type="submit" value="send">
</form>
Response
Parameter
Description
Example
status
Status code.
0
status_description
Status description.
Success
26
Parameter
Description
Example
access_type
Access type of the product.
Onetime
transaction_id
Identifier of the transaction.
0c92578d-31434bd8-aeae72f2455e2499
price
Information about the transaction
price.
The reference_amount attribute is
the price of the transaction in the
currency and exchange rate
specified in the currency and
exchange attributes.
paid
Amount actually paid
customer in currency.
by
the
The reference_amount attribute is
the price of the transaction in the
currency and exchange rate
specified in the currency and
exchange attributes.
validation_date
Date
the
validated.
product_name
Name of the product.
website
Information on the website on
which the product is valid.
customer_ip
Customer IP address.
83.167.62.196
customer_country
Country code of the customer.
FR
code(s)
was/were 2009-0611T08:23:10+00:
00
MY PRODUCT
This two-letter code complies with
ISO-3166.
expected_number_of
_codes
Number of codes required to 1
access the product (from 1 to 5).
codes
List of access codes for this
transaction.
merchant_transaction
_id
The transaction ID used by the
merchant.
data
Custom merchant data.
affiliate
Partner code
program.
partners
List of partners defined by the
merchant.
via
an
affiliate
27
Sample response
Code Example
<?xml version="1.0" encoding="utf-8" ?>
<response xmlns="https://api.allopass.com/rest"code="O" message="OK">
<status>0</status>
<status_description>success</status_description>
<access_type>onetime</access_type>
<transaction_id>0c92578d-3143-4bd8-aeae-72f2455e2499</transaction_id>
<price currency="EUR" amount="3.60"
exchange="1.0000000" reference_currency="EUR" reference_amount="3.60" />
<paid currency="EUR" amount="3.60"
exchange="1.0000000" reference_currency="USD" reference_amount="3.60" />
<validation_date>2009-06-11T08:23:10+00:00</validation_date>
<product_name><![CDATA[SPARE CHANGE TOPUP]]></product_name>
<website id="123456" name="MY-WEBSITE.COM" url="http://my-website.com" />
<customer_ip>83.167.62.196</customer_ip>
<customer_country>FR</customer_country>
<expected_number_of_codes>2</expected_number_of_codes>
<codes>
<code value="5MHE5939">
<pricepoint id="2"code="FR"type="premium-calling"/>
<price currency="EUR"amount="1.80"
exchange="1.0000000" reference_currency="EUR"reference_amount="1.80"/>
<paid currency="EUR"amount="1.80"
exchange="1.0000000" reference_currency="EUR"reference_amount="1.80"/>
<payout currency="EUR"amount="1.00"
exchange="1.0000000"reference_currency="EUR" reference_amount="1.00"/>
</code>
<code value="6Q5GF542">
<pricepoint id="2"code="FR"type="premium-calling"/>
<price currency="EUR"amount="1.80"
exchange="1.0000000" reference_currency="EUR"reference_amount="1.80"/>
<paid currency="EUR"amount="1.80"
exchange="1.0000000" reference_currency="EUR"reference_amount="1.80"/>
<payout currency="EUR"amount="1.00"
exchange="1.0000000"reference_currency="EUR" reference_amount="1.00"/>
</code>
</codes>
<merchant_transaction_id><![CDATA[20090611-69784535]]></merchant_transaction_id>
<data><![CDATA[userid=1981&login=username@host.com]]></data>
<affiliate>X058G469879E5</affiliate>
<partners>
<partner id="12397654" share="10" map="" />
</partners>
</response>
Status codes
Code
Description
Example
0
Success
Access code validated.
1
Failed
Validation failed.
Signature verification
Check the signature of a notification
Description
A unique signature is sent (api_sig) each time that HiPay Mobile contacts a
merchant page.
28
Verification of
the signature
To verify this signature, you will need your API Secret Key.
Find the Secret You will find this key in your HiPay Mobile back office under the
Key
« Toolbox » category.
Signature verification example
Example in
PHP
<?php
$parameters = $_GET;
$signature = $parameters['api_sig'];
unset($parameters['api_sig']);
ksort($parameters);
$secretKey
= ''; // fill here with your personal secret key
$string2compute = '';
foreach ($parameters as $name => $value) {
$string2compute .= $name . $value;
}
// true if OK, false if not
// if you are using md5 instead of sha1 please replace
if (sha1($string2compute . $secretKey) == $signature) {
$code
= 0;
$message = 'OK';
}
else {
$code
= 1;
$message = 'KO';
}
header('Content-Type: text/xml; charset=UTF-8');
echo '<?xml version="1.0" encoding="UTF-8" ?>';
?>
<response status="1">
<code><?php echo $code; ?></code>
<message><?php echo $message; ?></message>
</response>
29
Testing
Virtual bank card
(only for One-Time Dynamic products)
Description
HiPay Mobile lets you use a virtual bank card to test your payments; you
will find it in your HiPay Mobile back office under the « Toolbox » category.
This virtual bank card number allows you to purchase YOUR products for
test purposes.
Note
Test credit card number is only valid for discrete price points
(payments up to 60€). You cannot use it for fixed price points.
Test codes
Description
To facilitate the testing of your integration, for each product set up on the
HiPay Mobile merchant account, you can specify a test code that will
always lead to an unbilled, successful transaction.
Code security
It is your responsibility to use strong enough test codes that won’t be
easily guessed or brute-forced by the end-user.
Note
The Test codes don’t send any notification to your notification URL, if you
want to test the notifications, please test them with Free Codes.
30
Free codes (only for One-Time Fixed products)
Description
Free codes are more sophisticated than test codes as they are meant to
behave more like real codes.
Their validity can be adjusted by duration or number of uses, so they can
be used for customer support as well.
Free code
You can generate free codes on your HiPay Mobile back office under the
« Toolbox » category.
Note
Please note that these free codes are tied to specific product IDs.
When using the API to generate transactions that are not associated
with product IDs, you need to select “Generic Product” in the dropdown list.
More questions?
Contact our Merchant support at: contact.mobile@hipay.com or visit our Support center
at http://help.hipay.com/mobile.
31
32
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising