Mobile Payment System: Web and Mobile Web

Mobile Payment System
Web and Mobile web
Integration Guide 4.3.7

Mobile Payment System PC and Mobile web Integration Guide 4.3.7
Contents
1 About this document 3
1.1 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Notice of non-liability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4 Typographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Change Log 4
3 Introduction 7
4 Onebip Mobile Payment Integration 8
4.1 One-Time Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1.1 Constructing One-Time Payment Requests . . . . . . . . . . . . . . . . . . . . . 8
4.1.2 Processing One-Time Transaction Notifications . . . . . . . . . . . . . . . . . . 19
4.1.3 Return URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 Subscription-Based Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.2.1 Constructing Subscription Payment Requests . . . . . . . . . . . . . . . . . . . 29
4.2.2 Processing Subscription Transaction Notifications . . . . . . . . . . . . . . . . . 36
4.2.3 Change State Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2.4 Billing Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.2.5 Notification Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.2.6 Notification Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.2.7 Signature Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.2.8 Return URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.2.9 Login users already subscribed . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5 API Integration 53
5.1 Unsubscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2
5.2 Messages API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.2.1 Message through buyer intention . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.3 Revenue Shares APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.3.1 Available Countries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.3.2 Available Pricepoints in Country . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.3.3 Revenue Shares in Country . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.3.4 Revenue Shares per Pricepoint in Country . . . . . . . . . . . . . . . . . . . . . 59
6 Skinability 61
6.1 Skin Creation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1.1 Processing Skin Creation API Response . . . . . . . . . . . . . . . . . . . . . . . 63
6.2 Skin Cancellation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2.1 Processing Skin Cancellation API Response . . . . . . . . . . . . . . . . . . . . . 63
6.3 Skin Cancellation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3.1 Processing Skin Cancellation API Response . . . . . . . . . . . . . . . . . . . . . 64
7 Automated start 65
3
1 About 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.
1.1 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.
1.2 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 con-
tained 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 docu-
ment or resulting from the application or use of the product or service described herein.
Onebip reserves the right to make changes to any information herein without further notice.
Onebip does not guarantee that the features described in this document will be announced or made
available to anyone in the future.
1.3 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.
1.4 Typographic conventions
• Code fragments, URLs, and paramaters cited inline are rendered with a monospace font.
• Additionally, for the sake of clarity, URLs with lots of parameters use curl extended syntax.
• Parameter names are broken up without the usual ”-” in order to avoid confusion.
4
2 Change Log
Version Date Content
4.3.7 21/02/2018 Adding specification for automated start
4.3.6 19/01/2018 Adding revenue shares APIs
4.3.5 12/01/2018 Adding context parameter to the container specification
4.3.4 06/12/2017 Adding subscription behaviour for user already subscribed
4.3.3 14/11/2017 Adding buyer intention initiated flow
4.3.2 11/09/2017 Correcting one time payment price format.
4.3.1 04/09/2017 Added specification on the notifications sequence.
4.3.0 08/08/2017 Changed unsubscription endpoint’s hostname & improved

doc around response codes.
4.2.7 29/05/2017 Adding product_id parameter to the container specification
4.2.6 24/05/2017 Adding credit_provider parameter to the container speci-

fication
4.2.5 17/05/2017 Adding customer_account_id parameter to the container

specification
4.2.4 21/04/2016 Adding recommendation on the sandbox attribute which

must be removed when the Onebip payment page is included
in an iframe
4.2.3 12/04/2016 Adding specification of the encoding of the parameters when

calculating the signature of the payment page request
4.2.2 10/03/2016 Adding payment_method description as a payment page pa-

rameter for one time payments
4.2.1 07/03/2016 Updating price description in the notifications of both one

time/subscription payments; the field format is a float.
4.2.0 06/03/2016 Updating country payment page parameter for both one
time/subscription payments; now this field is optional. Remov-
ing command as it is no longer used.
Continued on next page
5
Continued from previous page
4.1.9 22/02/2016 Updating one time/subscription transactions notifica-

tions: • removing mobile_phone_operator (replaced
by credit_provider); • updating the specifications of
mobile_phone_number_enc and mobile_phone_number;
• adding customer_email, customer_firstname and
customer_lastname; • updating why error codes list.
4.1.8 20/12/2016 Removing BKO sections, updating new logo, updating com-
pany info
4.1.7 01/12/2016 Updating Skins API
4.1.6 15/11/2016 Content access identity msisdn is now in E.164 format
4.1.5 07/11/2016 Added content_access_credentials paragraph and sbb_

id parameter in notifications
4.1.4 28/10/2016 Added content_access parameter to SUBSCRIPTION_

ACTIVATED and SUBSCRIPTION_PENDING notifications
4.1.3 24/10/2016 Changed api url with pay.onebip.com for purchases and sub-
scriptions
4.1.2 21/10/2016 Removed to_url, created_at and closed_at from notifi-

cations
4.1.1 13/10/2016 Adding SUBSCRIPTION_ACTIVATION_FAILED status and en-

riching the notification examples with new fields.
4.1.0 16/12/2013 Added subscription change status notifications for states be-
fore activation
4.0.7 23/09/2013 Updated footnote for HTTPS payment request
4.0.6 10/09/2013 Updated chapter 7 Authentication as a service by introducing

new parameter before_walkin_url
4.0.5 16/04/2013 Added signature specifications for request in chapter 3.1.1.2

and 3.2.1.2
Updated signature specifications for return_url in chapter

3.1.3 and 3.2.3
4.0.4 29/03/2013 Added chapter 7 Authentication as a service
4.0.3 11/02/2013 Added chapter 6 Skinability
6
Updated signature encryption
Updated notification parameters list with new

notification_id and first_notification_at
4.0.2 04/02/2013 Added chapter 5 Versioning
Updated chapter 4.3 Back-office API
4.0.1 25/01/2013 Updated chapter 4 API Integration and updated new examples
in this chapter
4.0.0 14/01/2013 New release of Onebip API
7
3 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 mo-
bile 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.
8
4 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 inte-
gration conducted with HTTP requests.
You can immediately start integrating one-time payments and receiving transactions from your cus-
tomers by following the integration steps detailed in this integration guide. To start receiving trans-
actions 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. See
subscription-based payments for more details.
4.1 One-Time Payments
One-time payments means that your customers will be billed only once for the price you are request-
ing 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.
4.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://pay.onebip.com/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 HTTPS1 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 255

Onebip account.
description Yes Description of the item being sold. This 255

will be displayed on the payment page
and on the payment receipt.

1 HTTPS payment requests are not supported for the following country: France
9
price Yes End user price in hundredth (local value -

added taxes included) as actual amount.
e.g. 100 matches with the amount 1.00 in

the local currency
e.g. 99 matches with the amount 0.99 in

the local currency
currency Yes Local currency code. Please find all the 3

currency codes allowed in Onebip in ISO
4217 standard
e.g. USD
country No Used only to restrict payments to users 2

from a specific country.
e.g. US
Please find all the country codes allowed

in Onebip in ISO 3166 standard. This
field is optional however we strongly rec-
ommend to always pass it. When not
passed among the parameters Onebip
will lookup the user IP and will propose
the price in local currency by looking for
the closest price found.
Note: the country code is UK for United

