mobile payment system

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.


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


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


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.


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].

http://www.onebip.com/

mailto:[email protected]


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


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


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”.

http://my.onebip.com/signup

http://my.onebip.com/myprofile

https://www.merchantname.com/

https://www/

https://www/

https://notify/

http://www.onebip.com/


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

http://www.onebip.com/api/

http://en.wikipedia.org/wiki/Currency_codes


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

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2



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

http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes


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











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.















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&currency=USD&return_url=http://www.webgame.com/thankyou.htm&notify_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>


http://www.webgame.com/thankyou.htm

http://www.webgame.com/notify.php

http://www.onebip.com/otms/?command=standard_pay&username=business%40webgame.com&description=1000+game+credits&price=99&currency=USD&return_url=http%3A%2F%2Fwww.webgame.com%2Fthankyou.htm&notify_url=http%3A%2F%2Fwww.webgame.com%2Fnotify.php




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.


target="onebip">




<input type="hidden" name="item_code" value="gm427xl" />




<input type="hidden" name="lang" value="en" />


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" />



/>

</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.


Taking the example of the previous chapter, with the following GET request, without signature:



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&currency=USD&return_url=http%3A%2F%2Fwww.

webgame.com%2Fthankyou.htm&notify_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:



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:


target="onebip">








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" />



/>

</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.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.


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




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”

}



In case of billing aborted, the structure of the JSON body will be the following:

{

“what”: “BILLING_ABORTED”,



“business_model”: “pull”,



“price”: 0.99,

“container”: “purchase/09iuh7549bnn4rdc32h80op4”,



“remote_txid”: “12666721”,

“item_code”: “gm427xl”

“why”: “insufficient-credit”

“notification_id”: “9iou8yy4sd1n43ww3nj887u0”


}

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>))



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.



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:


$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&timestamp=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:


000+game+credits&price=99&country=US&currency=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&timestamp=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.

http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1000+game+credits&price=99&country=US&currency=USD&return_url=http://www.webgame.com/thankyou.html&custom%5bpromo_id%5d=23332



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_phone_number_enc=b667aea7c956ac72ecb6af65e1d9cfec&timestamp=1366103067&signature=c56ce063388fdd99683b2b79b8d051cdfd120f296e0769948defa006b3fbb0ce





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].

http://www.onebip.com/api/



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

http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes


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/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


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


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&notify_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" />



value="http://www.webgame.com/thankyou_new.html" />


value="http://www.webgame.com/notify_updated.php" />



/>

</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.



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:


rn_url=http://www.webgame.com/thankyou_new.html&notify_url=http://www.webgame.com/notify.updated.php


http://www.webgame.com/error.htm


http://www.onebip.com/api/subscriptions?command=express_pay&serice_id=5012b69ca4ee4aa3f3d3r415&return_url=http%3A%2F%2Fwww.webgame.com%2Fthankyou_new.htm&notify_url=http%3A%2F%2Fwww.webgame.com%2Fnotify.updated.php





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&notify_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:


rn_url=http://www.webgame.com/thankyou_new.html&notify_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" />



value="http://www.webgame.com/thankyou_new.html" />


value="http://www.webgame.com/notify_updated.php" />

<input type="hidden" name="signature" value="

ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622" />



/>

</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




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



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



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


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.




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



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


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


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.




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.


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”,


“container”: ““subscription/20332b9ca4er34aa3g3d3r19”,

“service_id”: “5012b69ca4ee4aa3f3d3r415”,

“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”


“notification_id”: “9iou8yy4sd1n43ww3nj887u0”,


}

{



“business_model”: “subscription_activation“,

“container”: “subscription/20332b9ca4er34aa3g3d3r19”,







“price”: 5,



}

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”,


“container”: “subscription/11132555a4er3faa3g3d3fff”,





}






{



“business_model”: “subscription_activation“,

“container”: “subscription/11132555a4er3faa3g3d3fff”,







“price”: 5,



}

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”,


“container”: ““subscription/20332b9ca4er34aa3g3d3r19”,






}

{



“business_model”: “subscription_renewal“,


“payment_id”: “00rtlaa31129inn3y7t5tg21”,

“transaction_id”: “06312uaa55690op398ilwq30”,





“price”: 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.

{



“business_model”: “subscription_renewal”,


“transaction_id”: “00132uuaa56nwa4398il732a”,





“price”: 5,



}

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”,








}

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.





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.


“signature”: is the security signature given by Onebip, described in detail in the following.



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


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


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&notify_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&timesta

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&timestamp=1366102294&signature=6042d0f9d722

a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f



http://www.webgame.com/error.htm




http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7&mobile_phone_operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7&is_subscribed_to=5012b69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415&timestamp=1366102294&signature=6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f





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.


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



http://www.onebip.com/api/subscription/

mailto:[email protected]:m3rc4nt123

https://www.onebip.com/api/blacklist


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.



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.


https://www.onebip.com/api/blacklist



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.


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",


"custom":

{

"your_variable1":"your_value1",


“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


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:


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


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",


"custom":

{



“foo”:”bar”

},

},

}]

}


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.


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



value of the tring computed with the following formula:


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.


curl -u "[email protected]:123456" 'https://www.onebip.com/bko/transactions-

stats?query={“container”:”subscription”}'


'https://www.onebip.com/bko/transactions-

stats?query={“container”:”subscription”}'


4.3.2.1. Processing Back-office Transactions Stats API response

The possible response from Onebip for a transaction statistics request are the following:


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


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


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"

}


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.



value of the trying computed with the following formula:


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.

https://www.onebip.com/bko/customer-base-status



curl -u "[email protected]:123456" 'https://www.onebip.com/bko/customer-base-

status?service_id=50f3baacc1b659b91b000000'


'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:


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


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.


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"

}


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."}


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”.


000+game+credits&price=99&country=US&currency=USD&skin=colorful&return_url=http://www.webgame.com/thankyou

.htm&notify_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.

http://www.onebip.com/api/purchases?command=express_pay&[email protected]&description=1000+game+credits&price=99&country=US&currency=USD&skin=colorful&return_url=http://www.webgame.com/thankyou.htm&notify_url=http://www.webgame.com/notify.php




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.

https://www.onebip.com/bko/skins/colorful


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


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


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:



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

http://www.webgame.com/bppage

http://www.webgame.com/gameaccess3

http://www.onebip.com/pay-or-play-for/service/w33b2d48dederc07d328a11a?before_payment_url=http%3A%2F%2Fwww.webgame.com%2Fbppage&only_silent_authentications=0&return_url=http%3A%2F%2Fwww.webgame.com%2Fgameaccess3&command=express_pay&lang=en&signature=59d818a6bd236c74939428b07daf5805d599fbcb39cf1ab008b3833d380e6a82






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


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

mobile payment system

Documents