Project Name:



WIN PayforIT API

Version 2.0

Issued: 1st September 2008

Table of Contents

1 Introduction 7

1.1 Purpose of document 7

1.2 Getting Started 7

1.3 WIN PFI API overview 7

2 Technical Integration 8

2.1 Basic Principles 8

2.1.1 Synchronous and Asynchronous 8

2.1.2 Products 8

2.1.3 Billing and Subscriptions 9

2.2 Checkout API 10

2.2.1 Query String Definition 10

2.2.2 Constructing Your Query String 11

You can test your URL creation and MD5 Hash by entering your completed URL into which will check to see if it is valid. 11

Completed URL 12

2.2.3 Embedding Your Links 12

2.2.4 API Response 12

2.2.5 Single Billing Payment Statuses 13

2.2.6 Re-occurring Billing Payment Statuses 13

2.3 Notification API 14

2.3.1 Parameters 14

2.3.2 Status Codes 14

2.3.3 Server Response 14

2.4 Subscriber STOP API 15

2.4.1 Parameters 15

2.4.2 Calling the API 15

2.4.3 Server Response 15

2.5 Product Configuration API 16

2.5.1 Create Product Parameters 16

2.5.2 Update Product Parameters 18

2.5.3 Calling the API 19

2.5.4 Server Response 19

2.6 Personalise API 20

2.6.1 Personalise Parameters 20

2.6.2 Constructing Your Query String 20

2.6.3 Finished URL 20

2.6.4 API Response 21

2.7 Marketing API 22

2.7.1 Send Message Parameters 22

2.7.2 Calling the API 22

2.7.3 Server Response 22

3 Appendices 23

3.1 Appendix 1 – MD5 23

3.1.1 Basic process 23

3.1.2 Code Examples 23

3.2 Appendix 2 – Price Points 26

3.3 Appendix 3 – Period Intervals 26

3.4 Appendix 4 – Status Values 26

Document Revision History

|Date |Issue |Authors |Comments/Reasons For Change |

| 01/05/2007 |1.0.1 |M. Stanton |Initial Draft |

| 12/05/2007 |1.0.2 |M. Stanton |Final Draft |

| 21/05/2007 |1.0.3 |M. Stanton |Release Draft |

| 22/05/2007 |1.04 |S. Howton |Release Final |

| 07/05/2008 |1.05 |D. Slater |Product Configuration API |

| 27/05/2008 |1.06 |D. Slater |Marketing API |

| 22/08/2008 |2.00 |M. Stanton |Update to version 2.0 of PFI framework |

What’s new in Version 2.0 ?

There are a number of changes in version 2.0 of the payforIT framework. Many of these changes do not change the core functionality of this API, but do offer a better user experience and greater commercial opportunities and branding. The primary changes are listed below, but please refer the PFI framework documentation for full detail:

• The ability to configure your own banners at the top of the PFI pages. This is achieved through your account via the WIN PFI console , enabling you to configure a banner for each one of your sites (this functionality is not available on O2).

• Branded operator logo’s. From version 2.0 the original PFI logo is replaced with a network specific logo to re-enforce the PFI brand, and to try and improve user perception of PFI.

[pic]

• Marketing opt in checkbox is now pre – ticked for all network operators, giving improved user uptake for marketing.

• Terms and conditions have been moved to a new page, reducing the amount of clutter on the page.

• You can configure on a per domain basis whether or not you want WIN to display the payment confirmation page, or whether you want to do this in your site. This reduces the number of pages to display to the user, and gives a more integrated feel.

• More flexibility in subscription models that can be configured, plus retry strategies for increased billing success rates.

• New extended reporting to give clearer management information.

[pic]

Changes to the API’s

The following items are all additions to the existing WIN PFI Gateway, and therefore if you do not wish to implement these extra features, and you are already using a previous version, you need not make any changes.:

• Personalisation API. This extension allows WIN to pass your systems a unique reference for a given browsing user so that you can personalise the experience that you provide to them.

• SMS Marketing API. Enables you to send a free to user text message to a user that has used your services, based on their unique reference.

• Product configuration API. Enables you to configure the WIN PFI Gateway products programmatically so that you can integrate this feature into your own systems.

Introduction

1 Purpose of document