Kingdom.
return_url Yes The URL to which your customers’ 4096

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.
10
notify_url No The URL to which Onebip will send 4096

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 Mer-
chant settings. If also this configuration is
missing, any notification is sent to you for
the given purchase.
See Processing One-Time Transaction No-

tifications for more details.
cancel_url No The URL to which your customers’ 4096

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

rection is made towards the cancel_url
value set in the Onebip Panel configura-
tion, under merchant’s settings. If also
this value is not set the behaviour will be
a redirection towards referrer url.
country_ No Used to prevent you to receive transac-

disabled tion 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 in ISO 3166 standard

Kingdom.
11
item_code No Pass-through variable you can use to 64

identify your internal item code for this
payment.
product_id No The identification of the product ID con- 24

figured in the Onebip system.
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.
lang No The language used on the payment page 2

that your customers will make the pay-
ments in ISO 639-1 standard
e.g. en
If the value is not set, the default lan-

guage will be the current language of the
browser used for navigation.
remote_txid No A pass-through variable and a single and 64

unique transaction ID reference number
assigned to your system (your internal
transaction ID) for each and single pay-
ment.
It is used to avoid duplicated transactions,

and for this reason the same value can-
not be re-used, not even in test phase,
because the controls is made on Onebip
side.
skin No The skin to be used for the required pur- 255

chase page. Usable only for enabled
users.
Please see Skinability for more details.
logo_url No This URL is the link to integrate your logo 4096

inside the Onebip purchase page, in the
upper left corner.
The mandatory format for the image is

109x33-pixel.
12
The supported extensions are: jpeg, gif,

png.
e.g. http://www.yoursite.com/
images/logo109.jpg
custom No User-defined array of key-value pairs Max 10 vari-

which will be passed through the system ables per 64
and returned in your notify_url and characters
will be appended to your return_url. each
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]
=googlecampaign
Please note that the name of the cus-

tom variable chosen by you cannot be the
same as one of the parameters used in
this table.
customer_email No Your customer’s email address. If passed 255

this field will be returned in your notify_
url.
customer_email_ No Boolean value (true or false, 1 or 0) 5

lock
If true, the email address field on the pay-

ment page can’t be edited manually by
your customer
customer_ No Your customer’s first name. If passed this 50

firstname field will be returned in your notify_
url.
customer_ No Boolean value (true or false, 1 or 0) 5

firstname_lock
13
If true, the first name field on the pay-

ment page can’t be edited manually by
your customer
customer_ No Your customer’s last name. If passed this 50

lastname field will be returned in your notify_
url.
customer_ No Boolean value (true or false, 1 or 0) 5

lastname_lock
If true, the last name field on the payment

page can’t be edited manually by your
customer
customer_cell No Your customer’s cell phone number in in- 15

ternational format with no leading
e.g. 447700900999
Note that customer_cell must match

with customer_country prefix
customer_cell_ No Boolean value (true or false, 1 or 0) 5

lock
If true, the mobile phone number field on

the payment page can’t be edited manu-
ally by your customer
customer_ No Your customer’s country code. Please find 2

country all the country codes allowed in in ISO
3166 standard
e.g. US
Note that customer_country must

match the value given in country
parameter, if used.

Kingdom.
buyer_ No The buyer intention identification found

intention_id in BUYER_INTENTION_RECEIVED notifi-
cation.
14
customer_ No A value recognized by the merchant as a 50

account_id customer’s identification. This parameter
will be used for fraud checks.
with_content_ No A value that the user will use to identify 128

access_by himself during the login phase when ac-
cessing to the content he paid for.
Right now the only supported value is

msisdn.
with_content_ No A value that the user will use to con- ≤8

access_code firm his identity during the login phase
when accessing to the content he paid
for if with_content_access_by param-
eter is specified.
If with_content_access_code is omit-
ted Onebip will generate a random nu-
meric access code for you which will be
sent to the user and communicated in the
notifications after a successful payment.
payment_method No When specified the possible values are

msisdn (which can be omitted because it
is the default) or line if you want the cur-
rent payment to be paid throw an ISP line.
credit_provider No The URN (Universal Resource 50

Name) of the mobile operator (ex.
mop/IT/Vodafone) or internet ser-
vice provider (ex. isp/FR/Orange) of
the user. This parameter will only be
used to customize the payment page
in accordance with the credit provider
policies.
context No The context of the current purchase. ≤6

Available values web, mobile.
autostart No Flags which defines whether the auto- 1

mated start feature is enabled or not. For
more details please check this chapter
HTML Examples Below you can find the simplest integration examples with Onebip Payment Sys-
tem for one-time payments, using only mandatory parameters and some important ones.
15
You can consider the case below as for a web entertainment service with one-time payment model
(associated to the merchant business@webgame.com), 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 business@webgame.com
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 an HTTP GET request:
curl http://pay.onebip.com/purchases \
-d username=business@webgame.com \
-d description=1000+game+credits \
-d price=99 \
-d country=US \
-d currency=USD \
-d return_url=http://www.webgame.com/thankyou.htm \
-d notify_url=http://www.webgame.com/notify.php
The same result can be performed with an HTTP POST request by using the same parameters:
<form action="http://pay.onebip.com/purchases" method="post"

,→ target="onebip">
<input type="hidden" name="username" value="business@webgame.com" />
<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="submit" value="Pay with Onebip" />
</form>
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.
16

<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="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="john.smith@email.com" />
<input type="hidden" name="customer_firstname" value="John" />
<input type="hidden" name="customer_lastname" value="Smith" />
<input type="hidden" name="customer_cell" value="0116434774000" />
<input type="hidden" name="customer_country" value="US" />
</form>
In order to avoid any navigation problem we would like to remind you to make sure not to use the
sandbox tag (with its attributes) when including Onebip payment page within an iframe.
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, named signature.
This parameter should always be last one the HTTP request. Onebip will control the signature, accept-
ing the request only if the value check is correct.
The signature encryption is calculated as the HMAC-SHA256 of the URL returned by Onebip, given
your secret key, which you can set via the ”API Key” entry 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, given the following GET request, without signature:
17
-d price=99 \
-d country=US \
-d currency=USD \
with MySecretKey123456 as the value set in ”API Key”, the resulting URL will be:
-d price=99 \
-d country=US \
-d currency=USD \
-d notify_url=http://www.webgame.com/notify.php \
-d signature=\
5afec3299620f2f7983713a84f9e710173c90e01e9bac306fa2c73d7226ad3ef
The same, identical, process may be applied to HTTP POST request, where the signature value is elab-
orated in the same way, and where the final representation of the request would be:

