Onebip API

Mobile Payment System
Web and Mobile
Integration Guide 3.8.4

Index
THIS DOCUMENT ............................................................................................................................................. 3

INTENDED AUDIENCE..................................................................................................................................... 3
NOTICE OF NON-LIABILITY ............................................................................................................................ 3
1 INTRODUCTION....................................................................................................................................... 4
1.1 ONEBIP PRESENTATION ....................................................................................................................... 4
1.2 ONEBIP PAYMENT SYSTEMS AND FLOWS ............................................................................................. 4
I. STANDARD FLOW .................................................................................................................................... 164
II. EXPRESS FLOW ........................................................................................................................................... 5
2 REGISTRATION AND SET-UP ................................................................................................................ 9

2.1 ACCOUNT CREATION ........................................................................................................................... 9
2.2 PAYMENT & COUNTRY ENABLING ......................................................................................................... 9
2.3 BASIC MERCHANT INFORMATION ........................................................................................................ 10
3 MOBILE PAYMENTS INTEGRATION ................................................................................................... 11

3.1 ONE-TIME PAYMENTS ........................................................................................................................ 11
3.1.1 CONSTRUCTING ONE-TIME PAYMENT REQUESTS ................................................................................. 11
3.1.2 PROCESSING THE ONEBIP ONE-TIME TRANSACTION RESPONSE ........................................................... 15
3.1.2.1 Notification Parameters ............................................................................................................................. 16
3.1.2.2 MD5 Encryption of the Notification URL .................................................................................................... 18
3.1.3 RETURN URL ................................................................................................................................... 20
3.2 SUBSCRIPTIONS ............................................................................................................................... 20
3.2.1 CONSTRUCTING SUBSCRIPTION REQUESTS ........................................................................................ 21
3.2.2 PROCESSING SUBSCRIPTION TRANSACTION RESPONSE ....................................................................... 21
3.2.2.1 Notification Parameters ............................................................................................................................. 21
3.2.2.2 MD5 Encryption of the Notification URL .................................................................................................... 22
3.2.3 RETURN URL ................................................................................................................................... 22
4. API INTEGRATION ................................................................................................................................ 23

4.1 CANCEL SUBSCRIPTION ..................................................................................................................... 23
4.2 BLACKLIST ....................................................................................................................................... 23
4.2.1 CONSTRUCTING BLACKLIST REQUESTS............................................................................................... 24
4.2.2 PROCESSING THE BLACKLIST REQUEST .............................................................................................. 24
5 APPENDIX .............................................................................................................................................. 26
5.1 COUNTRY CODES ............................................................................................................................. 26
5.2 LANGUAGE CODES ........................................................................................................................... 27
5.3 ONEBIP ADD FUNDS PRICE POINTS (VAT INCL.) .................................................................................. 28
5.4 EXPRESS PRICE POINTS (VAT INCL.) ................................................................................................. 30
5.5 SUBSCRIPTION-BASED PRICE POINTS (VAT INCL.) .............................................................................. 32
This Document
This document describes how to receive Onebip payments from your website with a customised integration.
Even though Onebip can be integrated in its simplest form just with basic web development skills, you will also need
familiarity with scripting languages if you use a dynamic platform to handle customer registrations, logins, and
transactions, and you want Onebip to be integrated with it.
Intended Audience
This document is written for merchants and developers who want to configure and test their Onebip-based applications
before using them in production.
Notice of non-liability
Onebip is providing the information in this document to you AS-IS with all faults. Onebip makes no warranties of any kind
(whether express, implied or statutory) with respect to the information contained herein. Onebip assumes no liability for
damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the
information contained in this document or resulting from the application or use of the product or service described herein.
Onebip reserves the right to make changes to any information herein without further notice.
Onebip does not guarantee that the features described in this document will be announced or made available to anyone
in the future.
1 Introduction
1.1 Onebip presentation
Thanks to Onebip it’s possible to allow mobile phone subscribers to transfer pre-paid or post-paid credit from their SIM
card to another partner. By following next steps in this guide, it’s easy and quick to integrate mobile phone payment.
Integration allows you to create a Onebip button on your website thanks to which Onebip iframe payment panel opens.
1.2 Onebip Payment Systems and Flows
Onebip micro-payment solutions can be used to:
- Make Mobile payment on two different contexts that are web and mobile;
- Make DSL billing1 payment: home phone (land line) payment available on web.
For this last one payment system, please note that Onebip API for integration can be found on
http://www.onebip.com/wesite/docs/onebip_ip_billing_api.pdf: you can download the API and start integrating DSL billing
payments to your system with a few simple modifications with respect to mobile payments API.
Onebip Mobile payments can be requested using 2 types of payment flows: standard and express.
“Standard” flow: it develops when you want to collect money from a registered user. With standard integrations you can
determine the amount of money you want to receive using flexible price points. The standard flow is available only on
web context.
“Express” flow: it develops when you want to collect money from a non-registered user directly from your website.
Express payments can be used for a limited number of price points (please see Appendix 5.4 for Express price points).
The Express flow is available both on web context and on mobile context.
I. Standard Flow
“Standard” flow is integrated when you want to collect money from a registered user. This type of integration allows you
to deploy the Onebip billing system on your website in a very short time without worrying about the complexity of
managing a mobile phone-based payment on your servers.
Using this type of integration will allow you to request payments in a very flexible way. In fact, thanks to the Onebip
wallet, registered users can pay you any amount of money by topping up their Onebip balance through their mobile
phone credit.
Users can add funds to their Onebip wallet using a set of pre-determined price ranges that differ from country to country
(please see Appendix 5.3 for Onebip add funds price points.)
As a result, you can request any amount (e.g. $ 5.97, € 8.41, £ 15.75) just like any other online payment system, without
pricing limitations typically imposed by Mobile Network Operators.
In standard integrations, also non-registered users can send you money by opening a Onebip account. The Onebip
account creation requires a free of charge one-time registration process.
The registration is entirely managed by Onebip and does not require any action from your website/application.
Benefits of Standard flow:
 Flexible billing
 High price points available