This document has been drafted to assist you to integrate with the Wireless Information Network Limited (WIN) Payforit API. The API is based on a simple HTTP GET request.

There are a range of methods available, and these are laid out over the following pages.

2 Getting Started

Before you can integrate with the API you will require a WIN Payforit account, which provides account details and access to the WIN Payforit management tool, and which can be accessed at . To get your PFI account, please complete the form at the end of this document and give to your account manager.

The WIN PFI API implements the Paryforit scheme framework, in order to understand this framework fully and to make sure your site is compliant with the framework, please take time to read through the Payforit scheme, the latest copy of which you can download at .

3 WIN PFI API overview

Payforit is a WAP billing system, enabling you to bill your customers for one off transactions and create subscriptions from within a WAP session. For this to take place all transactions for the WIN Payforit gateway need to be processed through the WIN primary gateway URL, as it is this action that gives the gateway the required information to identify and bill a user.

This API has been produced to give you a simple and efficient interface into the WIN Payforit gateway with the minimum of development.

For billing within the Payfoit framework there are two forms, direct and Premium SMS (PSMS). Currently the following UK network operators work as listed bellow.

|Network Operator |Premium SMS |Direct Billing |

|Vodafone |No |Yes |

|Orange |Yes (as a backup method) |Yes |

|O2 |Yes |No |

|TMobile |Yes |No |

|Virgin |Yes |No |

|Three |Yes (as a backup method) |Yes |

Technical Integration

1 Basic Principles

The WIN Payforit gateway enables the ability to detect the end users mobile number from a WAP session that is directed to it’s URL. Based on the options you specify in the management portal, either bill an amount or create a subscription to bill at a re-occurring frequency until the end user stops the service.

In order for this to happen the end user must be re-directed to the WIN PFI Gateway (“”). To simplify the API this URL has been extended, and all of the information required to complete the transaction is passed in this URL. The user is then lead through the Payforit framework, and at the end, the gateway will return the user to a URL that you have defined, along with the result of the transaction. Your systems then simply need to take the appropriate action to process the result, whether this is successful billing, pending billing or failed billing.

1 Synchronous and Asynchronous

There are two types of transaction process that may occur:

1. Synchronous – the transaction is completed in full in real time, and therefore the result that you get is the final result. This would be the case for example with Vodafone transactions as this is a synchronous direct billing transaction.

2. Asynchronous – the transaction is two part, therefore the result you initially receive is a status of pending, and at a later point in time you will receive a final status. This is typical of SMS and applies wherever the network operator is using SMS billing as opposed to direct billing.

2 Products

Within the context of the PFI a product is not an individual item, but a classification. The classification is comprised of a minimum of:

• Content type (eg. Video, wallpaper)

• Billing type (eg. Single bill or subscription)

• Billing amount (e.g. £3.00)

• Billing Frequency (e.g. Weekly, if the product is a subscription)

• Adult rating (eg. Is the product classified as 18+ or not)

You need to set up one product for each of the above classifications that you wish to operate, and it is this productID that you pass in the API request to specify the model that you wish to use. So for example if you have a ringtone club that has a subscription of £3.00 per week, then you may create a product called “Ringtone_£3.00_Weekly_non_adult” and set the appropriate flags in the management portal to create the product. Alternatively you can use the Configuration API to create products programmatically.

3 Billing and Subscriptions

There are two types of billing that can be initiated through the API, single and re-occurring (otherwise known as a subscription). The type is defined in the product definition (as previously discussed).

For single billing you simply pass the request to the API and wait for a response as the user is directed back to your site. For subscriptions this is also the case, however as billing will continue beyond the initial transaction you will receive notifications, via the notification API, to give you the billing and subscription status of the user. There is also a pull version of the status API where you can look up this status.

The amount that you can bill in each instance is technically any amount between 1p and £5, however as some of the networks are using premium SMS the actual available price points are more restricted. See Appendix 2 for a list.

2 Checkout API

This section of the API combines both the ability to initiate a purchase charge to a user for content, and initiate a subscription for a user. In order to access the API you simply have to place the following link into your WAP page(s) :

?{Query String}

Where {Query String} is defined below.

1 Query String Definition

The query string for this call is made up of the following parameters:

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you |No |mid=42 |

| |when your account is created. | | |