,→ value="http://www.webgame.com/thankyou.htm" />
<input type="hidden" name="signature"
,→ value="5afec3299620f2f7983713a84f9e710173c90e01e9bac306fa2c73d7226ad3ef"
,→ />
</form>
In order to avoid any navigation problem we would like to remind you to make sure not to use the
sandbox tag (with its attributes) when including Onebip payment page within an iframe.
Please consider that for both GET and POST the calculation of the signature will be performed on the
url encoded parameters meaning the signature has to be calculated for both on the URL encoded
query string.
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.
18
Content access credentials Among the various features available on Onebip, we also offer you the
possibility to authenticate on your side (login) a user which access code has been delivered by Onebip
after the completion of a purchase (see HTML Examples) (ex. with_content_access_by=msisdn).
The access code has to be provided during the purchase creation by using the parameter with_
content_access_code (see HTML Examples) or can be randomly generated by Onebip (6 random
numbers) if not provided.
If this feature is enabled (through the parameter with_content_access_code) after a successful

payment the following things will happen:
• The user will receive the access code (ex. when using with_content_access_by=msisdn the
access code will be sent by SMS)
• The merchant will receive a BILLING_COMPLETED notification (see Processing One-Time Trans-
action Notifications) with the access code and the encrypted access identity
In this case the user has to be allowed to access the content he paid for by using its identity (ex.
msisdn) and the associated access code.
On your side user’s identity must be compared with the encrypted access identity via bcrypt (see
Processing One-Time Transaction Notifications)
Buyer intention In some cases the payment flow is initiated with a message (command) sent by the
user which content is a message asking to buy a product. Onebip system is able to start a payment
process when receiving a specific message however sometimes this isn’t always possible because
there can be many products that the user wants to purchase or just because we don’t have all the
customer base hence we can’t know if the use already bought that product. In those cases we see the
message sent by the user, his intention to buy something and the content as the instructions, we call
it the BuyerIntention. All the information we can extract from this message are notified through
the BUYER_INTENTION_RECEIVED notification. In this notification two pieces of information are par-
ticularly important:
• The intention.message which represents the command sent by the user that needs to be
interpreted by you. So you will receive the complete unchanged message text sent by the user.
• The intention.id which represents the identification of this intention that needs to be used
to create the purchase so that we can correlate the purchase with the initial buyer intention.
When you receive the notification you can check if the user has already bought the product and send
him a message using the specific API or you can start a purchase with a s2s integration.
Customer account identifier With this parameter Onebip will be able to track the behaviour of a
customer accout, for example Onebip will be able to track the number of unique MSISDNs used by a
specific customer_account_id to buy things from you hence to detect fraudulent behaviours. Once
we detect a fraudulent behaviour we will temporarily block that account, which means that that ac-
count will not be able to create payment transactions on our platform. When a transaction is aborted
because the buyer is using a blocked account the BILLING_ABORTED notification will contain the
why parameter with the value fraudulent-customer-account. This feature needs to be explicitly
enabled and configured by Onebip.
19
4.1.2 Processing One-Time Transaction Notifications
Onebip will send you 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 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.
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 Required Description
what Yes Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
to_url No 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 regis-
tered more than once on your side.

20
business_model Yes For one-time payments and transactions the only one allow-
able value is pull.
Other values will be used in subscription-based model.
country No The country code in ISO 3166 standard. This field is optional
however we strongly recommend to always pass it. When not
passed among the parameters Onebip will lookup the user IP
and will propose the price in local currency by looking for the
closest price found.
Note: the country code is UK for United Kingdom.
currency Yes The local currency code in ISO 4217 standard
price Yes End user price in float (local value added taxes included) as ac-
tual amount.
e.g. 1 is the amount in the local
e.g. 0.99 is the amount in the local
original_ Yes The original currency set by you before Onebip converts it to
currency 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 pro-

vided.
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 follow-
ing:
check-pin-failed-too-many-times
mobile-blocked
insufficient-credit
routing-error
21
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
operator-integration-error
syntax-error
considered-lost
not-authorized-by-the-user
routing-error
free-mandatory-message-failed
retry-later
operator-spending-limit-reached
user-unsubscribed
mobile-payment-sim-limitations
billed-with-different-amount
user-already-subscribed-on-operator-side
creation-on-credit-provider-side-failed
22
canceled-by-user
invalid-argument-exception
timeout
configuration-problem
container-closing-requested
realtime-billing-is-not-permitted-aggregator-will-bill-shortly
request-exception
subscription-expired
user-already-billed-for-current-period
Note that more values may be added in future without chang-

ing 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 “pur-

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

tion. Used to prevent any possible duplicate in merchant’s no-
tifications management. If two notifications with the same
notification_id are repeated, they represent the single
event.
e.g. 9iou8yy4sd1n43ww3nj887u0
first_ Yes It’s a n an integer having the value of the UNIX timestamp
notification_at 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
23
Please pay attention that Unix timestamp is a number, equal to

the number of seconds passes since its birth.
mobile_phone_ No The value of the MSISDN of the your customer, who has tried
number_enc the one-time payment on Onebip payment page which is en-
crypted in md5. This field will not be passed for the ISP pur-
chases.
e.g. 88504199e070fc43d2ca1f4896f24b1b
credit_provider Yes The mobile network operator (mop) of the MSISDN of your
customer in case of mobile purchases or the internal service
provider (isp) in case of ISP purchases.
eg. mop/UK/Virgin,
isp/FR/Orange
This value is always present in notifications.
mobile_phone_ No The MSISDN of your customer. This field will not be passed for
number the ISP purchases.
This value can be shared with you only under proper commer-
cial 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.
customer_email No This value will be returned in the notification if passed on the

one-time payment request
customer_ No This value will be returned in the notification if passed on the

firstname one-time payment request

lastname one-time payment request
content_access No A JSON object, present only in the BILLING_COMPLETED noti-

fications, containing the information so to allow you to know
how the user must be able to access the content he paid for.
custom No A JSON object containing all your custom parameters specified

by your request.
24
ssb_id Yes Strictly Sequential Billing Identifier, a JSON object identifying