1
DSL billing is a system adopted by Broadband Internet Service Providers (ISP) to offer online payment, according to which users are
charged for their online purchases directly on their DSL / fixed phone line bills. This innovative billing system is based on customer’s IP
recognition. ISP’s DSL and Broadband customers can purchase a product via internet choosing DSL billing option among other
payment methods and being charged over their ISP land line’s monthly bill, like a postpaid system.
 Low charge backs
Please see the basic flow diagrams on the following page for the standard flow:
Standard payment basic flow diagram
Your website
Your payment page START
Buy coins with Customer selects Onebip as a payment method on your website
Buy coins! and redirected to Onebip payment page by clicking on Onebip
button
Redirected
Onebip payment page
Customer logs in or registers to Onebip

Login
Sign-up
Onebip payment page
Customer confirms payment (1-click)
Buy now
Onebip payment page
Customer completes the payment
Completed!
Redirected
Your website END

Your payment page Customer redirected to your website and receives your message
Thank you!
Thank you for your purchase!
II. Express Flow
Express flow is integrated when you want to collect money from a non-registered user.
This type of integration is ideal if you are looking for a full integration of Onebip within your website. With Onebip Express
you can request a payment directly from your pages without redirecting the user to an external page.
Each express payment requires to be manually confirmed by the user to be validated.

This operation can be performed with different workflows accordingly to the rules defined per country and per operator,
and it’s different in web context and mobile context.
 WEB MO WORFLOW: by texting a confirmation message to a short code with a keyword,

 WEB PIN WORKFLOW: by entering a PIN code received by SMS into a web form,
 MOBILE LINK WORKFLOW: by clicking on a link received on the same mobile used for navigation
 MOBILE ONECLICK WORKFLOW: by clicking on a proper button via mobile navigation (only where available
with local operators)
In all cases the workflow is entirely managed by Onebip, that automatically ensures the use of the workflow more
efficient available on the market, and does not require any action from your website/application.
Express payments can be requested for a limited number of price points based on the country of origin of the user
(please see Appendix 5.4 for Express price points).
Benefits of Onebip express flow:
 Full integration within your website
 Fast check-out process for non-registered users
You can integrate express flow in two different ways. Please see the basic flow diagrams of express flows on the
following pages.
Express basic payment flow 1 - You can embed Onebip payment page* on your own payment page.
Your website
Buy coins with Customer selects Onebip as the payment method on your website
by clicking on Onebip button
Your website
Your payment page
Customer stays on your website and enters his mobile phone
number
Enter your phone
Your website Customer confirms the payment (via text message or PIN)
Your payment page
Verify your phone
Your website Customer completes the payment

Your payment page
Completed!
Your website END

Your payment page Customer receives your confirmation message
*Please consider the iframe sizes for the following countries: USA mobile billing: max. 670x520px (widthxheight), France mobile billing:
max. 700x520px (widthxheight).
Express basic payment flow 2: You can redirect your customers to Onebip payment page.
Your website
Buy coins with Customer selects Onebip as the payment method on your website
Buy coins! redirected to Onebip payment page by clicking on Onebip button
Redirected
Onebip payment page

Customer enters his mobile phone number
Enter your number
Onebip payment page

Customer confirms the payment (via text message or PIN)
Verify your number
Onebip payment page

Customer completes the payment
Completed!
Redirected
Your website END

Customer redirected to your website and receives your message
Your payment page
Thank you!
2 Registration and Set-up

Having access to the Onebip features is easy, quick and user friendly.
First step is to create a personal account, thanks to which it enables and handles mobile payments.
2.1 Account creation
To create a Onebip account, please perform following steps:
1. Go to the following URL and complete the registration process: http://my.onebip.com/signup

2. After you have completed the registration, your Onebip account is ready to be used.
3. Please include further information within your Onebip account, related to Financial and Account data: after
logging into account, please include data into below sections, at My Profile: http://my.onebip.com/myprofile
4. Please make sure that all data especially within Company Information and Bank accounts are included (VAT
number or equivalent and website are mandatory for most of the countries!).
2.2 Payment & Country enabling

After account creation, merchant needs to be enabled to receive payments. To this aim Onebip will verify merchant
account and after proper checks, account will be enabled.
Merchant has to forward to Onebip request for country enabling, by communicated specific information at below button.
This button will be found within Onebip account at My Profile section (application has to be made for requiring activation
of account to receive payment).
After the approval, the merchant can start receiving transactions into his account from users from all the countries
Onebip is connected to.
2.3 Basic Merchant information