|pid |Product ID. This an integer value that relates to a |Yes |pid=1568 |

| |Payforit product that you have configured in the |[Note] | |

| |Management portal or using the configuration API. |If this parameter is not supplied | |

| | |then you must supply the mref | |

| | |parameter. | |

|mref |Merchant Reference. This is a string value up to 32 |Yes |mref=abc123 |

| |characters long. This value needs to be configured on |[Note] | |

| |the Payforit Management portal when you set up a |If this parameter is not supplied you| |

| |product or using the configuration API. |must supply the pid parameter. | |

| |[Note] as this parameter is a string it should be URL | | |

| |encoded before being added to the query string. | | |

|msref |Merchant Sub Reference. This is a string value up to 32|Yes |msref=games_new_2 |

| |characters long. This parameter can be used for | | |

| |reporting purposes. | | |

| |[Note] as this parameter is a string it should be URL | | |

| |encoded before being added to the query string. | | |

|mtid |Merchant Transaction ID. This is a string value up to |Yes |mtid=tran123 |

| |32 characters long. |[Note] | |

| |This field contains your own system reference for the |If this parameter is not passed then | |

| |transaction or order and will be passed back to you |it will not be passed back to you on | |

| |when the results are given. |the result query string. | |

| |[Note] as this parameter is a string it should be URL | | |

| |encoded before being added to the query string | | |

| | | | |

| |. | | |

|rurl |Response URL. This is a string field up to 255 |Yes |rurl=http%3A%2F%2Ftest|

| |characters long. This parameter is used to enable you | |url%2Ecom%2Ftest%2Easp|

| |to specify a URL that will be called to pass the user | |%3F |

| |back to your site with the status of the Payforit | | |

| |transaction. If this parameter is not specified then | | |

| |the default URL’s you have specified on your account | | |

| |will be used. | | |

| |[Note] You must not have a query string in this URL but| | |

| |you may include the “?” symbol at the end of the URL. | | |

| |[Note] as this parameter is a string it should be URL | | |

| |encoded before being added to the query string. | | |

|hash |MD5 Hash Key. This is an MD5 Hash Key for security |No |hash= |

| |purposes. There are instructions in Appendix 1 on the | |1a7081daee63614d5d3498|

| |creation of this key. | |38762a5c27 |

2 Constructing Your Query String

Given the above parameters you simply need to construct your query string. By placing an ampersand (&) between each name=value pair. So for example:

mid=42&pid=1568&hash=b188ab42af61bb3d4787c19428d7a7c3

Note

If you do not wish to use one of the optional parameters, please make sure that you do not put it in the query string with a blank value.

e.g.

mid=42&pid=1568&mtid=&hash=b188ab42af61bb3d4787c19428d7a7c3 [INCORRECT]

mid=42&pid=1568&hash=b188ab42af61bb3d4787c19428d7a7c3 [CORRECT]

You can test your URL creation and MD5 Hash by entering your completed URL into which will check to see if it is valid.

Completed URL

Once you have constructed the query string you simply need to append it to the base URL to form the completed link for your WAP page. So given the above example you will achieve the following link:



5 Embedding Your Links

As you do not need to create a session or use any other transaction to use the API, and also as the API will only process the links that a user click’s on, there is no reason why you should not generate the API link’s throughout your site. This keeps the navigation consistent for the user and simplifies the implementation.

6 API Response

Once the Payforit transaction has been processed on the WIN Payforit Gateway, then the user will be passed back to your systems via the URL that you either specified on your request, or that you set up against your account. When the response is passed to you the API adds several parameters to the query string so that you can get the result of the transaction. It is important that you do not use any of the below parameters in the URL that you specify for the return path.

|Parameter |Description |Optional |Example |

|tid |Transaction ID. This is an integer value representing |No |tid=10536 |

| |the transaction that has just been processed. | | |

|mtid |This is your merchant transaction id as specified in |Yes |mtid=123abc |

| |your request. If you did not specify it, it will not be| | |

| |returned. This is a string value up to 32 characters | | |

| |long. | | |

|msisdn |The mobile number of the user that accessed the |Yes |msisdn=447712300123 |

| |transaction. Depending on you account setup this will | | |

| |either be the plain text value of the mobile number |[Note] | |

| |which is 12 characters long. Or it will be a key value |This parameter will only be populated| |

