mobile payment system
TRANSCRIPT
Mobile Payment System PC and Mobile web
Integration Guide 4.0.5
2 Integration Guide 4.0.5
This Document
This document describes how to integrate Onebip Mobile Payment System with your service. Even though Onebip can be integrated in its simplest form just with basic web development skills, you will also need to be familiar with the scripting languages if you use a dynamic platform to handle customer registrations, logins, and transactions, and you would like Onebip to be integrated with it.
Intended Audience
This document is written for the merchants and the developers who want to configure and test their Onebip-based web 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.
Version
Onebip Integration Guides are updated in time to add new functionalities and to provide the best features available. Please ensure that you have the latest version to take advantage of the new features that have been updated and improved which are not available in the previous versions.
3 Integration Guide 4.0.5
Document change log
Version Date Content
4.0.0 14/01/2013 New release of Onebip API
4.0.1 25/01/2013 Updated chapter 4 API Integration and updated new examples in this chapter
4.0.2 04/02/2013 Added chapter 5 Versioning
Updated chapter 4.3 Back-office API
4.0.3 11/02/2013 Added chapter 6 Skinability
4.0.4 29/03/2013 Added chapter 7 Authentication as a service
Updated signature encryption
Updated notification parameters list with new “notification_id” and “first_notification_at”
4.0.5 16/04/2013 Updated signature specifications for request in ch.3.1.1.2 and ch.3.2.1.2.
Updated signature specifications for “return_url” in ch.3.1.3 and ch.3.2.3
4 Integration Guide 4.0.5
INDEX
INTRODUCTION ......................................................................................................................................... 5
1. ONEBIP MOBILE PAYMENT FLOW ................................................................................................... 6
2. REGISTRATION AND SET-UP ........................................................................................................... 9
2.1. ACCOUNT CREATION ...................................................................................................................... 9
2.2. PAYMENT AND COUNTRY ENABLING ................................................................................................. 9
3. ONEBIP MOBILE PAYMENT INTEGRATION ....................................................................................10
3.1. ONE-TIME PAYMENTS ....................................................................................................................10
3.1.1. Constructing one-time payment requests ..............................................................................................10
3.1.2. Processing one-time transaction response ............................................................................................17
3.1.3 Return URL .........................................................................................................................................21
3.2. SUBSCRIPTION-BASED PAYMENTS ..................................................................................................23
3.2.1 Constructing subscription payment requests .........................................................................................23
3.2.2 Processing subscription transaction response .......................................................................................27
3.2.3. Return URL .........................................................................................................................................35
4 API INTEGRATION ............................................................................................................................38
4.1 UNSUBSCRIPTION API ..................................................................................................................38
4.2 BLACKLIST API ............................................................................................................................38
4.2.1 Constructing a blacklist requests ..........................................................................................................38
4.2.2 Constructing an un-blacklist requests ...................................................................................................39
4.2.3 Processing the blacklist / un-blacklist response .....................................................................................40
4.3 BACK-OFFICE API ........................................................................................................................40
4.3.1 Back-office Transactions API ................................................................................................................40
4.3.2 Back-office Transaction Stats API .........................................................................................................45
4.3.3 Back-office Customer Base Status API .................................................................................................47
5. VERSIONING .....................................................................................................................................50
6. SKINABILITY .....................................................................................................................................51
6.1 SKIN CREATION API .....................................................................................................................52
6.1.1 Processing skin creation API response .................................................................................................52
6.2 SKIN CANCELLATION API ..............................................................................................................53
6.2.1 Processing skin cancellation API response ...........................................................................................53
7. AUTHENTICATION AS A SERVICE ..................................................................................................54
7.1 CONSTRUCTING AN AUTHENTICATION AAS REQUEST .........................................................................55
7.2 PROCESSING AUTHENTICATION AAS RESPONSE ...............................................................................56
5 Integration Guide 4.0.5
Introduction
Onebip Mobile Payment System will allow you to receive payments from mobile phone subscribers for your services
within a PC or Mobile website.
With Onebip, mobile phone subscribers will be able to make payments for your products and services by debiting their
mobile phone bill or pre-paid account.
Onebip is the simplest payment solution that enables users to make payments for your services through their on-
handsets. Onebip makes mobile payments an easy and immediate experience for all the mobile phone users.
By following the steps detailed in the next chapters in this integration guide, it will be easy and quick to integrate Onebip
mobile payment solution.
6 Integration Guide 4.0.5
1. Onebip Mobile Payment Flow
Onebip Mobile Payment System can be used to:
make mobile payments available within PC website and Mobile website
make ISP billing payments within PC website and Mobile website 1
The mobile payments available within PC and Mobile website can be performed by the end-users with different payment
flow experience depending on the mobile network operator’s technology and policy and the market regulations. Onebip
ensures to deliver the best user experience for your services across multiple devices and different mobile networks in
different countries. Onebip’s continuous optimization of the payment flows and the use of the newest mobile technologies
available ensures higher conversion rates possible.
With Onebip, today there are different payment flows available:
PC WEB MO FLOW: by sending a KEYWORD to a SHORTCODE or by replying an SMS with a KEYWORD
PC WEB PIN FLOW: by receiving a PIN CODE by SMS and inserts it in Onebip payment page,
In addition the flows above, there are 2 flows optimized and specific for mobile web:
MOBILE WEB SMS-LINK FLOW: by clicking on a LINK received by SMS
MOBILE WEB ONE-CLICK FLOW: by clicking on a payment button
The mobile payment flow and the end-user experience is entirely managed by Onebip which automatically then ensures
you to have the best flow available on the market, and does not require any action from your website and/or application.
You can integrate Onebip Mobile Payment System in 2 different ways as seen on the following diagrams which will
perform the above-mentioned payment flows depending on the country2.
1 The ISP billing payment system is not included in this integration guide. Please go to http://www.onebip.com to download the latest
version of Onebip ISP Billing Integration Guide. 2 To get more details about the payment flows used in different countries you can contact us on [email protected].
7 Integration Guide 4.0.5
Onebip Mobile Payment System 1 - You can embed Onebip payment page3 within your own payment page.
START
Customer selects Onebip as the payment method on your website
by clicking on Onebip button
Customer stays on your website and enters his mobile phone
number
Customer confirms the payment (via text message or PIN)
Customer completes the payment
END
Customer receives your confirmation message
3 Please consider the iframe sizes for the following countries: USA mobile billing: max. 670x520px (width x height), France mobile
billing: max. 700x520px (width x height).
Your website
Your website
Your website
Your website
Enter your phone
Authorize
Buy coins with
Completed!
Your payment page
Your payment page
Your payment page
Your payment page
Your website
Thank you for your purchase!
Your payment page
8 Integration Guide 4.0.5
Onebip Mobile Payment System 2: You can redirect your customers to a Onebip payment page opening in a new
browser.
START
Customer selects Onebip as the payment method on your website
redirected to Onebip payment page by clicking on Onebip button
Customer enters his mobile phone number
Customer confirms the payment (via text message or PIN)
Customer completes the payment
END
Customer redirected to your website and receives your message
Your website
Onebip payment page
Enter your number
Onebip payment page
Authorize
Buy coins!
Redirected
Onebip payment page
Completed!
Redirected
Your website
Thank you!
Buy coins with
Thank you for your purchase!
Your payment page
Your payment page
9 Integration Guide 4.0.5
2. Registration and Set-up
In order to start the integration, you first need to create your personal Onebip account through which you will manage all
the activities needed and have a detailed view of every transaction you will receive from your customers.
2.1. Account creation
To create a Onebip account, you should perform the following steps:
1. Go to the following URL and complete the registration process: http://my.onebip.com/signup. After this, you can
now reach your Onebip account and go to step 2.
2. Go to “My Profile” section: http://my.onebip.com/myprofile and include further information about your account,
and the relevant “Financial” and “Account Information”.
3. Make sure that all data are inserted correctly, especially “Company Information” and “Bank accounts” sections
must be complete.
You can see a preview of “My Profile” section on the screenshot below.
2.2. Payment and country enabling
After creating your account, Onebip will have to make certain checks, verify and enable your account to receive the
payments from certain countries. Therefore, you need to communicate with Onebip for the countries which you would like
to receive payments from by clicking “Click here” on the “How to increase your sales” part where you will find on “My
Profile” section.
After Onebip enables your account, you will start receiving transactions into your account from all the mobile subscribers
from all the countries globally where Onebip is connected to mobile network operators4.
Creating a Onebip solution is very simple and straightforward thus the following information are very useful and
mandatory in order for us to properly enable your account:
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 points5 (e.g., 4.99€ for 500 credits, 9.99€ for 1000 Credits)
4 To get more details about Onebip’s coverage please check our website at http://www.onebip.com under “Market info”.
10 Integration Guide 4.0.5
3. Onebip Mobile Payment Integration
Onebip Mobile Payment System will allow you to charge your customers both for one-time payments and subscription-
based payments depending on your service offering with a simple technical integration conducted with HTTP requests.
You can immediately start integrating one-time payments and receiving transactions from your customers by following
the integration steps detailed in this integration guide. To start receiving transactions for the subscription-based
payments also known as “recurring payments”, due to the country regulations, Onebip needs to obtain formal carriers’
approval before you launch your services. You can find more details about the subscription-based payments on chapter
3.2.
3.1. One-time payments
One-time payments means that your customers will be billed only once for the price you are requesting for your service.
One-time payments are also called single purchases where the price of your service are deducted from your customer’s
mobile phone bill or pre-paid account only once.
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:
http://www.onebip.com/api/purchases
Please note that the connection to Onebip payment page can be performed using a standard HTTP request or using a
128bit SSL encryption on our secure server where the structure of the call will be identical, apart from the use of HTTPS
instead of HTTP in the payment page URL.
The following table shows all the case sensitive dynamic parameters you must 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 payment page and on the payment receipt.
255
price Yes End user price in cents (local value added taxes included) as integer cents (actual amount * 100).
e.g. 100 is for 1 of the local currency e.g. 99 is for 0,99 of the local currency
-
currency Yes Local currency code. Please find all the currency codes allowed in Onebip in ISO 4217 standard on http://en.wikipedia.org/wiki/Currency_codes
e.g. USD
3
command Yes Determines the integration type with Onebip. At the moment only allowable values is “express_pay” and other options will be available in the future. e.g. express_pay
50
11 Integration Guide 4.0.5
country Yes
Used only to restrict payments to users from a specific country. e.g. US Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
2
return_url Yes The URL to which your customers’ browser is redirected after they complete a payment. This parameter is fundamental for the complete payment experience of your customers. Your customer is redirected to the page in which she has confirmation of the given payment, and of the resulting benefit. By default, if the parameter is not set in the request, it’s used the value set on the Onebip Panel, under merchant’s settings.
4096
notify_url No The URL to which Onebip will send the technical information and the details about the transaction. If no value is set on the request, it’s used the value set on Onebip Panel, under Merchant settings. If also this configuration is missing, any notification is sent to merchant for the given purchase. For more information about all the notifications available in Onebip please go to the chapter “3.1.2 Processing the Onebip one-time transaction response”.
4096
cancel_url No The URL to which your customers’ browser is redirected if the user click on the “CANCEL” button on the purchase page. This parameter must be used only in the countries in which the cancel button is present on the purchase page. If no value is set in the request, the redirection is made towards the “cancel_url” value set in the Onebip Panel configuration, under merchant’s settings. If also this value is not set the behaviour will be a redirection towards referrer url.
4096
country_disabled No Used to prevent you to receive transaction from specific countries. Typically used if you don’t want to collect money from weak-currency countries. The value is given by a list of country codes comma separated e.g. EG,CO,CL Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
item_code No Pass-through variable you can use to identify your internal item code for this payment. Please note that this is not the Onebip item ID, that may be alphanumeric and may be used to trace the coupling item- payment inside the process.
64
12 Integration Guide 4.0.5
lang No The language used on the payment page that your customers will make the payments. Please find all the language codes allowed in Onebip in ISO 639-1 standard on http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes e.g. en If the value is not set, the default language will be the current language of the browser used for navigation.
2
remote_txid No A pass-through variable and a single and unique transaction ID reference number assigned to your system (your internal transaction ID) for each and single payment. It is used to avoid duplicated transactions, and for this reason the same value cannot be re-used, not even in test phase, because the controls is made on Onebip side.
64
skin No The skin to be used for the required purchase page. Usable only for enabled users. Please see chapter 6 for any detail.
255
logo_url No This URL is the link to integrate a merchant logo inside the Onebip purchase page, in the upper left corner. The mandatory format for the image is 109x33-pixel. The supported extensions are: jpeg, gif, png. e.g. http://www.yoursite.com/images/logo109.jpg
4096
custom No User-defined array of key-value pairs which will be passed through the system and returned in your notify_url and will be appended to your return_url. A maximum of 10 variables (64 characters each) can be used. The formal structure will be: custom[your_variable1] e.g. custom[campaign_code]= promo_oct_10 custom[promo_code]= google campaign Please note that the name of the custom variable chosen by you cannot be the same as one of the parameters used in this table.
Max 10 variables per 64 characters
each
customer_email No Your customer’s email address 255
customer_email_lock No Boolean value (true or false, 1 or 0) If true, the email address field on the payment page can’t be edited manually by your customer
5
customer_firstname No Your customer’s first name 50
customer_firstname_lock No Boolean value (true or false, 1 or 0) If true, the first name field on the payment page can’t be edited manually by your customer
5
13 Integration Guide 4.0.5
customer_lastname No Your customer’s last name 50
customer_lastname_lock No Boolean value (true or false, 1 or 0) If true, the last name field on the payment page can’t be edited manually by your customer
5
customer_cell No Your customer’s cell phone number in international format with no leading e.g. 447700900999 Note that customer_cell must match with customer_country prefix
15
customer_cell_lock No Boolean value (true or false, 1 or 0) If true, the mobile phone number field on the payment page can’t be edited manually by your customer
5
customer_country No Your customer’s country code Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 e.g. US Note that customer_country must match the value given in “country” parameter, if used.
2
The HTTP POST integration model is provided through a payment button to be inserted in your payment page. Below the
URLs of the Onebip payment buttons currently placed at your disposal to have a complete POST integration:
http://www.onebip.com/tools/bts/btn01.gif
http://www.onebip.com/tools/bts/btn02.gif
http://www.onebip.com/tools/bts/btn03.gif
http://www.onebip.com/tools/bts/btn04.gif
http://www.onebip.com/tools/bts/btn05.gif
http://www.onebip.com/tools/bts/btn06.gif
http://www.onebip.com/tools/bts/btn07.gif
http://www.onebip.com/tools/bts/btn08.gif
http://www.onebip.com/tools/bts/btn09.gif
http://www.onebip.com/tools/bts/btn10.gif
http://www.onebip.com/tools/bts/btn20.gif
3.1.1.1. HTML Examples
Below you can find the simplest integration examples with Onebip Payment System for one-time payments, using only
mandatory parameters and some important ones.
You can consider the case below as for a web entertainment service with one-time payment model (associated to the
merchant [email protected]), which will create a Onebip payment button on this merchant’s web site, for the
merchant’s service which will cost $ 0,99 for 1000 game credits in United States for its customers.
14 Integration Guide 4.0.5
The transaction to be created will have the following data:
Username: [email protected]
Item name: 1000 game credits
Item price: $ 0.99 USD
Country: United States
Return URL: http://www.webgame.com/thankyou.htm
Notify URL: http://www.webgame.com/notify.php
The sample HTML code below illustrates a HTTP GET request::
http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1
000+game+credits&price=99&country=US¤cy=USD&return_url=http://www.webgame.com/thankyou.htm¬ify_u
rl=http://www.webgame.com/notify.php
The same result can be performed with a HTTP POST request by using the same parameters:
<form action="http://www.onebip.com/api/purchases" method="post"
target="onebip">
<input type="hidden" name="command" value="express_pay" />
<input type="hidden" name="username" value="[email protected]" />
<input type="hidden" name="description" value="1000 game credits" />
<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="return_url"
value="http://www.webgame.com/thankyou.htm" />
<input type="hidden" name="notify_url" value="http://www.webgame.com/notify.php"
/>
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
15 Integration Guide 4.0.5
In the following, an extended and more realistic example of the integration with HTTP POST for the same operation,
using all the optional parameters will give you more complete control and better tracing of your payment operations.
<form action="http://www.onebip.com/api/purchases" method="post"
target="onebip">
<input type="hidden" name="command" value="express_pay" />
<input type="hidden" name="username" value="[email protected]" />
<input type="hidden" name="description" value="1000 game credits" />
<input type="hidden" name="item_code" value="gm427xl" />
<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.webgame.com/thankyou.html" />
<input type="hidden" name="notify_url"
value="http://www.webgame.com/notify.php" />
<input type="hidden" name="remote_txid" value="12666721" />
<input type="hidden" name="custom[promo_code]" value="promo_oct_10" />
<input type="hidden" name="custom[channel]" value="google campaign" />
<input type="hidden" name="custom[foo]" value="bar" />
<input type="hidden" name="customer_email" value="[email protected]" />
<input type="hidden" name="customer_firstname" value="John" />
<input type="hidden" name="customer_lastname" value="Smith" />
<input type="hidden" name="customer_cell" value="0116434774000" />
<input type="hidden" name="customer_country" value="US" />
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
3.1.1.2. Security signature
Onebip provides you with a process to enforce the security between you and Onebip, using a signature process inside
the http request.
Signature is not mandatory, but can be used if you would like to be sure to protect in the best way the connection with
Onebip, to prevent any possible type of fraud.
If you introduce the signature in the request, Onebip will accept the request only if the signature check is OK, and will
discard it if the check is not passed. If the signature is not present the control won’t be performed.
If used, the signature must be inserted as an additional parameter of the request, always as last parameter of the http
string. Onebip will control the signature, accepting the request only if the value check is correct.
Signature encryption is based on hashing, and has the following form:
signature: hash_hmac('sha256', $url, $key)
This feature requires a secret “key” value, that is the “API Key” that the you must set under the “My Account” section on
Onebip Panel. API key is mandatory to use signature in the request.
16 Integration Guide 4.0.5
Taking the example of the previous chapter, with the following GET request, without signature:
http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1
000+game+credits&price=99&country=US¤cy=USD&return_url=http://www.webgame.com/thankyou.htm¬ify_u
rl=http://www.webgame.com/notify.php
And using the configured API key, that is, the signature is elaborated using the following data, where the url value must
be encoded:
$url:
http://www.onebip.com/api/purchases?command=express_pay&username=business%40webgame.com&d
escription=1000+game+credits&price=99&country=US¤cy=USD&return_url=http%3A%2F%2Fwww.
webgame.com%2Fthankyou.htm¬ify_url=http%3A%2F%2Fwww.webgame.com%2Fnotify.php
$key = 'MySecretKey123456' And the result of the hashing will be:
Signature: 1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7ad8f43
So that, the final version of the GET request, with the signature used, will be:
http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1
000+game+credits&price=99&country=US¤cy=USD&return_url=http://www.webgame.com/thankyou.htm¬ify_u
rl=http://www.webgame.com/notify.php&signature=1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7a
d8f43
The same, identical, process may be applied to http POST request, where the signature value is elaborated in the same
way, and where the final representation of the request would be:
<form action="http://www.onebip.com/api/purchases" method="post"
target="onebip">
<input type="hidden" name="command" value="express_pay" />
<input type="hidden" name="username" value="[email protected]" />
<input type="hidden" name="description" value="1000 game credits" />
<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="return_url"
value="http://www.webgame.com/thankyou.htm" />
<input type="hidden" name="notify_url" value="http://www.webgame.com/notify.php"
/>
<input type="hidden" name="signature"
value="1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7ad8f43" />
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
17 Integration Guide 4.0.5
You can also ask to enforce more security, making the signature control mandatory on Onebip side. This means that the
control of the request will be always made by Onebip for every request, and the request will be accepted only if the check
is ok.
3.1.2. Processing one-time transaction response
Onebip will respond you with a proper notification for each one of your one-time payment requests.
The transaction response must be executed by your landing script to ensure that the transaction is committed on the
Onebip system before recording the customer’s payment as successful in your database. This guarantees no
discrepancies between your transaction records and Onebip.
Onebip responds to successful request of billing notification with:
HEADER: empty
BODY: JSON
All the important and useful information will be inside the JSON body in order for you to understand and manage the
notification successfully.
The following structure will manage both the successful transaction and billing cases, with all the relevant information,
and the error cases, with the description and coding of the error occurred.
Name Always? Description
what: Yes Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
to_url: Yes It’s the notify_url given by you in the HTTP request which is reproposed
here only for compatibility and tracing.
payment_id: No This is a unique ID identifying the payment at Onebip which is present only in case of BILLING_COMPLETED. This ID will be shown in your panel and in your customers’ panel, and will be used to identify the relevant payment. You may use this ID to avoid that the same payment is registered more than once on your side. Note that the format is alphanumeric.
transaction_id: Yes This is a unique ID identifying the transaction at Onebip, that is an object created both for billing completed that for billing aborted. You may use this ID to avoid that the same payment is registered more than once on your side.
Note that the format is alphanumeric.
business_model: Yes For one-time payments and transactions the only one allowable value
is “pull”.
Other values will be used in subscription-based model.
18 Integration Guide 4.0.5
country: Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
currency: Yes The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes
price: Yes End user price in current currency The decimal separator used is “.”; no thousands separator is provided. e.g. 1.99
original_currency: Yes The original currency set by you before Onebip converts it to the local currency of your customer’s country
original_price: Yes The original price set by you before Onebip converts it to the local price of your customer’s country The decimal separator used is “.”; no thousands separator is provided. e.g. 1.99
why: No This parameter is used only in case of BILLING_ABORTED. The value is one of the error code available, listed in the following:
check-pin-failed-too-many-times
mobile-blocked
insufficient-credit
routing-error
invalid-msisdn
out-of-network
payment-failed
transfer-in-aborted
spending-limit-reached
unable-to-send-messages
connectivity-layer-failure
age-verification
sim-full
subscription-already-exists
unknown-error
unknown-exception
Note that more values may be added in future without changing the behaviour of the integration you are currently using.
container: Yes The container, in Onebip environment, is the object of the purchase operation, that may be a one-time payment or a subscription-based payment. In this case of one-time payment the value will be always “purchase”, with the value of the item (a 24 chars alphanumeric). e.g. purchase/09iuh7549bnn4rdc32h80op4
notification_id Yes It’s a unique, alphanumeric id identifying this single notification. Used to prevent any possible duplicate in merhant’s notifications management. If two notifications with the same notification_id are repeated, they represent the single event. e.g. 9iou8yy4sd1n43ww3nj887u0
19 Integration Guide 4.0.5
first_notification_at Yes It’s a n an integer having the value of the UNIX timestamp of when the notification is performed. In case of retries, this timestamp is fixed and always points to the instant at which the first attempt was made. e.g 1364471150 Please pay attention that Unix timestamp is a number, equal to the number of seconds passes since its birth.
mobile_phone_number_enc: Yes The value of the MSISDN of the your customer, who has tried the one-time payment on Onebip payment page which is encrypted in md5. e.g. 88504199e070fc43d2ca1f4896f24b1b
mobile_phone_operator: Yes The mobile network operator of the MSISDN of your customer.
This value is always present in notifications.
e.g. US/Verizon
mobile_phone_number: No The MSISDN of your customer.
This value can be shared with you only under proper commercial
agreements between parties.
remote_txid: No Pass-through variable, a unique transaction reference number for your 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 A JSON object, containing all your custom parameters specified by your request.
3.1.2.1. Notification Examples
The JSON body of a notification message sent from Onebip to your notify_url in case of successful billing will be:
{
“what”: “BILLING_COMPLETED”,
“to_url”: “http://www.webgame.com/notify.php“,
“payment_id”: “23dtle561129ij562jn5tg44”,
“transaction_id”: “84332uu3b56nwa4398il762r”,
“business_model”: “pull”,
“country”: “US”,
“currency”: “USD”,
“price”: 0.99,
“container”: “purchase/09iuh7549bnn4rdc32h80op4”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“remote_txid”: “12666721”,
“item_code”: “gm427xl”
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”
“first_notification_at”: “1364471150”
}
20 Integration Guide 4.0.5
In case of billing aborted, the structure of the JSON body will be the following:
{
“what”: “BILLING_ABORTED”,
“to_url”: “http://www.webgame.com/notify.php“,
“transaction_id”: “84332uu3b56nwa4398il762r”,
“business_model”: “pull”,
“country”: “US”,
“currency”: “USD”,
“price”: 0.99,
“container”: “purchase/09iuh7549bnn4rdc32h80op4”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“remote_txid”: “12666721”,
“item_code”: “gm427xl”
“why”: “insufficient-credit”
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”
“first_notification_at”: “1364471150”
}
Obviously the content of the parameter “why” is dependent on the error with the possible available values listed in the
previous table through which you will be able to store the transaction results in order to create your own statistics about
the failures.
3.1.2.2. Notification Retry
In the notification system, as a consequence of its notifications, Onebip expects to receive a response with:
HEADER STATUS CODE: 200 OK
HEADER BODY: (empty)
If you fail to respond OK, for instance if there is a system error in your web server, Onebip will place the corresponding notification in a queue and will retry periodically to deliver it, until it will be successful.
The retry rules are the following:
One attempt per minute in the first 5 minutes.
One attempt every 5 minutes for the first hour
One retry per hour after the first hour
A total retry period for a payment notification of 24 hours
During the retry period the payment will be stored in your Onebip account as “Pending”.
If Onebip receives no outcome after the total retry period, the payment is considered “Completed” the same, and like that
shown on the panel.
3.1.2.3. Signature encryption
Onebip provides a signature encryption based on hashing, that is an encryption method that ensures the HTTP body
has not been manipulated or changed. This allows the integrity of the body in a data exchange between two parties to be
checked, through an information given in the header of the notifications.
The signature included in the header has the following form:
X-Onebip-Signature: base64_encode(hash_hmac("sha256", <http raw body>, <Onebip API Key>))
21 Integration Guide 4.0.5
X-Onebip-signature is a HMAC hash that uses an hashing algorithm “sha256”, that is 256 bits, encoded in base64.
This feature requires a secret key value (API Key) you will choose that you can set under the “My Account” section.
Enabling the API key means that you will receive a notification with the header enriched with the X-Onebip-Signature.
In the following the example API key is set, and a purchase is completed, with the following data:
$raw_body = '{"country":"US","container":"purchase\\/812894dh207c88056d000000","mobile_phone_number_enc":"10b23c1039c704f87d7bf3cc1a0b8638","status":"completed","price":5,"currency":"USD","business_model":"pull","transaction_id":"726378172","original_price":5,"original_currency":"USD","what":"BILLING_COMPLETED","to_url":"https:\\/\\/www.merchant.com\\/onebip_notification","payment_id":2349872834}';
$key = 'MySecretKey123456'; The result of hashing is the following:
$ X-Onebip-Signature = base64_encode(hash_hmac('sha256', $raw_body, $key, true));
Expected X-Onebip-Signature: cZ7OIG5nS5j2t8nqQBpuUWnGWqN7O0A8U1OpesfqfTE=
Pay attention that hmac must be calculated in binary mode, not in hexadecimal. The hmac is always in binary data.
3.1.3 Return URL
Onebip will append all the pass-through parameters you have specified in the transaction request 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 your customer to her account on your site, or to build customized “post-
payment” also known as “thank you” pages.
Onebip provides you a couple of additional parameters for security reasons:
“timestamp”: is the Unix timestamp, given at the exact time of return_url creation. It can be used to verify
that the url has been created recently.
“signature”: is the security signature given by Onebip, described in detail in the following.
Signature encryption is based on hashing, and has the following form:
signature: hash_hmac('sha256', $url, $key)
This feature requires a secret “key” value (API Key) that you can set under the “My Account” section on Onebip Panel.
Please note that without setting of the API key on Onebip panel, no signature can be created, and so in the return_url
both signature and timestamp parameters will be missing.
In the following example the API key is set on the Onebip Panel so that the signature can be created with the following
data:
22 Integration Guide 4.0.5
$url:
http://www.webgame.com/thankyou.html?payment_id=100801483&original_price=99&original_currency=U
SD&promo_id=23332&whois=msisdn%2Fb667aea7c956ac72ecb6af65e1d9cfec&mobile_phone_operator
=US%2FVerizon&mobile_phone_number_enc=b667aea7c956ac72ecb6af65e1d9cfec×tamp=136610
3067
$key = 'MySecretKey123456' The result of the hashing will be:
Signature: c56ce063388fdd99683b2b79b8d051cdfd120f296e0769948defa006b3fbb0ce
We can now provide a complete example. The completed billing request for a purchase, like in the following example:
http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1
000+game+credits&price=99&country=US¤cy=USD&return_url=http://www.webgame.com/thankyou.html&custom
[promo_id]=23332
will imply, in case of successful billing, a redirection towards the url:
http://www.webgame.com/thankyou.html?payment_id=100801483&original_price=99&original_currency=USD&promo_id
=23332&whois=msisdn%2Fb667aea7c956ac72ecb6af65e1d9cfec&mobile_phone_operator=US%2FVerizon&mobile_ph
one_number_enc=b667aea7c956ac72ecb6af65e1d9cfec×tamp=1366103067&signature=c56ce063388fdd99683b2
b79b8d051cdfd120f296e0769948defa006b3fbb0ce
The return_url page can also route your customer to a specific download page, using the notify_url to authorize it. The
return_url page could also be used to host the scripts needed to grant the permissions for the user to access a specific
product/service you are offering.
We strongly suggest that permissions or other actions needed to deliver your service or product to your customers are
not to be triggered by the return_url page, but by the notify_url.
23 Integration Guide 4.0.5
3.2. Subscription-based payments
You can use Onebip subscription-based payments when you would like to sell your subscription services. If you are not
interested in subscription-based service models you can skip this chapter.
Subscription-based payment, also known as recurring billing or recurring payment, can be used when your customers
are subscribed to your service and are charged periodically such as weekly or monthly for the service you offer.
The technical integration for the subscription-based payments is similar to the one-time payments integration as
explained in the previous chapter. However, to start receiving transactions from subscription-based payments, due to the
country regulations, Onebip needs to obtain formal carriers’ approval before you launch your services and to create a
specific service ID which will be associated to each of your subscription-based service.
In order to obtain a service ID, you should communicate with Onebip business team by agreeing on the specifications of
your services such as the price6 and the frequency of the service. Once you have the formal carriers’ approval and the
service ID for your service you should include the service ID into the integration as specified in the following paragraphs.
3.2.1 Constructing subscription payment requests
The connection with Onebip payment page is achieved by using HTTP GET or POST requests to the following URL:
http://www.onebip.com/api/subscriptions
Please note that the connection to Onebip payment page can be performed using a standard HTTP request or using a
128bit SSL encryption on our secure server where the structure of the call will be identical, apart from the use of HTTPS
instead of HTTP in the payment page URL.
The following table shows all the case sensitive dynamic parameters you must use in your payment query string to
Onebip:
Name Required? Description Length
service_id Yes The foremost value for the subscription-based calls. It will be a specific service ID which will be associated to each of your subscription-based service which must be used always for all the requests. The format is a 24 chars alphanumeric.
24
command Yes Determines the integration type with Onebip. At the moment only allowable values is “express_pay” and other options will be available in the future. e.g. express_pay
50
return_url Yes The URL to which your customers’ browser is redirected after they complete a payment. This parameter is fundamental for the complete payment experience of your customers. Your customer is redirected to the page in which she has confirmation of the given payment, and of the resulting benefit. By default, if the parameter is not set in the request, it’s used the value set on the Onebip Panel, under merchant’s settings.
4096
6 To learn the available subscription-based price points please contact our business team on [email protected].
24 Integration Guide 4.0.5
notify_url No The URL to which Onebip will send the technical information and the details about the transaction. If no value is set on the request, it’s used the value set on Onebip Panel, under Merchant settings. If also this configuration is missing, any notification is sent to merchant for the given purchase. For more information about all the notifications available in Onebip please go to the chapter “3.2.2 Processing the Onebip subscription transaction response”.
4096
cancel_url No The URL to which your customers’ browser is redirected if the user click on the “CANCEL” button on the purchase page. This parameter must be used only in the countries in which the cancel button is present on the purchase page. If no value is set in the request, the redirection is made towards the “cancel_url” value set in the Onebip Panel configuration, under merchant’s settings. If also this value is not set the behaviour will be a redirection towards referrer url.
4096
item_code No Pass-through variable you can use to identify your internal item code for this payment. Please note that this is not the Onebip item ID, and may be used to trace the coupling item- payment inside the process.
64
lang No The language used on the payment page that your customers will make the payments. Please find all the language codes allowed in Onebip in ISO 639-1 standard on http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes e.g. en If the value is not set, the default language will be the one currently used by the browser used.
2
remote_txid No A pass-through variable and a single and unique transaction ID reference number assigned to your system (your internal transaction ID) for each and single payment. It is used to avoid duplicated transactions, and for this reason the same value cannot be re-used, not even in test phase, because the controls is made on Onebip side.
64
skin No The skin to be used for the required purchase page. Usable only for enabled users. Please see chapter 6 for any detail.
255
logo_url No This URL is the link to integrate a merchant logo inside the Onebip purchase page, in the upper left corner. The mandatory format for the image is 109x33-pixel. The supported extensions are: jpeg, gif, png. e.g. http://www.yoursite.com/images/logo109.jpg
4096
25 Integration Guide 4.0.5
custom No User-defined array of key-value pairs which will be passed through the system and returned in your notify_url and will be appended to your return_url. A maximum of 10 variables (64 characters each) can be used. The formal structure will be: custom[your_variable1] e.g. custom[campaign_code]= promo_oct_10 custom[promo_code]= google campaign Please note that the name of the custom variable chosen by you cannot be the same as one of the parameters used in this table.
Max 10 variables per 64 characters
each
customer_cell No Your customer’s cell phone number in international format with no leading e.g. 447700900999 Note that customer_cell must match customer_country prefix
15
customer_cell_lock No Boolean value (true or false, 1 or 0) If true, the mobile phone number field on the payment page can’t be edited manually by your customer
5
The HTTP POST integration model is provided through a payment button to be inserted in your payment page. Below the
URLs of the Onebip payment buttons currently placed at your disposal to have a complete POST integration:
http://www.onebip.com/tools/bts/btn01.gif
http://www.onebip.com/tools/bts/btn02.gif
http://www.onebip.com/tools/bts/btn03.gif
http://www.onebip.com/tools/bts/btn04.gif
http://www.onebip.com/tools/bts/btn05.gif http://www.onebip.com/tools/bts/btn06.gif http://www.onebip.com/tools/bts/btn07.gif http://www.onebip.com/tools/bts/btn08.gif http://www.onebip.com/tools/bts/btn09.gif http://www.onebip.com/tools/bts/btn10.gif
3.2.1.1. HTML Examples
Below you can find the simplest integration examples with Onebip Payment System for one-time payments, using only
mandatory parameters and some important ones.
You can consider the case below as for a web entertainment service with subscription-based payment model (associated
to the merchant [email protected]), which will create a Onebip payment button on this merchant’s web site, for
the merchant’s weekly subscription service named “Supergame” which will cost € 5,00 per week in Spain for its
customers.
The transaction to be created will have the following data:
Service ID: 5012b69ca4ee4aa3f3d3r415
Username: [email protected]
Description: Supergame
Frequency: weekly
Price: 5,00
Currency: EUR
26 Integration Guide 4.0.5
Country: Spain
Language: Spanish
Return URL: http://www.webgame.com/thankyou.html
Cancel URL: http://www.webgame.com/error.html
Notify URL: http://www.webgame.com/notify.php
The sample HTML code below illustrates a HTTP GET request. In the example, apart from the mandatory parameters, it
is assumed that the merchant has overwritten the return_url and the notify_url for its particular needs:
http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415&retu
rn_url=http://www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php
The same result can be performed with a HTTP POST request with the same parameters:
<form action="http://www.onebip.com/api/subscriptions" method="post"
target="onebip">
<input type="hidden" name="service_id" value="5012b69ca4ee4aa3f3d3r415" />
<input type="hidden" name="command" value="express_pay" />
<input type="hidden" name="return_url"
value="http://www.webgame.com/thankyou_new.html" />
<input type="hidden" name="notify_url"
value="http://www.webgame.com/notify_updated.php" />
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
3.2.1.2 Security signature
Onebip provides you with a process to enforce the security between you and Onebip, using a signature process inside
the http request.
Signature is not mandatory, but can be used if you would like to be sure to protect in the best way the connection with
Onebip, to prevent any possible type of fraud.
If you introduce the signature in the request, Onebip will accept the request only if the signature check is OK, and will
discard it if the check is not passed. If the signature is not present the control won’t be performed.
If used, the signature must be inserted as an additional parameter of the request, always as last parameter of the http
string. Onebip will control the signature, accepting the request only if the value check is correct.
Signature encryption is based on hashing, and has the following form:
signature: hash_hmac('sha256', $url, $key)
This feature requires a secret “key” value, that is the “API Key” that you must set under the “My Account” section on
Onebip Panel. API key is mandatory to use signature in the request.
Taking the example of the previous chapter, with the following GET request, without signature:
http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415&retu
rn_url=http://www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php
27 Integration Guide 4.0.5
And using the configured API key, that is, the signature is elaborated using the following data, where the url must be
encoded for what concerns the parameters:
$url:
http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r41
5&return_url=http%3A%2F%2Fwww.webgame.com%2Fthankyou_new.html¬ify_url=http%3A%2F%2F
www.webgame.com%2Fnotify.updated.php
$key = 'MySecretKey123456' And the result of the hashing will be:
Signature: ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622
So that, the final version of the GET request, with the signature used, will be:
http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415&retu
rn_url=http://www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php&
signature=ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622
The same, identical, process may be applied to http POST request, where the signature value is elaborated in the same
way, and where the final representation of the request would be:
<form action="http://www.onebip.com/api/subscriptions" method="post"
target="onebip">
<input type="hidden" name="service_id" value="5012b69ca4ee4aa3f3d3r415" />
<input type="hidden" name="command" value="express_pay" />
<input type="hidden" name="return_url"
value="http://www.webgame.com/thankyou_new.html" />
<input type="hidden" name="notify_url"
value="http://www.webgame.com/notify_updated.php" />
<input type="hidden" name="signature" value="
ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622" />
<input type="image" name="submit"
src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
You can also ask to enforce more security, making the signature control mandatory on Onebip side. This means that the
control of the request will be always made by Onebip for every request, and the request will be accepted only if the check
is ok.
3.2.2 Processing subscription transaction response
The transaction response has to be executed by your landing script to ensure the transaction is committed on the Onebip
system before recording your payment as successful in your database.
Two kinds of notifications are provided to you:
1. Change State event: change of state related to a subscription, among the existing ones.
SUBSCRIPTION_ACTIVATION: new subscription succeeded, triggered by merchant request
SUBSCRIPTION_CANCELED: new subscription failed, caused by no possible charging of the user
28 Integration Guide 4.0.5
SUBSCRIPTION_TERMINATED: existing subscription termination, triggered by merchant (using the API
described in chapter 4.1), or by Onebip cc, or by operators’ cc.
SUBSCRIPTION_SUSPENDED: triggered by operators, only in some countries
SUBSCRIPTION_REACTIVATED: triggered by operators, only in some countries
SUBSCRIPTION_RENEWED: event for every renewal case of every subscription, depending by payment
completion
2. Billing event: status of the billing linked to the subscription events of activation and renewal
Onebip notification format will be always the same:
HEADER: empty
BODY: JSON
All the important and useful information will be inside the JSON body in order for you to understand and manage the
notification successfully.
3.2.2.1. Change state event notification
For every change in the state of the event, a notification is sent to you, containing the following information:
Name Always? Description
what: Yes Represent the content of the notification regarding a subscription-based
payment. The possible values, without a need of an explanation, are:
SUBSCRIPTION_ACTIVATED
SUBSCRIPTION_TERMINATED
SUBSCRIPTION_CANCELED
SUBSCRIPTION_SUSPENDED
SUBSCRIPTION_REACTIVATED
SUBSCRIPTION_RENEWED
to_url Yes It’s the notify_url given by you in the HTTP request which is reproposed
here only for compatibility and tracing.
country: Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
container: Yes The container, in Onebip environment, is the object of the purchase operation, that may be a one-time payment or a subscription-based payment. In the case of subscription-based payment the value will be always the “subscription_id” created by Onebip as a result of successful subscription transaction. The subscription id is univocally related to one service_id and one MSISDN only, and it’s a 24 chars alphanumeric, not repeatable. e.g. subscription/20332b9ca4er34aa3g3d3r198
service_idff Yes It’s the key value that identifies with a unique and not repeatable index of the service concerning the operation. Note that this value will be a 24 chars alphanumeric. e.g. : 5012b69ca4ee4aa3f3d3r415
29 Integration Guide 4.0.5
notification_id Yes It’s a unique, alphanumeric id identifying this single notification. Used to prevent any possible duplicate in merhant’s notifications management. If two notifications with the same notification_id are repeated, they represent the single event. e.g. 9iou8yy4sd1n43ww3nj887u0
first_notification_at Yes It’s a n an integer having the value of the UNIX timestamp of when the notification is performed. In case of retries, this timestamp is fixed and always points to the instant at which the first attempt was made. e.g 1364471150 Please pay attention that Unix timestamp is a number, equal to the number of seconds passes since its birth.
mobile_phone_number_enc: Yes The value of the MSISDN of the your customer, who has tried the one-time payment on Onebip payment page which is encrypted in md5. e.g. 88504199e070fc43d2ca1f4896f24b1b
mobile_phone_operator: Yes The mobile network operator of the MSISDN of your customer.
This value is always present in every notification.
e.g. : US/Verizon
mobile_phone_number: No The MSISDN of your customer. This value can be shared with you only
under proper commercial agreements between parties.
remote_txid: No Pass-through variable, a unique transaction reference number for your 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 A JSON object, containing all your custom parameters specified by your request.
3.2.2.2. Billing event notification
For every event regarding billing, you will receive a notification with these information:
Name Always present? Description
what: Yes Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
to_url Yes It’s the notify_url given by you in the HTTP request which is reproposed
here only for compatibility and tracing.
30 Integration Guide 4.0.5
payment_id: No This is a unique ID identifying the payment at Onebip which is present only in case of BILLING_COMPLETED. This ID will be shown in your panel and in your customers’ panel, and will be used to identify the relevant payment. You may use this ID to avoid that the same payment is registered more than once on your side. Note that the format is alphanumeric.
transaction_id: Yes This is a unique ID identifying the transaction at Onebip, that is an object created both for billing completed that for billing aborted. You may use this ID to avoid that the same payment is registered more than once on your side.
Note that the format is alphanumeric.
business_model: Yes The possible values are:
subscription_activation
subscription_renewal
country: Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
currency: Yes The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes
price: Yes End user price in current currency. The decimal separator used is “.”; no thousands separator is provided. e.g. 1.99
original_currency: Yes The original currency set by you before Onebip converts it to the local currency of your customer’s country
original_price: Yes The original price set by you before Onebip converts it to the local price of your customer’s country The decimal separator used is “.”; no thousands separator is provided. e.g. 1.99
container: Yes The container, in Onebip environment, is the object of the purchase operation, that may be a single purchase or a subscription. In this case of subscription-based transaction the value will always be “subscription”, with the value of the item (a 24 chars alphanumeric). e.g. subscription/20332b9ca4er34aa3g3d3r198
mobile_phone_number_enc: Yes The value of the MSISDN of the your customer, who has tried the subscription-based payment on Onebip payment page which is encrypted in md5. e.g. 88504199e070fc43d2ca1f4896f24b1b
mobile_phone_operator: Yes The mobile network operator of the MSISDN of your customer.
This value is always present, in every notification:
e.g.: US/Verizon
31 Integration Guide 4.0.5
mobile_phone_number: No The MSISDN of your customer.
This value can be shared with you only under proper commercial
agreements between parties.
remote_txid: No Pass-through variable, a unique transaction reference number for your 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 A JSON object, containing all your custom parameters specified by your request.
why: No This parameter is used only in case of BILLING_ABORTED. The value is one of the error code available, listed in the following:
check-pin-failed-too-many-times
mobile-blocked
insufficient-credit
routing-error
invalid-msisdn
out-of-network
payment-failed
transfer-in-aborted
spending-limit-reached
unable-to-send-messages
connectivity-layer-failure
age-verification
sim-full
subscription-already-exists
unknown-error
unknown-exception
Note that more values may be added in future without changing
Hash No Hash checksum of your API Key and of the notification URL parameters.
3.2.2.3. Notification examples
The examples following are the series of examples to represent you all the different business cases related to a
subscription-based service, with the consequent notifications that you will receive.
32 Integration Guide 4.0.5
Subscription activation succeeded
Following a specific request received from you, Onebip will send two notifications to you: the event of activation, the first
billing.
{
“what”: “SUBSCRIPTION_ACTIVATED”,
“to_url”: “http://www.webgame.com/notify.php“,
“container”: ““subscription/20332b9ca4er34aa3g3d3r19”,
“service_id”: “5012b69ca4ee4aa3f3d3r415”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”
"mobile_phone_operator":"US/Verizon",
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364498611”
}
{
“what”: “BILLING_COMPLETED”,
“to_url”: “http://www.webgame.com/notify.php“,
“business_model”: “subscription_activation“,
“container”: “subscription/20332b9ca4er34aa3g3d3r19”,
“payment_id”: “23dtle561129ij562jn5tg44”,
“transaction_id”: “84332uu3b56nwa4398il762r”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“country”: “US”,
“currency”: “USD”,
“price”: 5,
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364498612”
}
Subscription activation failed
When a subscription process is not completed successfully, in most cases because it was not possible to charge your
customer, or there was a problem with the mobile network operator, Onebip will send two notifications to you:
{
“what”: “SUBSCRIPTION_CANCELED”,
“to_url”: “http://www.webgame.com/notify.php“,
“container”: “subscription/11132555a4er3faa3g3d3fff”,
“service_id”: “5012b69ca4ee4aa3f3d3r415”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364498611”
}
33 Integration Guide 4.0.5
{
“what”: “BILLING_ABORTED”,
“to_url”: “http://www.webgame.com/notify.php“,
“business_model”: “subscription_activation“,
“container”: “subscription/11132555a4er3faa3g3d3fff”,
“payment_id”: “23dtle561129ij562jn5tg44”,
“transaction_id”: “84332uu3b56nwa4398il762r”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“country”: “US”,
“currency”: “USD”,
“price”: 5,
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364498676”
}
Subscription renewal succeeded
This is called a “push” operation generated by Onebip after a completed renewal of an active subscription. The
notification towards you will be about change state the payment completed.
{
“what”: “SUBSCRIPTION_RENEWED”,
“to_url”: “http://www.webgame.com/notify.php“,
“container”: ““subscription/20332b9ca4er34aa3g3d3r19”,
“service_id”: “5012b69ca4ee4aa3f3d3r415”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”
"mobile_phone_operator":"US/Verizon",
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364498676”
}
{
“what”: “BILLING_COMPLETED”,
“to_url”: “http://www.webgame.com/notify.php“,
“business_model”: “subscription_renewal“,
“container”: “subscription/20332b9ca4er34aa3g3d3r19”,
“payment_id”: “00rtlaa31129inn3y7t5tg21”,
“transaction_id”: “06312uaa55690op398ilwq30”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“country”: “US”,
“currency”: “USD”,
“price”: 5,
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364471150”
}
34 Integration Guide 4.0.5
Subscription renewal failed
This notification is sent when the renewal attempt of a subscription service is failed because it was not possible to charge
your customer.
{
“what”: “BILLING_ABORTED”,
“to_url”: “http://www.webgame.com/notify.php“,
“business_model”: “subscription_renewal”,
“container”: “subscription/20332b9ca4er34aa3g3d3r19”,
“transaction_id”: “00132uuaa56nwa4398il732a”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”,
"mobile_phone_operator":"US/Verizon",
“country”: “US”,
“currency”: “USD”,
“price”: 5,
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364471150”
}
Subscription termination
This notification is a result of your request towards “Unsubscription API” in this guide or a result of a “push” notification
due to the other termination methods such as inquiries received to Onebip customer care call centre.
In this case, the same notification for the status change will be sent to you:
{
“what”: “SUBSCRIPTION_TERMINATED”,
“to_url”: “http://www.webgame.com/notify.php“,
“container”: “subscription/20332b9ca4er34aa3g3d3r19”,
“service_id”: “5012b69ca4ee4aa3f3d3r415”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”
"mobile_phone_operator":"US/Verizon",
“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,
“first_notification_at”: “1364471150”
}
Analogous notifications are provided for the suspension and reactivation of the operations, that moreover are used only
in few special payment flows in some countries, due to specific operators’ regulations.
3.2.2.4. Notification retry
In the notification system, as a consequence of its notifications, Onebip expects to receive a response with::
HEADER STATUS CODE: 200 OK
HEADER BODY: (empty)
If you fail to respond OK, for instance if there is a system error in your web server, Onebip will place the corresponding
notification in a queue and will retry periodically to deliver it, until it will be successful.
The retry rules are the following:
One attempt per minute in the first 5 minutes.
35 Integration Guide 4.0.5
One attempt every 5 minutes for the first hour
One retry per hour after the first hour
A total retry period for a payment notification of 24 hours
If Onebip receives no outcome after the total retry period, the notification will be automatically cancelled.
3.2.2.5. Signature encryption
Onebip provides a signature encryption based on hashing, that is an encryption method that ensures the HTTP body
has not been manipulated or changed. This allows the integrity of the body in a data exchange between two parties to be
checked, through an information given in the header of the notifications. The signature included in the header has the
following form:
X-Onebip-Signature: base64_encode(hash_hmac("sha256", <http raw body>, <Onebip API Key>))
X-Onebip-signature is a HMAC hash that uses an hashing algorithm “sha256”, that is 256 bits, encoded in base64.
This feature requires a secret key value (API Key) you will choose that you can set under the “My Account” section.
Enabling the API key means that you will receive a notification with the header enriched with the X-Onebip-Signature.
In the following the example the API key is set, and purchase is completed, with the following data:
$key = 'MySecretKey123456';
$raw_body = '{"country":"TR","remote_txid":"AB_22022122","container":"subscription\\/562634za43bc76051d003309","mobile_phone_number_enc":"10b23c1039c704f87d7bf3cc1a0b8638","status":"completed","price":8,"currency":"TRY","business_model":"pull","transaction_id":"76939310","original_price":8,"original_currency":"TRY","what":"BILLING_COMPLETED","to_url":"http:\\/\\/merchant.com\\/vpncontrol\\/onebip\\/ip n","payment_id":11149219}';
The result of hashing is the following:
$ X-Onebip-Signature = base64_encode(hash_hmac('sha256', $raw_body, $key, true));
Expected X-Onebip-Signature: UsuOSZINqUdDpxkM2/anV5+mtjim0ZPjxWLDPwiPQR4=
Pay attention that hmac must be calculated in binary mode, not in hexadecimal. The hmac is always in binary data.
3.2.3. Return URL
Onebip will append all the pass-through parameters you have specified in the transaction request 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 your customer to her account on your site, or to build customised “post-
payment” also known as “thank you” pages.
Onebip provides you with couple of additional parameters for security reasons:
“timestamp”: is the Unix timestamp, given at the exact time of return_url creation. It can be used by
merchant to verify that the url has been created recently.
36 Integration Guide 4.0.5
“signature”: is the security signature given by Onebip, described in detail in the following.
Signature encryption is based on hashing, and has the following form:
signature: hash_hmac('sha256', $url, $key)
This feature requires a secret “key” value (API Key) that you can set under the “My Account” section on Onebip Panel.
Please note that without setting of the API key on Onebip panel, no signature can be created, and so in the return_url
both signature and timestamp parameters will be missing.
In the following example the API key is set on the Onebip Panel so that the signature can be created with the following
data:
Service ID: 5012b69ca4ee4aa3f3d3r415
Username: [email protected]
Description: Supergame
Frequency: weekly
Price: 5,00
Currency: EUR
Country: Spain
Language: Spanish
Return URL: http://www.webgame.com/thankyou.html
Cancel URL: http://www.webgame.com/error.html
Notify URL: http://www.webgame.com/notify.php
The request for the subscription activation will be the following one:
http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415&return_url=http://www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php
The signature to be added in the return url can be created with the following data:
$url:
http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7&
mobile_phone_operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf
2e7&is_subscribed_to=5012b69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415×ta
mp=1366102294
$key = 'MySecretKey123456' The result of the hashing will be:
Signature: 6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f
So that, in our example, the final return url will be:
http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7&mobile_phone_
operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7&is_subscribed_to=5012b
69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415×tamp=1366102294&signature=6042d0f9d722
a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f
37 Integration Guide 4.0.5
The return_url page can also route your customer to a specific download, using the notify_url to authorize it. The
return_url page could also be used to host the scripts needed to grant the permissions for the user to access a specific
product/service you offer.
We strongly suggest that permissions or other actions needed to deliver your service or product to your customers are
not to be triggered by the return_url page, but by the notify_url.
38 Integration Guide 4.0.5
4 API integration
Onebip provides with the opportunity to have the additional features that will allow you to manage the operations of
unsubscription and black-lists.
4.1 Unsubscription API
You can change the state of a subscription from ACTIVE to TERMINATED using a specific Onebip Unsubscription API.
The method will be the following:
DELETE /api/subscription/<ID>
Where <ID> is the subscription_id created by Onebip at the act of first subscription.
You will be allowed to use this action only with the authentication by using your username and password that you created
during your registration process of Onebip.
An example, using curl, can be seen in the following box:
curl -u [email protected]:m3rc4nt123 -X DELETE
http://www.onebip.com/api/subscription/291dd69cr4ee4aa3f1d3rt85
Onebip expects to receive a response with::
HEADER: 200 OK
BODY: empty
4.2 Blacklist API
With blacklist API you can decide to “blacklist” an MSISDN or a Onebip user who may have one or more MSISDNs
associated to her Onebip account, which has performed at least one one-time or subscription-based transaction towards
for one of your services.
On one hand, this means that the blacklisted user won’t be able to complete any other transactions for any of your
services in future. On the other hand, with a similar operation you can also “un-blacklist” the MSISDNs or the users which
you have blacklisted before in order to allow them to make transactions again for your services.
4.2.1 Constructing a blacklist requests
You can request a blacklist operation using a HTTP POST method towards the url:
http(s)://www.onebip.com/api/blacklist
You will be allowed to use this action only with the authentication by using your username and password that you created
during your registration process of Onebip.
39 Integration Guide 4.0.5
The following table presents the 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 parameters.
Name Required Description
payment_id As alternative If you are interested in blacklisting the user starting from one of his transactions.
user_email As alternative If you are interested in blacklist the user associated to that email address. The consequence is to black list all the mobile phone numbers associated to the user, than can be one or more.
mobile_phone_number
As alternative If you are interested in blacklist the mobile phone number associated (when available).
mobile_phone_number_enc
As alternative If you are interested in blacklist the mobile phone number associated.
An example, using curl, of this communication by using an HTTP POST request would be:
curl -v -u [email protected]:secret_password
http://www.onebip.com/api/blacklist -X POST
-d "mobile_phone_number_enc=4812c91a1bbG8f5a78889cf62e28aedc"
or, as an alternative:
curl -v -u [email protected]:secret_password
http://www.onebip.com/api/blacklist -X POST
-d "[email protected]"
4.2.2 Constructing an un-blacklist requests
You can request an un-blacklist operation using a HTTP DELETE method towards the url:
http(s)://www.onebip.com/api/blacklist/[ID]
where [ID] is one of the valid IDs which is useful for the un-blacklist operation.
You will be allowed to use this action only with the authentication by using your username and password that you created
during your registration process of Onebip.
The following are the case sensitive dynamic parameters that you can choose to use in your un-blacklist request
according to your needs.
Please note that you need to use just one of the following parameter, without the parameter name:
Required Description
user_email As alternative If you are interested in un-blacklist the user associated to that email address
mobile_phone_number
As alternative If you are interested in un-blacklist the mobile phone number associated (when available).
mobile_phone_number_enc
As alternative If you are interested in unblacklist the mobile phone number associated.
40 Integration Guide 4.0.5
An example, using curl, of this communication using an HTTP DELETE request having the user email:
curl -X DELETE -v -u [email protected]:secret_password
http://www.onebip.com/api/blacklist/[email protected]
4.2.3 Processing the blacklist / un-blacklist response
The possible response from Onebip for a Blacklist or Un-blacklist request will be the following:
200 OK after a successful GET response; Header – Content-Type: application/json Body – a JSON object containing the list of blacklisted MSISDNs, or just an MSISDN.
201 Created through a POST, the MSISDN or list of MSISDNs have been blacklisted; Header – Location: <resource_id> where <resource_id> is the unique identifier that can be used to retrieve the just created resource (blacklisted MSISDN).
401 Unauthorized when wrong authorization keys are sent, or the user is not allowed for the blacklist operation.
400 Bad Request when the passed parameters are not valid, or some parameters are missed.
403 Forbidden when who tries to blacklist some MSISDNs is not allowed for some reason.
404 Not Found when the resource was not found.
500 Internal Server Error Some unexpected error occurred.
4.3 Back-office API
Back-office API will allow you to obtain some additional and asynchronous information about a large quantity of data from
Onebip platform. In particular, the information available is the data for the transactions related to your services
(Transaction API), the aggregated data about the transactions results (Transactions Stats), the aggregated data about
active customer base and subscription behaviour (Customer Base Status API).
4.3.1 Back-office Transactions API
You can retrieve the transaction data from Onebip related to your services using Onebip Back-office Transactions API.
Onebip will expose the transaction data to you by giving you the opportunity to filter them by using relevant fields.
41 Integration Guide 4.0.5
Below is an example of a transaction:
{
"id":"50c84ed2c1b6592135000000",
"container":"subscription/50c84ed2c1b6592135000000",
"created_at":"2012-12-04T09:08:07Z",
"country":"US",
"currency":"USD",
"amount": 7.50,
"status":"aborted",
"why":"insufficient-credit",
"business_model": "subscription_renewal",
"context":"web",
"description":"1000 game credits",
"details":
{
"flow":"no-optin-flow",
"source":"MTB",
"remote_txid":"12QW34ER56TY,
"mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af",
"mobile_phone_number":"154797140490",
"mobile_phone_operator":"US/Verizon",
"custom":
{
"your_variable1":"your_value1",
"your_variable2":"your_value2",
“foo”:”bar”
},
},
}
To obtain a list of transactions, you must perform a GET HTTP request towards the following url:
https://www.onebip.com/bko/transactions
This HTTP route is the only point of access to gain information about the transactions and you can be fine grained as you
want to use the filters which may be expressed in the query string as a value of the parameter query.
Filters must be written in JSON format.
There are four fields through which you can filter the result:
id: the id of the transaction
container: the id of the container (to select its transactions)
MSISDN: the msisdn of the transaction
created_at: the creation date of the transaction
42 Integration Guide 4.0.5
The following examples will give you the complete idea of the operational behaviour. The first one is to obtain all the
transactions for a given MSISDN:
GET /bko/transactions?query={“msisdn”:”393482456742”}
The result will be a JSON object with a property called ‘element’ which contains a list of all the transactions owned by
you which has been generated from the MSISDN you have specified in the filter.
Another example is about a query per transaction_id, that will return a JSON Object with a property called ‘elements’
which contains a list with a single transaction as result.
GET /bko/transactions?query={“id”:”00096877511”}
Another one is about the container_id that may be related a subscription-based service:
GET /bko/transactions?query={“container”:”subscription/50b392d9419615990b00111a”}
The result in this case will be a JSON object with a property called ‘element’ which contains a list of all the transactions
owned by you which has been generated within the container specified.
Another example may refer to the creation date, that can be a single date or a range.
Onebip Back-office API uses only date which are in the UTC time-zone and they must be specified like in the following
pattern: YYYYMMDDhhmmss.
GET /bko/transactions?query={“created_at”:”20121212000000”}
Onebip Back-office API supports also the filtering of the range of the date like in the following example:
GET /bko/transactions?query={“created_at”: {“$gt”:”20121201000000”, “$lt”: “20121215235959””}
In this case four operators are available to specify the role of a date in the filter:
$gt means greater than
$gte means greater than or equals
$lt means less than
$lte means less than or equals
Onebip Back-office API should only be used through an authentication. You can perform requests only following the
HTTP Basic Authentication which consists in placing the “Authorization” HTTP Header in the HTTP Request with the
value of the tring computed with the following formula:
43 Integration Guide 4.0.5
Base64(“username:password”)
Moreover, Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are
not in HTTPS will result in a 400 Bad Request response.
The following two complete examples, using curl, comprehends:
curl -u " [email protected]:123456"
'https://www.onebip.com/bko/transactions?query={"id":"50bdaf6721bc88790d000001"}'
curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY="
'https://www.onebip.com/bko/transactions?query={"id":"50bdaf6721bc88790d000001"}'
4.3.1.1. Processing Back-office Transactions API response
The possible response from Onebip for a transactions request will be the following:
200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format
400 Bad Request The request is malformed and Onebip doesn’t want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed filter
401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request.
403 Forbidden The merchant has not enough privileges to access the resource
404 Not Found Onebip is not able to find the resource requested from the merchant
44 Integration Guide 4.0.5
The following is a complete example of a 200 OK response:
Status: 200
{
“elements”:[{
"id":"50c84ed2c1b6592135000000",
"container":"subscription/50c84ed2c1b6592135000000",
"created_at":"2012-12-04T09:08:07Z",
"country":"US",
"currency":"USD",
"amount": 7.50,
"status":"aborted",
"why":"insufficient-credit",
"business_model": "subscription_renewal",
"context":"web",
"description":"1000 game credits",
"details":
{
"flow":"no-optin-flow",
"source":"MTB",
"remote_txid":"12QW34ER56TY,
"mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af",
"mobile_phone_number":"393482355312",
"mobile_phone_operator":"US/Verizon",
"custom":
{
"your_variable1":"your_value1",
"your_variable2":"your_value2",
“foo”:”bar”
},
},
}]
}
45 Integration Guide 4.0.5
4.3.2 Back-office Transaction Stats API
Using Onebip Back-office API it’s also possible to retrieve transaction statistics from Onebip by mean of aggregation data
stored and managed by Onebip platform.
Onebip indeed exposes the data about the transaction statistics, giving you the opportunity to you to filter them by using
some fields.
Here is an example of a transaction Stats output:
{
"country":"TR",
"ok":153,
"ko":33,
"total":186
}
To list the transaction statistics you must perform a GET HTTP request towards the following url:
https://www.onebip.com/bko/transactions-stats
This HTTP route is the only point of access to gain information about transactions statistics and you can be fine grained
as you want to use filters which may be expressed in the query string as a value of the parameter query.
Filters must be written in JSON format.
Onebip Back-office API for Transactions Statistics supports the following fields for filtering:
date: the date on which perform statistics counts
container: the type of the container (subscription or purchase)
amount: the amount of the transaction
country: the country where the transaction happened
carrier: the carrier of the transaction in to form COUNTRY\Operator
context: the context of the transaction (web, mobile, …)
The following example will give the complete idea of the operational behaviour.
The first one is to obtain the result for a given country:
GET /bko/transactions-stats?query={“country”:”TR”}
And the result will be the transaction statistics for the transactions owned by you filtered on the country specified in the
filter.
Another example is about a query per container:
GET /bko/transactions-stats?query={“container”:”subscription”}
The result are the transaction statistics for the transactions owned by you filtered on the container specified in the filter.
46 Integration Guide 4.0.5
Another example is about a combined filter:
GET /bko/transactions-stats?query={“container”:”subscription”,”amount”:10}
The result are transaction statistics for the transactions owned by you filtered on the container and the amount as specified in the filter.
Another example may refer to the creation date, that can be a single date or a range.
Onebip Back-office API uses only the date which are in the UTC time-zone and they must be specified following this
pattern: YYYYMMDDhhmmss.
GET /bko/transactions-stats?query={“date”:”20121212000000”}
Onebip Back-office API supports also the filtering of the range of the date as seen on the following example:
GET /bko/transactions-stats?query={“created_at”: {“$gt”:”20121201000000”, “$lt”: “20121215235959””}
The result is to give to you the access to the statistics of your subscriptions for the amount 10 resulted in 12/12/2012.
In this last case four operators are available, to specify the role of a date in the filter:
$gt means greater than
$gte means greater than or equals
$lt means less than
$lte means less than or equals
Onebip Back-office API should only be used through an authentication. You can perform requests only following the
HTTP Basic Authentication which consists in placing the “Authorization” HTTP Header in the HTTP Request with the
value of the tring computed with the following formula:
Base64(“username:password”)
Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are not in
HTTPS will result in a 400 Bad Request response.
The following two complete examples, using curl, comprehends:
curl -u "[email protected]:123456" 'https://www.onebip.com/bko/transactions-
stats?query={“container”:”subscription”}'
curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY="
'https://www.onebip.com/bko/transactions-
stats?query={“container”:”subscription”}'
47 Integration Guide 4.0.5
4.3.2.1. Processing Back-office Transactions Stats API response
The possible response from Onebip for a transaction statistics request are the following:
200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format
400 Bad Request The request is malformed and Onebip doesn’t want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed filter
401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request.
403 Forbidden The merchant has not enough privileges to access the resource
404 Not Found Onebip is not able to find the resource requested from the merchant
The following is a complete example of a 200 OK response:
Status: 200
{
"country":"IT",
"ok":1234,
"ko":690,
"total":1924
}
4.3.3 Back-office Customer Base Status API
Using Onebip Back-office Customer Base API, it is possible to retrieve information related to your subscription services
which contains the active users and the subscription service events.
Here is an example of a customer base status, for a given service:
{
"customer-base":307,
"subscription-created":1254,
"subscription-activation-requested":125,
"subscription-activation-failed":8,
"subscription-initialized":115,
"subscription-activation-succeeded ":73,
"subscription-terminated":18,
"daily-churn-rate": {
"value":0.0027,
"symbol":"%"
},
"date":"2013-01-14"
}
48 Integration Guide 4.0.5
Where:
customer-base: is the number of user in ACTIVE state for the given service
subscription-created: number of users that visualized the purchase page
subscription-initialized: events of initialization of the subscription, MSISDN given by the user
subscription-activation-requested: event of opt-in request by the user
subscription-activation-failed: number of transaction not completed after the opt-in process (i.e. not sufficient
credit)
subscription-activation-succeeded : subscription completed, after the opt-in process and the billing is
succeeded, the number of the users in ACTIVE state at the end of the process
subscription-terminated: unsubscription operation completed
daily-churn-rate: calculated as subscription-terminated /customer-base
To show the customer base status of a specific day you must perform a GET HTTP request towards the following url:
https://www.onebip.com/bko/customer-base-status
This HTTP route is the only point of access to gain information about the status of the customer base and you can
retrieve it for a specific service on a specific date. In the following list the parameters available for the GET request.
Onebip Back-office API for Customer Base Status supports the following fields for filtering:
service_id: the service_id of the service on which retrieve the status
date: the specific date on which retrieve the customer base status. This field is optional and if not supplied
Onebip will use the current day as default
The following example will give the complete idea of the operational behaviour.
The first one is to obtain the result for a given service on a given date:
GET /bko/customer-base-status?service_id=50f3baacc1b659b91b000000&date=20130101
And the result will be the customer base status for the service with id 50f3baacc1b659b91b000000 at the day 01-01-
2013.
As already written in the lines above, you can submit a request without the date parameter:
GET /bko/customer-base-status?service_id=50f3baacc1b659b91b000000
And in this case the result will be the customer base status for the service with id 50f3baacc1b659b91b000000 based on
today’s data.
Onebip Back-office API should only be used through an authentication. You can perform requests only following the
HTTP Basic Authentication which consists in placing the “Authorization” HTTP Header in the HTTP Request with the
value of the trying computed with the following formula:
Base64(“username:password”)
Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are not in
HTTPS will result in a 400 Bad Request response.
49 Integration Guide 4.0.5
The following two complete examples, using curl, comprehends:
curl -u "[email protected]:123456" 'https://www.onebip.com/bko/customer-base-
status?service_id=50f3baacc1b659b91b000000'
curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY="
'https://www.onebip.com/bko/customer-base-status?
service_id=50f3baacc1b659b91b000000'
4.3.3.1. Processing Back-office Customer Base Status API response
The possible response from Onebip for a customer base status request are the following:
200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format
400 Bad Request The request is malformed and Onebip doesn’t want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed query string
401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request.
403 Forbidden The merchant has not enough privileges to access the resource. For example trying to access the customer base status of a service which is not owned by the merchant will result in a Forbidden request.
The following is a complete example of a 200 OK response:
Status: 200
{
"customer-base":307,
"subscription-created":1254,
"subscription-activation-requested":125,
"subscription-activation-failed":8,
"subscription-initialized":115,
"subscription-activation-succeeded ":73,
"subscription-terminated":18,
"daily-churn-rate": {
"value":0.0027,
"symbol":"%"
},
"date":"2013-01-14"
}
50 Integration Guide 4.0.5
5. Versioning
Onebip accepts a version parameter containing the API version for all the calls. This parameter can be specified by you
to require the compatibility with a previously available service version. In case the specified version cannot be found, the
latest available one will be served by Onebip.
The root resource /api and /bko have each its own version, called API version and BKO version. These version numbers
have no correlation to each other and can evolve independently.
The current version numbers are exposed from API and BKO endpoints.
A sample request is:
curl -v http://www.dev.onebip.com/api/version
And a sample response is:
HTTP/1.1 200 OK
Date: Tue, 05 Feb 2013 14:10:06 GMT
Server: Apache/2.2.17 (Ubuntu)
X-Powered-By: PHP/5.3.5-1ubuntu7.11
Content-Length: 16
Content-Type: application/json
{"number":"1.0"}
A specific version of the API can be required through an HTTP header:
curl -v -H 'X-Onebip-Version: 1.0' http://www.dev.onebip.com/api/ping
or by using a prefix:
curl -v http://www.dev.onebip.com/api/v1.0/ping
In case the requested version is not supported (the number is not existent), the following response will be returned:
curl -v -H 'X-Onebip-Version: 1.1' http://www.dev.onebip.com/api/ping
HTTP/1.1 412 Precondition Failed
Date: Tue, 05 Feb 2013 14:12:00 GMT
Server: Apache/2.2.17 (Ubuntu)
X-Powered-By: PHP/5.3.5-1ubuntu7.11
Content-Length: 99
Content-Type: application/json
{"error":"The api version 1.1 is not supported.","message":"The api version 1.1
is not supported."}
51 Integration Guide 4.0.5
6. Skinability
Onebip Skinability feature will allow you to customize the look and feel of the Onebip payment pages and to use your
personalized layout and the graphics for their different products, services both for one-time and subscription payments in
any country. To start using your customized payment pages with the use of a proper “skin” you should communicate with
Onebip business team assigned to you in Onebip who will check and confirm the skin in terms of codes of conduct
published by mobile network carriers before launching your services7.
The application of a given skin which is previously uploaded on the server will be made by you enriching your purchase
page request, both with GET and POST methods, with an optional parameter:
'skin={skin-name}'
The following example, made with a HTTP GET request, a Onebip payment button will be created to propose 1000 game
credits for $ 0,99 in United States, using a page customized with the skin named “colourful”.
http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1
000+game+credits&price=99&country=US¤cy=USD&skin=colorful&return_url=http://www.webgame.com/thankyou
.htm¬ify_url=http://www.webgame.com/notify.php
If the skin requested is not applicable (i.e. skin with the name specified is not exist, or you are not using Skinability
feature) the payment page will be shown without any customization, in its standard Onebip payment page format and a
specific feedback will be given to you, using a comment inside the html code of the page displayed, in which a self-
explaining note about the error will be given. A skin is an aggregate, that may be composed by:
One or more CSS file
One or more JavaScript file
One or more images file that may be used or mentioned by the JavaScript files, with the relative inclusion path (ex. file <PATH>/fancy.css may use the image file <PATH>/img/beautiful.png with relative path "img/beautiful.png")
The following example represents the content of a zip file for Skinability in which there are default files and custom files
specific only for feature phone (without JavaScript file not supported), smartphone and desktop:
skin_colorful.zip
- common.css
- common.js
- logo_company.jpg
- smartphone
- custom-3.css
- custom-3.js
- logocustom-31.jpg
- desktop
- custom-DT.css
- custom-6.js
- logocustom-6.jpg
- featurephone
- custom-feature.css
- logocustom-feature-small.jpg
7 To prevent any commercial problem, Onebip will have the grant to remove any skin and disable this feature at its sole discretion
without forewarning to keep the services live.
52 Integration Guide 4.0.5
As a result the set for a smartphone in this example will be composed by: common.css + custom-3.css (loaded in this
order), common.js + custom-3.js (loaded in this order), logo_company.jpg, logocustom-31.jpg.
A skin may also specify the customization that must be applied according to the agent type used by your customer to
access the payment page for the payment.
The three supported agent type are:
desktop: every kind of device that uses a desktop browser
smartphone: mobile device with O.S Android or IOS (including iPad also)
featurephone: all the other mobile device (including Nokia Lumia, an BB10)
If the skin contains a file such as <PATH>/smartphone/smart.css, this file will be included in the payment page only if the
agent used by your customer is identified as a smartphone.
6.1 Skin Creation API
You can create more than one skin for one of your products, services. Every skin must have a univocal name, to be
specified in the request. In the case that the name of the skin is the same with a skin already exist, the content will be
overwritten.
To complete a skin creation operation, you must perform a PUT HTTP request towards the following url:
https://www.onebip.com/bko/skins/{skin-name}
This HTTP route is the only point of access to make this operation.
Authentication will be mandatory, with a standard authorization: Basic {base64({username}:{password})}.
The skin package will be always a file with content type equals to zip.
In the following example a new skin called “colorful” is enabled, by uploading the “skin_colorful.zip” file on local file
system.
curl -X PUT -v -u [email protected]:secret_password
https://www.onebip.com/bko/skins/colorful --data @skin_colorful.zip
-H ‘content_type:application/zip’
6.1.1 Processing skin creation API response
The possible response from Onebip for the request for creating a skin will be the following:
200 OK The skin has been successfully created. With empty json.
400 Bad Request Not valid skin. With the error explanation contained in the json attached.
403 Forbidden The merchant is not enabled to use Skinability feature. With empty json.
53 Integration Guide 4.0.5
6.2 Skin Cancellation API
You have the possibility to cancel a skin already applied using a Sin cancellation API. Please note that the files related to
the skin cancelled will be definitively deleted the roll back will be possible. The same skin can be created again only with
a skin creation operation explained.
To complete a skin cancellation operation, you must perform a DELETE HTTP request towards the following url:
https://www.onebip.com/bko/skins/{skin-name}
This HTTP route is the only point of access to make this operation.
Authentication will be mandatory, with a standard authorization: Basic {base64({username}:{password})}.
In the following example the skin called “colorful” is disabled from local file system:
curl -X DELETE -v -u [email protected]:secret_password
https://www.onebip.com/bko/skins/colorful
6.2.1 Processing skin cancellation API response
The possible response from Onebip for the request of the cancellation of a skin will be the following:
200 OK The skin has been successfully disabled. With empty json.
403 Forbidden Merchant not enabled to use Skinability feature. With empty json
54 Integration Guide 4.0.5
7. Authentication as a service
Onebip’s authentication aas feature will allow you to implement subscription payments for your services without being
required to manage the customer base and the authentication of the subscribers.
To start using Onebip’s authentication aas feature you should communicate with Onebip business team assigned to you
who will agree and confirm the service use before launching your services.
This solution is constituted by a powerful interface that allow you to give Onebip the management of all the operations
for the registration and authentication of your subscribers. The goal of this service is to make you be in charge only the
content delivery for your subscription services, without handling the database of your subscribers, the authentication and
the control about payments and subscription state.
The following image summarizes a generic service using Onebip authentication as a service.
The requirement is that “content pages” (ex: image galleries, video streaming, downloadable files) can be reached only
by users subscribed to a service, with a payment completed successfully.
Pay or play API is called for a given service_id, that has been configured for you and is live in production.
Pay_or_play box, is correspondent to a given URL and is a service that will try to authenticate the subscriber. Two
different modules are provided inside it, to be used with this sequence, aiming at recognizing automatically the
subscriber’s MSISDN:
authenticate via MSISDN recognition8
if not authenticated then authenticate via cookie9
If the MSISDN is recognized the subscriber is authenticated by Onebip. In this case subscriber is redirected to a further
control, to verify if he is currently subscribed to your service in question; in case of positive check he’s redirected to the
service content without any further operation or confirmation by completing the happy path.
8 Please note that MSISDN recognition is available in the countries where mobile network operators permit this process and MSISDN of
the subscriber is automatically given.
9 Cookie feature, then, is based on a cookie written inside subscriber’s device, that means that if the user tries to login with a different
device cannot be successful
55 Integration Guide 4.0.5
If the user is not authenticated, it means that the MSISDN is not recognized. A subsequent control verifies that for this
process, according to the request structure set, if the before_pay_url is defined in order Onebip to decide where to
redirect the user’s before the payment page.
The “before_pay_url” page defined by you should contain (apart service description, explanations, creativity) a button to
let users complete the subscription to the service with Onebip. If the user choose to go on, he automatically is redirected
to Onebip subscription page where he will complete the payment process. If the payment is completed successfully the
user becomes a subscriber to your service, and is redirected to the page where the content is delivered.
The same path, through before_pay which is optional, and through the payment page is the one provided to the user
authenticated not currently subscribed, as shown in the image.
7.1 Constructing an authentication aas request
The request to enable Authentication as a service process is a GET HTTP request towards the following url:
http://www.onebip.com/pay-or-play-for/service/<SERVICE_ID>?<PAY_OR_PLAY_PARAMETERS>
where
<SERVICE_ID> is the specific service_id associated to each of your subscription-based service and
communicated to you by Onebip business team
<PAY_OR_PLAY_PARAMETERS>
o before_payment_url (<URL>, optional) where to redirect the user if the user is authenticated and not subscribed or if not authenticated
o only_silent_authentications (<0 or 1>, optional, default=1) eventually use (value=1) or not (value=0) an opt-in to authenticate the user
o SUBSCRIPTION_PARAMETERS
service_id (<ALPHA>, not required, if used must be identical to <SERVICE_ID>)
command (express_pay, mandatory)
item_code
return_url (mandatory)
notify_url
cancel_url
remote_txid
lang
custom
o signature (<STRING>, mandatory)
The subscription parameters are evidently the same used for a standard request for a subscription-based payment and
follow the rules given in chapter 3.2.1, where the “service_id” is not mandatory since it is already presented as the main
parameter of the call as <SERVICE_ID>.
For the security reason “signature” will be always mandatory. Onebip provides a signature encryption based on hashing,
that has the following form:
signature: hash_hmac('sha256', $url, $key)
56 Integration Guide 4.0.5
This feature requires a secret “key” value (API Key) that you can set under the “My Account” section on Onebip Panel,
and obviously the complete “URL” of the request.
In the following example the API key is set on the Onebip Panel and completed a request to pay-or-play-for API, with the
following data:
$url =
http://www.onebip.com/pay-or-play-
for/service/w33b2d48dederc07d328a11a?before_payment_url=http%3A%2F%2Fwww.w
ebgame.com%2Fbppage&only_silent_authentications=0&return_url=http%3A%2F%2F
www.webgame.com%2Fgameaccess3&command=express_pay&lang=en
$key = 'MySecretKey123456'
Please note that the signature must be appended as last parameter of the GET. Note also that all the parameters values must be encoded and the alphabetic characters after % must always be uppercase (ex: / is encoded in %2F and not %2f). The result of hashing is the following:
$ signature = (hash_hmac('sha256', $url, $key, true));
Expected signature:
59d818a6bd236c74939428b07daf5805d599fbcb39cf1ab008b3833d380e6a82
The following final example is a complete GET request, created for a service realized for a specific service where:
service_id= w33b2d48dederc07d328a11a
before_payment_url= http://www.webgame.com/bppage (where the user is sent to pay for the service)
return_url= http://www.webgame.com/gameaccess3 (where the service is provided)
The complete request will be like in the following
GET http://www.onebip.com/pay-or-play-
for/service/w33b2d48dederc07d328a11a?before_payment_url=http%3A%2F%2Fwww.webgame.com%2Fbp
page&only_silent_authentications=0&return_url=http%3A%2F%2Fwww.webgame.com%2Fgameaccess3&
command=express_pay&lang=en&signature=59d818a6bd236c74939428b07daf5805d599fbcb39cf1ab008b
3833d380e6a82
7.2 Processing Authentication aas response
The response to the Authentication aas request is always a redirection (HTTP 302: Found), in which the landing URL is
dependent on the rules explained above.
The possible response from Onebip can be formalized like in the following example, where only the redirection URL
changes, accordingly to the dynamics of the process already described:
302 Found Location: <BEFORE_PAYMENT_URL>?<RETURN_URL_PAY_OR_PLAY_PARAMETERS> Where <BEFORE_PAYMENT_URL> is the before_payment_ur configured in the pay_or_play_for request. This redirection is completed if the user is not authenticated or not subscribed.
302: Found
57 Integration Guide 4.0.5
Location: <PAYMENT_FAILED_URL>?<RETURN_URL_PAY_OR_PLAY_PARAMETERS> Where <PAYMENT_FAILED_URL> is the return_url. The redirection is in this case completed with a 'why' parameter that will pilot the behavior of the landing page (that is the same used for contents provisioning). The possible values for “why” are:
o service-id-conflict = service_id inside <PAY_OR_PLAY_PARAMETERS> is different than
<SERVICE_ID>
o invalid-request-signature = request signature not valid
o invalid-request-service = the service_id given do not exist
o service-not-available = corresponding to a html 503 error, caused by internal error
302: Found Location: <CONTENT_URL>?<RETURN_URL_PAY_OR_PLAY_PARAMETERS>
Where <CONTENT_URL> is the return_url configured in the request. This redirection is completed only for users authenticated and subscribed to the service.
Where <RETURN_URL_PAY_OR_PLAY_PARAMETERS> comprehend:
o whois = MSISDN_URN_ENCRYPTED
o is_subscribed_to = list of services (filtered by current merchant) to which the user is subscribed to
o has_paid_for = list of services (filtered by current merchant) to which the user has paid for
o timestamp = current timestamp
o signature = signature given in the request
o SUBSCRIPTION_RETURN_PARAMETERS
58 Integration Guide 4.0.5
Neomobile S.p.A. | Viale Pasteur 78, 00144 Rome Onebip office: Largo Donegani, 3 - 20121 Milan, Italy
Tel. +39 02 45473397 - Fax +39 02 45473398 www.onebip.com | www.neomobile.com