this billing in a sequence of billing originated in the same con-
tainer, in this case in the same purchase.
hash No Hash checksum of your API Key and of the notification URL pa-
rameters.
content_access JSON object
by What the user will use to identify himself. Right now the only supported value is msisdn
identity The encrypted value of the user identity. Right now it’s the encrypted (bcrypt with 10
iterations) msisdn in E.164 format (e.g. +44254578961)
code The value that the user must use to confirm their identity. This value is communicated by us to
the user after the payment confirmation. This value is not encrypted.
custom JSON object
period_id identifies the progressive billing period, it’s meaningful only for subscriptions, for pur-
chases it will always be 1
fraction_id identifies the progressive billing fraction, it will increase after each successful user’s
payment, this is meaningful whenever to accumulate the purchase amount we need to invite
the user to pay multiple time because the credit provider doesn’t support the specific amount
as price point
attempt_id identifies the progressive billing attempt, it will increase after each failed user’s pay-
ment
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",
"payment_id": "23dtle561129ij562jn5tg44",
"transaction_id": "84332uu3b56nwa4398il762r",
"business_model": "pull",
"context": "web",
"country": "US",
"status":"completed",
"currency": "USD",
"lang": "en",
25
"price": 0.99,
"original_price":20,
"original_currency":"TRY",
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
},
"container": "purchase/09iuh7549bnn4rdc32h80op4",
"mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b",
"credit_provider":"mop/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",
"context": "web",
"country": "US",
"currency": "USD",
"lang": "en",
"original_price":20,
"price": 0.99,
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
},
"container": "purchase/09iuh7549bnn4rdc32h80op4",
"remote_txid": "12666721",
"item_code": "gm427xl"
"why": "insufficient-credit"
"transaction_id":"not_available",
"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.
26
When we receive a buyer intention we will send the following notification:
{
"what":"BUYER_INTENTION_RECEIVED",
"country":"UK",
"credit_provider":"mop/UK/T-Mobile",
"credit_device":"msisdn/449993332438",
"mobile_phone_operator":"UK/T-Mobile",
"mobile_phone_number":"449993332438",
"intention":{
"message":"TEST unlock GAME 001",
"received_at":1510670665,
"kind":"mo",
"id":"5a0b0149df895c12c51ea161"
},
"notification_id":"5a0b0149df895c12c51ea162",
"first_notification_at":1510670665
}
Notification Retry In the notification system, as a consequence of its notifications, Onebip expects
to receive a response with:
Header Status Code 200OK

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.
Signature encryption Onebip provides a signature encryption based on hashing, that is an encryp-
tion 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 via the HTTP header
X-Onebip-Signature. See Security signature for more details.
27
In this case there is the additional requirement of encoding in Base64 the resulting HMAC. So, given
the following raw body:
{
"country":"US",
"container":"purchase/812894dh207c88056d000000",
"mobile_phone_number_enc":"10b23c1039c704f87d7bf3cc1a0b8638",
"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
}
with MySecretKey123456 as the value set in ”API Key”, the value for the X-Onebip-Signature HTTP
header, encoded in Base64, will be:
cZ7OIG5nS5j2t8nqQBpuUWnGWqN7O0A8U1OpesfqfTE=
Please note: HMAC must be calculated in binary mode, not in hexadecimal. The HMAC is always in
binary data.
4.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 that is described in more detail in Security signa-
ture.
Given the following completed billing request for a purchase:
28
-d price=99 \
-d country=US \
-d currency=USD \
-d return_url=http://www.webgame.com/thankyou.html \
-d custom[promo_id]=23332
given the following GET request, without signature:
curl http://www.webgame.com/thankyou.html \
-d payment_id=100801483 \
-d original_price=99 \
-d original_currency=USD \
-d promo_id=23332 \
-d whois=msisdn%2Fb667aea7c956ac72ecb6af65e1d9cfec \
-d mobile_phone_operator=US%2FVerizon \
-d mobile_phone_number_enc=b667aea7c956ac72ecb6af65e1d9cfec \
-d timestamp=1366103067
-d price=99 \
-d country=US \
-d currency=USD \
-d notify_url=http://www.webgame.com/notify.php \
-d signature=\
5afec3299620f2f7983713a84f9e710173c90e01e9bac306fa2c73d7226ad3ef
In the following example, the URL to be signed with MySecretKey123456 as the value set in ”API
Key” will be:
-d promo_id=23332 \
-d timestamp=1366103067 \
-d signature=\
c56ce063388fdd99683b2b79b8d051cdfd120f296e0769948defa006b3fbb0ce
29
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.
4.2 Subscription-Based Payments
Subscription payments also known as ”recurring payments” is a way to charge your users periodically
for a certain time period such as daily, weekly, monthly or even quarterly.
Onebip subscription service is easy and quick to set-up with its 4-step service launch approach which
you should follow as explained below.
Country/the mobile networks You should confirm with your Onebip account manager the country
and the mobile networks that you would like to launch your services with.
Technical Integration The technical integration for the subscription-based payments is very similar
to the one-time payments integration as explained in the previous chapter. If you are already
using Onebip for one-time payments, this integration will be even easier for you.
Mobile network approvals Mobile networks have their own subscription rules and therefore we will
need their approval before the service launch to be compliant with them. Onebip will get these
approvals for you in advance without involving you in this process.
Subscription service ID Your Onebip account manager will give you a 24 characters alphanumeric
subscription service ID for each of your subscription-based service. This ID will contain all the
details of your service such as the price, frequency and the description of your service and will
make the technical integration easier for you.
4.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://pay.onebip.com/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 HTTPS1 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:
30
service_id Yes The foremost value for the subscription- 24

based calls. It will be a specific ser-
vice 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.
return_url Yes The URL to which your customers’ 4096

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.
notify_url No The URL to which Onebip will send 4096

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 Mer-
chant settings. If also this configuration is
missing, any notification is sent to you for
the given purchase.
See Processing One-Time Transaction No-

tifications for more details.
cancel_url No The URL to which your customers’ 4096

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.
31
If no value is set in the request, the redi-

rection is made towards the cancel_url
value set in the Onebip Panel configura-
tion, under merchant’s settings. If also
this value is not set the behaviour will be
a redirection towards referrer url.
item_code No Pass-through variable you can use to 64

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 cou-
pling item- payment inside the process.
lang No The language used on the payment page 2

that your customers will make the pay-
ments in ISO 639-1 standard.
e.g. en
If the value is not set, the default lan-

guage will be the one currently used by
the browser used.
remote_txid No A pass-through variable and a single and 64

unique transaction ID reference number
assigned to your system (your internal
transaction ID) for each and single pay-
ment.
It is used to avoid duplicated transactions,

and for this reason the same value can-
not be re-used, not even in test phase,
because the controls is made on Onebip
side.
skin No The skin to be used for the required pur- 255

chase page. Usable only for enabled
users.
Please see Skinability for more details.
logo_url No This URL is the link to integrate your logo 4096

inside the Onebip purchase page, in the
upper left corner.
32
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
custom No User-defined array of key-value pairs Max 10 vari-

which will be passed through the system ables per 64
and returned in your notify_url and characters
will be appended to your return_url. each
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]
=googlecampaign
Please note that the name of the cus-

tom variable chosen by you cannot be the
same as one of the parameters used in
this table.
customer_cell No Your customer’s cell phone number in in- 15

ternational format with no leading
e.g. 447700900999
Note that customer_cell must match

customer_country prefix
customer_cell_ No Boolean value (true or false, 1 or 0) 5

lock
If true, the mobile phone number field on

the payment page can’t be edited manu-
ally by your customer
33
customer_email No Your customer’s email address. If passed 255

this field will be returned in your notify_
url.
customer_ No Your customer’s first name. If passed this 50

firstname field will be returned in your notify_
url.
customer_ No Your customer’s last name. If passed this 50

lastname field will be returned in your notify_
url.
customer_ No A value recognized by the merchant as a 50

account_id customer’s identification. This parameter
will be used for fraud checks.
with_content_ No A value that the user will use to identify 128

access_by himself during the login phase when ac-
cessing to the content he paid for.
Right now the only supported value is

msisdn.
with_content_ No A value that the user will use as con- ≤8

access_code firm his identity during the login phase
when accessing to the content he paid
for if with_content_access_by param-
eter is specified.
If with_content_access_code is omit-
ted Onebip will generate a random nu-
meric access code for you which will be
sent to the user and communicated in the
notifications after a successful payment.
credit_provider No The URN (Universal Resource 50

Name) of the mobile operator (ex.
mop/IT/Vodafone) or internet ser-
vice provider (ex. isp/FR/Orange) of
the user. This parameter will only be
used to customize the payment page
in accordance with the credit provider
policies.
context No The context of the current subscription. ≤6