| |that represents this mobile number which can be up to |if the user has given their | |

| |75 characters long. |permission. | |

|status |Transaction Status. This is an integer value that give |No |status=3 |

| |the status of the request. For the specific status | | |

| |values please refer to the tables below. | | |

|subid |Subscription ID. This is an integer value giving you |Yes. |subid=666387 |

| |the subscription ID of a user that has just subscribed | | |

| |to your specified product. |[Note] | |

| | |This parameter will be provided if | |

| | |the product is a subscription | |

| | |product. | |

|time |Time Stamp. This is a string value that indicates the |No |time=20070501174523 |

| |GMT time that this transaction occurred. The format for| | |

| |the timestamp is”yyyymmddhhnnss”. | | |

|hash |MD5 Hash Key. This is an MD5 Hash Key for security |No |hash= |

| |purposes. There are instructions in Appendix 1 on the | |1a7081daee63614d5d3498|

| |creation of this key. | |38762a5c27 |

Note

If the msisdn parameter is passed as a key value instead of the plain text it would look like this:

e587c99f22be-62603fb14eee-1754a906812b-0f620c4f589a-9c4e0c39647b-13b0

7 Single Billing Payment Statuses

|Status |Final |Description |Example |

|1 |Yes |Transaction processed successfully. | |

|2 |Yes |Transaction processed unsuccessfully. |Insufficient Credit |

|3 |Yes |Transaction has failed. |Incorrect parameters passed to Payforit Platform. |

|4 |No |Transaction is pending a result. |Billing is being performed by SMS billing and |

| | | |payforit platform is awaiting a receipt. |

8 Re-occurring Billing Payment Statuses

|Status |Final |Description |Example |

|5 |Yes |Transaction processed successfully. | |

|6 |Yes |Transaction processed unsuccessfully. |Insufficient Credit |

|7 |Yes |Transaction has failed. |Incorrect parameters passed to Payforit Platform. |

|8 |Yes |Transaction processed successfully but the user is already| |

| | |subscribed to this product. | |

|9 |No |Transaction is pending a result. |Billing is being performed by SMS billing and |

| | | |Payforit platform is awaiting a receipt. |

3 Notification API

The Notification API is used to notify your systems of a change of subscription status for a given subscriber. It comprises of an HTTP GET with a query string. The URL that is used needs to be specified when you set up your account, and the parameters for the Query string are listed below:

1 Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you |No |mid=42 |

| |when your account is created. | | |

|subid |Subscription ID. This is an integer value giving you |No |subid=666387 |

| |the subscription ID of a user that has just subscribed | | |

| |to your specified product. | | |

|status |Status is an integer value that gives the current |No |status=1 |

| |status of the subscription. The possible status values | | |

| |are listed in the below table. | | |

|time |Time Stamp. This is a string value that indicates the |No |time=20070501174523 |

| |GMT time that this status change occurred. The format | | |

| |for the timestamp is ”yyyymmddhhnnss”. | | |

|hash |MD5 Hash Key. This is an MD5 Hash Key for security |No |hash= 1a7081daee63614d5d349838762a5c27|

| |purposes. There are instructions in Appendix 1 on the | | |

| |creation of this key. | | |

2 Status Codes

|Status |Description |

|1 |User has subscribed |

|2 |User has unsubscribed |

|3 |User Subscription billing has failed |

3 Server Response

Your server should respond with a HTTP 200 status to let the notification API know that you have received the notification. If your server does not give an HTTP status 200 then the system will retry three times. If your response body contains “STOP=123” (this enables you to unsubscribe the user if the billing has failed) where “123” is the subscription ID, this subscription will be terminated.

An example of the notification given the above values would be:



4 Subscriber STOP API

This API allows your systems to stop a user’s subscription, this can be built into your own customer services or be called when you receive a subscription notification telling that the billing has failed.

1 Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you |No |mid=42 |

| |when your account is created. | | |

|subid |Subscription ID. This is an integer value that you |No |subid=666387 |

| |would have been given when the specific user | | |

| |subscribed. | | |

|hash |MD5 Hash Key. This is an MD5 Hash Key for security |No |hash= 1a7081daee63614d5d349838762a5c27|

| |purposes. There are instructions in Appendix 1 on the | | |