Creating a Onebip solution is simple and straightforward. The following information are useful and mandatory to properly
integrate Onebip:
 Your main website URL (e.g., https://www.merchantname.com)
 Return URL after successful purchase (e.g., https://www. merchantname.com/return)
 Cancel URL after failure or in case of error (e.g., https://www. merchantname.com/failure)
 Notification URL for payment events (e.g., https://notify. merchantname.com)
 Descriptions (e.g., 500 Gaming Credits, 1000 Gaming Credits)
 Price points (e.g., 4.99€ for 500 credits, 9.99€ for 1000 Credits)
3 Mobile Payments Integration

With the Onebip solution it is possible to handle both One-time payments and Subscription recurrent payments, with a
simple technical integration based on http.
It’s very important to underline that the one-time payments can be activated by one merchant on his own, using the self-
provisioning integration layer described in the following paragraphs.
To open and manage a subscription service, with recurrent billing events, it’s mandatory the formal approval of all the
Mobile Operators of each country.
3.1 One-time payments
With one-time payments your customers are billed only once for the amount of money you are requesting. Typically used
for single items, one-time payments will be deducted from the payer’s account, in case of a “standard” payment flow, or
deducted directly from the mobile phone in case of “express” payment flow.
3.1.1 Constructing one-time payment requests
The connection with Onebip payment page is achieved by using HTTP GET or POST requests to the following URL:
https://www.onebip.com/otms/
The following are case sensitive dynamic parameters you have to use in your payment query string to Onebip:
Name Required? Description Length
username Yes The email address associated to your Onebip account. 255
description Yes Description of the item being sold. This will be displayed on the 255
payment page and on the payment receipt.
price Yes End user price in cents/pence (local value added taxes -
included) as integer cents (actual amount * 100).
currency Yes Local currency code in ISO 4217 standard 3

http://en.wikipedia.org/wiki/Currency_codes
e.g. USD
command Yes Determines the Onebip integration type. 50
Allowable values:
standard_pay
express_pay
country No Used only to restrict payments to users from a specific country.
Country code in ISO 3166 standard can be found on

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
e.g. US
If no value is inserted the price will be automatically converted

in the local currency of your customer.
Please see Appendix 5.1 for Country codes
billing_method No Used to specify billing methods allowable. For example:
 If not set all billing method are allowable.

 If mobile -> mobile billing allowable,
 if ip -> ip billing allowable,
 if mobile, ip both billing methods allowable.
e.g. mobile,ip (both billing methods available)
country_disabled No Used to prevent users from specific countries to send you a

payment. Typically used if you don’t want to collect money from
weak-currency countries.
Country code in ISO 3166 standard

e.g. EG,CO,CL (include one or more country codes comma

separated).
item_code No Pass-through variable you can use to identify your internal item 64
code for this payment.
Note: This is not the Onebip item ID
lang No The language used on the payment page. 2
Language code in ISO 639-1

http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
e.g. en
Default – English
Please see Appendix 5.2 for Language codes
return_url No The URL to which the payer’s browser is redirected after 255
completing the payment; for example, a URL on your site that
displays a “Thank you for your payment” page.
Default – The browser is redirected to a Onebip web page.
notify_url No The URL to which Onebip sends information about the 255
transaction.
For more information about notifications please see Notification

Parameters. The parameters are passed using HTTP GET
method.
cancel_url No The URL to which the payer’s browser is redirected if payment

is cancelled or failed by the merchant. For example:
 The URL on your website that displays a “Payment 255

Cancelled” notification page.
remote_txid No A pass-through variable and a single and unique transaction ID 64

reference number assigned to the merchant system (your
internal transaction ID) for each and single payment. It is used
to avoid duplicated transactions.
custom No User-defined array of key-value pairs which will be passed 10 variables

through the system and returned in your notify_url and will be max
appended to your return_url (Max 64
characters
Note: for each
 Your variable names cannot be the same as the one value)
used by Onebip (please see Notification Parameters)
 Max. 10 variables in total can be set
 A variable value cannot be longer than 64 characters
e.g. please refer to HTML examples below.
customer_email No Payer’s email address 255
customer_email_lock No Boolean value (true or false, 1 or 0) 5
If true, the email address field on the payment page can’t be

edited manually from the user
customer_firstname No Payer’s first name 50
customer_firstname_lock No Boolean value (true or false, 1 or 0) 5
If true, the first name field on the payment page can’t be edited
manually from the user
customer_lastname No Payer’s last name 50
customer_lastname_lock No Boolean value (true or false, 1 or 0) 5
If true, the last name field on the payment page can’t be edited
manually from the user
customer_cell No Payer’s cell phone number in international format with no 15

leading
e.g. 447700900999
Note: customer_cell must match customer_country or country
customer_cell_lock No Boolean value (true or false, 1 or 0) 5
If true, the mobile phone number field on the payment page

can’t be edited manually from the user
customer_country No Payer’s country code in ISO 3166 standard 2

e.g. US
Note: customer_country must match country, if used.
Please see Appendix 5.1 for Country codes

logo_url No The URL of the 360x45-pixel image displayed as your logo in 255
the upper left corner of the Onebip payment pages
Supported formats: jpeg, gif, png
terms_url No The URL in which you have published special terms and 255
conditions related to the item you are selling
debug No Boolean value (true or false, 1 or 0) 5
If true, displays a verbose error message in case of integration

failure
Note: Recommended for development purposes only.
debug_url No The URL through which you will be notified in case of 255
integration failure. The call will include the error and the list of
all parameters passed to the payment page
Note: The connection to Onebip payment page can be performed using a standard HTTP request or using a 128bit SSL
encryption on our secure server. In both cases, the way to call the payment page is the same: if you want to use the
secure server, it’s enough to use HTTPS instead of HTTP in the payment page URL.
HTML Examples
The sample HTML code below illustrates a HTTP GET request with these features:
 Username: business@email.com
 Item name: 1000 game credits
 Item price: $ 0.99 USD
 Return URL: http://www.yoursite.com/thankyou.htm
 Notify URL: http://www.yoursite.com/notify.php
https://www.onebip.com/otms/?command=standard_pay&username=business%40email.com&description=1000+game+
credits&price=99&currency=USD&return_url=http%3A%2F%2Fwww.yoursite.com%2Fthankyou.htm&notify_url=http%3A
%2F%2Fwww.yoursite.com%2Fnotify.php
An example of this communication using an HTTP POST request with optional parameters would be:
<form action="https://www.onebip.com/otms/" method="post" target="onebip">

<input type="hidden" name="command" value="standard_pay" />
<input type="hidden" name="username" value="business@email.com" />
<input type="hidden" name="description" value="1000 game credits" />
<input type="hidden" name="item_code" value="abc123" />
<input type="hidden" name="price" value="99" />
<input type="hidden" name="currency" value="USD" />
<input type="hidden" name="country" value="US" />
<input type="hidden" name="lang" value="en" />
<input type="hidden" name="return_url"
value="http://www.yoursite.com/thankyou.htm" />
<input type="hidden" name="cancel_url"
value="http://www.yoursite.com/cancel.htm" />
<input type="hidden" name="notify_url"
value="http://www.yoursite.com/notify.php" />
<input type="hidden" name="remote_txid" value="12QW34ER56TY" />
<input type="hidden" name="custom[your_variable1]" value="yourvalue1" />

<input type="hidden" name="custom[your_variable2]" value="yourvalue2" />
<input type="hidden" name="custom[foo]" value="bar" />
<input type="hidden" name="customer_email" value="user@email.com" />
<input type="hidden" name="customer_firstname" value="John" />
<input type="hidden" name="customer_lastname" value="Smith" />
<input type="hidden" name="customer_cell" value="17586584556" />
<input type="hidden" name="customer_country" value="US" />
<input type="hidden" name="logo_url" value="http://www.yoursite.com/logo.jpg" />
<input type="hidden" name="debug" value="true" />
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
Below the URLs of the Onebip buttons currently available:
http://www.onebip.com/tools/bts/btn01.gif
3.1.2 Processing the Onebip one-time transaction response
The transaction response has to be executed by the merchant landing script to ensure the transaction is committed on
the Onebip system before recording the customer payment as successful in the merchant database.
This guarantees no discrepancies between the merchant’s transaction records and Onebip.
The following Onebip values must be confirmed as returned to the merchant’s landing script:
Outcome Description
OK Payment accepted
ERROR: Your error message Payment rejected
If the request has been handled correctly, your notify_url will have to output the word OK, upper case, in plain text format
without any HTML code.
If your web page fails to respond OK, for instance if there is a system error, Onebip will place all notifications in a queue
and retry them periodically until they are successfully delivered.
The retries will be performed every 5 minutes for the first hour, and hourly after that.
The total retry period for a payment notification is 24 hours.
During the retry period the payment will be stored in your Onebip account as “Pending”.
If Onebip receives no outcome after the retry period the payment will be automatically cancelled and will be stored in
your Onebip account as “Failed”.
ERROR message should be returned in case of parameters mismatch in the notify_url, payment duplication or any other
appropriate reason identified by your system.
All payment details including status (pending, failed, completed) and ERROR reasons are available in your Onebip
business account in the “Transactions History” section.
Note: In case of ERROR outcome or NO OUTCOME after the retry period, funds will not be deducted from the
customer’s account and you will not be entitled to collect the payment. This is valid only in case of standard integration
adoption. Please see Section 1.2 for Onebip Payment Systems and Flows.
3.1.2.1 Notification Parameters
Onebip will notify you at the end of each successful payment. This is done with an HTTP GET request by our server to
the notify_url, hosted on your servers.
To configure or change your site’s notify_url, you have to set the URL of a web page that receives the notification and
takes appropriate action on your side.
The following are case sensitive dynamic parameters Onebip will notify you for each payment:
Parameter Always Description

name present?
notify Yes Type of notification. For one-time payments is:
payment_single
payment_id Yes This is a unique ID identifying the payment at Onebip. This ID will be shown in your
panel and in your customers’ panel, and will be used to identify the payment.
You may use this ID to prevent that the same payment is registered more than once
on your side.
country Yes Country code in ISO 3166 standard

currency Yes Local currency code in ISO 4217 standard

http://en.wikipedia.org/wiki/Currency_codes
price Yes End user price in cents/pence (local value added taxes included). The billed amount
is passed as integer cents (actual value * 100).
tax Yes Local value added taxes paid by the end user, if any (actual value * 100).
commission Yes Onebip commission fees for handling the transaction (actual value * 100).
Note: Mobile Network Operator fees included
amount Yes Merchant net revenue for the transaction after local taxes and onebip fees (actual
value * 100).
original_price Yes The original price set by the merchant before the onebip conversion in the local price
of the buyer
Note: Make sure that the amount notified is the same as the price amount passed in
the payment request
original_currency Yes The original currency set by the merchant before the onebip conversion in the local
currency of the buyer
remote_txid No Pass-through variable, a unique transaction reference number for the merchant
system (your internal transaction ID).
item_code No Pass-through variable you can use to identify your internal item code for this
payment.
custom No Any custom merchant parameters specified by the merchant in the transaction URL
are returned here.
hash No Hash checksum of the merchant API Key and the Notification URL parameters.
PHP Example
<?php
// Report parameters
// Onebip parameters:
$payment_id = $_REQUEST['payment_id'];
$country = $_REQUEST['country'];
$currency = $_REQUEST['currency'];
$price = $_REQUEST['price'];
$tax = $_REQUEST['tax'];
$commission = $_REQUEST['commission'];
$amount = $_REQUEST['amount'];
$original_price = $_REQUEST['original_price'];
$original_currency = $_REQUEST['original_currency'];
// Your internal transaction ID and item code, if you use them:

$remote_txid = $_REQUEST['remote_txid'];
$item_code = $_REQUEST['item_code'];
// Your custom parameters, if you use them:

$your_variable1 = $_REQUEST['your_variable1'];
$your_variable2 = $_REQUEST['your_variable2'];
$foo = $_REQUEST['foo'];
/*
...
you can use these parameters to make functions like
payment check, payment log, account enable ....
*/
if ($error) {
echo 'ERROR: Your error message';
} else {
echo 'OK'; // it is important you print "OK" in uppercase
}
?>
ASP Example
<%
' Report parameters
' Onebip parameters:

payment_id = Request("payment_id")
country = Request("country")
currency = Request("currency")
price = Request("price")
tax = Request("tax")
commission = Request("commission")
amount = Request("amount")
original_price = Request("original_price")
original_currency = Request("original_currency")
' Your internal transaction ID and item code, if you use them:
remote_txid = Request("remote_txid")
item_code = Request("item_code")
' Your custom parameters, if you use them:

your_variable1 = Request("your_variable1")
your_variable2 = Request("your_variable2")
foo = Request("foo")
' You can use these parameters to make functions like

' payment check, payment log, account enable...
If error Then
Response.Write("ERROR: Your error message")
Else
Response.Write("OK")
' It is important that you print "OK" in upper case
End If
%>
3.1.2.2 MD5 Encryption of the Notification URL
MD5 hashing is an encryption method that ensures that URLs have not been manipulated or changed. This allows the
integrity of the link in a data exchange between two parties to be checked.
MD5 is an abbreviation for “Message Digest Algorithm 5” and is a widely used cryptographic Hash function.
The length of the hash value produced by this hash function is 128 bits. The hash value is returned as a 32-digit
hexadecimal number, which looks like this:
34048ce4cd069b624f6e021ba63ecde5
The MD5 hash verifies the integrity of the URL by comparing the MD5 hash created by the merchant system with a
previously established hash made by the Onebip system. In this way, it can be determined whether the URL has been
changed.
The primary purpose of this is to prevent the manipulation of price and currency.
The MD5 feature requires a secret key value (API Key) of the merchant’s choice that can be set under the “My Account”
section.
A PHP example of how Onebip create the MD5 hash and append it as parameter hash to the Notification URL would be:
$basename = basename($notificationURL);
$hash = md5($ApiKey . $basename);
$notificationURL .= "&hash=" . $hash;
The PHP and ASP code below shows how standard and merchant parameters can be retrieved by the notification URL;
the script can then use these settings to grant access, add credits, or perform any other action your integration requires.
As an added security measure, the notification URL should not be too obvious (e.g.
http://www.yoursite.com/paymentnotification.php might be an easy guess)
PHP Example
<?php
// Check MD5 hash – anti-fraud measure
if (isset($_REQUEST['hash'])) {
$my_api_key = 'My Secret Key'; // stored in your account settings
$basename = basename($_SERVER['REQUEST_URI']);
$pos = strrpos($basename, "&hash");
$basename_without_hash = substr($basename, 0, $pos);
$my_hash = md5($my_api_key . $basename_without_hash);
if ($my_hash != $_REQUEST['hash']) {
log("ERROR: this isn't a valid Onebip notification!");
// Note: "log()" sample function
echo "ERROR: Invalid hash code";
exit();
}
}
echo 'OK'; // it is important you print "OK" in uppercase
?>
ASP Example
<%
' Check MD5 hash – anti-fraud measure
dim hash, my_api_key, basename, basenameexpl, pos, basename_without_hash,

my_hash
hash = Request("hash")
If hash <> "" Then
my_api_key = "My Secret Key"
' stored in your account settings
basename = Request.ServerVariables("SCRIPT_NAME")
basenameexpl = split(basename,"/")
basename = basenameexpl(ubound(basenameexpl))
pos = InStr(request.querystring, "&hash")
basename_without_hash = basename&left(Request.querystring, pos-1)

my_hash = Md5(my_api_key&basename_without_hash)
' Note: "Md5()" sample function
If my_hash <> hash Then
log("ERROR: this isn't a valid Onebip notification!" )
' Note: "Log()" sample function
Response.Write("ERROR: Invalid hash code")
Response.End()
End If
End If
Response.Write("OK")
' It is important that you print "OK" in upper case
%>
3.1.3 Return URL
Onebip will append all the pass-through parameters you have specified in the transaction URL to your return_url.
Pass-through parameters in the return_url page can be used in many ways, for example to pass an internal user-ID
through the payment process and redirect the customer to its account on your site, or to build customised thank you
pages. The return_url page can also route your user to a specific download, using the notify_url to authorize it.
The return_url page could be used to host the scripts needed to grant the permissions for the user to access a specific
product/service.
In case of no return_url parameter, the user will be redirected to a generic Onebip thank you page with the payment
summary.
Note: We strongly suggest any permission or other action needed to deliver the service or product to the final user is not
triggered by the return_url page but by the notify_url
3.2 Subscriptions
The subscription module is used when Onebip is required to manage recurrent automatic charges to a customer, who
has signed an explicit subscription service (e.g. daily, weekly, monthly or annual charges).
The subscription services cannot be opened independently by the merchants, because must be previously approved by
the Mobile Network Operators. For this reason the opening of a new subscription service with recurrent billing must be
analysed and planned with Onebip.
Due to some technical limitations imposed by Mobile Network Operators, subscription-based payments cannot benefit of
the pricing flexibility offered by the Onebip standard integration.
As a result the price parameter for subscriptions cannot be a flexible value but has to respect a set of pre-determined
price points which differ from country to country.
For a list of all price points currently available and the list of subscription enabled countries, please refer to Subscription-
based price points.
The technical integration for a Subscription service is pretty similar to the One-time integration one, apart from the
specific information due to subscription, as shown in the following paragraphs.
3.2.1 Constructing subscription requests
In addition to the parameters requested for one-time payments, shown in paragraph 3.1.1, in order to request a
subscription the following mandatory parameters are required:
Name Required? Description Length
country Yes Used only to restrict payments to users from a specific country. If no value is 2
inserted the price will be automatically converted in the local currency of your
customer
Country code in ISO 3166 standard

e.g. US
For allowable values, see Appendix 5.1 Country Codes
frequency Yes Used for recurring payments only. Defines the interval in between each payment in 3
days
daily=1
weekly=7
monthly=30
Note: All other mandatory parameters requested for one-time payments have to be included also when constructing a
subscription request (see Constructing one-time payment requests)
3.2.2 Processing subscription transaction response
The transaction response has to be executed by the merchant landing script to ensure the transaction is committed on
the Onebip system before recording the customer payment as successful in the merchant database.
The processing of transaction response, the outcome, and the error management is perfectly identical to what is
described in paragraph 3.1.2.
3.2.2.1 Notification Parameters
Onebip will notify you at the end of each successful payment. This is done with an HTTP GET request by our server to
the notify_url, hosted on your servers.
To configure or change your site’s notify_url, you have to set the URL of a web page that receives the notification
and takes appropriate action on your side.
In addition to the case sensitive dynamic parameters notified for one-time payments, described in paragraph 3.1.2.1, for
subscriptions the following parameters will be included:
Parameter name Always Description

present?
notify Yes Type of notification. For subscriptions allowable values are:
payment_subscription
unsubscription
Note: payment_subscription notifies the activation of a subscription and

unsubscription the cancellation of a subscription
subscription_id Yes This is a unique ID identifying a subscription. This ID will be passed to all recurring
payments associated to that particular subscription or when notifying an
unsubscription.
Subscription activation example:

http://www.yoursite.com/onebip_notify.php?notify=payment_subscription&subscripti
on_id=1234567
Subscription cancellation example:

http://www.yoursite.com/onebip_notify.php?notify=unsubscription&subscription_id=
1234567
3.2.2.2 MD5 Encryption of the Notification URL
MD5 hashing is an encryption method that ensures that URLs have not been manipulated or changed. This allows the
integrity of the link in a data exchange between two parties to be checked.
The complete description of MD5 using in Onebip is shown in paragraph 3.1.2.2.
3.2.3 Return URL
Onebip will append all the pass-through parameters you have specified in the transaction URL to your return_url.
The complete description of this feature is in paragraph 3.1.3.

4. API integration
Some additional features are given to the user by the integration with the Onebip API, that permit to a merchant to
manage the operations of unsubscription and black list.
4.1 Cancel subscription

Merchants can stop a subscription automatically using the Onebip API.
Web service URL: http(s)://www.onebip.com/api/subscription/
Input: GET parameters as described below:
Parameter name Description
username The Onebip ID or the email address associated to your Onebip

account.
password Your Onebip password.
action The type of request you want to perform. To cancel a subscription

use:
unsubscribe
subscription_id The ID of the subscription that you want to cancel.
Output: A plain/text message (no HTML)
Outcome Description
OK Subscription cancelled successfully
ERROR: error description Cancellation request failed
Example:
http://www.onebip.com/api/subscription/?username=name@mail.com&password=abcd&action=unsubscribe
&subscription_id=1234567
4.2 Blacklist
Merchant can decide to blacklist a MSISDN or an user (with one or more MSISDNs associated to his Onebip account),
that have performed at least one transaction towards the merchant that is asking for the blacklist.
4.2.1 Constructing blacklist requests
You can address your HTTP POST requests to the following URL:
https://www.onebip.com/api/blacklist
POST https://www.onebip.com/api/blacklist
AUTHORIZATION: http auth with email and password
The following are case sensitive dynamic parameters that you can choose to use in your blacklist request query string
according to your needs: please note that you need to use just one of the following parameter:
Name Required Description
payment_id Yes If you are interested in blacklisting the user starting from one
(also named transaction_id) of his transactions.
user_id As If you are interested in blacklisting the user associated to that

alternative correspondent Onebip account
user_email As If you are interested in blacklist the user associated to that

alternative email address
mobile_phone_number As If you are interested in blacklist the mobile phone number

(also named msisdn) alternative associated.
mobile_phone_number_enc As If you are interested in blacklist the mobile phone number

(also named msisdn_enc) alternative associated.
An example of this communication using an HTTP POST request with optional parameters would be:
curl -v -u merchant@yourcompany.com:secret_password
https://www.onebip.com/api/blacklist -X POST -d
"mobile_phone_number_enc=4812c91a1bbG8f5a78889cf62e28aedc"
or
curl -v -u merchant@yourcompany.com:secret_password
https://www.onebip.com/api/blacklist -X POST -d "payment_id=99344200033"
4.2.2 Processing the blacklist request

Response
HTTP/1.1 201 Created

Content-Type: application/json ;charset=utf-8
Errors
In case of missing or wrong parameters:
HTTP/1.1 400 Bad Request

{"error": "Bad Request"}
In case of wrong authentication:
HTTP/1.1 401 Unauthorized

{"error": "Unauthorized"}
If the Merchant is trying to blacklist an user that haven’t never performed a transaction
towards the requiring Merchant:
HTTP/1.1 403 Forbidden

{"error": "Forbidden"}
In case of call with method different from POST:
HTTP/1.1 405 Method Not Allowed

{"error": "Method Not Allowed"}

5 Appendix
5.1 Country Codes
The table below shows the list of countries currently supported by Onebip in ISO 4217 standard:
Nation Code Nation Code

Argentina AR Lithuania LT
Australia AU Luxemburg LU
Austria AT Malaysia MY
Bahrain BH Mexico MX
Belgium BE Morocco MA
Bosnia and Herzegovina BA Netherlands NL
Bulgaria BG Norway NO
Brazil BR Palestine PS
Canada CA Peru PE
Chile CL Poland PL
Colombia CO Portugal PT
China CN Qatar QA
Croatia HR Romania RO
Czech Republic CZ Russia RU
Denmark DK Saudi Arabia SA
Ecuador EC Serbia RS
Egypt EG Singapore SG
Estonia EE Slovenia SI
Finland FI South Africa ZA
France FR Spain ES
Germany DE Sudan SD
Greece GR Sweden SE
Hong Kong HK Switzerland CH
Hungary HU Syria SY
Indonesia ID Taiwan, Province of China TW
Iraq IQ Thailand TH
Ireland IE Turkey TR
Italy IT Ukraine UA
Jordan JO United Kingdom UK
Kazakhstan KZ United Arab Emirates AE
Kuwait KW United States US
Latvia LV Yemen YE
Lebanon LB
For updates please refer to http://en.wikipedia.org/wiki/ISO_3166-1

5.2 Language Codes

The table below shows the list of languages currently supported by Onebip in ISO 639-1 standard:
Language Name Native Name Code

Bulgarian Български bg
Bosnian Bosanski bs
Croatian Hrvatski hr
Danish Dansk da
German Deutsch de
English English en
Spanish Español es
Estonian Eesti keel et
Filipino Filipino fil
French Français fr
Indonesian Bahasa Indonesia id
Italian Italiano it
Latvian Latviešu valoda lv
Lithuanian Lietuvių kalba lt
Macedonian Makedonski mk
Dutch Nederlands nl
Norwegian Norsk no
Polish Polski pl
Portuguese (Brasil) Português (Brasil) pt_BR
Portuguese (Portugal) Português (Portugal) pt_PT
Romanian Română ro
Finnish Suomi fi
Slovak Slovenčina sk
Slovene Slovenščina sl
Swedish Svenska sv
Turkish Türkçe tr
Czech Čeština cs
Greek Ελληνικά el
Serbian Srpski Sr
Russian Русский Ru
Ukrainian Українська Uk
Hungarian Magyar Hu
Hebrew ‫עִ ב ְִרית‬ He
Arabic ‫العربية‬ Ar
Thai ภาษาไทย Th
Chinese 中文（简体） zh_CN
Japanese 日本語 Ja
Korean 한국어 Ko
For updates please refer to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
5.3 Onebip add funds price points2 (VAT incl.)
Nation Currency Price 1 Price 2 Price 3 Price 4

2
Argentina ARS 7,26 21,78 36,30 43,56
Australia AUD 6,60 13,20 19,80 26,40
2
Austria EUR 3,00 5,00 15,00 20,00
Bahrain BHD 0,50 1,00 1,50 2,00
Belgium EUR 4,00 8,00 12,00 16,00
Bosnia Herzegovina BAM 2,34 4,68 7,02 9,36
Brazil BRL 4,00 16,00 28,00 32,00
Bulgaria BGN 2,40 4,80 7,20 9,60
Canada CAD 5,00 10,00 15,00 20,00
2
Chile CLP 700,00 2.100,00 3.500,00 4.200,00
2
Colombia COP 4.408,00 8.816,00 13.224,00 17.632,00
Croatia HRK 6,10 12,20 18,30 24,40
Czech Republic CZK 50,00 99,00 500,00 600,00
Denmark DKK 5,00 35,00 150,00 200,00
2
Ecuador USD 1,45 4,35 7,25 8,70
Egypt EGP 5,00 10,00 15,00 20,00
Estonia EEK 35,60 50,80 101,60 152,40
Finland EUR 5,00 10,00 15,00 20,00
Germany EUR 0,99 15,00 29,00 30,00
Greece EUR 1,23 3,62 7,24 10,86
Hungary HUF 99,00 410,00 2032,00 5080,00
Hong Kong HKD 30,00 60,00 90,00 120,00
Indonesia IDR 15.000,00 30.000,00 45.000,00 60.000,00
Iraq IQD 1.200,00 2.400,00 3.600,00 4.800,00
Ireland EUR 2,00 4,00 6,00 8,00
Jordan JOD 0,70 1,40 2,10 2,80
Kazakhstan KZT 600,00 1200,00 1800,00 2400,00
Kuwait KWD 0,50 1,00 1,50 2,00
Latvia LVL 3,00 6,00 9,00 12,00
Lebanon LBP 3,00 5,00 10,00 15,00
Lithuania LTL 10,00 20,00 30,00 40,00
2
Other add funds price points are available upon your request. Please contact us on partner.relations@onebip.com.
Luxemburg EUR 3,00 6,00 9,00 12,00

Malaysia MYR 10,00 20,00 30,00 40,00
2
Mexico MXN 19,72 59,16 98,60 118,32
Morocco MAD 24,00 48,00 72,00 96,00
Netherlands EUR 1,50 3,00 4,50 6,00
Norway NOK 5,00 60,00 175,00 200,00
Palestine ILS 2,73 5,45 8,19 10,92
2
Peru PEN 3,50 10,50 17,50 21,00
Poland PLN 11,07 23,37 30,75 61,50
Portugal EUR 3,00 4,00 8,00 12,00
Romania EUR 2,48 3,72 6,20 12,40
Russia RUB 200,00 400,00 600,00 1200,00
Saudi Arabia SAR 3,00 6,00 9,00 12,00
Serbia RSD 236,00 472,00 944,00 1.416,00
Singapore SGD 20,00 30,00 40,00 60,00
South Africa ZAR 30,00 50,00 100,00 150,00
Spain EUR 1,42 4,06 7,08 14,16
Sweden SEK 5,00 40,00 150,00 200,00
Switzerland CHF 1,00 15,00 45,00 50,00
Syria SYP 25,00 50,00 75,00 100,00
Taiwan TWD 50,00 100,00 200,00 300,00
Thailand THB 100,00 150,00 300,00 450,00
Ukraine UAH 30,00 60,00 90,00 120,00
United Arab Emirates AED 5,00 10,00 20,00 30,00
2
United Kingdom GBP 10,00 - 20,00 30,00
3
United States USD 2,99 5,99 19,98 29,97
Vietnam VND 15000,00 30000,00 45000,00 60000,00
Yemen YER 50,00 100,00 150,00 200,00
5.4 Express price points (VAT incl.)

The table below shows the list of price points available for the express integration:

Argentina ARS 7,26 - - -
Australia AUD 6,60 - - -
Austria EUR 3,00 5,00 - -
Bahrain BHD 0,50 - - -
Belgium EUR 4,00 - - -
Bosnia Herzegovina BAM 2,34 - - -
Brazil BRL 0,99 1,99 4,00 8,50
Bulgaria BGN 2,40 - - -
Canada CAD 5,00 - - -
Chile CLP 700,00 - - -
China CNY 1,00 - - -
Colombia COP 4.408,00 - - -
Croatia HRK 6,10 - - -
Czech Republic CZK 50,00 99,00 500,00 600,00
3
Denmark DKK 5,00 35,00 150,00 200,00
Ecuador USD 1,45 - - -
Egypt EGP 5,00 - - -
Estonia EEK 15,20 35,60 50,80 -
Finland EUR 1,00 2,50 4,00 5,00
3
France EUR 1,50 5,00 9,00 10,00
3
Germany EUR 0,99 15,00 29,00 30,00
Greece EUR 1,23 3,62 - -
Hong Kong HKD 30,00 - - -
Hungary HUF 99,00 410,00 2032,00 5080,00
Indonesia IDR 8.000,00 10.000,00 15.000,00 -
Iraq IQD 1.200,00 - - -
Ireland EUR 1,00 2,00 - -
3
Italy EUR 0,50 5,00 12,00 15,00
Jordan JOD 0,70 - - -
3
Kazakhstan KZT 75,00 170,00 500,00 600,00
Kuwait KWD 0,50 - - -
Latvia LVL 0,35 0,59 0,95 3,00
Lebanon USD 3,00 5,00 - -
Lithuania LTL 3,00 5,00 7,00 10,00
Luxemburg EUR 3,00 - - -

Malaysia MYR 5,00 7,00 10,00 -
Mexico MXN 19,72 - - -
Morocco MAD 20,00 24,00 - -
Netherlands EUR 1,50 - - -
Norway 3 NOK 5,00 60,00 175,00 200,00
Palestine ILS 2,73 - - -
Peru PEN 3,50 - - -
Poland PLN 11,07 23,37 30,75 -
Portugal EUR 2,46 3,00 4,00 -
Qatar QAR 4,00 - - -
3
Romania EUR 1,24 2,60 6,20 12,40
Russia RUB 140,00 200,00 300,00 600,00
Saudi Arabia SAR 3,00 - - -
Serbia RSD 236,00 472,00 - -
3
Singapore SGD 2,00 6,00 20,00 30,00
South Africa ZAR 30,00 50,00 - -
Spain EUR 1,42 3.54 4,06 7,08
3
Sweden SEK 5,00 40,00 150,00 200,00
Switzerland CHF 1,00 15,00 45,00 50,00
Syria SYP 25,00 - - -
Taiwan TWD 30,00 50,00 100,00 -
Thailand THB 25,00 50,00 100,00 150,00
3
Turkey TRY 0,01 30,00 59,50 60,00
Ukraine UAH 8,00 12,00 16,00 30,00
United Arab Emirates AED 5,00 10,00 - -
United Kingdom 3 GBP 0,25 1,50 5,00 10,00
3
United States USD 1,99 5,99 14,99 24,99
Vietnam VND 15000,00 - - -
Yemen YER 50,00 - - -
3
Other express price points available upon request. Please contact us on partner.relations@onebip.com.
5.5 Subscription-based price points (VAT incl.)

The table below shows the list of subscription-enabled countries and price points currently supported by
Onebip:

Belgium EUR 4,00 - - -
Canada CAD 5,00 - - -
China CNY 1,00 - - -
Czech Republic CZK 79,00 - - -
4
Denmark DKK 30,00 60,00 100,00 150,00
4
Germany EUR 2,99 4,99 6,99 9,99
Greece EUR 1,23 3,62 - -
Hong Kong HKD 30,00 - - -
Ireland EUR 1,00 2,00 - -
4
Italy EUR 3,00 5,00 7,00 10,00
Jordan JOD 0,70 - - -
Latvia LVL 0,35 0,59 0,95 3,00
Lebanon USD 3,00 5,00 - -
Lithuania LTL 3,00 5,00 7,00 10,00
Netherlands EUR 1,50 - - -
Norway 4 NOK 20,00 30,00 50,00 60,00
4
Singapore SGD 3,00 5,00 8,00 10,00
4
Sweden SEK 10,00 20,00 30,00 50,00
Switzerland CHF 3,00 5,00 - -
Taiwan TWD 30,00 50,00 100,00 -
Turkey 4 TRY 5,00 10,00 15,00 20,00
4
United Kingdom GBP 1,50 3,00 5,00 10,00
Yemen YER 50,00 - - -
Subscription-based price points are not available for mobile flow.
4
Other subscription based price points available upon request. Please contact us on partner.relations@onebip.com.
Onebip S.r.l. | Sede Legale: Largo Donegani, 3 - 20121 Milano, Italia

Sede Amministrativa: Viale Pasteur 78, 00144 Roma | Tel. +39 02 45473397 - Fax +39 02 45473398
www.onebip.com | www.neomobile.com

Onebip API

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Onebip API

Încărcat de

Drepturi de autor:

Formate disponibile

Mobile Payment System

Web and Mobile

Integration Guide 3.8.4

THIS DOCUMENT ............................................................................................................................................. 3

2 REGISTRATION AND SET-UP ................................................................................................................ 9

3 MOBILE PAYMENTS INTEGRATION ................................................................................................... 11

4. API INTEGRATION ................................................................................................................................ 23

1.2 Onebip Payment Systems and Flows

Onebip micro-payment solutions can be used to:

Benefits of Standard flow:

 High price points available

 Low charge backs

Standard payment basic flow diagram

Onebip payment page

Customer logs in or registers to Onebip

Onebip payment page

Customer confirms payment (1-click)

Onebip payment page

Customer completes the payment

Your website END

II. Express Flow

Each express payment requires to be manually confirmed by the user to be validated.

 WEB MO WORFLOW: by texting a confirmation message to a short code with a keyword,

Benefits of Onebip express flow:

 Full integration within your website

 Fast check-out process for non-registered users

Enter your phone

Verify your phone

Your website Customer completes the payment

Your website END

Thank you for your purchase!

Onebip payment page

Enter your number

Onebip payment page

Verify your number

Onebip payment page

Your website END

2 Registration and Set-up

2.1 Account creation

To create a Onebip account, please perform following steps:

1. Go to the following URL and complete the registration process: http://my.onebip.com/signup

2.2 Payment & Country enabling

2.3 Basic Merchant information

 Your main website URL (e.g., https://www.merchantname.com)

 Return URL after successful purchase (e.g., https://www. merchantname.com/return)

 Cancel URL after failure or in case of error (e.g., https://www. merchantname.com/failure)

 Notification URL for payment events (e.g., https://notify. merchantname.com)

 Descriptions (e.g., 500 Gaming Credits, 1000 Gaming Credits)

3 Mobile Payments Integration

3.1 One-time payments

3.1.1 Constructing one-time payment requests

Name Required? Description Length

currency Yes Local currency code in ISO 4217 standard 3

command Yes Determines the Onebip integration type. 50

country No Used only to restrict payments to users from a specific country.

Country code in ISO 3166 standard can be found on

If no value is inserted the price will be automatically converted

Please see Appendix 5.1 for Country codes

billing_method No Used to specify billing methods allowable. For example:

 If not set all billing method are allowable.

e.g. mobile,ip (both billing methods available)

country_disabled No Used to prevent users from specific countries to send you a

Country code in ISO 3166 standard

e.g. EG,CO,CL (include one or more country codes comma