Available values web, mobile.
34
HTML Examples Below you can find the simplest integration examples with Onebip Payment Sys-
tem 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 pay-
ment model (associated to the merchant business@webgame.com), which will create a Onebip pay-
ment button on this merchant’s web site, for the merchant’s weekly subscription service named ”Su-
pergame” 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 an HTTP GET request. In the example, apart from the manda-
tory parameters, it is assumed that the merchant has overwritten the return_url and the notify_
url for its particular needs:
curl http://pay.onebip.com/subscriptions \
-d service_id=5012b69ca4ee4aa3f3d3r415 \
-d return_url=http://www.webgame.com/thankyou_new.html \
-d notify_url=http://www.webgame.com/notify.updated.php
The same result can be performed with an HTTP POST request with the same parameters:
<form action="http://pay.onebip.com/subscriptions" method="post"

<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>
35
Security signatures Taking the example of the previous chapter, given the following GET request,
without signature:
-d notify_url=http://www.webgame.com/notify.updated.php \
-d signature=\
ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622
The same, identical, process may be applied to HTTP POST request, where the signature value is elab-
orated in the same way, and where the final representation of the request would be:
<form action="http://pay.onebip.com/subscriptions" method="post"

<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.
See Security signature for more details.
Content Access Credentials Among the various features available on Onebip, we also offer you
the possibility on your side to authenticate (login) a user which access code has been delivered by
Onebip after the activation of a subscription, or when the subscription becomes PENDING (see 4.2.1)
(ex. with_content_access_by=msisdn). The access code has to be provided during the subscrip-
tion creation by using the parameter with_content_access_code (see 4.2.1) or can be randomly
generated by Onebip (6 random numbers) if not provided.
If this feature is enabled (through the parameter with_content_access_code) after a successful

payment the following things will happen:
36
• The user will receive the access code (ex. when using with_content_access_by=msisdn the
access code will be sent by SMS)
• The merchant will receive one or more of the following notifications: SUBSCRIPTION_ACTIVATED,
SUBSCRIPTION_PENDING or SUBSCRIPTION_TRIAL (see 4.2.3) which will contain the access
code and the encrypted access identity
In this case the user has to be allowed to access the content he paid for by using its identity (ex.
msisdn) and the associated access code.
On your side user’s identity must be compared with the encrypted access identity via bcrypt (see 4.2.3)
4.2.2 Processing Subscription Transaction Notifications
The transaction response has to be executed by your landing script to ensure the transaction is com-
mitted on the Onebip system before recording your payment as successful in your database.
Two kinds of notifications are provided to you:
Change State event change of state related to a subscription, among the existing ones.
• SUBSCRIPTION_WAITING_FOR_APPROVAL a billing request has been started after the user
has expressed the intention to pay.
• SUBSCRIPTION_ACQUIRED the operator has approved the subscription and the user has
entered the customer base.
• SUBSCRIPTION_ACTIVATED the first billing has succeeded and the user has become ac-
tive.
• SUBSCRIPTION_PENDING the first billing has failed and the subscription will be retried
later according to configuration.
• SUBSCRIPTION_ACTIVATION_FAILED it hasn’t been possible to activate the subscription
(which means that all the billing activation attempts resulted in a billing failure).
• SUBSCRIPTION_RENEWED event for every renewal case of every subscription, conditional
to payment completion.
• SUBSCRIPTION_CANCELED subscription becomes canceled without any succesful billing.
• SUBSCRIPTION_TERMINATED existing subscription termination, triggered by you (using
the Unsubscription API), or by Onebip cc, or by operators’ cc.
• SUBSCRIPTION_SUSPENDED reserved for future usage.
• SUBSCRIPTION_REACTIVATED reserved for future usage.
Billing event status of the billing linked to the subscription events of activation and renewal. These
BILLING_COMPLETED and BILLING_ABORTED notifications are identical to the purchase ones.
Onebip notification format will be always the same:
Header <empty>
37
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. Since subscription and billing notifications are events in a
distributed system it is not possibile to guarantee a strict sequence in receiving them.
4.2.3 Change State Event Notification
For every change in the state of the event, a notification is sent to you, containing the following infor-
mation:
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
...
country Yes The country code, in ISO 3166 standard
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 al-

ways the subscription_id created by Onebip as a result of
successful subscription transaction.
The subscription id is univocally related to one serviceid and

one MSISDN only, and it’s a 24 chars alphanumeric, not repeat-
able.
e.g. subscription/20332b9ca4er34aa3g3d3r198
service_id Yes It’s the key value that identifies with a unique and not repeat-
able index of the service concerning the operation. Note that
this value will be a 24 chars alphanumeric.
38
e.g. 5012b69ca4ee4aa3f3d3r415
notification_id Yes It’s a unique, alphanumeric id identifying this single notifica-

tion. Used to prevent any possible duplicate in merhant’s no-
tifications management. If two notifications with the same
notification_id are repeated, they represent the single
event.
e.g. 9iou8yy4sd1n43ww3nj887u0
first_ Yes It’s an integer having the value of the UNIX timestamp of when
notification_at the notification is performed. In case of retries, this timestamp
is fixed and always points to the instant at which the first at-
tempt 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_ Yes The value of the MSISDN of the your customer, who has tried
number_enc the one-time payment on Onebip payment page which is en-
crypted in md5.
e.g. 88504199e070fc43d2ca1f4896f24b1b
eg. mop/UK/Virgin,
isp/FR/Orange
This value is always present in every notification.
mobile_phone_ No The MSISDN of your customer. This value can be shared with
number you only under proper commercial agreements between par-
ties. This field will not be passed for the ISP purchases.


39
content_access No A JSON object, present only in SUBSCRIPTION_PENDING,

SUBSCRIPTION_ACTIVATED, SUBSCRIPTION_TRIAL notifica-
tions, containing everything so to allow you to know how the
user must be able to access the content he paid for.
custom No A JSON object, containing all your custom parameters speci-

fied by your request.
identity The encrypted value of the user identity. Right now it is the encrypted (bcrypt with 10
iterations) msisdn in E.164 format (ex. +44254578961)
code The value that the user must use to confirm their identity. This value is communicated to the
user by us after the payment confirmation. This value is not encrypted
grant Indicates whether the merchant has to allow or not the user to access to the content. Values:
mandatory optional
grant_mandatory_until In case grant parameter is mandatory, this field indicates the expiration
datetime when the grant is no more mandatory, e.g.: 2006-01-15T09:00:00.000Z
4.2.4 Billing Event Notification
For every event regarding billing, you will receive a notification with these information:
what Yes Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
40
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.
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 regis-
tered more than once on your side.
business_model Yes The possible values are:
subscription_activation
subscription_renewal
country Yes The country code in ISO 3166 standard
currency Yes The local currency code in ISO 4217 standard
price Yes End user price in current currency.

vided.
e.g. 1.99
original_ Yes The original currency set by you before Onebip converts it to
currency 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

vided.
e.g. 1.99
41
container Yes The container, in Onebip environment, is the object of the pur-
chase operation, that may be a single purchase or a subscrip-
tion.
In this case of subscription-based transaction the value will al-