| |creation of this key. | | |

2 Calling the API

Once you have created your query string simply perform an HTTP GET with the following URL:

3ceedca4efa48f185493e505460edd10

3 Server Response

The WIN Payforit gateway will respond with an HTTP 200 and in the response text the Subscription ID of the subscriber that you requested to be stopped.

5 Product Configuration API

This API allows your system to create and update Payforit products without having to use the WIN customer portal.

1 Create Product Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you|No |mid=42 |

| |when your account is created. | | |

|key |MD5 Key. This is the MD5 key provided when your |No |key=securepassword |

| |account id created | | |

|sname |Short Name. This is a string value up to 40 |No |sname=wallpaper |

| |characters long. This is the short name for the | | |

| |product displayed on the checkout pages. [Note] as | | |

| |this parameter is a string it should be URL encoded | | |

| |before being added to the query string. | | |

|mref |Merchant Reference. This is a string value up to 32 |Yes |mref=abc123 |

| |characters long. And represents your reference for | | |

| |this product. [Note] as this parameter is a string it| | |

| |should be URL encoded before being added to the query| | |

| |string. | | |

|lname |Long Name. This is a string value up to 64 characters|No |lname=cat%20wallpaper |

| |long. This is the product full name. [Note] as this | | |

| |parameter is a string it should be URL encoded before| | |

| |being added to the query string. | | |

|desc |Description. This is a string value up to 1024 |No |lname=cat wallpaper |

| |characters long. This is the description of the | | |

| |product. [Note] as this parameter is a string it | | |

| |should be URL encoded before being added to the query| | |

| |string. | | |

|priceid |Price Point ID. This is an integer value. See |No |priceid=1 |

| |appendix 2 for values | | |

|termsid |Terms & Conditions ID. This is an integer value. |Yes – If not |termsid=10 |

| |This parameter can be used if you have pre configured|provided terms | |

| |terms & conditions in your payforit account. |parameter must be | |

| | |used | |

|terms |Terms & Conditions. This is a string value up to 64 |Yes – If not |terms=terms and conditions |

| |characters long. If supplied this parameter will |provided termsid | |

| |create a new set of terms & conditions in your |parameter must be | |

| |payforit account [Note] as this parameter is a string|used | |

| |it should be URL encoded before being added to the | | |

| |query string. | | |

|deferredperiod |Deferred Billing Period. This is a string value in |Yes |deferredperiod=012h |

| |the format xxxInterval, where xxx = amount, e.g 001d | | |

| |= 1 day. See appendix 3 for available Intervals | | |

|billingfrequency |Subscription Billing Frequency. This is a string |Yes |billingfrequency=001w |

| |value in the format xxxInterval, where xxx = amount, | | |

| |e.g 001d = 1 day. See appendix 3 for available | | |

| |Intervals | | |

|iterations |Max Billing Iterations. This is an integer value. If|Yes |Iterations=10 |

| |supplied this is the total amount of billing | | |

| |iterations that will take place before the customer | | |

| |is unsubscribed | | |

|statusid |Status ID. This is an integer value. This is the |No |statusid=1 |

| |current status of the item. See appendix 4 for | | |

| |available values. | | |

2 Update Product Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you|No |mid=42 |

| |when your account is created. | | |

|key |MD5 Key. This is the MD5 key provided when your |No |key=securepassword |

| |account id created | | |

|pid |Product ID. This an integer value that relates to a |No |pid=1568 |

| |Payforit product that you have configured via the api| | |

| |or in the Management portal | | |

|mref |Merchant Reference. This is a string value up to 32 |Yes |mref=abc123 |

| |characters long. And represents your reference for | | |

| |this product. [Note] as this parameter is a string it| | |

| |should be URL encoded before being added to the query| | |

| |string. | | |

|sname |Short Name. This is a string value up to 40 |Yes |sname=wallpaper |

| |characters long. This is the short name for the | | |

| |product displayed on the checkout pages. [Note] as | | |

| |this parameter is a string it should be URL encoded | | |

| |before being added to the query string. | | |

|lname |Long Name. This is a string value up to 64 characters|Yes |lname=cat%20wallpaper |

| |long. This is the product full name. [Note] as this | | |

| |parameter is a string it should be URL encoded before| | |

| |being added to the query string. | | |

