Onebip Mobile Payment System Integration Guide
विज्ञापन
विज्ञापन
Mobile Payment System
PC and Mobile web
Integration Guide 4.0
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.
Integration Guide 4.0
2
INDEX
................................................................................................. 8
..................................................................................................19
3
Integration Guide 4.0
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 onhandsets. 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.
Integration Guide 4.0
4
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 dependi ng 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 country
2
.
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]
.
5
Integration Guide 4.0
Onebip Mobile Payment System
1 -
You can embed Onebip payment page
3
within your own payment page.
Your website
Your payment page
Buy coins with
START
Customer selects Onebip as the payment method on your website by clicking on Onebip button
Your website
Your payment page
Enter your phone
Customer stays on your website and enters his mobile phone number
Customer confirms the payment (via text message or PIN)
Your website
Your payment page
Authorize
Your website
Your payment page
Customer completes the payment
Your website
Completed!
Your payment page
Thank you for your purchase!
END
Customer receives your confirmation message
3
Please consider the iframe sizes for the following countries: USA mobile billing: max. 670x520px (widthxheight), France mobile billing: max. 700x520px (widthxheight).
6
Integration Guide 4.0
Onebip Mobile Payment System 2
:
You can redirect your customers to a Onebip payment page opening in a new browser.
Your website
Your payment page
Buy coins with
Buy coins!
Redirected
START
Customer selects Onebip as the payment method on your website redirected to Onebip payment page by clicking on Onebip button
Onebip payment page
Enter your number
Customer enters his mobile phone number
Customer confirms the payment (via text message or PIN)
Onebip payment page
Authorize
Customer completes the payment
Onebip payment page
Completed!
Your website
Your payment page
Redirected
Thank you!
Thank you for your purchase!
END
Customer redirected to your website and receives your message
7
Integration Guide 4.0
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
P rofile” 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 operators
4
.
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 points
5
(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”.
8
Integration Guide 4.0
3. Onebip Mobile Payment Integration
Onebip Mobile Payment System will allow you to charge your customers both for one-time payments and subscriptionbased 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 de ducted 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
username description price currency
Required
Yes
Description
The email address associated to your Onebip account.
Yes
Yes
Description of the item being sold. This will be displayed on the payment page and on the payment receipt.
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
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
Length
255
255
-
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
5
To learn the available price points and get the most updated list for the countries which you are interested in please check our website at http://www.onebip.com
under “Market info” or contact us on [email protected]
.
9
Integration Guide 4.0
country country_disabled item_code lang return_url notify_url remote_txid
Integration Guide 4.0
No
No
No
No
No
No
No
Used only to restrict payments to users from a specific country.
e.g. US
If no value is inserted the price will be automatically converted in the local currency of your customer.
Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
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
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.
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 English.
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, the browser is redirected to a Onebip web page.
The URL to which Onebip will send the technical information and the details about the transaction.
For more information about all the notifications available in
Onebip please go to the chapter
“3.1.2 Processing the Onebip onetime transaction response”.
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.
2
64
2
4096
4096
64
10
custom customer_email customer_email_lock customer_lastname customer_lastname_lock customer_cell customer_cell_lock customer_country
No
No
No customer_firstname customer_firstname_lock
No
No
No
No
No
No
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
Your customer’s email address
255
5 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
Your customer’s first name
Boolean value (true or false, 1 or 0)
If true, the first name field on the payment pa ge can’t be edited manually by your customer
Your customer’s last name
50
5
50
5 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
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
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
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.
15
5
2
11
Integration Guide 4.0
The HTTP POST integration model is provided through a payment button to be inserted in your payment page. Below the
URLs of the Onebip payment buttons currently placed at your disposal to have a complete POST integration: http://www.onebip.com/tools/bts/btn01.gif
http://www.onebip.com/tools/bts/btn02.gif
http://www.onebip.com/tools/bts/btn03.gif
http://www.onebip.com/tools/bts/btn04.gif
http://www.onebip.com/tools/bts/btn05.gif
http://www.onebip.com/tools/bts/btn06.gif
http://www.onebip.com/tools/bts/btn07.gif
http://www.onebip.com/tools/bts/btn08.gif
http://www.onebip.com/tools/bts/btn09.gif
http://www.onebip.com/tools/bts/btn10.gif
http://www.onebip.com/tools/bts/btn20.gif
3.1.1.1. HTML Examples
Below you can find the simplest integration examples with Onebip Payment System for one-time payments, using only mandatory parameters and some important ones.
You can consider the case below as for a web entertainment service with one-time payment model (associated to the merchant [email protected]
), which will create a Onebip payment button on this merchant’s web site, for the merchant’s service which will cost $ 0,99 for 1000 game credits in United States for its customers.
The transaction to be created will have the following data:
Username:
Item name:
Item price:
Country:
Return URL:
Notify URL: [email protected]
1000 game credits
$ 0.99 USD
United States http://www.webgame.com/thankyou.htm
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 & username = [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
12
Integration Guide 4.0
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>
In the following, an extended and more realistic example of the integration with HTTP POST for the same operation, using all the optional parameters will give you more complete control and better tracing of your payment operations.
<form action="http://www.onebip.com/api/purchases" method="post" target="onebip">
<input type="hidden" name=" command " value="
express_pay
" />
<input type="hidden" name=" username " value="
[email protected]
" />
<input type="hidden" name=" description " value="
1000 game credits
" />
<input type="hidden" name=" item_code " value="
gm427xl
" />
<input type="hidden" name=" price " value="
99
" />
<input type="hidden" name=" currency " value="
USD
" />
<input type="hidden" name=" country " value="
US
" />
<input type="hidden" name=" lang " value="
en
" />
<input type="hidden" name=" return_url " value="
http://www.webgame.com/thankyou.html
" />
<input type="hidden" name=" notify_url " value="
http://www.webgame.com/notify.php
" />
<input type="hidden" name=" remote_txid " value="
12666721
" />
<input type="hidden" name=" custom[promo_code] " value="
promo_oct_10
" />
<input type="hidden" name=" custom[channel] " value="
google campaign
" />
<input type="hidden" name=" custom[foo] " value="
bar
" />
<input type="hidden" name=" customer_email " value="
[email protected]
" />
<input type="hidden" name=" customer_firstname " value="
John
" />
<input type="hidden" name=" customer_lastname " value="
Smith
" />
<input type="hidden" name=" customer_cell " value="
0116434774000
" />
<input type="hidden" name=" customer_country " value="
US
" />
<input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
13
Integration Guide 4.0
3.1.2.
Processing the Onebip 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:
BODY: empty
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: to_url:
Yes
Yes
Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
It’s the notify_url given by you in the HTTP request which is reproposed here only for compatibility and tracing. payment_id: No transaction_id: business_model: country:
Yes
Yes
Yes
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.
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.
For one-time payments and transactions the only one allowable value is
“pull”.
Other values will be used in subscription-based model.
The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
14
Integration Guide 4.0
currency: price: original_currency: original_price: why: container: mobile_phone_number_enc: mobile_phone_number: mobile_phone_operator:
Yes
Yes
Yes
Yes
No
Yes
Yes
No
No
The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes
End user price in current currency
The decimal separator used is “.”; no thousands separator is provided.
e.g. 1.99
The original currency set by you before Onebip converts it to the local currency of your customer’s country
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
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.
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
The value of the MSISDN of the your customer, who has tried the onetime payment on Onebip payment page which is encrypted in md5.
e.g. 88504199e070fc43d2ca1f4896f24b1b
The MSISDN of your customer.
This value can be shared with you only under proper commercial agreements between parties.
The mobile network operator of the MSISDN of your customer.
This value can be shared with you only under proper commercial agreements between parties.
15
Integration Guide 4.0
remote_txid: item_code: custom:
No
No
No
Pass-through variable, a unique transaction reference number for your system (your internal transaction ID).
Pass-through variable you can use to identify your internal item code for this payment.
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” ,
“remote_txid”: “12666721” ,
“item_code”: “gm427xl”
}
In case of billing aborted, the structure of the JSON body will be the following:
{
“what”: “BILLING_ABORTED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“transaction_id”: “ 84332uu3b56nwa4398il762r ”,
“business_model”: “pull” ,
“country”: “US” ,
“currency”: “USD” ,
“price”: 0.99
,
“container”: “purchase/
09iuh7549bnn4rdc32h80op4
” ,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
“remote_txid”: “12666721” ,
“item_code”: “gm427xl”
“why”: “insufficient-credit”
}
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.
16
Integration Guide 4.0
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:
HEADER BODY:
200 OK
(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 will be automatically cancelled and will be stored in your Onebip account as
“Failed”.
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-Onebipsignature 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, like in the following the example:
X
-Onebip-Signature:
MDYwMTRlYjM1NWEyMjM3OTg1NzQzMTVhZDdlZDM5ZDIxN2RkYzViYmI2ZGZkZjFmOThiN2U3Zjc3ZDNh
ZjVjMg==
17
Integration Guide 4.0
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 customised
“postpayment” also known as “thank you” pages.
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.
Integration Guide 4.0
18
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 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 price
6 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 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
service_id command item_code
Required? Description
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.
Yes
No
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
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.
Length
24
50
64
6
To learn the available subscription-based price points please contact our business team on [email protected]
.
Integration Guide 4.0
19
lang return_url notify_url remote_txid custom customer_cell
No
No
No
No
No
No customer_cell_lock 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 English.
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, the browser is redirected to a Onebip web page.
The URL to which Onebip will send the technical information and the details about the transaction.
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”.
2
4096
4096
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
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
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
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
20
Integration Guide 4.0
The HTTP POST integration model is provided through a payment button to be inserted in your payment page. Below the
URLs of the Onebip payment buttons currently placed at your disposal to have a complete POST integration: http://www.onebip.com/tools/bts/btn01.gif
http://www.onebip.com/tools/bts/btn02.gif
http://www.onebip.com/tools/bts/btn03.gif
http://www.onebip.com/tools/bts/btn04.gif
http://www.onebip.com/tools/bts/btn05.gif
http://www.onebip.com/tools/bts/btn06.gif
http://www.onebip.com/tools/bts/btn07.gif
http://www.onebip.com/tools/bts/btn08.gif
http://www.onebip.com/tools/bts/btn09.gif
http://www.onebip.com/tools/bts/btn10.gif
3.2.1.1
HTML Examples
Below you can find the simplest integration examples with Onebip Payment System for one-time payments, using only mandatory parameters and some important ones.
You can consider the case below as for a web entertainment service with subscription-based payment model (associated to the merchant [email protected]
), which will create a Onebip payment button on this merchant’s web site, for the merchant’s weekly subscription service named “Supergame” which will cost € 5,00 per week in Spain for its customers.
The transaction to be created will have the following data:
Service ID:
Username:
Description:
Frequency:
Price:
Currency:
Country:
Language:
Return URL:
Cancel URL:
Notify URL:
5012b69ca4ee4aa3f3d3r415 [email protected]
Supergame weekly
5,00
EUR
Spain
Spanish http://www.webgame.com/thankyou.htm http://www.webgame.com/error.htm http://www.webgame.com/notify.php
The sample HTML code below illustrates a HTTP GET request. In the example, apart from the mandatory parameters, it is assumed that the merchant has overwritten the return_url and the notify_url for its particular needs: http://www.onebip.com/api/subscriptions?
command
=
express_pay
& service_id =
5012b69ca4 ee4aa3f3d3r415
& return_url
=
http://www.webgame.com/thankyou_new.htm
& notify_url
=
htt p://www.webgame.com/notify.updated.php
21
Integration Guide 4.0
The same result can be performed with a HTTP POST request with the same parameters:
<form action="http://www.onebip.com/api/subscriptions" method="post" target="onebip">
<input type="hidden" name=" service_id " value="
5012b69ca4ee4aa3f3d3r415
" />
<input type="hidden" name=" command " value="
express_pay
" />
<input type="hidden" name=" return_url " value="
http://www.webgame.com/thankyou_new.htm
" />
<input type="hidden" name=" notify_url " value="
http://www.webgame.com/notify_updated.php
" />
<input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt="Pay with Onebip" border="0"
/>
</form>
3.2.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
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:
BODY: empty
JSON
All the important and useful information will be inside the JSON body in order for you to understand and manage the notification successfully.
22
Integration Guide 4.0
3.2.1.2
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
to_url country: container: service_id mobile_phone_number_enc: mobile_phone_number: mobile_phone_operator: remote_txid: item_code: custom:
Yes
Yes
Yes
Yes
Yes
No
No
No
No
No
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
It’s the notify_url given by you in the HTTP request which is reproposed here only for compatibility and tracing.
The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
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
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
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
The MSISDN of your customer. This value can be shared with you only under proper commercial agreements between parties.
The mobile network operator of the MSISDN of your customer. This value can be shared with you only under proper commercial agreements between parties.
Pass-through variable, a unique transaction reference number for your system (your internal transaction ID).
Pass-through variable you can use to identify your internal item code for this payment.
A JSON object, containing all your custom parameters specified by your request.
Integration Guide 4.0
23
3.2.1.3
Billing event notification
For every event regarding billing, the merchant will receive a notification with these information:
Name Always present? Description
what:
Yes
to_url
Yes
Represents the content of the notification.
The possible values, without a need of explanation, are:
BILLING_COMPLETED
BILLING_ABORTED
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
business_model: country: currency: price: original_currency: original_price: container:
Yes
Yes
Yes
Yes
Yes
Yes
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.
The possible values are:
subscription_activation
subscription_renewal
The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes
End user price in current currency.
The decimal separator used is “.”; no thousands separator is provided.
e.g. 1.99
The original currency set by you before Onebip converts it to the local currency of your customer’s country
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
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
24
Integration Guide 4.0
mobile_phone_number_enc: mobile_phone_number: mobile_phone_operator: remote_txid: item_code: custom: why:
Hash
No
No
No
No
Yes
No
No
No
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
The MSISDN of your customer.
This value can be shared with you only under proper commercial agreements between parties.
The mobile network operator of the MSISDN of your customer.
This value can be shared with you only under proper commercial agreements between parties.
Pass-through variable, a unique transaction reference number for your system (your internal transaction ID).
Pass-through variable you can use to identify your internal item code for this payment.
A JSON object, containing all your custom parameters specified by your request.
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 checksum of your API Key and of the notification URL parameters.
25
Integration Guide 4.0
3.2.1.4
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” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“container”: “ “ subscription/20332b9ca4er34aa3g3d3r19 ”,
“service_id”: “
5012b69ca4ee4aa3f3d3r415
”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”
}
{
“what”: “BILLING_COMPLETED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“business_model”: “ subscription_activation “,
“container”: “ subscription/20332b9ca4er34aa3g3d3r19 ”,
“payment_id”: “ 23dtle561129ij562jn5tg44 ”,
“transaction_id”: “ 84332uu3b56nwa4398il762r ”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
“country”: “US” ,
“currency”: “USD” ,
“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” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“container”: “ subscription/11132555a4er3faa3g3d3fff ”,
“service_id”: “
5012b69ca4ee4aa3f3d3r415
”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
}
26
Integration Guide 4.0
{
“what”: “BILLING_ABORTED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“business_model”: “ subscription_activation “,
“container”: “ subscription/11132555a4er3faa3g3d3fff ”,
“payment_id”: “ 23dtle561129ij562jn5tg44 ”,
“transaction_id”: “ 84332uu3b56nwa4398il762r ”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
“country”: “US” ,
“currency”: “USD” ,
“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 the payment completed.
{
“what”: “BILLING_COMPLETED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“business_model”: “ subscription_renewal “,
“container”: “ subscription/20332b9ca4er34aa3g3d3r19 ”,
“payment_id”: “ 00rtlaa31129inn3y7t5tg21 ”,
“transaction_id”: “ 06312uaa55690op398ilwq30 ”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
“country”: “US” ,
“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.
{
“what”: “BILLING_ABORTED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“business_model”: “ subscription_renewal ”,
“container”: “ subscription/20332b9ca4er34aa3g3d3r19 ”,
“transaction_id”: “ 00132uuaa56nwa4398il732a ”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b” ,
“country”: “US” ,
“currency”: “USD” ,
“price”: 5
}
27
Integration Guide 4.0
Subscription termination
This notification is a result of your request towards
“Unsubscription API” in this guide or a result of a “push” notification due to the other termination methods such as inquiries received to Onebip customer care call centre.
In this case, the same notification for the status change will be sent to you:
{
“what”: “SUBSCRIPTION_TERMINATED” ,
“to_url”: “ http://www.webgame.com/notify.php
“,
“container”: “ subscription/20332b9ca4er34aa3g3d3r19 ”,
“service_id”: “
5012b69ca4ee4aa3f3d3r415
”,
“mobile_phone_number_enc”: “88504199e070fc43d2ca1f4896f24b1b”
}
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.1.5 Notification retry
In the notification system, as a consequence of its notifications, Onebip expects to receive a response with::
HEADER STATUS CODE:
HEADER BODY:
200 OK
(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.1.6 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-Onebipsignature 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.
28
Integration Guide 4.0
Enabling the API key means that you will receive a notification with the header enriched with the X-Onebip-Signature, like in the following the example:
X
-Onebip-Signature:
MDYwMTRlYjM1NWEyMjM3OTg1NzQzMTVhZDdlZDM5ZDIxN2RkYzViYmI2ZGZkZjFmOThiN2U3Zjc3ZDNh
ZjVjMg==
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 “postpayment” also known as “thank you” pages.
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.
29
Integration Guide 4.0
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:
BODY:
200 OK 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, t his means that the blacklisted user won’t be able to complete any other transactions for any of your services in future. On the other hand, with a similar operation you can also “un-blacklist” the MSISDNs or the users which you have blacklisted before in order to allow them to make transactions again for your services.
4.2.1. Constructing a blacklist requests
You can request a blacklist operation using a HTTP POST method towards the url:
http(s)://www.onebip.com/api/blacklist
You will be allowed to use this action only with the authentication by using your username and password that you created during your registration process of Onebip.
30
Integration Guide 4.0
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
payment_id
Required? Description
As alternative If you are interested in blacklisting the user starting from one of his transactions. user_email mobile_phone_ number
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.
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 "
user_email
"
4.2.2. Constructing an un-blacklist requests
You can request an un-blacklist operation using a HTTP DELETE method towards the url:
http(s)://www.onebip.com/api/blacklist/[ID]
where [ID] is one of the valid IDs which is useful for the un-blacklist operation.
You will be allowed to use this action only with the authentication by using your username and password that you created during your registration process of Onebip.
The following are the case sensitive dynamic parameters that you can choose to use in your un-blacklist request according to your needs.
Please note that you need to use just one of the following parameter, without the parameter name: user_email mobile_phone_ number
Required Description
As alternative If you are interested in un-blacklist the user associated to that email address
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.
31
Integration Guide 4.0
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 the information and the data for the transactions related to your services through asynchronous operations.
4.3.1. Back-office Transactions API
You can retrieve the transaction data from Onebip related to your services using Onebip Back-office API. Onebip will expose the transaction data to you by giving the opportunity to filter them by using relevant fields.
32
Integration Guide 4.0
Below is an example of a transaction:
{
"id":"50c84ed2c1b6592135000000",
"container":"subscription/50c84ed2c1b6592135000000",
"created_at":"2012-12-04T09:08:07Z",
"country":"US",
"currency":"USD",
"amount": 7.50,
"status":"aborted",
"why":"insufficient-credit",
"business_model": "subscription_renewal",
"context":"web",
"description":"1000 game credits",
"details":
{
"flow":"no-optin-flow",
"source":"MTB",
"remote_txid":"12QW34ER56TY,
"mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af",
"mobile_phone_number":"154797140490",
"mobile_phone_operator":"US/Verizon",
"custom":
{
"your_variable1":"your_value1",
"your_variable2":"your_value2",
“foo”:”bar”
},
},
}
To obtain a list of transactions, you must perform a GET HTTP request towards the following url:
https://www.onebip.com/bko/transactions
This HTTP route is the only point of access to gain information about the transactions and you can be fine grained as you want to use the filters which may be expressed in the query string as a value of the parameter query.
Filters must be written in JSON format.
There are four fields through which you can filter the result:
id: the id of the transaction
container: the id of the container (to select its transactions)
MSISDN: the msisdn of the transaction
created_at: the creation date of the transaction
33
Integration Guide 4.0
The following examples will give you the complete idea of the operational behaviour. The first one is to obtain all the transactions of an MSISDN given:
GET /bko/transactions?query={“msisdn”:”393482456742”}
The result will be the list of all the transactions owned by you which has been generated from the MSISDN you have specified in the filter.
Here an example is about a query per transaction_id:
GET /bko/transactions?query={“id”:”6-U7195446971053235”}
Another example is about the container_id that may be related a subscription-based service:
GET /bko/transactions?query={“container”:”subscription/50b392d9419615990b00111a”}
The result will be the list of all the transactions owned by you which has been generated within the container specified. A container may be a
“subscription” or a “purchase”.
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
34
Integration Guide 4.0
Onebip Back-office API should only be used through an authentication. The merchant can perform requests only following the HTTPE 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 blacklist or un-blacklist 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
35
Integration Guide 4.0
}
The following is a complete example of a 200 OK response:
Status: 200
[{
"id":"50c84ed2c1b6592135000000",
"container":"subscription/50c84ed2c1b6592135000000",
"created_at":"2012-12-04T09:08:07Z",
"country":"US",
"currency":"USD",
"amount": 7.50,
"status":"aborted",
"why":"insufficient-credit",
"business_model": "subscription_renewal",
"context":"web",
"description":"1000 game credits",
"details":
{
"flow":"no-optin-flow",
"source":"MTB",
"remote_txid":"12QW34ER56TY,
"mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af",
"mobile_phone_number":"393482355312",
"mobile_phone_operator":"US/Verizon",
"custom":
{
"your_variable1":"your_value1",
"your_variable2":"your_value2",
“foo”:”bar”
},
},
}]
4.3.2. Back-office Transaction Stats API
You can also retrieve transaction statistics from Onebip by using Onebip Back-office API.
Onebip indeed exposes the data about the transaction statistics, giving the opportunity to you to filter them by using some fields.
Here is an example of a transaction statistics:
{
"country":"TR",
"ok":153,
"ko":33,
"total":186
36
Integration Guide 4.0
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={“created_at”:”20121212000000”}
37
Integration Guide 4.0
Onebip Back-office API supports also the filtering of the range of the date as seen on the following example:
GET /bko/transactions-stats?query={“created_at”: {“$gt”:”20121201000000”,
“$lt”: “20121215235959””}
The result is to give to you the access to the statistics of your subscriptions for the amount 10 resulted in 12/12/2012.
In this last case four operators are available, to specify the role of a date in the filter:
$gt means greater than
$gte means greater than or equals
$lt means less than
$lte means less than or equals
Onebip Back-office API should only be used through an authentication. You can perform requests only following the
HTTP
Basic Authenticaion which consists in placing the “Authorization” HTTP Header in the HTTP Request with the value of the tring computed with the following formula:
Base64(“username:password”)
Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are not in
HTTPS will result in a 400 Bad Request response.
The following two complete examples, using curl, comprehends: curl -u "[email protected]:123456" 'https://www.onebip.com/bko/transactionsstats?query={“container”:”subscription”}' curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY="
'https://www.onebip.com/bko/transactionsstats?query={“container”:”subscription”}'
4.3.2.1. Processing Back-office Transactions Stats API response
The possible response from Onebip for a blacklist or un-blacklist request are the following:
200 OK
In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format
400 Bad Request
The request is malformed and Onebip doesn’t want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed filter
401 Unauthorized
The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request.
403 Forbidden
The merchant has not enough privileges to access the resource
404 Not Found
Onebip is not able to find the resource requested from the merchant
38
Integration Guide 4.0
The following is a complete example of a 200 OK response:
Status: 200
{
"country":"TR",
"ok":153,
"ko":33,
"total":186
}
Integration Guide 4.0
39
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
40
Integration Guide 4.0
डाउनलोड
सार्वजनिक लिंक अपडेट किया गया
आपकी चैट का सार्वजनिक लिंक अपडेट कर दिया गया है. You may view and manage your chat links after registration here.
दस्तावेज़ सार्वजनिक लिंक
विज्ञापन