ways be subscription, with the value of the item (a 24 chars
alphanumeric).
e.g. subscription/20332b9ca4er34aa3g3d3r198
mobile_phone_ Yes The value of the MSISDN of the your customer, who has tried
number_enc the subscription-based payment on Onebip payment page
which is encrypted in md5.
e.g. 88504199e070fc43d2ca1f4896f24b1b
eg. mop/UK/Virgin,
isp/FR/Orange
This value is always present in notifications.
mobile_phone_ No The MSISDN of your customer.

number
This value can be shared with you only under proper commer-
cial agreements between parties.


customer_email No This value will be returned in the notification if passed on the

subscription request

firstname subscription request

lastname subscription request
42
content_access No A JSON object, present only in the BILLING_COMPLETED noti-

fications, containing everything so to allow you to know how
the user must be able to access the content he paid for.
custom No A JSON object, containing all your custom parameters speci-

fied by your request.
why No This parameter is used only in case of BILLING_ABORTED.
The value is one of the error code available, listed in the follow-
ing:
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
unknown-error
unknown-exception
operator-integration-error
syntax-error
43
considered-lost
not-authorized-by-the-user
routing-error
free-mandatory-message-failed
retry-later
operator-spending-limit-reached
user-unsubscribed
mobile-payment-sim-limitations
billed-with-different-amount
user-already-subscribed-on-operator-side
creation-on-credit-provider-side-failed
canceled-by-user
invalid-argument-exception
timeout
configuration-problem
container-closing-requested
realtime-billing-is-not-permitted-aggregator-will-bill-shortly
request-exception
subscription-expired
user-already-billed-for-current-period
Note that more values may be added in future without chang-

ing
44
ssb_id Yes Strictly Sequential Billing Identifier, a JSON object identifying

this billing in a sequence of billing originated in the same con-
tainer, in this case in the same purchase. It contains the follow-
ing fields:
hash No Hash checksum of your API Key and of the notification URL pa-
rameters.
identity The encrypted value of the user identity. Right now it is the encrypted (bcrypt with 10
iterations) msisdn in E.164 format (e.g. +44254578961)
code The value that the user must use to confirm their identity. This value is communicated by us to
the user after the payment confirmation. This value is not encrypted
custom JSON object
period_id identifies the progressive billing period, it’s meaningful only for subscriptions, for pur-
chases it will always be 1
fraction_id identifies the progressive billing fraction, it will increase after each successful user’s
payment, this is meaningful whenever to accumulate the purchase amount we need to invite
the user to pay multiple time because the credit provider doesn’t support the specific amount
as price point
attempt_id identifies the progressive billing attempt, it will increase after each failed user’s pay-
ment
4.2.5 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",
45
"country": "US",
"lang": "en",
"context": "mobile",
"container": "subscription/20332b9ca4er34aa3g3d3r19",
"service_id": "5012b69ca4ee4aa3f3d3r415",
"notification_id": "9iou8yy4sd1n43ww3nj887u0" ,
"first_notification_at": "1364498611",
"price": 5,
"original_price": 5,
"original_currency": "EUR",
"remote_txid": "123458679898989898",
"next_action": "renewal",
"next_action_at": "2016-10-20T00:32:41+0000",
}
{
"business_model": "subscription_activation",
"payment_id": "58989898999342",
"country": "US",
"currency": "USD",
"price": 5,
"lang": "en",
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
},
"remote_txid": "123458679898989898",
"notification_id": "9iou8yy4sd1n43ww3nj887u0",
}
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",
46
"country": "US",
"lang": "en",
"container": "subscription/11132555a4er3faa3g3d3fff",
"price": 5,
"remote_txid": "123458679898989898",
}
{
"what": "SUBSCRIPTION_ACTIVATION_FAILED",
"country": "US",
"lang": "en",
"price": 5,
"next_action": "activation",
"next_action_at": "2016-10-20T00:32:41+0000",
"remote_txid": "123458679898989898",
}
{
"lang": "en",
"business_model": "subscription_activation",
"country": "US",
"currency": "USD",
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
47
},
"price": 5,
"remote_txid": "123458679898989898",
"why": "mobile-blocked",
}
Subscription renewal succeeded This is called a ”push” operation generated by Onebip after a com-
pleted renewal of an active subscription. The notification towards you will be about change state the
payment completed.
{
"what": "SUBSCRIPTION_RENEWED",
"lang": "en",
"mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b"
"price": 5,
"next_action": "renewal",
"next_action_at": "2016-10-20T00:32:41+0000"
}
{
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
},
"status": "completed",
"business_model": "subscription_renewal",
"payment_id": "00rtlaa31129inn3y7t5tg21",
"transaction_id": "06312uaa55690op398ilwq30",
"country": "US",
48
"currency": "USD",
"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.
{
"country": "US",
"lang": "en",
"ssb_id":{
"period_id":1,
"fraction_id":1,
"attempt_id":1
},
"status": "aborted",
"business_model": "subscription_renewal",
"transaction_id": "00132uuaa56nwa4398il732a",
"country": "US",
"currency": "USD",
"price": 5,
"why": "mobile-blocked",
}
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",
"country": "US",
"created_at": {
"sec" : l23456789,
49
"usec" : 0,
},
"lang": "en",
"mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b"
}
Analogous notifications are provided for the suspension and reactivation of the operations, that more-
over are used only in few special payment flows in some countries, due to specific operators’ regula-
tions.
4.2.6 Notification Retry
In the notification system, as a consequence of its notifications, Onebip expects to receive a response
with:
Header Status Code 200OK

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 can-
celled.
4.2.7 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
50
exchange between two parties to be checked via the HTTP header X-Onebip-Signature. See Se-
curity signature for more details.
In this case there is the additional requirement of encoding in Base64 the resulting HMAC. So, given
the following raw body:
{
"country":"TR",
"remote_txid":"AB_22022122",
"container":"subscription/562634za43bc76051d003309",
"mobile_phone_number_enc":"10b23c1039c704f87d7bf3cc1a0b8638",
"price":8,
"currency":"TRY",
"business_model":"pull",
"transaction_id":"76939310",
"original_price":8,
"what":"BILLING_COMPLETED",
"to_url":"http://merchant.com/vpncontrol/onebip/ipn",
"payment_id":11149219
}
with MySecretKey123456 as the value set in ”API Key”, the value for the X-Onebip-Signature HTTP
header, encoded in Base64, will be:
UsuOSZINqUdDpxkM2/anV5+mtjim0ZPjxWLDPwiPQR4=
Please note: HMAC must be calculated in binary mode, not in hexadecimal. The HMAC is always in
binary data.
4.2.8 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 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 to
verify that the url has been created recently.
signature is the security signature given by Onebip that is described in more detail in Security signa-
ture.
51
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:
given the following GET request, without signature:
curl http://www.webgame.com/thankyou_new.html \
-d whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7 \
-d mobile_phone_operator=ES%2FMovistar \
-d mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7 \
-d is_subscribed_to=5012b69ca4ee4aa3f3d3r415 \
-d has_paid_for=5012b69ca4ee4aa3f3d3r415 \
-d timestamp=1366102294
curl http://www.webgame.com/thankyou_new.html \
-d whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7 \
-d mobile_phone_operator=ES%2FMovistar \
-d mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7 \
-d is_subscribed_to=5012b69ca4ee4aa3f3d3r415 \
-d has_paid_for=5012b69ca4ee4aa3f3d3r415 \
-d signature=\
6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f
52
In the following example, the URL to be signed with MySecretKey123456 as the value set in ”API
Key” will be:
-d promo_id=23332 \
-d signature=\
c56ce063388fdd99683b2b79b8d051cdfd120f296e0769948defa006b3fbb0ce
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 triggered by the return_url page only when signature is verified or by relying
on the notifications.
4.2.9 Login users already subscribed
A user (msisdn) can have only one active subscription for the same service. When a user lands on
the Onebip subscription page and starts an acquisition process, Onebip verifies whether the user has
already an active subscription for the requested service_id. In case the user is already subscribed,
Onebip automatically redirects the user to the return_url of the already active subscription, by
adding all the return url parameters, including the current timestamp and signing the url with a new
signature. In this way the merchant can give the user the permission to accsess to the contents
without the need to mantain an internal customer base but simply by verifying the signed return_
url.
53
5 API Integration
Onebip provides with the opportunity to have the additional features that will allow you to manage
the operations related to the various kind of payments.
5.1 Unsubscription API
You can change the state of a subscription from ”active” to ”in-termination” using an HTTP
DELETE request using the subscription_id created by Onebip at the act of first subscription. The
subscription’s state will appear as ”intermination” until its current period closes and the customer
will no longer by charged. It will then appear as ”terminated”.
You will be allowed to use this action only with the authentication by using your username and pass-
word that you created during your registration process of Onebip.
For example, using curl, can be seen in the following box:
curl -X DELETE \
-u business@webgame.com:m3rc4nt123 \
https://api.onebip.com/subscriptions/291dd69cr4ee4aa3f1d3rt85
Possible outcomes:
• 202 Accepted
The request has been received and scheduled correctly. The subscription’s state will appear as
”intermination” until its current period closes and the customer will no longer by charged.
• 400 Bad Request
The given id is malformed. See the ”Formats” section.
• 404 Not Found