|desc |Description. This is a string value up to 1024 |Yes |lname=cat wallpaper |

| |characters long. This is the description of the | | |

| |product. [Note] as this parameter is a string it | | |

| |should be URL encoded before being added to the query| | |

| |string. | | |

|priceid |Price Point ID. This is an integer value. See |Yes – See value is |priceid=1 |

| |appendix 2 for values |only available for | |

| | |non subscription | |

| | |products | |

|termsid |Terms & Conditions ID. This is an integer value. This|Yes |termsid=10 |

| |parameter can be used if you have pre configured | | |

| |terms & conditions in your Management Portal. | | |

|terms |Terms & Conditions. This is a string value up to 64 |Yes |terms=terms and conditions |

| |characters long. If supplied this parameter will | | |

| |create a new set of terms & conditions in your | | |

| |payforit account. [Note] as this parameter is a | | |

| |string it should be URL encoded before being added to| | |

| |the query string. | | |

|deferredperiod |Deferred Billing Period. This is a string value in |Yes |deferredperiod=012h |

| |the format xxxInterval, where xxx = amount, e.g 001d | | |

| |= 1 day. See appendix 3 for available Intervals | | |

|statusid |Status ID. This is an integer value. This is the |Yes |statusid=1 |

| |current status of the item. See appendix 4 for | | |

| |available values. | | |

3 Calling the API

Once you have created your request, you need to perform a HTTP POST to the following URL:

Create Product:



Update Product:



4 Server Response

The WIN Payforit API will respond with an HTTP 200 and in the response text the Product ID. If an error has occurred the response will take the following format.

ERROR: [Error Description]

6 Personalise API

This API enables you to gain a unique reference for a user, and also gives you the users originating network, enabling you to customise the user experience based on the network.

It can also be used to customise the user experience for this user, or can be used in conjunction with the Marketing API to send a free to user SMS to the user.

1 Personalise Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you |No |mid=42 |

| |when your account is created. | | |

|pid |Product ID. This is not used for this call but is |No |pid=0 |

| |required, you can use the default value zero. | | |

|rurl |Response URL. This is a string field up to 255 |No |rurl=http%3A%2F%2Ftest|

| |characters long. This parameter is used to enable you | |url%2Ecom%2Ftest%2Easp|

| |to specify a URL that will be called to pass the user | |%3F |

| |back to your site with the lookup results. | | |

| |[Note] You must not have a query string in this URL. | | |

|hash |MD5 Hash. For security. There are instructions in |No |hash= |

| |Appendix 1 for the creation of this key. | |1a7081daee63614d5d3498|

| | | |38762a5c27 |

3 Constructing Your Query String

Given the above parameters you simply need to construct your query string. By placing an ampersand (&) between each name=value pair. So for example:

mid=42&pid=1568&rurl=http%3A%2F%2Ftesturl%2Ecom%2Ftest%2Easp%3F&hash=84c243ddc494603b71b361ac44d06934

[Note] For this example the security key for the md5 hash was “secretpassword”.

4 Finished URL

Once you have constructed the query string you only need to append it to the base URL, preceded with a question mark (?) to form the completed link for your WAP page. So given the above example you will achieve the following link:



5 API Response

Once the User Lookup has been processed, the user will be passed back to your systems via the URL you specified in your request. When the response is returned the API adds several parameters to the query string so that you can determine the results of the lookup.

|Parameter |Description |Optional |Example |

|msisdn |The mobile number of the user that accessed the |No |msisdn=447712300123 |

| |transaction. Depending | | |

| |on you account setup this will either be | | |

| |the plain text value of the mobile | | |

| |number which is 12 characters long. Or | | |

| |it will be a key value that represents this | | |

| |mobile number which can be up to 75 | | |

| |characters long. | | |

|network |The network id of the user that accessed the |No |network=1 |

| |transaction. | | |

| |1 – Vodafone | | |

| |2 – Orange | | |

| |3 – T-Mobile | | |

| |4 – Three | | |

| |5 – O2 | | |

|hash |MD5 Hash. For security. There are instructions in |No |hash= |

| |Appendix 1 for the creation of this key. | |1a7081daee63614d5d3498|

| | | |38762a5c27 |

7 Marketing API

This API allows your system to send promotional messages to existing customers that have opted in.

