Mobile Payment System
Mobile Payment System PC and Mobile web Integration Guide 4.2.0 Integration Guide 4.2.0 1 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.2.0 2 Document change log Version Date Content 4.0.0 14/01/2013 New release of Onebip API 4.0.1 25/01/2013 Update chapter 4 API Integration and updated new examples in this chapter 4.0.2 04/02/2013 Added chapter 5 Versioning Updated chapter 4.3 Back-office API 4.0.3 11/02/2013 Added chapter 6 Skinability 4.0.4 29/03/2013 Added chapter 7 Authentication as a service Updated signature encryption Updated notification parameters list with new "notification_id" and "first_notification_at" 4.0.5 16/04/2013 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.6 10/09/2013 Updated chapter 7 Authentication as a service by introducing new parameter "before_walkin_url" 4.0.7 23/09/2013 Updated footnote for HTTPS payment request 4.1.0 16/12/2013 Added subscription change status notifications for states before activation 4.2.0 28/3/2014 Added cancel_url redirect and explanation of parameters for both return_url and cancel_url. Added SUBSCRIPTION_*_FAILED notifications, details on transaction_id and notification_id Integration Guide 4.2.0 3 INDEX 1. Introduction 1.1. Onebip Mobile Payment Flow 2. Registration and Set-up 2.1. Account creation 2.2. Payment and country enabling 3. Onebip Mobile Payment Integration 3.1. One-time payments 3.1.1. Constructing one-time payment requests 3.1.1.1. HTML Examples 3.1.1.2. Security Signature 3.1.2. Processing one-time transaction notifications 3.1.2.1. Notification Examples 3.1.2.2. Notification Retry 3.1.2.3. Signature encryption 3.1.2.4. Redirect URLs: return_url and cancel_url 3.2. Subscription-based payments 3.2.1. Constructing subscription payment requests 3.2.1.1. HTML Examples 3.2.1.2. Security signature 3.2.2. Processing subscription transaction notifications 3.2.2.1. Change state event notification 3.2.2.2. Billing event notification 3.2.2.3. Notification examples 3.2.2.4. Notification retry 3.2.2.5. Signature encryption 3.2.2.6. Redirect URLs: return_url and cancel_url 4. API integration 4.1. Unsubscription API 4.2. Blacklist API 4.2.1. Constructing a blacklist requests 4.2.2. Constructing an un-blacklist requests 4.2.3. Processing the blacklist / un-blacklist response 4.3. Back-office API 4.3.1. Back-office Transactions API 4.3.1.1. Processing Back-office Transactions API response 4.3.2. Back-office Transaction Stats API 4.3.2.1. Processing Back-office Transactions Stats API response Integration Guide 4.2.0 4 4.3.3. Back-office Customer Base Status API 4.3.3.1. Processing Back-office Customer Base Status API response 5. Versioning 6. Skinnability 6.1. Skin Creation API 6.1.1. Processing skin creation API response 6.2. Skin Cancellation API 6.2.1. Processing skin cancellation API response 7. Authentication as a service 7.1. Constructing an authentication aas request 7.2. Processing Authentication aas response Integration Guide 4.2.0 5 1 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.2.0 6 1.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 website1 The mobile payments available within PC and Mobile website can be performed by the end-users with different payment flow experience depending on the mobile network operator's technology and policy and the market regulations. Onebip ensures to deliver the best user experience for your services across multiple devices and different mobile networks in different countries. Onebip's continuous optimization of the payment flows and the use of the newest mobile technologies available ensures higher conversion rates possible. With Onebip, today there are different payment flows available: PC WEB MO FLOW: by sending a KEYWORD to a SHORTCODE or by replying an SMS with a KEYWORD PC WEB PIN FLOW: by receiving a PIN CODE by SMS and inserts it in Onebip payment page, In addition the flows above, there are 2 flows optimized and specific for mobile web: MOBILE WEB SMS-LINK FLOW: by clicking on a LINK received by SMS MOBILE WEB ONE-CLICK FLOW: by clicking on a payment button The mobile payment flow and the end-user experience is entirely managed by Onebip which automatically then ensures you to have the best flow available on the market, and does not require any action from your website and/or application. You can integrate Onebip Mobile Payment System in 2 different ways as seen on the following diagrams which will perform the above-mentioned payment flows depending on the country2. 1 The ISP billing payment system is not included in this integration guide. Please go to http://www.onebip.com to download the latest version of Onebip ISP Billing Integration Guide. 2 To get more details about the payment flows used in different countries you can contact us on [email protected]. Integration Guide 4.2.0 7 Onebip Mobile Payment System 1 - You can embed Onebip payment page3 in your own payment page. START User selects Onebip as the payment method on your website by clicking on Onebip button. User stays on your website and enters his mobile phone number User confirms the payment (i.e. via text message or PIN) User completes the payment END User receives your confirmation message on your payment page 3 Please consider the iframe sizes for the following countries: USA mobile billing: max. 670x520px (width x height), France mobile billing: max. 700x520px (width x height). Integration Guide 4.2.0 8 Onebip Mobile Payment System 2 - You can redirect your customers to a Onebip payment page opening in a new window. START User selectes Onebip as the payment method on your website and is redirected to Onebip payment page after clicking on Onebip button User enters his mobile phone number User confirms the payment (i.e. via text message or PIN) User completes the payment and is redirected to your payment page END User receives your confirmation message on your payment page Integration Guide 4.2.0 9 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 that you will find on "My Profile" section. After Onebip enables your account, you will start receiving transactions into your account from all the mobile subscribers from all the countries globally where Onebip is connected to mobile network operators4. 4 For more information about Onebips coverage please contact us on [email protected]. Integration Guide 4.2.0 10 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 (e.g., 4.99€ for 500 credits, 9.99€ for 1000 Credits) Integration Guide 4.2.0 11 3 Onebip Mobile Payment Integration Onebip Mobile Payment System will allow you to charge your customers both for one-time payments and subscription-based payments depending on your service offering with a simple technical integration conducted with HTTP requests. You can immediately start integrating one-time payments and receiving transactions from your customers by following the integration steps detailed in this integration guide. To start receiving transactions for the subscriptionbased 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 is deducted from your customers 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 HTTPS5 instead of HTTP in the payment page URL. All parameters, being transmitted over HTTP(S), are serialized as strings and as such boolean parameters use 0 and 1 as possible values to make clear whether they evaluate to false or true. All parameters must be passed in the UTF-8 encoding, the default character encoding for the web. 5 HTTPS payment requests are not supported for the following country: France Integration Guide 4.2.0 12 The following table shows all the case sensitive dynamic parameters you must use in your payment query string to Onebip: Name Required Description Lenght username Yes The email address associated to your Onebip account. 255 description Yes Description of the item being sold. This will be displayed on the payment page and on the payment receipt. 255 price Yes End user price in cents (local value added taxes included) as integer cents (actual amount * 100). - e.g. 100 is for 1 of the local currency e.g. 99 is for 0,99 of the local currency currency Yes Local currency code. Please find all the currency codes allowed in Onebip ISO 4217 standard on http://en.wikipedia.org/wiki/Currency_codes e.g. USD 3 command Yes Determines the integration type with Onebip. At the moment the only allowed value is "express_pay". Other options will be available in the future. e.g. express_day 50 country Yes Used only to restrict payments to users from a specific country. e.g. US Please find all the country codes allowed in Onebip ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_31661_alpha-2 Note: the country code is UK for United Kingdom. 4096 return_url Yes The URL to which your customer's browser is redirected after they complete a payment. 4096 This parameter is fundamental for the complete payment experience of your customers. Your customer is redirected to the page in whcih has confirmation of the given payment, and of the resuling benefit. By default, if the parameter is not set in the request, it's used the value set on the Onebip Panel, under marchant's settings. notify_url No The URL to which Onebip will send the technical information and the details about the transaction. 4096 If no value is set on the request, it's used the value set on Onebip Panel, under Merchant settings. If also this configuration is missing, any notification is sent to you for the given purchase. For more information about all the notifications available in Onebip please go to the chapter "3.1.2 Processing the Onebip one-time transaction response". Integration Guide 4.2.0 13 cancel_url No The URL to which your customer's browser is redirected if the user clicks on the "CANCEL" button on the purchase page or if the payment cannot be completed correctly. 4096 If no value is set in the request, the redirection is made towards the "cancel_url" value set in the Onebip Panel configuration, under merchant's settings. If a default is not set, the user won't be redirect at all but will see a Onebip error message describing the problem. country_disabled No Used to prevent you to receive transaction from specific countries. Typically used if you don't want to collect money from weak-currency countries. The value is given by a list of country codes comma separated e.g. EG,CO,CL Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_31661_alpha-2 Note: the country code is UK for United Kingdom. item_code No Pass-through variable you can use to identify your internal item code for this payment. 64 Please note that this is not the Onebip item ID, that may be alphanumeric and may be used to trace the coupling itempayment inside the process. lang No The language used on the payment page that your customers will make the payments. 2 Please find all the language codes allowed in Onebip in ISO 639-1 standard on http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes e.g. en If the value is not set, the default language will be the current language of the browser used for navigation. remote_txid No A pass-through variable and a single and unique transaction ID reference number assigned to your system (your internal transaction ID) for each and single payment. 64 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. skin No The skin to be used for the required purchase page. Usable only for enabled users. 255 Please see chapter 6 for any detail. Integration Guide 4.2.0 14 logo_url No This URL is the link to integrate your logo inside the Onebip purchase page, in the upper left corner. 4096 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 which will be passed through the system and returned in your notify_url and will be appended to your return_url and cancel_url. A maximum of 10 variables (64 characters each) can be used. The formal structure will be: custom[your_variable1] Max 10 variables per 64 characters each 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. customer_email No Your customer's email address 255 customer_email_lock No Boolean value (true or false, 1 or 0) 5 If true, the email address field on the payment page can't be edited manually by your customer customer_firstname No Your customer's first name 50 customer_firstname_lock No Boolean value (true or false, 1 or 0) 5 If true, the first name field on the payment page can't be edited manually by your customer customer_lastname No Your customer's last name 50 customer_lastname_lock No Boolean value (true or false, 1 or 0) 5 If true, the last name field on the payment page can't be edited manually by your customer customer_cell No Your customer's cell phone number in international format with no leading 15 e.g. 447700900999 Note that customer_cell must match with customer_country prefix customer_cell_lock No Boolean value (true or false, 1 or 0) 5 If true, the mobile phone number field on the payment page can't be edited manually by your customer Integration Guide 4.2.0 15 customer_country No Your customer's country code. Please find all the country codes allowed in Onebip in ISO 3166 standard on http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 2 e.g. US Note that customer_country must match the value given in "country" parameter, if used. Note: the country code is UK for United Kingdom. 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: [email protected] Item name: 1000 game credits Item price: $ 0.99 USD Country: United States Return URL: http://www.webgame.com/thankyou.htm Notify URL: http://www.webgame.com/notify.php Integration Guide 4.2.0 16 The sample HTML code below illustrates a HTTP GET request URL: http://www.onebip.com/api/purchases?command=express_pay&[email protected] &description=1000+game+credits&price=99&country=US¤cy= USD&return_url=http://www.webgame.com/thankyou.htm¬ify_url=http://www.webgame.com/notify.php The same result can be performed with a HTTP POST request by using the same parameters: <form action="http://www.onebip.com/api/purchases" method="post" target="onebip"> <input type="hidden" name="command" value="express_pay" /> <input type="hidden" name="username" value="[email protected]" /> <input type="hidden" name="description" value="1000 game credits" /> <input type="hidden" name="price" value="99" /> <input type="hidden" name="currency" value="USD" /> <input type="hidden" name="country" value="US" /> <input type="hidden" name="return_url" value="http://www.webgame.com/thankyou.htm" /> <input type="hidden" name="notify_url" value="http://www.webgame.com/notify.php" /> <input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt= "Pay with Onebip" border="0" /> </form> In the following, an extended and more realistic example of the integration with HTTP POST for the same operation, using all the optional parameters will give you more complete control and better tracing of your payment operations. <form action="http://www.onebip.com/api/purchases" method="post" target="onebip"> <input type="hidden" name="command" value="express_pay" /> <input type="hidden" name="username" value="[email protected]" /> <input type="hidden" name="description" value="1000 game credits" /> <input type="hidden" name="item_code" value="gm427xl" /> <input type="hidden" name="price" value="99" /> <input type="hidden" name="currency" value="USD" /> <input type="hidden" name="country" value="US" /> <input type="hidden" name="lang" value="en" /> <input type="hidden" name="return_url" value="http://www.webgame.com/thankyou.html" /> <input type="hidden" name="notify_url" value="http://www.webgame.com/notify.php" /> <input type="hidden" name="remote_txid" value="12666721" /> <input type="hidden" name="custom[promo_code]" value="promo_oct_10" /> <input type="hidden" name="custom[channel]" value="google campaign" /> <input type="hidden" name="custom[foo]" value="bar" /> <input type="hidden" name="customer_email" value="[email protected]" /> <input type="hidden" name="customer_firstname" value="John" /> <input type="hidden" name="customer_lastname" value="Smith" /> <input type="hidden" name="customer_cell" value="0116434774000" /> <input type="hidden" name="customer_country" value="US" /> <input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt= "Pay with Onebip" border="0" /> </form> 3.1.1.2 Security Signature Onebip provides you with a process to enforce the security between you and Onebip, using a signature process inside the http request. Signature is not mandatory, but can be used if you would like to be sure to protect in the best way the connection with Onebip, to prevent any possible type of fraud. Integration Guide 4.2.0 17 If you introduce the signature in the request, Onebip will accept the request only if the signature check is OK, and will discard it if the check is not passed. If the signature is not present the control won't be performed. If used, the signature must be inserted as an additional parameter of the request, always as last parameter of the http string. Onebip will control the signature, accepting the request only if the value check is correct. Signature encryption is based on hashing, and has the following form: signature: hash_hmac('sha256', $url, $key) This feature requires a secret "key" value, that is the "API Key" that the you must set under the "My Account" section on Onebip Panel. API key is mandatory to use signature in the request. Taking the example of the previous chapter, with the following GET request, without signature URL : http://www.onebip.com/api/purchases?command=express_pay&[email protected] &description=1000+game+credits&price=99&country=US¤cy= USD&return_url=http://www.webgame.com/thankyou.htm¬ify_url=http://www.webgame.com/notify.php And using the configured API key, that is, the signature is elaborated using the following data, where the url value must be encoded: $url: http://www.onebip.com/api/purchases?command=express_pay&username=business%40webgame.com &description=1000+game+credits&price=99&country=US¤cy=USD &return_url=http%3A%2F%2Fwww.webgame.com%2Fthankyou.htm ¬ify_url=http%3A%2F%2Fwww.webgame.com%2Fnotify.php $key = 'MySecretKey123456' And the result of the hashing will be: Signature: 1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7ad8f43 So that, the final version of the GET request, with the signature used, will be URL : http://www.onebip.com/api/purchases?command=express_pay&[email protected] &description=1000+game+credits&price=99&country=US¤cy= USD&return_url=http://www.webgame.com/thankyou.htm¬ify_url=http://www.webgame.com/notify.php &signature=1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7ad8f43 Integration Guide 4.2.0 18 The same, identical, process may be applied to http POST request, where the signature value is elaborated in the same way, and where the final representation of the request would be: <form action="http://www.onebip.com/api/purchases" method="post" target="onebip"> <input type="hidden" name="command" value="express_pay" /> <input type="hidden" name="username" value="[email protected]" /> <input type="hidden" name="description" value="1000 game credits" /> <input type="hidden" name="price" value="99" /> <input type="hidden" name="currency" value="USD" /> <input type="hidden" name="country" value="US" /> <input type="hidden" name="return_url" value="http://www.webgame.com/thankyou.htm" /> <input type="hidden" name="notify_url" value="http://www.webgame.com/notify.php" /> <input type="hidden" name="signature" value= "1eb737cf166bab51effa85fbf7a121d377fe1b5a76e95452dfcbe51bb7ad8f43" /> <input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt= "Pay with Onebip" border="0" /> </form> You can also ask to enforce more security, making the signature control mandatory on Onebip side. This means that the control of the request will be always made by Onebip for every request, and the request will be accepted only if the check is ok. 3.1.2 Processing one-time transaction notifications Onebip will respond you with a proper notification for each one of your one-time payment requests. The transaction response must be executed by your landing script to ensure that the transaction is committed on the Onebip system before recording the customer's payment as successful in your database. This guarantees no discrepancies between your transaction records and Onebip. Onebip responds to successful request of billing notification with: HEADER: empty BODY: JSON All the important and useful information will be inside the JSON body in order for you to understand and manage the notification successfully. Integration Guide 4.2.0 19 The following structure will manage both the successful transaction and billing cases, with all the relevant information, and the error cases, with the description and coding of the error occurred. Name Always? Description what Yes Represents the content of the notification. The possible values, without a need of explanation, are: BILLING_COMPLETED BILLING_ABORTED to_url Yes It's the notify_url given by you in the HTTP request which is reproposed here only for compatibility and tracing. payment_id No This is a unique ID identifying the payment at Onebip which is present only in case of BILLING_COMPLETED. This ID will be shown in your panel and in your customers' panel, and will be used to identify the relevant payment. You may use this ID to avoid that the same payment is registered more than once on your side. Note that the format is alphanumeric. transaction_id Yes This is a unique ID identifying the transaction at Onebip, that is an object created both for billing completed that for billing aborted. You may use this ID to avoid that the same payment is registered more than once on your side. In case a failure is notified but no transaction has been started yet, the value will be "not_available". Note that the format is alphanumeric. business_model Yes For one-time payments and transactions the only one allowable value is "pull". Other values will be used in subscription-based model. country Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Note: the country code is UK for United Kingdom. currency Yes The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes price Yes End user price in current currency The decimal separator used is "."; no thousands separator is provided. e.g. 1.99 original_currency Yes The original currency set by you before Onebip converts it to the local currency of your customer's country original_price Yes The original price set by you before Onebip converts it to the local price of your customer's country The decimal separator used is "."; no thousands separator is provided. e.g. 1.99 Integration Guide 4.2.0 20 why No This parameter is used only in case of BILLING_ABORTED. The value is one of the error code available, listed in the following: check-pin-failed-too-many-times mobile-blocked insufficient-credit routing-error invalid-msisdn out-of-network payment-failed transfer-in-aborted spending-limit-reached unable-to-send-messages connectivity-layer-failure age-verification sim-full subscription-already-exists unknown-error unknown-exception Note that more values may be added in future without changing the behaviour of the integration you are currently using. container Yes The container, in Onebip environment, is the object of the purchase operation, that may be a one-time payment or a subscription-based payment. In this case of one-time payment the value will be always "purchase", with the value of the item (a 24 chars alphanumeric). e.g. purchase/09iuh7549bnn4rdc32h80op4 notification_id Yes first_notification_at Yes It's a unique, alphanumeric id identifying this single notification. Used to prevent any possible duplicate in merchant's notifications management after we retry following an error response or a timeout. If two notifications with the same notification_id are repeated, they represent the single event. e.g. 9iou8yy4sd1n43ww3nj887u0 It's an integer having the value of the UNIX timestamp of when the notification is performed. In case of retries, this timestamp is fixed and always points to the instant at which the first attempt was made. e.g 1364471150 Please pay attention that Unix timestamp is a number, equal to the number of seconds passes since the Unix epoch. Integration Guide 4.2.0 21 mobile_phone_number_enc Yes mobile_phone_operator Yes 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 mobile network operator of the MSISDN of your customer. This value is always present in notifications. e.g. US/Verizon mobile_phone_number No The MSISDN of your customer. This value can be shared with you only under proper commercial agreements between parties remote_txid No Pass-through variable, a unique transaction reference number for your system (your internal transaction ID). item_code No Pass-through variable you can use to identify your internal item code for this payment. custom No A JSON object, containing all your custom parameters specified by your request. Integration Guide 4.2.0 22 3.1.2.1 Notification Examples The JSON body of a notification message sent from Onebip to your notify_url in case of successful billing will be: { "what": "BILLING_COMPLETED", "to_url": "http://www.webgame.com/notify.php", "payment_id": "23dtle561129ij562jn5tg44", "transaction_id": "84332uu3b56nwa4398il762r", "business_model": "pull", "country": "US", "currency": "USD", "price": 0.99, "container": "purchase/09iuh7549bnn4rdc32h80op4", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "remote_txid": "12666721", "item_code": "gm427xl" "notification_id": "9iou8yy4sd1n43ww3nj887u0" "first_notification_at": "1364471150" } In case of billing aborted, the structure of the JSON body will be the following: { "what": "BILLING_ABORTED", "to_url": "http://www.webgame.com/notify.php", "transaction_id": "84332uu3b56nwa4398il762r", "business_model": "pull", "country": "US", "currency": "USD", "price": 0.99, "container": "purchase/09iuh7549bnn4rdc32h80op4", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "remote_txid": "12666721", "item_code": "gm427xl" "why": "insufficient-credit" "notification_id": "9iou8yy4sd1n43ww3nj887u0" "first_notification_at": "1364471150" } Obviously the content of the parameter "why" is dependent on the error with the possible available values listed in the previous table through which you will be able to store the transaction results in order to create your own statistics about the failures. 3.1.2.2 Notification Retry In the notification system, as a consequence of its notifications, Onebip expects to receive a response with: HEADER STATUS CODE: 200 OK HEADER BODY: (empty) If you fail to respond OK, for instance if there is a system error in your web server, Onebip will place the corresponding notification in a queue and will retry periodically to deliver it, until it will be successful. The retry rules are the following: One attempt per minute in the first 5 minutes. Integration Guide 4.2.0 23 One attempt every 5 minutes for the first hour One retry per hour after the first hour A total retry period for a payment notification of 24 hours During the retry period the payment will be stored in your Onebip account as "Pending". If Onebip receives no outcome after the total retry period, the payment is considered "Completed" the same, and like that shown on the panel. 3.1.2.3 Signature encryption Onebip provides a signature encryption based on hashing, that is an encryption method that ensures the HTTP body has not been manipulated or changed. This allows the integrity of the body in a data exchange between two parties to be checked, through an information given in the header of the notifications. The signature included in the header has the following form: X-Onebip-Signature: base64_encode(hash_hmac("sha256", 'http raw body', 'Onebip API Key')) X-Onebip-signature is a HMAC hash that uses an hashing algorithm "sha256", that is 256 bits, encoded in base64. This feature requires a secret key value (API Key) you will choose that you can set under the "My Account" section. Enabling the API key means that you will receive a notification with the header enriched with the X-OnebipSignature. In the following the example API key is set, and a purchase is completed, with the following data: $raw_body = '{ "country": "US", "container": "purchase\\/812894dh207c88056d000000", "mobile_phone_number_enc": "10b23c1039c704f87d7bf3cc1a0b8638", "status": "completed", "price": 5, "currency": "USD", "business_model": "pull", "transaction_id": "726378172", "original_price": 5, "original_currency": "USD", "what": "BILLING_COMPLETED", "to_url": "https:\\/\\/www.merchant.com\\/onebip_notification", "payment_id": 2349872834 }'; $key = "MySecretKey123456"; $signature = base_64_encode(hash_hmac("sha256", $rawBody, $key, true)); var_dump($signature);// X-Onebip-Signature should be "gLazLSwGRgNMvXqTgzm/Jt9Yo5JnbpIrai6CiMmVv5s=" 3.1.2.4 Redirect URLs: return_url and cancel_url Onebip will append all the pass-through parameters you have specified in the transaction request to your redirect url. The user will be redirected back to your web pages on the return_url or cancel_url set during the creation of the container, depending on the successful completion of the payment. Pass-through parameters in the redirect url page can be used in many ways, for example to pass an internal user-ID Integration Guide 4.2.0 24 through the payment process and redirect your customer to her account on your site, or to build customized "postpayment" 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 redirect url creation. It can be used to verify that the url has been created recently. "signature": is the security signature given by Onebip, described in detail in the following. Signature encryption is based on hashing, and has the following form: "signature" => hash_hmac("sha256", $url, $key) This feature requires a secret "key" value (API Key) that you can set under the "My Account" section on Onebip Panel. Please note that without setting of the API key on Onebip panel, no signature can be created, and so in the redirect url both signature and timestamp parameters will be missing. In the following example the API key is set on the Onebip Panel so that the signature can be created with the following data: $url = "http://www.webgame.com/thankyou.html?payment_id=100701483&original_price=99" . "&original_currency=USD&promo_id=2332&whois=msisdn/%2Fb667aea7c956ac72ecb6af65e1d9cfec" . "mobile_phone_operator=US%2FVerizon&mobile_phone_number_enc=b667aea7c956ac72ecb6af65e1d9cfec" . "×tamp=1366103067"; $key = "MySecretKey123456"; $signature = bin2hex(hash_hmac("sha256", $url, $key, true)); var_dump($signature); // signature should be "6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f" We can now provide a complete example. The completed billing request for a purchase, like in the following example: http://www.onebip.com/api/purchases?command=express_pay&[email protected] &description=1000+game+credits&price=99&country=US¤cy=USD &return_url=http://www.webgame.com/thankyou.html?custom[promo_id]=23332 will simply, in case of successful billing, a redirection towards the url: http://www.webgame.com/thankyou.html?payment_id=100701483&original_price=99 &original_currency=USD&promo_id=2332&whois=msisdn/%2Fb667aea7c956ac72ecb6af65e1d9cfec mobile_phone_operator=US%2FVerizon&mobile_phone_number_enc=b667aea7c956ac72ecb6af65e1d9cfec ×tamp=1366103067&signature=a6e16edf2e6de9894b870d6f99aa1ea095a11f4c51664f41a996d0039fd71f44 The redirect url page can also route to your customer to a specific download page, using the notify_url to authorize it. The redirect url page could also be used to host the scripts needed to grant 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. Notifications delivery is a server-to-server and Integration Guide 4.2.0 25 retried for a day in case of connection problems, where as the user may close the page or lost connection before the return_url can be loaded. So that, in our example, the final redirect url will be URL: http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7 &mobile_phone_operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7 &is_subscribed_to=5012b69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415 ×tamp=1366102294&signature=6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f The redirect url page can also route your customer to a specific download, using the notify_url to authorize it. The redirect 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 redirect url page, but by the notify_url. Successful completions are defined as: status "completed" for purchases. Not successful completions of the flow correspond instead to: status "aborted" for purchases. The following parameters may be appended to these redirect URLs: Name Description return_url cancel_url container The id of the created purchase, e.g. purchase/1234567890 Yes Yes whois A unique key anonimously representing the user e.g. msisdn/e/1234567890124567890 Yes Optional mobile_phone_operator Shows the operator the user's SIM belongs e.g. IT/Vodafone Yes Optional original_price Shows the original price requested in cents even if currency conversion has happened e.g. 500 Yes Yes original_currency Shows the original currency requested e.g. EUR Yes Yes timestamp Shows the timestamp at which the transaction was closed as a UNIX timestamp, either successfully or not e.g. 1396001781 Yes Yes payment_id A unique id for the payment performed e.g. 123456789 Yes No why A label for the type of error that has happened e.g. insufficient-credit No Yes custom The custom parameters passed, as a map of values e.g. custom[channel]=adsense Optional Optional remote_txid The remote_txid passed during the container creation. Optional Optional Integration Guide 4.2.0 26 signature Onebip signature of the URL that you can check to ensure no tampering has happened. Yes Yes 3.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. 1. 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 2. 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 onetime payments, this integration will be even easier for you. 3. 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. 4. 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. Integration Guide 4.2.0 27 3.2.1 Constructing subscription payment requests The connection with Onebip payment page is achieved by using HTTP GET or POST requests to the following URL: http://www.onebip.com/api/subscriptions Please note that the connection to Onebip payment page can be performed using a standard HTTP request or using a 128bit SSL encryption on our secure server where the structure of the call will be identical, apart from the use of HTTPS instead of HTTP in the payment page URL. The following table shows all the case sensitive dynamic parameters you must use in your payment query string to Onebip: Name Required? Description Length service_id Yes The foremost value for the subscription-based calls. It will be a specific service ID which will be associated to each of your subscription-based service which must be used always for all the requests. 24 The format is a 24 chars alphanumeric. 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. 50 e.g. express_pay return_url Yes The URL to which your customers' browser is redirected after they complete a payment. 4096 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 the technical information and the details about the transaction. 4096 If no value is set on the request, it's used the value set on Onebip Panel, under Merchant settings. If also this configuration is missing, any notification is sent to you for the given purchase. For more information about all the notifications available in Onebip please go to the chapter "3.2.2 Processing the Onebip subscription transaction response". Integration Guide 4.2.0 28 cancel_url No The URL to which your customers' browser is redirected if the user click on the "CANCEL" button on the purchase page. This parameter must be used only in the countries in which the cancel button is present on the purchase page. 4096 If no value is set in the request, the redirection is made towards the "cancel_url" value set in the Onebip Panel configuration, under merchant's settings. If also this value is not set the behaviour will be a redirection towards referrer url. item_code No Pass-through variable you can use to identify your internal item code for this payment. 64 Please note that this is not the Onebip item ID, and may be used to trace the coupling item- payment inside the process. lang No The language used on the payment page that your customers will make the payments. 2 Please find all the language codes allowed in Onebip in ISO 639-1 standard on http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes e.g. en If the value is not set, the default language will be the one currently used by the browser used. remote_txid No A pass-through variable and a single and unique transaction ID reference number assigned to your system (your internal transaction ID) for each and single payment. It is used to avoid duplicated transactions, and for this reason the same value cannot be re-used, not even in test phase, because the controls is made on Onebip side. 64 skin No The skin to be used for the required purchase page. Usable only for enabled users. Please see chapter 6 for any detail. 255 logo_url No This URL is the link to integrate your logo inside the Onebip purchase page, in the upper left corner. 4096 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 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] Max 10 variables per 64 characters each 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. Integration Guide 4.2.0 29 customer_cell No Your customer's cell phone number in international format with no leading 15 e.g. 447700900999 Note that customer_cell must match customer_country prefix customer_cell_lock No Boolean value (true or false, 1 or 0) 5 If true, the mobile phone number field on the payment page can't be edited manually by your customer The HTTP POST integration model is provided through a payment button to be inserted in your payment page. Below the URLs of the Onebip payment buttons currently placed at your disposal to have a complete POST integration: http://www.onebip.com/tools/bts/btn01.gif http://www.onebip.com/tools/bts/btn02.gif http://www.onebip.com/tools/bts/btn03.gif http://www.onebip.com/tools/bts/btn04.gif http://www.onebip.com/tools/bts/btn05.gif http://www.onebip.com/tools/bts/btn06.gif http://www.onebip.com/tools/bts/btn07.gif http://www.onebip.com/tools/bts/btn08.gif http://www.onebip.com/tools/bts/btn09.gif http://www.onebip.com/tools/bts/btn10.gif 3.2.1.1 HTML Examples Below you can find the simplest integration examples with Onebip Payment System for one-time payments, using only mandatory parameters and some important ones. You can consider the case below as for a web entertainment service with subscription-based payment model (associated to the merchant [email protected]), which will create a Onebip payment button on this merchant's web site, for the merchant's weekly subscription service named "Supergame" which will cost € 5,00 per week in Spain for its customers. The transaction to be created will have the following data: Service ID: 5012b69ca4ee4aa3f3d3r415 Username: [email protected] Description: Supergame Frequency: weekly Price: 5,00 Currency: EUR Country: Spain Language: Spanish Return URL: http://www.webgame.com/thankyou.html Cancel URL: http://www.webgame.com/error.html Notify URL: http://www.webgame.com/notify.php Integration Guide 4.2.0 30 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 URL : http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415 &return_url=http://www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php The same result can be performed with a HTTP POST request with the same parameters: <form action="http://www.onebip.com/api/subscriptions" method="post" target="onebip"> <input type="hidden" name="service_id" value="5012b69ca4ee4aa3f3d3r415" /> <input type="hidden" name="command" value="express_pay" /> <input type="hidden" name="return_url" value="http://www.webgame.com/thankyou_new.html" /> <input type="hidden" name="notify_url" value="http://www.webgame.com/notify_updated.php" /> <input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt= "Pay with Onebip" border="0" /> </form> 3.2.1.2 Security signature Onebip provides you with a process to enforce the security between you and Onebip, using a signature process inside the http request. Signature is not mandatory, but can be used if you would like to be sure to protect in the best way the connection with Onebip, to prevent any possible type of fraud. If you introduce the signature in the request, Onebip will accept the request only if the signature check is OK, and will discard it if the check is not passed. If the signature is not present the control won't be performed. If used, the signature must be inserted as an additional parameter of the request, always as last parameter of the http string. Onebip will control the signature, accepting the request only if the value check is correct. Signature encryption is based on hashing, and has the following form: signature: hash_hmac('sha256', $url, $key) This feature requires a secret "key" value, that is the "API Key" that you must set under the "My Account" section on Onebip Panel. API key is mandatory to use signature in the request. Taking the example of the previous chapter, with the following GET request, without signature URL : http://www.onebip.com/api/subscriptions?command=express_pay &service_id=5012b69ca4ee4aa3f3d3r415&return_url=http://www.webgame.com/thankyou_new.html ¬ify_url=http://www.webgame.com/notify.updated.php And using the configured API key, that is, the signature is elaborated using the following data, where the url must be encoded for what concerns the parameters: $url: http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415 &return_url=http%3A%2F%2Fwww.webgame.com%2Fthankyou_new.html ¬ify_url=http%3A%2F%2Fwww.webgame.com%2Fnotify.updated.php Integration Guide 4.2.0 31 $key = 'MySecretKey123456' And the result of the hashing will be: Signature: ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622 So that, the final version of the GET request, with the signature used, will be URL : http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415 &return_url=http: //www.webgame.com/thankyou_new.html¬ify_url=http://www.webgame.com/notify.updated.php &signature=ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622 The same, identical, process may be applied to http POST request, where the signature value is elaborated in the same way, and where the final representation of the request would be: <form action="http://www.onebip.com/api/subscriptions" method="post" target="onebip"> <input type="hidden" name="service_id" value="5012b69ca4ee4aa3f3d3r415" /> <input type="hidden" name="command" value="express_pay" /> <input type="hidden" name="return_url" value="http://www.webgame.com/thankyou_new.html" /> <input type="hidden" name="notify_url" value="http://www.webgame.com/notify_updated.php" /> <input type="hidden" name="signature" value= " ba75e32e30ec7af959862cbc973730425d8deac931972cac1f5a4515df0c6622" /> <input type="image" name="submit" src="http://www.onebip.com/tools/bts/btn04.gif" alt= "Pay with Onebip" border="0" /> </form> You can also ask to enforce more security, making the signature control mandatory on Onebip side. This means that the control of the request will be always made by Onebip for every request, and the request will be accepted only if the check is ok. 3.2.2 Processing subscription transaction notifications 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: Change state event A change of state related to a subscription, among the existing ones. Some notifications are related to acquisition: 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. This notification is sent after the user has reached a pending or active status. SUBSCRIPTION_PENDING: the first billing has failed and the subscription will be retried later according to configuration. The user has reached the pending state. Integration Guide 4.2.0 32 These notifications are related to activation: they can be received either immediately during acquisition or after several retries in the following days. SUBSCRIPTION_ACTIVATED: the first billing has succeeded and the user has become active. SUBSCRIPTION_ACTIVATION_FAILED: the first attempt to activate the user has not succeeded. It's the opposite of SUBSCRIPTION_ACTIVATED. In the case of smart billing it is sent only after a full cycle of attempts at different amounts has been performed. These notifications are related to renewals: SUBSCRIPTION_RENEWED: event for every renewal case of every subscription, conditional to payment completion. SUBSCRIPTION_RENEWAL_FAILED: event for every renewal attempts that has failed. It is the opposite of SUBSCRIPTION_RENEWED. In the case of smart billing it is sent only after a full cycle of attempts at different amounts has been performed. These notifications are sent when an user exits the customer base, due to the impossibility to charge him even after retries or a request for deletion triggered by the API or by customer care: SUBSCRIPTION_CANCELED: a subscription that has been pending or in a state previous to acquisition goes into the canceled state. SUBSCRIPTION_TERMINATED: a subscription that has been active goes into the terminated state. These notifications are reserved for future usage: SUBSCRIPTION_SUSPENDED. SUBSCRIPTION_REACTIVATED. 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 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. Integration Guide 4.2.0 33 3.2.2.1 Change state event notification For every change in the state of the event, a notification is sent to you, containing the following information: Name Always? Description what Yes Represent the content of the notification regarding a subscription-based payment. The possible values are listed in the previous page. to_url Yes It's the notify_url given by you in the HTTP request which is reproposed here only for compatibility and tracing. country Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Note: the country code is UK for United Kingdom. container Yes service_id Yes The container, in Onebip environment, is the object of the purchase operation, that may be a one-time payment or a subscription-based payment. In the case of subscription-based payment the value will be always the "subscription_id" created by Onebip as a result of successful subscription transaction. The subscription id is univocally related to one service_id and one MSISDN only, and it's a 24 chars alphanumeric, not repeatable. e.g. subscription/20332b9ca4er34aa3g3d3r198 It's the key value that identifies with a unique and not repeatable index of the service concerning the operation. Note that this value will be a 24 chars alphanumeric. e.g. : 5012b69ca4ee4aa3f3d3r415 notification_id Yes first_notification_at Yes It's a unique, alphanumeric id identifying this single notification. Used to prevent any possible duplicate in merchant's notifications management after we retry following an error response or a timeout. If two notifications with the same notification_id are repeated, they represent the single event. e.g. 9iou8yy4sd1n43ww3nj887u0 It's an integer having the value of the UNIX timestamp of when the notification is performed. In case of retries, this timestamp is fixed and always points to the instant at which the first attempt was made. e.g 1364471150 Please pay attention that Unix timestamp is a number, equal to the number of seconds passes since the Unix epoch. mobile_phone_number_enc Yes 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 Integration Guide 4.2.0 34 mobile_phone_operator Yes The mobile network operator of the MSISDN of your customer. This value is always present in every notification. mobile_phone_number No The MSISDN of your customer. This value can be shared with you only under proper commercial agreements between parties. remote_txid No Pass-through variable, a unique transaction reference number for your system (your internal transaction ID). item_code No Pass-through variable you can use to identify your internal item code for this payment. custom No A JSON object, containing all your custom parameters specified by your request. e.g. : US/Verizon 3.2.2.2 Billing event notification For every event regarding billing, you will receive a notification with these information: Name Always present? Description what Yes Represents the content of the notification. The possible values, without a need of explanation, are: BILLING_COMPLETED BILLING_ABORTED to_url Yes It's the notify_url given by you in the HTTP request which is reproposed here only for compatibility and tracing. payment_id No This is a unique ID identifying the payment at Onebip which is present only in case of BILLING_COMPLETED. This ID will be shown in your panel and in your customers' panel, and will be used to identify the relevant payment. You may use this ID to avoid that the same payment is registered more than once on your side. Note that the format is alphanumeric. transaction_id Yes This is a unique ID identifying the transaction at Onebip, that is an object created both for billing completed that for billing aborted. You may use this ID to avoid that the same payment is registered more than once on your side. In case a failure is notified but no transaction has been started yet, the value will be "not_available". Note that the format is alphanumeric. business_model Yes The possible values are: 1. subscription_activation 2. subscription_renewali Integration Guide 4.2.0 35 country Yes The country code in ISO 3166 standard http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Note: the country code is UK for United Kingdom. currency Yes The local currency code in ISO 4217 standard http://en.wikipedia.org/wiki/Currency_codes price Yes End user price in current currency. The decimal separator used is "."; no thousands separator is provided. e.g. 1.99 original_currency Yes The original currency set by you before Onebip converts it to the local currency of your customer's country original_price Yes The original price set by you before Onebip converts it to the local price of your customer's country The decimal separator used is "."; no thousands separator is provided. e.g. 1.99 container Yes The container, in Onebip environment, is the object of the purchase operation, that may be a single purchase or a subscription. In this case of subscription-based transaction the value will always be "subscription", with the value of the item (a 24 chars alphanumeric). e.g. subscription/20332b9ca4er34aa3g3d3r198 notification_id Yes It's a unique, alphanumeric id identifying this single notification. Used to prevent any possible duplicate in merchant's notifications management after we retry following an error response or a timeout. If two notifications with the same notification_id are repeated, they represent the single event. e.g. 9iou8yy4sd1n43ww3nj887u0 first_notification_at Yes It's an integer having the value of the UNIX timestamp of when the notification is performed. In case of retries, this timestamp is fixed and always points to the instant at which the first attempt was made. e.g 1364471150 Please pay attention that Unix timestamp is a number, equal to the number of seconds passes since its birth. mobile_phone_number_enc Yes mobile_phone_operator Yes The value of the MSISDN of the your customer, who has tried the subscription-based payment on Onebip payment page which is encrypted in md5. e.g. 88504199e070fc43d2ca1f4896f24b1b The mobile network operator of the MSISDN of your customer. This value is always present, in every notification: e.g.: US/Verizon mobile_phone_number No The MSISDN of your customer. This value can be shared with you only under proper commercial agreements between parties. Integration Guide 4.2.0 36 remote_txid No Pass-through variable, a unique transaction reference number for your system (your internal transaction ID). item_code No Pass-through variable you can use to identify your internal item code for this payment. custom No A JSON object, containing all your custom parameters specified by your request. why No This parameter is used only in case of BILLING_ABORTED. The value is one of the error code available, listed in the following: check-pin-failed-too-many-times mobile-blocked insufficient-credit routing-error invalid-msisdn out-of-network payment-failed transfer-in-aborted pending-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 existing ones. Hash Integration Guide 4.2.0 No Hash checksum of your API Key and of the notification URL parameters. 37 3.2.2.3 Notification examples The examples following are the series of examples to represent you all the different business cases related to a subscription-based service, with the consequent notifications that you will receive. Subscription activation succeeded Following a specific request received from you, Onebip will send two notifications to you: the event of activation, the first billing. { "what": "SUBSCRIPTION_ACTIVATED", "to_url": "http://www.webgame.com/notify.php", "container": "subscription/20332b9ca4er34aa3g3d3r19", "service_id": "5012b69ca4ee4aa3f3d3r415", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b" "mobile_phone_operator":"US/Verizon", "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364498611" } { "what": "BILLING_COMPLETED", "to_url": "http://www.webgame.com/notify.php", "business_model": "subscription_activation", "container": "subscription/20332b9ca4er34aa3g3d3r19", "payment_id": "23dtle561129ij562jn5tg44", "transaction_id": "84332uu3b56nwa4398il762r", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "country": "US", "currency": "USD", "price": 5, "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364498612" } Subscription activation failed When a subscription process is not completed successfully, in most cases because it was not possible to charge your customer, or there was a problem with the mobile network operator, Onebip will send two notifications to you: { "what": "SUBSCRIPTION_CANCELED", "to_url": "http://www.webgame.com/notify.php", "container": "subscription/11132555a4er3faa3g3d3fff", "service_id": "5012b69ca4ee4aa3f3d3r415", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364498611" } { "what": "BILLING_ABORTED", "to_url": "http://www.webgame.com/notify.php", "business_model": "subscription_activation", "container": "subscription/11132555a4er3faa3g3d3fff", "payment_id": "23dtle561129ij562jn5tg44", "transaction_id": "84332uu3b56nwa4398il762r", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "country": "US", "currency": "USD", "price": 5, Integration Guide 4.2.0 38 "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364498676" } Subscription renewal succeeded This is called a "push" operation generated by Onebip after a completed renewal of an active subscription. The notification towards you will be about change state the payment completed. { "what": "SUBSCRIPTION_RENEWED", "to_url": "http://www.webgame.com/notify.php", "container": "subscription/20332b9ca4er34aa3g3d3r19", "service_id": "5012b69ca4ee4aa3f3d3r415", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b" "mobile_phone_operator":"US/Verizon", "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364498676" } { "what": "BILLING_COMPLETED", "to_url": "http://www.webgame.com/notify.php", "business_model": "subscription_renewal", "container": "subscription/20332b9ca4er34aa3g3d3r19", "payment_id": "00rtlaa31129inn3y7t5tg21", "transaction_id": "06312uaa55690op398ilwq30", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "country": "US", "currency": "USD", "price": 5, "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364471150" } Subscription renewal failed This notification is sent when the renewal attempt of a subscription service is failed because it was not possible to charge your customer. { "what": "BILLING_ABORTED", "to_url": "http://www.webgame.com/notify.php", "business_model": "subscription_renewal", "container": "subscription/20332b9ca4er34aa3g3d3r19", "transaction_id": "00132uuaa56nwa4398il732a", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b", "mobile_phone_operator":"US/Verizon", "country": "US", "currency": "USD", "price": 5, "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364471150" } Integration Guide 4.2.0 39 Subscription termination This notification is a result of your request towards "Unsubscription API" in this guide or a result of a "push" notification due to the other termination methods such as inquiries received to Onebip customer care call centre. In this case, the same notification for the status change will be sent to you: { "what": "SUBSCRIPTION_TERMINATED", "to_url": "http://www.webgame.com/notify.php", "container": "subscription/20332b9ca4er34aa3g3d3r19", "service_id": "5012b69ca4ee4aa3f3d3r415", "mobile_phone_number_enc": "88504199e070fc43d2ca1f4896f24b1b" "mobile_phone_operator":"US/Verizon", "notification_id": "9iou8yy4sd1n43ww3nj887u0", "first_notification_at": "1364471150" } Analogous notifications are provided for the suspension and reactivation of the operations, that moreover are used only in few special payment flows in some countries, due to specific operators' regulations 3.2.2.4 Notification retry In the notification system, as a consequence of its notifications, Onebip expects to receive a response with: HEADER STATUS CODE: 200 OK HEADER BODY: (empty) If you fail to respond OK, for instance if there is a system error in your web server, Onebip will place the corresponding notification in a queue and will retry periodically to deliver it, until it will be successful. The retry rules are the following: One attempt per minute in the first 5 minutes. 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. Integration Guide 4.2.0 40 3.2.2.5 Signature encryption Onebip provides a signature encryption based on hashing, that is an encryption method that ensures the HTTP body has not been manipulated or changed. This allows the integrity of the body in a data exchange between two parties to be checked, through an information given in the header of the notifications. The signature included in the header has the following form: "signature" => base64_encode(hash_hmac("sha256", "http raw body", "Onebip API Key") X-Onebip-signature is a HMAC hash that uses an hashing algorithm "sha256", that is 256 bits, encoded in base64. This feature requires a secret key value (API Key) you will choose that you can set under the "My Account" section. Enabling the API key means that you will receive a notification with the header enriched with the X-OnebipSignature. In the following the example the API key is set, and purchase is completed, with the following data: $raw_body = '{ "country": "TR", "remote_txid": "AB_22022122", "container": "subscription\\/562634za43bc76051d003309", "mobile_phone_number_enc": "10b23c1039c704f87d7bf3cc1a0b8638", "status": "completed", "price": 8, "currency": "TRY", "business_model": "pull", "transaction_id": "76939310", "original_price": 8, "original_currency": "TRY", "what": "BILLING_COMPLETED", "to_url": "http:\\/\\/merchant.com\\/vpncontrol\\/onebip\\/ipn", "payment_id": 11149219 }'; $key = "MySecretKey123456"; var_dump(base64_encode(hash_hmac("sha256", $raw_body, $key, true))); // signature should be "1dEDSiSZL6OAntUPNTzQoggnt6RXWo9ld3371MkhSdI=" Pay attention that hmac must be calculated in binary mode, not in hexadecimal. The hmac is always in binary data. 3.2.2.6 Redirect URLs: return_url and cancel_url Onebip will append all the pass-through parameters you have specified in the transaction request to your redirect url. The user will be redirected back to your web pages on the return_url or cancel_url set during the creation of the container, depending on the successful completion of the payment. Pass-through parameters in the redirect 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 "postpayment" 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 redirect url creation. It can be used to verify that the url has been created recently. "signature": is the security signature given by Onebip, described in detail in the following. Integration Guide 4.2.0 41 Signature encryption is based on hashing, and has the following form: "signature" => hash_hmac("sha256", $url, $key) This feature requires a secret "key" value (API Key) that you can set under the "My Account" section on Onebip Panel. Please note that without setting of the API key on Onebip panel, no signature can be created, and so in the redirect url both signature and timestamp parameters will be missing. In the following example the API key is set on the Onebip Panel so that the signature can be created with the following data: Service ID:ID5012b69ca4ee4aa3f3d3r415 Username: [email protected] Description: Supergame Frequency: Weekly Price: 5,00 Currency: EUR Country: Spain Language: Spanish Return URL: http://www.webgame.com/thankyou.html Cancel URL: http://www.webgame.com/error.html Notify URL: http://www.webgame.com/notify.html The request for the subscription activation will be the following one URL : http://www.onebip.com/api/subscriptions?command=express_pay&service_id=5012b69ca4ee4aa3f3d3r415 &return_url=http://www.webgame.com/thankyou_new.html ¬ify_url=http://www.webgame.com/notify.updated.php The signature to be added in the redirect url can be created with the following data: $url = "http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7" . "&mobile_phone_operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7" . "&is_subscribed_to=5012b69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415" . "×tamp=1366102294"; $key = "MySecretKey123456"; $signature = bin2hex(hash_hmac("sha256", $url, $key, true)); var_dump($signature); // signature should be "6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f" So that, in our example, the final redirect url will be URL: http://www.webgame.com/thankyou_new.html?whois=msisdn%2F7edf143f80f2356ae8a200e394bdf2e7 &mobile_phone_operator=ES%2FMovistar&mobile_phone_number_enc=7edf143f80f2356ae8a200e394bdf2e7 &is_subscribed_to=5012b69ca4ee4aa3f3d3r415&has_paid_for=5012b69ca4ee4aa3f3d3r415 ×tamp=1366102294&signature=6042d0f9d722a18a67a7876a0032296da3f30c0512c6eeed7fb2e846d726c30f URL URLs are sent to new line due to formatting needs. They should be on a single line when tried or implemented in production. Integration Guide 4.2.0 42 The redirect url page can also route your customer to a specific download, using the notify_url to authorize it. The redirect 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. The user will be redirected back to your web pages on the return_url or cancel_url set during the creation of the container, depending on the successful completion of the payment. Successful completions are defined as: status "active" for subscriptions, or "pending" when enable. Not successful completions of the flow correspond instead to: status "canceled" for subscriptions. The following parameters may be appended to these redirect URLs: Name Description return_url cancel_url container The id of the created subscription, e.g. subscription/1234567890 Yes Yes whois A unique key anonimously representing the user e.g. msisdn/e/1234567890124567890 Yes Optional mobile_phone_operator Shows the operator the user's SIM belongs e.g. IT/Vodafone Yes Optional original_price Shows the original price requested in cents even if currency conversion has happened e.g. 500 Yes Yes original_currency Shows the original currency requested e.g. EUR Yes Yes timestamp Shows the timestamp at which the transaction was closed as a UNIX timestamp, either successfully or not e.g. 1396001781 Yes Yes payment_id A unique id for the payment performed e.g. 123456789 Yes No why A label for the type of error that has happened e.g. insufficient-credit No Yes custom The custom parameters passed, as a map of values e.g. custom[channel]=adsense Optional Optional remote_txid The remote_txid passed during the container creation. Optional Optional signature Onebip signature of the URL that you can check to ensure no tampering has happened. Yes Yes Integration Guide 4.2.0 43 4 API integration Onebip provides with the opportunity to have the additional features that will allow you to manage the operations of unsubscription and black-lists. 4.1 Unsubscription API You can change the state of a subscription from ACTIVE to TERMINATED using a specific Onebip Unsubscription API. The method will be the following: DELETE /api/subscription/{ID} Where {ID} is the subscription_id created by Onebip at the act of first subscription. You will be allowed to use this action only with the authentication by using your username and password that you created during your registration process of Onebip. An example, using curl, can be seen in the following box: curl -u [email protected]:m3rc4nt123 -X DELETE http://www.onebip.com/api/subscription/291dd69cr4ee4aa3f1d3rt85 Onebip expects to receive a response with: HEADER: 200 OK BODY: empty 4.2 Blacklist API With blacklist API you can decide to "blacklist" an MSISDN or a Onebip user who may have one or more MSISDNs associated to her Onebip account, which has performed at least one one-time or subscription-based transaction towards for one of your services. On one hand, this means that the blacklisted user won't be able to complete any other transactions for any of your services in future. On the other hand, with a similar operation you can also "un-blacklist" the MSISDNs or the users which you have blacklisted before in order to allow them to make transactions again for your services. 4.2.1 Constructing a blacklist requests You can request a blacklist operation using a HTTP POST method towards the url: http(s)://www.onebip.com/api/blacklist You will be allowed to use this action only with the authentication by using your username and password that you created during your registration process of Onebip. 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. Integration Guide 4.2.0 44 Name Required Description payment_id As alternative If you are interested in blacklisting the user starting from one of his transactions. user_email As alternative If you are interested in blacklist the user associated to that email address. The consequence is to black list all the mobile phone numbers associated to the user, than can be one or more. mobile_phone_number As alternative If you are interested in blacklist the mobile phone number associated (when available). mobile_phone_number_enc As alternative If you are interested in blacklist the mobile phone number associated. An example, using curl, of this communication by using an HTTP POST request would be: curl -v -u [email protected]:secret_password http://www.onebip.com/api/blacklist -X POST -d "mobile_phone_number_enc=4812c91a1bbG8f5a78889cf62e28aedc" or, as an alternative: curl -v -u [email protected]:secret_password http://www.onebip.com/api/blacklist -X POST-d "[email protected]" 4.2.2 Constructing an un-blacklist requests You can request an un-blacklist operation using a HTTP DELETE method towards the url: http(s)://www.onebip.com/api/blacklist/[ID] where [ID] is one of the valid IDs which is useful for the un-blacklist operation. You will be allowed to use this action only with the authentication by using your username and password that you created during your registration process of Onebip. The following are the case sensitive dynamic parameters that you can choose to use in your un-blacklist request according to your needs. Please note that you need to use just one of the following parameter, without the parameter name: Name Required Description user_email As alternative If you are interested in un-blacklist the user associated to that email address mobile_phone_number As alternative If you are interested in 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 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] Integration Guide 4.2.0 45 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: 1. 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. 2. 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). 3. 401 Unauthorized when wrong authorization keys are sent, or the user is not allowed for the blacklist operation. 4. 400 Bad Request when the passed parameters are not valid, or some parameters are missed. 5. 403 Forbidden when who tries to blacklist some MSISDNs is not allowed for some reason. 6. 404 Not Found when the resource was not found. 7. 500 Internal Server Error Some unexpected error occurred. Integration Guide 4.2.0 46 4.3 Back-office API Back-office API will allow you to obtain some additional and asynchronous information about a large quantity of data from Onebip platform. In particular, the information available is the data for the transactions related to your services (Transaction API), the aggregated data about the transactions results (Transactions Stats), the aggregated data about active customer base and subscription behaviour (Customer Base Status API). 4.3.1 Back-office Transactions API You can retrieve the transaction data from Onebip related to your services using Onebip Back-office Transactions API. Onebip will expose the transaction data to you by giving you the opportunity to filter them by using relevant fields. Below is an example of a transaction: { "id":"50c84ed2c1b6592135000000", "container":"subscription/50c84ed2c1b6592135000000", "created_at":"2012-12-04T09:08:07Z", "country":"US", "currency":"USD", "amount": 7.50, "status":"aborted", "why":"insufficient-credit", "business_model": "subscription_renewal", "context":"web", "description":"1000 game credits", "details": { "flow":"no-optin-flow", "source":"MTB", "remote_txid":"12QW34ER56TY", "mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af", "mobile_phone_number":"154797140490", "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) Integration Guide 4.2.0 47 MSISDN: the MSISDN of the transaction created_at: the creation date of the transaction The following examples will give you the complete idea of the operational behaviour. The first one is to obtain all the transactions for a given MSISDN: GET /bko/transactions?query={"msisdn":"393482456742"} The result will be a JSON object with a property called ‘element' which contains a list of all the transactions owned by you which has been generated from the MSISDN you have specified in the filter. Another example is about a query per transaction_id, that will return a JSON Object with a property called ‘elements' which contains a list with a single transaction as result. GET /bko/transactions?query={"id":"00096877511"} Another one is about the container_id that may be related a subscription-based service: GET /bko/transactions?query={"container":"subscription/50b392d9419615990b00111a"} The result in this case will be a JSON object with a property called ‘element' which contains a list of all the transactions owned by you which has been generated within the container specified. Another example may refer to the creation date, that can be a single date or a range. Onebip Back-office API uses only date which are in the UTC time-zone and they must be specified like in the following pattern: YYYYMMDDhhmmss. GET /bko/transactions?query={"created_at":"20121212000000"} Onebip Back-office API supports also the filtering of the range of the date like in the following example: GET /bko/transactions?query={"created_at": {"$gt":"20121201000000", "$lt": "20121215235959""} In this case four operators are available to specify the role of a date in the filter: $gt means greater than $gte means greater than or equals $lt means less than $lte means less than or equals Onebip Back-office API should only be used through an authentication. You can perform requests only following the HTTP Basic Authentication which consists in placing the "Authorization" HTTP Header in the HTTP Request with the value of the tring computed with the following formula: Base64("username:password") Moreover, Onebip Back-office API should only be used through requests performed in HTTPS. All the requests Integration Guide 4.2.0 48 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"}" or curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY=" "https://www.onebip.com/bko/transactions?query={"id":"50bdaf6721bc88790d000001"}" 4.3.1.1 Processing Back-office Transactions API response The possible response from Onebip for a transactions request will be the following: 200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format 400 Bad Request The request is malformed and Onebip doesn't want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed filter 401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request. 403 Forbidden The merchant has not enough privileges to access the resource 404 Not Found Onebip is not able to find the resource requested from the merchant Integration Guide 4.2.0 49 The following is a complete example of a 200 OK response: Status: 200 { "elements":[{ "id":"50c84ed2c1b6592135000000", "container":"subscription/50c84ed2c1b6592135000000", "created_at":"2012-12-04T09:08:07Z", "country":"US", "currency":"USD", "amount": 7.50, "status":"aborted", "why":"insufficient-credit", "business_model": "subscription_renewal", "context":"web", "description":"1000 game credits", "details": { "flow":"no-optin-flow", "source":"MTB", "remote_txid":"12QW34ER56TY", "mobile_phone_number_enc":"81fc6dfffa2f2ce6d9d905d2bc15f6af", "mobile_phone_number":"393482355312", "mobile_phone_operator":"US/Verizon", "custom": { "your_variable1":"your_value1", "your_variable2":"your_value2", "foo":"bar" }, }, }] } 4.3.2 Back-office Transaction Stats API Using Onebip Back-office API it's also possible to retrieve transaction statistics from Onebip by mean of aggregation data stored and managed by Onebip platform. Onebip indeed exposes the data about the transaction statistics, giving you the opportunity to you to filter them by using some fields. Here is an example of a transaction Stats output: { "country":"TR", "ok":153, "ko":33, "total":186 } To list the transaction statistics you must perform a GET HTTP request towards the following url: https://www.onebip.com/bko/transactions-stats This HTTP route is the only point of access to gain information about transactions statistics and you can be fine grained as you want to use filters which may be expressed in the query string as a value of the parameter query. Filters must be written in JSON format. Integration Guide 4.2.0 50 Onebip Back-office API for Transactions Statistics supports the following fields for filtering: date: the date on which perform statistics counts container: the type of the container (subscription or purchase) amount: the amount of the transaction country: the country where the transaction happened carrier: the carrier of the transaction in to form COUNTRY\Operator context: the context of the transaction (web, mobile, ...) The following example will give the complete idea of the operational behaviour. The first one is to obtain the result for a given country: GET /bko/transactions-stats?query={"country":"TR"} And the result will be the transaction statistics for the transactions owned by you filtered on the country specified in the filter. Another example is about a query per container: GET /bko/transactions-stats?query={"container":"subscription"} The result are the transaction statistics for the transactions owned by you filtered on the container specified in the filter. Another example is about a combined filter: GET /bko/transactions-stats?query={"container":"subscription","amount":10} The result are transaction statistics for the transactions owned by you filtered on the container and the amount as specified in the filter. Another example may refer to the creation date, that can be a single date or a range. Onebip Back-office API uses only the date which are in the UTC time-zone and they must be specified following this pattern: YYYYMMDDhhmmss. GET /bko/transactions-stats?query={"date":"20121212000000"} Onebip Back-office API supports also the filtering of the range of the date as seen on the following example: GET /bko/transactions-stats?query={"created_at": {"$gt":"20121201000000", "$lt": "20121215235959""} The result is to give to you the access to the statistics of your subscriptions for the amount 10 resulted in 12/12/2012. In this last case four operators are available, to specify the role of a date in the filter: $gt means greater than Integration Guide 4.2.0 51 $gte means greater than or equals $lt means less than $lte means less than or equals Onebip Back-office API should only be used through an authentication. You can perform requests only following the HTTP Basic Authentication which consists in placing the "Authorization" HTTP Header in the HTTP Request with the value of the tring computed with the following formula: Base64("username:password") Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are not in HTTPS will result in a 400 Bad Request response. The following two complete examples, using curl, comprehends: curl -u "[email protected]:123456" 'https://www.onebip.com/bko/transactions-stats?query={"container":"subscription"}' curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY=" 'https://www.onebip.com/bko/transactions-stats?query={"container":"subscription"}' 4.3.2.1 Processing Back-office Transactions Stats API response The possible response from Onebip for a transaction statistics request are the following: 200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format 400 Bad Request The request is malformed and Onebip doesn't want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed filter 401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request. 403 Forbidden The merchant has not enough privileges to access the resource 404 Not Found Onebip is not able to find the resource requested from the merchant The following is a complete example of a 200 OK response: Status: 200 { "country":"IT", "ok":1234, "ko":690, "total":1924 } Integration Guide 4.2.0 52 4.3.3 Back-office Customer Base Status API Using Onebip Back-office Customer Base API, it is possible to retrieve information related to your subscription services which contains the active users and the subscription service events. Here is an example of a customer base status, for a given service: { "customer-base":307, "subscription-created":1254, "subscription-activation-requested":125, "subscription-activation-failed":8, "subscription-initialized":115, "subscription-activation-succeeded ":73, "subscription-terminated":18, "daily-churn-rate": { "value":0.0027, "symbol":"%" }, "date":"2013-01-14" } Where: customer-base: is the number of user in ACTIVE state for the given service subscription-created: number of users that visualized the purchase page subscription-initialized: events of initialization of the subscription, MSISDN given by the user subscription-activation-requested: event of opt-in request by the user subscription-activation-failed: number of transaction not completed after the opt-in process (i.e. not sufficient credit) subscription-activation-succeeded : subscription completed, after the opt-in process and the billing is succeeded, the number of the users in ACTIVE state at the end of the process subscription-terminated: unsubscription operation completed daily-churn-rate: calculated as subscription-terminated /customer-base To show the customer base status of a specific day you must perform a GET HTTP request towards the following url: https://www.onebip.com/bko/customer-base-status This HTTP route is the only point of access to gain information about the status of the customer base and you can retrieve it for a specific service on a specific date. In the following list the parameters available for the GET request. Onebip Back-office API for Customer Base Status supports the following fields for filtering: service_id: the service_id of the service on which retrieve the status date: the specific date on which retrieve the customer base status. This field is optional and if not supplied Onebip will use the current day as default The following example will give the complete idea of the operational behaviour. Integration Guide 4.2.0 53 The first one is to obtain the result for a given service on a given date: GET /bko/customer-base-status?service_id=50f3baacc1b659b91b000000&date=20130101 And the result will be the customer base status for the service with id 50f3baacc1b659b91b000000 at the day 01-012013. As already written in the lines above, you can submit a request without the date parameter: GET /bko/customer-base-status?service_id=50f3baacc1b659b91b000000 And in this case the result will be the customer base status for the service with id 50f3baacc1b659b91b000000 based on today's data. Onebip Back-office API should only be used through an authentication. You can perform requests only following the HTTP Basic Authentication which consists in placing the "Authorization" HTTP Header in the HTTP Request with the value of the trying computed with the following formula: Base64("username:password") Onebip Back-office API should only be used through requests performed in HTTPS. All the requests which are not in HTTPS will result in a 400 Bad Request response. The following two complete examples, using curl, comprehends: curl -u "[email protected]:123456" 'https://www.onebip.com/bko/customer-base-status?service_id=50f3baacc1b659b91b000000' with reply URL: curl -H "Authorization: Basic bWVyY2hhbnRAb25lYmlwLmNvbToxMjM0NTY=" 'https://www.onebip.com/bko/customer-base-status?service_id=50f3baacc1b659b91b000000' Integration Guide 4.2.0 54 4.3.3.1 Processing Back-office Customer Base Status API response The possible response from Onebip for a customer base status request are the following: 200 OK In this case the request has been satisfied by Onebip and the payload is in the body of the response in JSON format 400 Bad Request The request is malformed and Onebip doesn't want to satisfy it. Probably errors should be the use of HTTP instead of HTTPS, a malformed query string 401 Unauthorized The credentials supplied from the merchant are wrong or the merchant is not allowed to perform this request. 403 Forbidden The merchant has not enough privileges to access the resource. For example trying to access the customer base status of a service which is not owned by the merchant will result in a Forbidden request. The following is a complete example of a 200 OK response: Status: 200 { "customer-base":307, "subscription-created":1254, "subscription-activation-requested":125, "subscription-activation-failed":8, "subscription-initialized":115, "subscription-activation-succeeded ":73, "subscription-terminated":18, "daily-churn-rate": { "value":0.0027, "symbol":"%" }, "date":"2013-01-14" } URL URLs are sent to new line due to formatting needs. They should be on a single line when tried or implemented in production. Integration Guide 4.2.0 55 5 Versioning Onebip accepts a version parameter containing the API version for all the calls. This parameter can be specified by you to require the compatibility with a previously available service version. In case the specified version cannot be found, the latest available one will be served by Onebip. The root resource /api and /bko have each its own version, called API version and BKO version. These version numbers have no correlation to each other and can evolve independently. The current version numbers are exposed from API and BKO endpoints. A sample request is: curl -v http://www.dev.onebip.com/api/version And a sample response is: HTTP/1.1 200 OK Date: Tue, 05 Feb 2013 14:10:06 GMT Server: Apache/2.2.17 (Ubuntu) X-Powered-By: PHP/5.3.5-1ubuntu7.11 Content-Length: 16 Content-Type: application/json {"number":"1.0"} A specific version of the API can be required through an HTTP header: curl -v -H "X-Onebip-Version: 1.0" http://www.dev.onebip.com/api/ping or by using a prefix: curl -v http://www.dev.onebip.com/api/v1.0/ping In case the requested version is not supported (the number is not existent), the following response will be returned: curl -v -H "X-Onebip-Version: 1.1" http://www.dev.onebip.com/api/ping HTTP/1.1 412 Precondition Failed Date: Tue, 05 Feb 2013 14:12:00 GMT Server: Apache/2.2.17 (Ubuntu) X-Powered-By: PHP/5.3.5-1ubuntu7.11 Content-Length: 99 Content-Type: application/json {"error":"The api version 1.1 is not supported.","message":"The api version 1.1 is not supported."} Integration Guide 4.2.0 56 6 Skinnability Onebip Skinability feature will allow you to customize the look and feel of the Onebip payment pages and to use your personalized layout and the graphics for their different products, services both for one-time and subscription payments in any country. To start using your customized payment pages with the use of a proper "skin" you should communicate with Onebip business team assigned to you in Onebip who will check and confirm the skin in terms of codes of conduct published by mobile network carriers before launching your services7. The application of a given skin which is previously uploaded on the server will be made by you enriching your purchase page request, both with GET and POST methods, with an optional parameter: "skin={skin-name}" The following example URL, made with a HTTP GET request, a Onebip payment button will be created to propose 1000 game credits for $ 0,99 in United States, using a page customized with the skin named "colourful". http://www.onebip.com/api/purchases?command=express_pay&[email protected] &description=1000+game+credits&price=99&country=US¤cy=USD &skin=colorful&return_url=http://www.webgame.com/thankyou.htm ¬ify_url=http://www.webgame.com/notify.php If the skin requested is not applicable (i.e. skin with the name specified is not exist, or you are not using Skinability feature) the payment page will be shown without any customization, in its standard Onebip payment page format and a specific feedback will be given to you, using a comment inside the html code of the page displayed, in which a self-explaining note about the error will be given. A skin is an aggregate, that may be composed by: One or more CSS file One or more JavaScript file One or more images file that may be used or mentioned by the JavaScript files, with the relative inclusion path (ex. file /fancy.css may use the image file /img/beautiful.png with relative path "img/beautiful.png") The following example represents the content of a zip file for Skinability in which there are default files and custom files specific only for feature phone (without JavaScript file not supported), smartphone and desktop: 7To 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. Integration Guide 4.2.0 57 As a result the set for a smartphone in this example will be composed by: common.css + custom-3.css (loaded in this order), common.js + custom-3.js (loaded in this order), logo_company.jpg, logocustom-31.jpg. A skin may also specify the customization that must be applied according to the agent type used by your customer to access the payment page for the payment. The three supported agent type are: desktop: every kind of device that uses a desktop browser smartphone: mobile device with O.S Android or IOS (including iPad also) featurephone: all the other mobile device (including Nokia Lumia, an BB10) If the skin contains a file such as {PATH}/smartphone/smart.css, this file will be included in the payment page only if the agent used by your customer is identified as a smartphone. Integration Guide 4.2.0 58 6.1 Skin Creation API You can create more than one skin for one of your products, services. Every skin must have a univocal name, to be specified in the request. In the case that the name of the skin is the same with a skin already exist, the content will be overwritten. To complete a skin creation operation, you must perform a PUT HTTP request towards the following url: https://www.onebip.com/bko/skins/{skin-name} This HTTP route is the only point of access to make this operation. Authentication will be mandatory, with a standard authorization: Basic {base64({username}:{password})}. The skin package will be always a file with content type equals to zip. In the following example a new skin called "colorful" is enabled, by uploading the "skin_colorful.zip" file on local file system. curl -X PUT -v -u [email protected]:secret_password https://www.onebip.com/bko/skins/colorful --data @skin_colorful.zip-H "content_type:application/zip" 6.1.1 Processing skin creation API response The possible response from Onebip for the request for creating a skin will be the following: 200 OK The skin has been successfully created. With empty json. 400 Bad Request Not valid skin. With the error explanation contained in the json attached. 403 Forbidden The merchant is not enabled to use Skinability feature. With empty json. 6.2 Skin Cancellation API You have the possibility to cancel a skin already applied using a Sin cancellation API. Please note that the files related to the skin cancelled will be definitively deleted the roll back will be possible. The same skin can be created again only with a skin creation operation explained. To complete a skin cancellation operation, you must perform a DELETE HTTP request towards the following url: https://www.onebip.com/bko/skins/{skin-name} This HTTP route is the only point of access to make this operation. Authentication will be mandatory, with a standard authorization: Basic {base64({username}:{password})}. In the following example the skin called "colorful" is disabled from local file system: curl -X DELETE -v -u [email protected]:secret_passwordhttps://www.onebip.com/bko/skins/colorful 6.2.1 Processing skin cancellation API response The possible response from Onebip for the request of the cancellation of a skin will be the following: 200 OK The skin has been successfully created. With empty json. 403 Forbidden The merchant is not enabled to use Skinability feature. With empty json. Integration Guide 4.2.0 59 7 Authentication as a service Onebip's authentication aas feature will allow you to implement subscription payments for your services without being required to manage the customer base and the authentication of the subscribers. To start using Onebip's authentication aas feature you should communicate with Onebip business team assigned to you who will agree and confirm the service use before launching your services. This solution is constituted by a powerful interface that allow you to give Onebip the management of all the operations for the registration and authentication of your subscribers. The goal of this service is to make you be in charge only the content delivery for your subscription services, without handling the database of your subscribers, the authentication and the control about payments and subscription state. The following image summarizes a generic service using Onebip authentication as a service. The requirement is that "content pages" (ex: image galleries, video streaming, downloadable files) can be reached only by users subscribed to a service, with a payment completed successfully. Integration Guide 4.2.0 60 Pay or play API is called for a given service_id, that has been configured for you and is live in production. Pay_or_play box, is correspondent to a given URL and is a service that will try to authenticate the subscriber. Two different modules are provided inside it, to be used with this sequence, aiming at recognizing automatically the subscriber's MSISDN: authenticate via MSISDN recognition8 if not authenticated then authenticate via cookie9 If the MSISDN is recognized the subscriber is authenticated by Onebip. In this case subscriber is redirected to a further control, to verify if he is currently subscribed to your service in question; in case of positive check he's redirected to the service content without any further operation or confirmation by completing the happy path. If the user is not authenticated, it means that the MSISDN is not recognized. A subsequent control verifies that for this process, according to the request structure set, if the before_pay_url is defined in order Onebip to decide where to redirect the user's before the payment page. The "before_pay_url" page is proprietary and totally defined by merchant, should contain (apart service description, explanations, creativity) a button to let users complete the subscription to the service with Onebip. If the user choose to go on, he is redirected to Onebip subscription page where he will complete the payment process. If the payment is completed successfully the user becomes a subscriber to your service, and is redirected to the page where the content is delivered. It's important to underline that the whole logic within this page is built by merchant. The same path, through before_pay, which is optional, and through the payment page is the one provided to the user authenticated not currently subscribed, as shown in the image. Another opportunity given by Authentication as a Service is "before_walkin_url". This page, again, is optional, and is completely managed by merchant. Its use is alternative to the one of "before_pay_url" indicated in particular for Server to server integration. The main difference is in fact due to the http parameters passed with the redirection, as shown in the following chapter. 8 Please note that MSISDN recognition is available in the countries where mobile network operators permit this process and MSISDN of the subscriber is automatically given. 9 Cookie feature, then, is based on a cookie written inside subscriber's device, that means that if the user tries to login with a different device cannot be successful Integration Guide 4.2.0 61 7.1 Constructing an authentication aas request The request to enable Authentication as a service process is a GET HTTP request towards the following url: http://www.onebip.com/api/pay-or-play-for/service/{SERVICE_ID}?{PAY_OR_PLAY_PARAMETERS} where {SERVICE_ID} is the specific service_id associated to each of your subscription-based service and communicated to you by Onebip business team {PAY_OR_PLAY_PARAMETERS} before_payment_url ({URL}, optional) where to redirect the user if the user is authenticated and not subscribed or if not authenticated before_walkin_url ({URL}, optional) where to redirect the user if not authenticated only_silent_authentications ({0 or 1}, optional, default=1) eventually use (value=1) or not (value=0) an opt-in to authenticate the user SUBSCRIPTION_PARAMETERS service_id ({ALPHA}, not required, if used must be identical to ) command (express_pay, mandatory) item_code return_url (mandatory) notify_url cancel_url remote_txid lang custom signature (-STRING-, mandatory) The subscription parameters are evidently the same used for a standard request for a subscription-based payment and follow the rules given in chapter 3.2.1, where the "service_id" is not mandatory since it is already presented as the main parameter of the call as . For the security reason "signature" will be always mandatory. Onebip provides a signature encryption based on hashing, that has the following form: signature: hash_hmac('sha256', $url, $key) Integration Guide 4.2.0 62 This feature requires a secret "key" value (API Key) that you can set under the "My Account" section on Onebip Panel, and obviously the complete "URL" of the request. In the following example a merchant set its API key on the Onebip Panel and completed a request to pay-or-play-for API, with the following data: $url = http://www.onebip.com/api/pay-or-playfor/service/w33b2d48dederc07d328a11a?before_payment_url=http%3A%2F%2Fwww.w webgame.com%2Fbppage&only_silent_authentications=0&return_url=http%3A%2F% 2Fwww.webgame.com%2Fgameaccess3&command=express_pay&lang=en $key = 'MySecretKey123456' Please note that the signature must be appended as last parameter of the GET. Note also that all the parameters values must be encoded and the alphabetic characters after % must always be uppercase (ex: / is encoded in %2F and not %2f). The result of hashing is the following: $signature = (hash_hmac("sha256", $url, $key, true)); Expected signature:59d818a6bd236c74939428b07daf5805d599fbcb39cf1ab008b3833d380e6a82 The following final example is a complete GET request, created for a service realized for a specific merchant's service where: service_id= w33b2d48dederc07d328a11a before_payment_url= http://www.webgame.com/bppage (where the user is sent to pay for the service) return_url= http://www.webgame.com/gameaccess3 (where the service is provided) The complete request will be like in the following URL GET http://www.onebip.com/api/pay-or-play-for /service/w33b2d48dederc07d328a11a?before_payment_url=http%3A%2F%2Fwww.webgame.com%2Fbppage &only_silent_authentications=0&return_url=http%3A%2F%2Fwww.webgame.com %2Fgameaccess3&command=express_pay&lang=en &signature=59d818a6bd236c74939428b07daf5805d599fbcb39cf1ab008b3833d380e6a82 Integration Guide 4.2.0 63 7.2 Processing Authentication aas response The response to the Authentication aas request is always a redirection (HTTP 302: Found), in which the landing URL is dependent on the rules explained above. The possible response from Onebip can be formalized like in the following example, where only the redirection URL changes, accordingly to the dynamics of the process already described: 302 Found Location: {BEFORE_PAYMENT_URL}?{RETURN_URL_PAY_OR_PLAY_PARAMETERS} Where {BEFORE_PAYMENT_URL} is the before_payment_ur configured in the pay_or_play_for request. This redirection is completed if the user is not authenticated or not subscribed. 302: Found Location: {BEFORE_WALKIN_URL>?{BEFORE_WALKIN_PARAMETERS} Where {BEFORE_WALKIN_URL} is the optional url configured in the request. This redirection is completed only for users not authenticated and with "before_walkin_url" parameter configured. Where {BEFORE_WALKIN_PARAMETERS} comprehend: container_url =complete url to be used for walkin, containing the subscription_id (ex:https://www.onebip.com/api/subscription/50bdb06721bc882152000002/walkin) container_token=the security token to be used for authentication in walkin phase (ex:f9f2bb837298fcc61f4f40fd33158afc; path=/api/; expires=Wed, 04-Dec-2013 08:12:23 UTC) 302: Found Location: {PAYMENT_FAILED_URL}?{RETURN_URL_PAY_OR_PLAY_PARAMETERS} Where {PAYMENT_FAILED_URL} is the return_url. The redirection is in this case completed with a 'why' parameter that will pilot the behavior of the landing page (that is the same used for contents provisioning). The possible values for "why" are: service-id-conflict = service_id inside {PAY_OR_PLAY_PARAMETERS} is different than {SERVICE_ID} invalid-request-signature = request signature not valid invalid-request-service = the service_id given do not exist service-not-available = corresponding to a html 503 error, caused by internal error 302: Found Integration Guide 4.2.0 64 Location: {CONTENT_URL}?{RETURN_URL_PAY_OR_PLAY_PARAMETERS} Where {CONTENT_URL} is the return_url configured in the request. This redirection is completed only for users authenticated and subscribed to the service. Where {RETURN_URL_PAY_OR_PLAY_PARAMETERS} comprehend: whois = MSISDN_URN_ENCRYPTED is_subscribed_to = list of services (filtered by current merchant) to which the user is subscribed to has_paid_for = list of services (filtered by current merchant) to which the user has paid for timestamp = current timestamp signature = signature given in the request SUBSCRIPTION_RETURN_PARAMETERS URL URLs are sent to new line due to formatting needs. They should be on a single line when tried or implemented in production. Integration Guide 4.2.0 65 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 Integration Guide 4.2.0 66
© Copyright 2025