A subscription with such id cannot be found.
• 405 Method Not Supported
The subscription cannot be terminated by using this API, due to business rules.
• 409 Conflict
The subscription is already scheduled for termination.
5.2 Messages API
If authorized to do so you can send a message to the buyer associated to one of your transactions
(payment or subscription) or to a buyer for which you received a buyer intention notification
54
5.2.1 Message through buyer intention
After you receive a buyer intention notification you can send a limited number of messages to the
buyer to ex. send him the unlock code to the product he already bought.
The needed information are the buyer_intention_id that you can find in the notification and the
message you want to send
For example, using curl, can be seen in the following box:
curl -X POST \
-d'message=Your unlock code for XXX is YYY' \
,→ https://api.onebip.com/buyer-intention/5a0c00a25ab9088b8c0955cb/messages
Possible outcomes:
• 200 Ok
The message is on its way
• 400 Bad Request
The message is not valid (ex. empty, missing, too long, ecc…)
• 403 Forbidden
The buyer has been blacklisted and therefore we can’t send him a message
• 404 Not Found
The buyer_intention_id is unknown
• 409 Conflict
The maximum number of messages has already been sent
5.3 Revenue Shares APIs
This section contains all the API through which you can retrieve information related to the available
pricepoints for countries and credit providers and the applied revenue shares for those pricepoints.
5.3.1 Available Countries
List of available countries, meaning all countries with at least one pricepoint with at least one credit
provider
Request example:
curl -u username:password https://pay.onebip.com/merchant/countries
Possible outcomes:
55
200 OK
{
"countries": [
"BR",
"DE",
"IT",
"UK"
]
}
401 Unauthorized The credentials (username or password) are wrong
5.3.2 Available Pricepoints in Country
List of available pricepoints in a country, meaning all pricepoints available through at least one credit
provider
Request template:
curl -u username:password
,→ https://pay.onebip.com/merchant/country/{COUNTRY}/pricepoints
COUNTRY Is the country code of the country you are interested in
Request example:
,→ https://pay.onebip.com/merchant/country/IT/pricepoints
Possible outcomes:
200 OK
{
"pricepoints": [
{
"currency": "EUR",
"amount": "1.0000",
"type": "point"
},
{
"currency": "EUR",
56
"amount": {
"from": "2.0000",
"to": "10.0000",
"step": "0.0100"
},
"type": "range"
}
]
}
currency Is the standard ISO 4217 currency code
type Can be point or range

point The amount is fixed
range The amount is inside a range
amount Can be fixed or a range
• If it is fixed then the value is a number with 4 digits precision

• If it is a range then the value is composed of multiple fields
from The amount where the range begins (included)
to The amount where the range ends (included)
steps The amount of the increments inside the range
In the example the available pricepoints in Italy are: 1.0000/EUR, 2.0000/EUR, 2.0100/EUR, 2.
0200/EUR, …, 10.0000/EUR
401 Unauthorized The credentials (username or password) are wrong.
404 Not Found The country you specified doesn’t exists or is not available.
5.3.3 Revenue Shares in Country
Details about revenue shares in a particular country. For each available pricepoint and for each credit
provider that provides such pricepoint you’ll get the revenue shared. When the pricepoint is a range
then you’ll get the revenue shares of the start and the end of the range.
Request template:
,→ https://pay.onebip.com/merchant/country/{COUNTRY}/revenue-shares
57
Request example:
,→ https://pay.onebip.com/merchant/country/IT/revenue-shares
Possible outcomes:
200 OK
{
"revenue_shares": [
{
"revenue_share": {
"applied_to": "gross-transaction-value",
"value": [
60,
"%"
]
},
"credit_provider": "mop/IT/X001",
"currency": "EUR",
"amount": "1.0000",
"type": "point"
},
{
"revenue_share": {
"value": [
60,
"%"
]
},
"currency": "EUR",
"amount": "1.0000",
"type": "point"
},
{
"revenue_share": {
"to": {
"value": [
60,
"%"
]
},
"from": {
58
"value": [
60,
"%"
]
}
},
"currency": "EUR",
"amount": {
"step": "1.0000",
"to": "10.0000",
"from": "1.0000"
},
"type": "range"
},
{
"revenue_share": {
"value": [
60,
"%"
]
},
"currency": "EUR",
"amount": "2.0000",
"type": "point"
}
]
}
The revenue shares are specified by pricepoints and credit providers (different pricepoints can have
different revenue shares and different credit providers for the same pricepoint can have different rev-
enue shares).
The revenue share is a percentage that can be applied to
• gross-transaction-value
• gross-transaction-value-vat-excluded
If the pricepoint is a range then the output will provide the revenue share of start of the range and
the revenue share of the end of the range.
404 Not Found The country you specified doesn’t exists or is not available.
59
5.3.4 Revenue Shares per Pricepoint in Country
Details about revenue shares in a particular country for a particular pricepoint. For each credit provider
that provides such pricepoint you’ll get the revenue shared. When the pricepoint is a range then you’ll
get the revenue shares of the start and the end of the range.
Request template:
,→ https://pay.onebip.com/merchant/country/{COUNTRY}/pricepoints/{AMOUNT}/{CURRENCY}/revenue-sh