1 Send Message Parameters

|Parameter |Description |Optional |Example |

|mid |Merchant ID. This is an integer value supplied to you|No |mid=42 |

| |when your account is created. | | |

|key |MD5 Key. This is the MD5 key provided when your |No |key=securepassword |

| |account id created | | |

|subid |Subscription ID. This is the id returned to you when |Yes – If not |subid=100 |

| |a subscription is processed |supplied, msisdn | |

| | |needs to be | |

| | |supplied. | |

|sourceaddr |This is the source address that the SMS will appear | | |

| |to come from, when presented to the user. | | |

|msisdn |MSISDN or Encrypted MSISDN. This is a string value up|Yes – If not |msisdn= |

| |to 64 characters long. This is the customers MSISDN |supplied, subid |b8O8srfBgkUq3JuBf65JTzYAuc8FRT8s |

| |or Encrypted MSISDN value. |needs to be | |

| | |supplied. | |

|message |Message. This is a string value up to 160 characters |No |message=[FreeMsg] This is a message |

| |long. This is the message to send to the customer. | | |

2 Calling the API

Once you have created your request, you need to perform a HTTP POST to the following URL:



3 Server Response

The WIN Payforit API will respond with an HTTP 200 and in the response text the Message ID of the message that has been sent. If an error has occurred the response will take the following format.

ERROR: [Error Description]

Appendices

1 Appendix 1 – MD5

The MD5 digest is used in the API as your authorisation for the transaction to go ahead. The transaction will fail if this hash value is not correct, so it is important to make sure that it is implemented in all cases. Below are a list of examples from different code environments that demonstrate how to implement the MD5 checksum in your code.

1 Basic process

The MD5 hash that is put at the end of the string is a security measure that proves that the request has been generated by your system. Most programming languages support MD5, which is used to create a check sum that is very difficult to decrypt. The method used in the API is as follows:

1) Take the completed query string prior to the hash parameter being added and non-url encoded.

e.g. mid=42&pid=1568&mtid=tran123

2) Concatenate onto this the secret security password that you have been given for your Payforit API account.

e.g. mid=42&pid=1568&mtid=tran123secretpassword

3) Perform an MD5 of the complete string.

e.g. md5(“mid=42&pid=1568&mtid=tran123secretpassword”)

The result from this will be the hash value that you need to put on the end of the query string. Given the above example the result will be: “b188ab42af61bb3d4787c19428d7a7c3”.

Once you have the hash value this can then be added to the query string giving the final query string of:

“mid=42&pid=1568&mtid=tran123&hash=b188ab42af61bb3d4787c19428d7a7c3”

2 Code Examples

If you have any difficulty with these examples or if you are using a code environment that has no example, then please contact your account manager to arrange assistance.

Note:

These examples are given to aid your implantation, and are not suggested implantations for the API.

MySQL Example:

select md5('mid=42&pid=1568&mtid=tran123secretpassword') as hash;

returns:

+--------------------------------+

|hash |

+--------------------------------+

|b188ab42af61bb3d4787c19428d7a7c3|

+--------------------------------+

Java Script Example:

  hash = hex_md5("mid=42&pid=1568&mtid=tran123secretpassword");

Note.

This code utilizes the MD5.js file, the source of which can be found in the documentation section of the Management portal. This code is provided with no warranty as it is an open source example.

C# Example

using System;

using System.Text;

using System.Security.Cryptography;

...

public string MD5(string originalString)

{

  //Declarations

  Byte[] originalBytes;

  Byte[] encodedBytes;

  MD5 md5;

  //Instantiate MD5CryptoServiceProvider, get bytes for original string and compute hash (encoded string)

  md5 = new MD5CryptoServiceProvider();

  originalBytes = ASCIIEncoding.Default.GetBytes(originalString);

  encodedBytes = puteHash(originalBytes);

  //Convert encoded bytes back to a 'readable' string

  return BitConverter.ToString(encodedBytes);

}

PHP Example

Available in versions (PHP 4, PHP 5, PECL hash:1.1-1.3)

Description

string md5 ( string $str [, bool $raw_output] )

Calculates the MD5 hash of str using the » RSA Data Security, Inc. MD5 Message-Digest Algorithm, and returns that hash. The hash is a 32-character hexadecimal number. If the optional raw_output is set to TRUE, then the md5 digest is instead returned in raw binary format with a length of 16.

