Bango Relay service

Control content access and payment in real-time

Integration Guide

Doc version 5.3

Page 1 of 20

Contents
Contents Before we begin Bango Relay what does it do? Bango Relay how does it work? User IDs Some parameters only available in selected packages Using Bango Analytics with Relay How to
Pass data Pass multiple data parameters Check a transaction ID Customise the payment flow Set prices dynamically Set the exact price in different currencies Set timed access or multiple access for my content Pre-fill phone number/email field on register/sign-in page Keep track of my customers Find out how customers are connecting to my site Ensure only paying customers access my content (standard) Ensure only paying customers access my content (advanced)

2 3 3 4 5 5 5 6
6 7 8 8 9 10 11 12 13 14 15 16

Need more help? Appendix

18 19

Doc version 5.3

Page 2 of 20

Before we begin
The Relay service is enabled and configured via the Management Tools on Bango.com. Relay is only available on higher Bango packages. To see if Relay functionality is supported in your Bango package log into your package and check the Package Information page, under the Account tab. If you are in any doubt or would like to upgrade your Bango package to include Relay then please contact support@bango.com. You can assign Relay functionality to any of your Content link Bango Numbers. The number of Relay functions available to you is determined by: The number available as part of your package Any additional Relay functions you have purchased through the Management Tools

You can reassign your Relay functions to different Bango Numbers as and when you wish. Simply remove Relay functionality from one Bango Number and you will have it available to assign to another. This can be done in the Properties section of your Management Tools or in the Content settings screen for each of your Bango Numbers.

Bango Relay what does it do?

With Relay you can: Set prices and currencies dynamically Use just one Bango Number to charge for multiple items of content Find out a customers User ID in real time to track repeat users Protect against fraud by using security tokens Find out the exact amount you will earn for a transaction in real-time Have the customers mobile network and region returned to you in real-time Have the customers current connection network and region returned to you in real-time Customise the payment flow dynamically

You can use these features to improve the service you offer your customers. For example, to tailor your pricing depending upon the customer's currency, or recognise repeat customers in your system.

Doc version 5.3

Page 3 of 20

Bango Relay how does it work?

Relay is based on in-putting and out-putting parameters. You send us extra information when you pass a user to Bango, and we send you extra parameters when we return them to your site. You can use these extra parameters for a variety of payment, access and configuration purposes. To begin you need to enable the Relay feature on one of your Bango Numbers in your Management Tools. You then pass the user to that Bango Number, using a URL like this (where 123456 is your Relay enabled Bango Number):

http://bango.net/go/?bango=123456

We will then pass the user back to a URL that you specify, perhaps a script on your server, along with all the extra parameters. There is a table in the Appendix below which shows all the parameters that you can expect to see on a Relay enabled URL. The parameters p, u, c, t and b are passed back to you automatically by Bango. Any others must be specified by you at the end of your input URL string or enabled in your Bango Management Tools. So the output URL from Bango containing just these parameters would look similar to the one shown below:

http://www.yoursite.mobi/yourscript.asp?p=0&u=0&t=0&c=0&b=123456
Here, the parameters are all set to the value 0 and the ampersand (&) delimits or separates each parameter.

Doc version 5.3

Page 4 of 20

User IDs
Every end user that interacts with the Bango system is given their own unique User ID so we can keep track of them. In most cases we are able to automatically identify each user or they provide us with manual sign-in credentials so we can give them a standard persistent User ID. If we cannot automatically identify a user and they dont provide sign-in credentials they will be given a Tracking User ID. Tracking User IDs can be useful but are not guaranteed to remain persistent over multiple browser sessions. Therefore the Relay will not output tracking IDs by default, instead they will be replaced with 0. To receive Tracking User IDs in the Relay output they must be enabled in the Properties section of the Bango Management tools. To enable them you need to activate Send tracking User IDs which is found in the Real-time outputs section.

Some parameters only available in selected packages

If you do not see a parameter that you are expecting, remember that certain parameters are only available in some levels of Bango package. Also some parameters need to be switched on before they will be passed back to you. For example, x (transaction ID) and e (amount earned) parameters need to be enabled by you before they will be returned. Log in to the Management Tools on Bango.com and then go to the Properties tab for your package. Scroll to the Real-time outputs section to see each parameter and then click Edit to enable these parameters. Remember that these additional parameters are only available for specific package types, so contact Bango Customer Services if your package does not support them.