AMOUNT Is the amount of the pricepoint with 4 digit precisions and the dot (.) as separator
CURRENCY Is the currency code of the country
Request example:
,→ https://pay.onebip.com/merchant/country/IT/pricepoints/1.0000/EUR/revenue-shares
Possible outcomes:
200 OK
{
"revenue_shares": [
{
"revenue_share": {
"to": {
"value": [
60,
"%"
]
},
"from": {
"value": [
60,
"%"
]
}
},
"currency": "EUR",
60
"amount": {
"step": "1.0000",
"to": "10.0000",
"from": "1.0000"
},
"type": "range"
},
{
"revenue_share": {
"to": {
"value": [
60,
"%"
]
},
"from": {
"value": [
60,
"%"
]
}
},
"currency": "EUR",
"amount": {
"step": "1.0000",
"to": "10.0000",
"from": "1.0000"
},
"type": "range"
}
]
}
400 Bad Request One or more of the supplied data in the URL is malformed.
404 Not Found The country you specified doesn’t exists or is not available or the pricepoint you
specified doesn’t exists or is not available in the country you specified.
61
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 services.2
The application of a given skin which is previously uploaded on the server will be made by you en-
riching your purchase page request, both with GET and POST methods, with an optional parameter:
skin={skin-name}
The following example, made with an 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
colorful.
-d price=99 \
-d country=US \
-d currency=USD \
-d skin=colorful \
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 images file that may be used or mentioned by the JavaScript files, with the rela-
tive 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 smartphone and desktop:
• common.css
• logo_company.jpg
2 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.
62
• smartphone
– custom-3.css
– logocustom-31.jpg
• desktop
– custom-DT.css
– logocustom-6.jpg
• tablet
– custom-feature.css
– logocustom-feature-small.jpg
As a result the set for a smartphone in this example will be composed by: common.css + custom-3.
css (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 Android or IOS (including iPad)
• tablet: flat mobile computer with a touchscreen display
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 an HTTP PUT request towards the following
url:
https://api.onebip.com/skins/{skin-name}
This HTTP route is the only point of access to make this operation.
Authentication will be mandatory, with a standard basic access mechanism3 . 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.
3 I.e. the base64 encoding of <username>:<password>
63
curl -X PUT -v -H 'content_type:application/zip' \

-u merchant@yourcompany.com:secret_password \
https://api.onebip.com/skins/colorful \
--data @skin_colorful.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.
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 an HTTP DELETE request towards the
following url:
https://api.onebip.com/ skins/{skin-name}
Authentication will be mandatory, with a standard basic access mechanism3 . In the following example
the skin called “colorful” is disabled from local file system:
curl -X DELETE -v \
https://api.onebip.com/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
64
6.3 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 an HTTP DELETE request towards the
following url:
https://api.onebip.com/skins/{skin-name}
Authentication will be mandatory, with a standard basic access mechanism3 . In the following example
the skin called “colorful” is disabled from local file system:
curl -X DELETE -v \
https://api.onebip.com/skins/colorful
6.3.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
65
7 Automated start
The automated start allows a merchant to skip the MSISDN entry page, and go directly to the 2nd
Step, e.g. PIN entry or SMS instruction page. This feature needs to be enabled for your account, please
contact your account manager for more details.
For using this feature, you need to pass the following information’s within the standard start request:
• mobile number of the user

• mobile operator of the user in Onebip syntax as described for the parameter credit_provider
The list of operators can be retrieved over the revenue share API functionality.
66
Onebip S.r.l. | Via Fara, 28 Milan Italy www.onebip.com
67

Mobile Payment System: Web and Mobile Web

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Mobile Payment System: Web and Mobile Web

Uploaded by

Copyright:

Available Formats

Mobile Payment System

Web and Mobile web

Integration Guide 4.3.7

1 About this document 3

1.1 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Notice of non-liability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.4 Typographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

4 Onebip Mobile Payment Integration 8

4.1 One-Time Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.1.1 Constructing One-Time Payment Requests . . . . . . . . . . . . . . . . . . . . . 8

4.1.2 Processing One-Time Transaction Notifications . . . . . . . . . . . . . . . . . . 19

4.1.3 Return URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.2 Subscription-Based Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.2.1 Constructing Subscription Payment Requests . . . . . . . . . . . . . . . . . . . 29

4.2.2 Processing Subscription Transaction Notifications . . . . . . . . . . . . . . . . . 36

4.2.3 Change State Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

4.2.4 Billing Event Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

4.2.5 Notification Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

4.2.6 Notification Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.2.7 Signature Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.2.8 Return URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4.2.9 Login users already subscribed . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

5.1 Unsubscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

5.2 Messages API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

5.2.1 Message through buyer intention . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.3 Revenue Shares APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.3.1 Available Countries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.3.2 Available Pricepoints in Country . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.3.3 Revenue Shares in Country . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.3.4 Revenue Shares per Pricepoint in Country . . . . . . . . . . . . . . . . . . . . . 59

6.1 Skin Creation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

6.1.1 Processing Skin Creation API Response . . . . . . . . . . . . . . . . . . . . . . . 63

6.2 Skin Cancellation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

6.2.1 Processing Skin Cancellation API Response . . . . . . . . . . . . . . . . . . . . . 63

6.3 Skin Cancellation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

6.3.1 Processing Skin Cancellation API Response . . . . . . . . . . . . . . . . . . . . . 64

1 About this document

1.1 Intended Audience

1.2 Notice of non-liability

1.4 Typographic conventions

Version Date Content

4.3.7 21/02/2018 Adding specification for automated start

4.3.6 19/01/2018 Adding revenue shares APIs

4.3.5 12/01/2018 Adding context parameter to the container specification

4.3.4 06/12/2017 Adding subscription behaviour for user already subscribed

4.3.3 14/11/2017 Adding buyer intention initiated flow

4.3.2 11/09/2017 Correcting one time payment price format.

4.3.1 04/09/2017 Added specification on the notifications sequence.

4.3.0 08/08/2017 Changed unsubscription endpoint’s hostname & improved

4.2.7 29/05/2017 Adding product_id parameter to the container specification

4.2.6 24/05/2017 Adding credit_provider parameter to the container speci-

4.2.5 17/05/2017 Adding customer_account_id parameter to the container

4.2.4 21/04/2016 Adding recommendation on the sandbox attribute which

4.2.3 12/04/2016 Adding specification of the encoding of the parameters when

4.2.2 10/03/2016 Adding payment_method description as a payment page pa-

4.2.1 07/03/2016 Updating price description in the notifications of both one

Continued on next page

Continued from previous page

Version Date Content

4.1.9 22/02/2016 Updating one time/subscription transactions notifica-

4.1.7 01/12/2016 Updating Skins API

4.1.6 15/11/2016 Content access identity msisdn is now in E.164 format

4.1.5 07/11/2016 Added content_access_credentials paragraph and sbb_