Note

The optional raw_output parameter was added in PHP 5.0.0 and defaults to FALSE

ASP Example

Note

For this example to work you will need to download MD5.asp which includes the function for the MD5 Hash. This code is provided with no warranty as it is an open source example.

2 Appendix 2 – Price Points

|Current Price Points Cross UK Network |Price ID |

|PFI 25p |4 |

|PFI 50p |2 |

|PFI 100p |3 |

|PFI 150p |1 |

|PFI 200p |5 |

|PFI 250p |6 |

|PFI 300p |7 |

|PFI 500p |8 |

3 Appendix 3 – Period Intervals

|Interval |Description |

|D |Day(s) |

|H |Hour(s) |

|W |Week(s) |

|M |Month(s) |

4 Appendix 4 – Status Values

|Status ID |Description |

|1 |Inserted |

|2 |Active |

|3 |Suspended |

|4 |Barred |

|5 |Deleted |

|Merchant Name: | |

|Project No. | |

|WIN Dist ID: | |

|Document Version: |1.0 |

|Author: | |

| |

|WIN PayforIT |

|Merchant Configuration Form |

| |

| |

| |

| |

| |

|Issued: 1st September 2008 |

Please complete this form in order to open you WIN PFI Merchant account. Items marked with (**) are optional fields. As a merchant you need to fill in the fields marked in Blue, the fields marked Red will be filled in by a WIN operator and returned to you once your account has been set up.

1. Contact Details

1.1 Merchant Details:

|DISTID: (**) |If you have an existing WIN DISTID please insert this here. |

|Short Name: |Merchant Name (short version) |

|Long Name: |Merchant Name (long version) |

|Address: | |

| | |

| | |

| | |

| | |

| | |

1.2 Technical Contact Details:

|Contact: |Technical Contact Name |

|Landline: |Technical Contact Landline |

|Mobile: |Technical Contact Mobile |

|Email: |Technical Contact Email |

1.3 Customer Service Details:

|Help Url: |The URL on your WAP site giving user help and information. |

|Helpline No: |This needs to be a local rate UK number. E.g. 0845 |

|Help Email: |Email address for Customer Support |

2. Portal

2.1 Login Details:

|Password Domain: |This is the username format to be used on the portal eg |

| |admin@ or admin@.co.uk |

|Admin Username: |What the user name should be (generally should be same as first part |

| |of password domain eg admin) |

|Admin Password: |What the password should be |

3. Platform

3.1 Callbacks:

The following optional URL’s, and only need to be filled out if you do not intend to use the rurl parameter in the API.

The Notification URL need’s to be filled in if you are running subscription services and wish to receive status information on your subscribers.

|Success URL: (**) | |

|Failed URL: (**) | |

|Pending URL: (**) | |

|Notification URL: | |

|MD5 Key: |Security key (secret password) – Generated By WIN |

|MSISDN Passthrough: |Yes / No – Should the MSISDN be passed to Merchant? |

3.2 WIN Gateway:

|Dist ID: |To be completed by WIN |

|Username: |To be completed by WIN |

|Password: |To be completed by WIN |

3.2 Domain Management:

|Type: |None / Strict / Unapproved Allowed / Record & Reject |

|Domains: |This section refers to whether the merchant requires WIN to ensure that the requests|

| |coming in are coming from the domains which are registered or not. |

| | |

| |None – request can come from any domain and is not recorded. |

| | |

| |Strict - request must come from registered domain eg ‘’ |

| | |

| |Unapproved allowed – unauthorised domains are allowed but attempts are recorded for |

| |later analysis if required |

| | |

| |Record & reject – unauthorised domains are not allowed but attempts are recorded for|

| |later analysis if required |

| | |

| |If specific domains are to be allowed then they must be listed in this section. |

3.3 Products:

|Use Merchant Product Ref: |Yes / No Do you want to use the mref (your product reference) or pid (the |

| |WIN product reference? |

-----------------------

( Wireless Information Network Ltd.

The information contained herein is the property of Wireless Information Network Ltd,

and may not be copied, used or disclosed in whole or in part, except with the prior

written permission of Wireless Information Network ltd.

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download