Using Bango Analytics with Relay

You can add various analytics parameters to your Relay-enabled URL so that you can get valuable information about customer visiting and paying for content on your site. Simply use Bango Analytics Campaign Parameters (http://bango.custhelp.com/app/answers/detail/a_id/1189) as additional parameters on your URLs to generate this information. Have a look at the Analytics Reports tab in the Management tools for specific Campaign Parameter reports.

Doc version 5.3

Page 5 of 20

How to
Pass data
Description: You may want to make data that exists in one page available to another page, such as before and after the payment process. This data can be passed through Bango as a parameter in a URL query string. The data can be any information that you wish to send through with the referring or input URL. The information you pass through could be: A session id 654321 A log of where a customer has gone within the site ringtones_popmusic_kylie A wallpaper or ringtone Kylie5

Or, in fact, any other information that you want to know after the customer has been charged.

Inputs: p The data you want to pass http://bango.net/go/?bango=123456&p=kylie5 Outputs: p The data you passed http://www.yoursite.mobi/yourscript.asp?p=kylie5&b=123456 Notes:

Top Tip!
Please note that there is a URL size limit of 255 characters with some older phones. The p parameter is only passed back to you if you send one to Bango. If there is no p parameter in your input URL then there wont be one in your output URL.

Doc version 5.3

Page 6 of 20

Pass multiple data parameters

Description: You may want to pass more than one piece of information through Bango at a time, for example a session ID and a content title. Only one p parameter can be passed through the Bango Service, using standard web practice you can batch or concatenate multiple data parameters into the single parameter p. For example, if you wanted to send the data parameters: Product=kylie5 SessionID=65321

You could concatenate them into a single string: Product=kylie42&SessionID=65321 (parameters are delimited with &) and then URL encode it to send it through as p=product%3Dkylie42%26SessionID%3D65321 When it is sent back to your site, your server can decode the parameter, reinstate the session and deliver the appropriate content. Inputs: p The data you want to pass http://bango.net/go/?bango=123456&p=product%3Dkylie5%26SessionID%3D65321 Outputs: p The data you passed

http://www.yoursite.mobi/yourscript.asp?p=product%3Dkylie5%26SessionID%3D65321&b= 123456 Notes:

Top Tip!
More information on URL encoding can be found at http://www.blooberry.com/indexdot/html/topics/urlencoding.htm

Doc version 5.3

Page 7 of 20

Check a transaction ID
Description: Relay allows the output of a Transaction ID using the x parameter. Each unique transaction is captured and associated with a Transaction ID, making this feature particularly useful for financial reporting or audit logs. Remember that these additional parameters are only available for specific package types, so contact support@bango.com if your package does not support them. The x parameter must be enabled in your Bango Management Tools as outlined above. Once enabled you will receive the parameter appended to your URL Inputs: Outputs: http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=0&t=0&c=0&x=98765&b=123456 Notes: None, enable the x parameter in your Management Tools, under the properties tab.

Customise the payment flow

Description: You can use Relay to dynamically customise the payment pages Bango presents to your customers. You can change the page title and content title that are displayed to the users on the Bango payment pages at the time of payment. The parameter pt sets the page title and the parameter ct sets the content title. Inputs: pt ct

Sets page title Sets content title http://bango.net/go/?bango=123456&p=kylie5&pt=Kylie&ct=Kylie_ringtone

Outputs:

None

Notes:

The pt and ct parameters are NOT passed back to you

Doc version 5.3

Page 8 of 20

Set prices dynamically

Description: Use Relay to dynamically set the price of your content. Using one Relay enabled Bango Number you can: Charge different prices with one Bango Number Each piece of content can have a different price You can set a price of 1 pence/cent to test the service without changing the price for customers

For example, you may have set a default price for a Bango Number in your Management Tools of $1. Using Relay you can override this and charge a different amount. This is done using the c parameter in the URL string. The value of the c parameter will be in the lowest denominator for your package currency (e.g. $2 would be passed as c=200). Inputs:

The amount you want to charge for the content. This will default to the currency your Bango package was created with. E.g. c=200 would be 2, $2, or 2. If the c parameter is sent to Bango without a value (c=) then your default amount for that Bango Number will be charged. http://bango.net/go/?bango=123456&p=kylie5&c=200

Outputs: c The amount charged http://www.yoursite.mobi/yourscript.asp?p=kylie5&c=200&u=0&t=0&b=123456 c=-1 Your default price can only be overridden in the range 0-1000. So you could charge 0-1000 US cents, UK pence or Euro cents. If a figure outside of this range is sent through, the Bango system will ignore it and charge your default price for that Bango Number. The parameter c will be sent through to you with the value 1 to indicate this error: c=-1 If a customer has paid for multiple accesses, then you will receive the c=-2 parameter on a subsequent visit as they have already paid.

c=-2

Notes:

Doc version 5.3

Page 9 of 20

Set the exact price in different currencies

Description: In a standard Bango package your prices are all set in your default currency (this is the one you are paid in, specified when you opened the account). If a customer using a different currency purchases your content, Bango will convert the amount you have set into the customers currency. So if the customer is not using the same currency as you, the amount they pay will fluctuate slightly depending upon exchange rates. If you have one of the higher Bango packages you can offer your customers fixed prices in their own currency. This is done using parameters based on the customers currency. For example, to charge a UK customer 1.50 exactly and a US customer exactly $3, you would pass cgbp=150 and cusd=300. The value of the cxxx parameter will always be in the lowest denominator for your package currency (e.g. $3 would be passed as cusd=300). Inputs: cgbp cusd ceur The price you want to charge in that currency.

http://bango.net/go/?bango=123456&p=kylie5&cgbp=150&cusd=300 Outputs: cgbp cusd ceur The price charged in that currency

The output URL will only contain the currency parameter relevant to the customers local or preferred currency. This shows the customer paid in US dollars: http://www.yoursite.mobi/yourscript.asp?p=kylie5&cusd=300&b=123456 Notes: Please see our knowledgebase for details on the supported currencies and maximum price points. http://bango.custhelp.com/app/answers/detail/a_id/571

Doc version 5.3

Page 10 of 20

Set timed access or multiple access for my content

Description: If you set up a Relay-enabled number with multiple or timed access, you can dynamically change the length of time or number of visits a customer can make to your content. This is done using the ta and na parameters. For example, you may have a Bango Number set up to charge a customer 100p for 1 access. Using the na parameter you can dynamically change the number of accesses you offer a customer. Changing a timed access Bango Number works in a similar fashion but this time using the parameter ta. If the Bango Number 123456 was now set to charge the customer 100p for 5 minutes you can use ta to change the time period.

Inputs:

na ta

The number of times your content can be accessed http://bango.net/go/?bango=123456&p=kylie5&c=200&na=3 The length of time your content is available for http://bango.net/go/?bango=123456&p=kylie5&c=200&ta=60

Outputs: na The number of times your content can be accessed http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&na=3&b=123456 c=-2 na=-2 If a customer has paid for multiple accesses, then you will receive the c=-2 parameter on a subsequent visit as they have already paid. The na=-2 parameter also indicates that this is was a subsequent access

http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&c=-2&na=-2&b=123456 ta The length of time your content is available for http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&ta=60&b=123456 Notes:

Top Tip!
If you have the Bango Number set up to charge per hour, or per day etc, changing the ta parameter will always change the length of time in that time period.

Limitations
ta and na will only be passed back to you if you send them to Bango. If a ta or na parameter is passed to Bango and the Number is NOT set up for either timed or multiple access, the parameter will be ignored. The value of these parameters in the output URL will then be -3. There is a maximum limit of 999 for the value of na and of 525600 (365 days) for the value of ta. Any invalid values will be ignored and the default settings for the Bango number will be used. In this case a value of -1 will be sent back in the output URL.

Doc version 5.3

Page 11 of 20

Pre-fill phone number/email field on register/sign-in page

Description: Where a user cant automatically be identified (e.g. they are a first-time user connected via Wi-Fi; or are using an AT&T iPhone gateway where real-time identity isnt supplied by AT&T), a simple manual sign-in or registration page is presented to the user. If you have access to a mobile number or email address for this user, you can pass this value to the Bango Identitifier via the register parameter. When set to a mobile number or email address, the value is automatically pre-filled into the sign-in form Bango presents to a manual identification user. Inputs:

register=1555123456

If Bango needs to ask the user to sign in, pre-fill the phone number field with 1555123456

http://bango.net/go/?bango=123456&register=1555123456

register=someone@s omewhere.com

If Bango needs to ask the user to sign in, pre-fill the email field with someone@somewhere.com

http://bango.net/go/?bango=123456&register=someone@somewhere.com

Doc version 5.3

Page 12 of 20

Keep track of my customers

Description: You can use Relay to identify an individual customer. This allows you to: Keep track of repeat purchases are customers coming back to make repeat purchases or are most sales one offs? Tally up customer queries, for example, a customer may say they bought X and Y, you can see if this matches your records.

Bango can identify each customer from information sent through from the gateways and the Mobile Operators. Each individual customer has a User ID created for them when they first access the Bango Service. Bango can pass this ID to you when using the Bango Relay service. Bango will NOT pass you the customers mobile telephone number. A u parameter is sent through to you when a customer accesses a Relay-enabled number

Inputs: Outputs:

None u Your customers User ID http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&c=150&b=123456

Notes:

Just pass the customer through to your Relay-enabled Bango Number in the usual way http://bango.net/go/?bango=123456&p=kylie42

Doc version 5.3

Page 13 of 20

Find out how customers are connecting to my site

Description: You can use Relay to identify a customers operator network and region, and also the network and region of their current connection. For example, if a customer connects through WiFi we can still identify them and continue to pass on their operator details as well as the details of their WiFi connection. Inputs: Outputs: n r cn cr Your customers operator network (identity network) Your customers operator region (identity region) using the 3 digit ISO country code Your customers current network (connection network) Your customers current region (connection region) using the 3 digit ISO country code http://www.yoursite.mobi/yourscript.asp?p=kylie5&n=USA_ATT &cn=GBR_BTBROADBAND&r=USA&cr=GBR&b=123456 Notes: Just pass the customer through to your Relay-enabled Bango Number in the usual way http://bango.net/go/?bango=123456&p=kylie5 None

Doc version 5.3

Page 14 of 20

Ensure only paying customers access my content (standard)

Description: Security tokens are the best way for you to make sure only paying customers access your content. When a customer purchases your content, a one-time token is sent to you from Bango. It certifies that the customer has gone through the Bango system and paid to access the content. The token is a unique combination of numbers and letters that is created by Bango on the successful completion of a customer purchase. All you have to do is check that you havent seen this token before then you can let the customer access the content. Inputs: None Outputs:

The unique security token for that transaction

The output URL will only contain the currency parameter relevant to the customers local or preferred currency. This shows the customer paid in US dollars: http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&c=150&t=07BF116742F440CA 961D11473FDB81FB Notes: Just pass the customer through to your Relay-enabled Bango Number in the usual way http://bango.net/go/?bango=123456&p=kylie5

Top Tip!
You can test for the format of the token as well. If the token doesnt conform to the following format, then you can reject the customer. A token from Bango will be 32-digits, alpha numeric and in the range A-F and 0-9. All letters will be in CAPITALS

Doc version 5.3

Page 15 of 20

Ensure only paying customers access my content (advanced)

Description: The advanced token checker allows you to verify that the parameters you receive are the ones that Bango issued after the relay payment. Along with the parameters that Bango passes through a t parameter will be passed. This is the token. http://www.yoursite.mobi/yourscript.asp?p=kylie5&u=12345678&c=150&t=07BF116742F440CA 961D11473FDB81FB You can use this token to validate that other parameters that you have received are the ones that Bango issued by making a server-to-server web request to:

http://xml.bango.net/tokenCheck.aspx
If the token and parameters match, Bango will send back XML with response attribute of true, if not Bango will send XML with response attribute of false. Once validated, a token is automatically expired. This means sending the same request to Bango again (using the same token) will result in a false response. For an extra level of security, each token expires 5 minutes from the time that it was created by Bango. Any validation request must be performed within the 5-minute expiry time otherwise a false response will be returned. If the response is false then one or more failed reasons will be added to the response node of the returned XML document. Each failed reason will be in a node called failedReason. Inputs:

Send a http request to Bango in the following format, where t is the security token you want to check and u is the customers User ID and bango is the Bango number. Mandatory inputs: http://xml.bango.net/tokencheck.aspx?t=07BF116742F440CA961D11473FDB81FB &u=12345678&bango=35513354 t u bango The token that Bango supplied The user ID The Bango number

Optional inputs: http://xml.bango.net/tokencheck.aspx?t=07BF116742F440CA961D11473FDB81FB &u=12345678&bango=35513354&c=100&na=5 c na ta The price parameter. This could also be a currency specific price such as cusd or cgbp The number of accesses Time allowed

Doc version 5.3

Page 16 of 20

Outputs: Bango sends a simple XML response back either: <?xml version="1.0" ?> <response success="true"> <n>GBR_ORANGE</n> </response> Or <?xml version="1.0" ?> <response success="false" > <failedReason>INVALID_BANGONUMBER</failedReason> <failedReason>INVALID_PRICE</failedReason> </response> There may be one or more failed reasons. Failed reasons: INVALID_TOKEN INVALID_USERID INVALID_BANGONUMBER INVALID_CURRENCY Token has expired or doesnt exist The user ID supplied doesnt match the user ID associated with the token The Bango number supplied doesnt Bango number associated with the token The price parameter currency supplied doesnt match the price parameter currency associated with the token. The price parameter value doesnt match the price parameter value associated with the token The number of accesses supplied doesnt match the number of access associated with the token The time allowed supplied doesnt match the time allowed associated with the token

INVALID_PRICE INVALID_NUMBEROFACCESSES INVALID_TIMEALLOWED

Doc version 5.3

Page 17 of 20

Need more help?

http://forums.bango.com Ask questions and discuss your ideas with the mobile community on the Bango Forums http://bangoserviceblog.wordpress.com Keep up-to-date with the latest service announcements, releases and advice on the Bango Blog http://bango.custhelp.com Get an instant answer from the Bango Knowledgebase

Doc version 5.3

Page 18 of 20

Appendix
Relay parameters Parameter p c cgbp Input or output Both Both Both Description The data passed Price charged Price charged in a currency Number of accesses Timed access Bango number Page title Comments Can be used to pass custom parameters Cost of content Set an exact price in a particular currency. Can be used INSTEAD of c parameter Number of times your content can be accessed Length of time your content can be accessed Number for free or charged content Set the page title that is displayed to users on the Bango payment pages at the time of payment Set the content title that is displayed to users on the Bango payment pages at the time of payment Unique payment information. Must be enabled in Bango.com Amount earned from a transaction. Must be enabled in Bango.com The name of the customers mobile network operator. Enabled in Bango.com The location of the customers mobile network operator. Enabled in Bango.com This could differ from the identity network if connected via something other than the operator network. E.g. WiFi This could differ from the identity region if the customer is in another location. Unique customer identifier Helps prevent fraud

na

Both Both Both Input only

ta b pt

ct

Input only

Content title

x e

Output only Output only

Transaction ID Amount earned Customers identity network Customers identity region Current connection network Current connection region User ID Security token

Output only

Output only

cn

Output only

cr u t

Output only Output only Output only

Doc version 5.3

Page 19 of 20

na=-2, c=-2

Output only

User already paid

For multiple or timed access, indicates user has already paid for content Must be activated by Customer Services. Please email support@bango.com. If you have chosen to show the postpayment marketing opt-in page a value of y or n will indicate whether a user has opted in to your marketing messages

subid

Output only

Users subscription ID

optedin

Output only

Users marketing optin status

Payment hierarchy If you choose to pass currency and price parameters using Relay, there are five layers to be aware of in the hierarchy that will control the price your customer sees:

1 Your default package currency. The currency you are paid in, chosen by you when you setup your Bango account. 2 The default content price. The price you specified for a piece of content in your Bango Management Tools. 3 Additional currency prices. The exact price you specify for currencies other than your default package currency. These are set up on Bango.com. 4 Relay price parameter (c). For example, c=150. 5 Relay currency parameter (cusd, ceur, cgbp and so on for other currencies). For example cusd=150.

Customers will be charged in your default package currency (1) or equivalent, unless Additional currency prices are fixed (3).

If passing Relay parameters, the currency parameter (5) will always override other pricing options (1-4). This applies to all currencies if (5) matches the default currency (1) or just to the specified currencies if it doesnt match the default.

Doc version 5.3

Page 20 of 20