WIN Payforit API

WIN Payforit API

WIN ppt black img

WIN PayforIT API

Version 2.0

Issued: 1st September 2008


Table of Contents

1Introduction

1.1Purpose of document

1.2Getting Started

1.3WIN PFI API overview

2Technical Integration

2.1Basic Principles

2.1.1Synchronous and Asynchronous

2.1.2Products

2.1.3Billing and Subscriptions

2.2Checkout API

2.2.1Query String Definition

2.2.2Constructing Your Query String

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

2.2.3Embedding Your Links

2.2.4API Response

2.2.5Single Billing Payment Statuses

2.2.6Re-occurring Billing Payment Statuses

2.3Notification API

2.3.1Parameters

2.3.2Status Codes

2.3.3Server Response

2.4Subscriber STOP API

2.4.1Parameters

2.4.2Calling the API

2.4.3Server Response

2.5Product Configuration API

2.5.1Create Product Parameters

2.5.2Update Product Parameters

2.5.3Calling the API

2.5.4Server Response

2.6Personalise API

2.6.1Personalise Parameters

2.6.2Constructing Your Query String

2.6.3Finished URL

2.6.4API Response

2.7Marketing API

2.7.1Send Message Parameters

2.7.2Calling the API

2.7.3Server Response

3Appendices

3.1Appendix 1 – MD5

3.1.1Basic process

3.1.2Code Examples

3.2Appendix 2 – Price Points

3.3Appendix 3 – Period Intervals

3.4Appendix 4 – Status Values

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.

  • 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.

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.

1 Introduction

1.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.

1.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

1.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

2 Technical Integration

2.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.

2.1.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.
  1. 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.1.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.

2.1.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.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) :

String}

Where {Query String} is defined below.

2.2.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 when your account is created. / No / mid=42
pid / Product ID. This an integer value that relates to a Payforit product that you have configured in the Management portal or using the configuration API. / Yes
[Note]
If this parameter is not supplied then you must supply the mref parameter. / pid=1568
mref / Merchant Reference. This is a string value up to 32 characters long. This value needs to be configured on the Payforit Management portal when you set up a product or using the configuration API.
[Note] as this parameter is a string it should be URL encoded before being added to the query string. / Yes
[Note]
If this parameter is not supplied you must supply the pid parameter. / mref=abc123
msref / Merchant Sub Reference. This is a string value up to 32 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. / Yes / msref=games_new_2
mtid / Merchant Transaction ID. This is a string value up to 32 characters long.
This field contains your own system reference for the transaction or order and will be passed back to you when the results are given.
[Note] as this parameter is a string it should be URL encoded before being added to the query string
. / Yes
[Note]
If this parameter is not passed then it will not be passed back to you on the result query string. / mtid=tran123
rurl / Response URL. This is a string field up to 255 characters long. This parameter is used to enable you to specify a URL that will be called to pass the user 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. / Yes / rurl=http%3A%2F%2Ftesturl%2Ecom%2Ftest%2Easp%3F
hash / MD5 Hash Key. This is an MD5 Hash Key for security purposes. There are instructions in Appendix 1 on the creation of this key. / No / hash= 1a7081daee63614d5d349838762a5c27

2.2.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:

2.2.3 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.

2.2.4 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 the transaction that has just been processed. / No / tid=10536
mtid / This is your merchant transaction id as specified in your request. If you did not specify it, it will not be returned. This is a string value up to 32 characters long. / Yes / mtid=123abc
msisdn / The mobile number of the user that accessed the 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. / Yes
[Note]
This parameter will only be populated if the user has given their permission. / msisdn=447712300123
status / Transaction Status. This is an integer value that give the status of the request. For the specific status values please refer to the tables below. / No / status=3
subid / Subscription ID. This is an integer value giving you the subscription ID of a user that has just subscribed to your specified product. / Yes.
[Note]
This parameter will be provided if the product is a subscription product. / subid=666387
time / Time Stamp. This is a string value that indicates the GMT time that this transaction occurred. The format for the timestamp is”yyyymmddhhnnss”. / No / time=20070501174523
hash / MD5 Hash Key. This is an MD5 Hash Key for security purposes. There are instructions in Appendix 1 on the creation of this key. / No / hash= 1a7081daee63614d5d349838762a5c27

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

2.2.5 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.

2.2.6 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.

2.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:

2.3.1 Parameters

Parameter / Description / Optional / Example
mid / Merchant ID. This is an integer value supplied to you when your account is created. / No / mid=42
subid / Subscription ID. This is an integer value giving you the subscription ID of a user that has just subscribed to your specified product. / No / subid=666387
status / Status is an integer value that gives the current status of the subscription. The possible status values are listed in the below table. / No / status=1
time / Time Stamp. This is a string value that indicates the GMT time that this status change occurred. The format for the timestamp is ”yyyymmddhhnnss”. / No / time=20070501174523
hash / MD5 Hash Key. This is an MD5 Hash Key for security purposes. There are instructions in Appendix 1 on the creation of this key. / No / hash= 1a7081daee63614d5d349838762a5c27

2.3.2 Status Codes

Status / Description
1 / User has subscribed
2 / User has unsubscribed
3 / User Subscription billing has failed

2.3.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:

2.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.

2.4.1 Parameters

Parameter / Description / Optional / Example
mid / Merchant ID. This is an integer value supplied to you when your account is created. / No / mid=42
subid / Subscription ID. This is an integer value that you would have been given when the specific user subscribed. / No / subid=666387
hash / MD5 Hash Key. This is an MD5 Hash Key for security purposes. There are instructions in Appendix 1 on the creation of this key. / No / hash= 1a7081daee63614d5d349838762a5c27

2.4.2 Calling the API