Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Content Zone
locationtop

Overview

Interactive login is to be used when the user is present to login (for example, 3rd Party Desktop Applications) and will manage any additional information required at login depending upon a customer's account (such as 2 Factor Authentication codes or National Identifiers). 

This is achieved by embedding the Betfair IdentitySSO login page in your application and then obtaining a successful session token upon login. The

...

Keep Alive operation should be called

...

within session expiry time if the user is still actively using your application.

...

Image Removed

You should be able to detect the presence of a session token in the requests upon successful login for use by your application.

Interface

Login

URL definition

International users:

 

https://identitysso.betfair.com/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

 

Spanish jurisdiction users:

 

https://identitysso.betfair.es/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

 

Italian jurisdiction users:

 

https://identitysso.betfair.it/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

 

...

NameDescriptionSample
product(mandatory)The product for which the login page is used and on which the user will do the login; This should be your application key."IhDSui3ODdsdwo"
url (mandatory)The url to which the the browser should be redirected in case of a successful login. 
By default, https://www.betfair.com will be allowed but further URLs can be added upon agreement with Betfair.
https://www.betfair.com

 

Keep Alive

URL Definition

https://identitysso.betfair.com/api/keepAlive

The presence of the "Accept: application/json" header will signal that the service should respond with JSON and not an HTML page

Headers

Name
Description
Sample
Accept (mandatory)header that signals that the response should be returned as JSONapplication/json
X-Authentication (mandatory)header that represents the session token that needs to be keep aliveSession Token
X-Application (optional)header the Application Key used by the customer to identify the product.App Key

Response structure

 

Code Block
{
  "token":"<token_passed_as_header>",
  "product":"product_passed_as_header",
  "status":"<status>",
  "error":"<error>"
}

...

 

SUCCESS
FAIL

 

Error values

INPUT_VALIDATION_ERROR
INTERNAL_ERROR
NO_SESSION

 

Call sample

 

Code Block
# full request
curl -k -i -H "Accept: application/json" -H "X-Application: AppKey" -H "X-Authentication: <token>" https://identitysso.betfair.com/api/keepAlive

 

Logout

URL Definition

https://identitysso.betfair.com/api/logout

The presence of the "Accept: application/json" header will signal that the service should respond with JSON and not an HTML page

Headers
Name
Description
Sample
Accept (mandatory)Header that signals that the response should be returned as JSONapplication/json
X-Authentication (mandatory)Header that represents the session token that needs to be keep aliveSession Token
X-Application (optional)Header the Application Key used by the customer to identify the product.App Key

 

Response structure

 

Code Block
{
  "token":"<token_passed_as_header>",
  "product":"product_passed_as_header",
  "status":"<status>",
  "error":"<error>"
}

 

Status values

 

SUCCESS
FAIL

 

Error values

 

INPUT_VALIDATION_ERROR
INTERNAL_ERROR
NO_SESSION

 

Call sample

...

 

...

 

Obtaining the sessionToken from the POST data

Once a login has been successfully made, the Javascript in the page will POST the session token (ssoid) to the URL provided as a redirect URL. For a desktop application, this is not required to be a real page as the desktop application can intercept the POST request as it happens via the embedded browser container. A Windows based application can embed a web browser into the application and use the BeforeNavigate2 event to catch the post data sent to the redirect URL and there are platform specific alternatives. The POST request body will contain two URL encoded parameters (which you will need to URL Decode):

  • ssoid - This is your session token and should be attached to requests made to API-NG in the X-Authentication header.  
  • errorCode - This is returned in a URL by Betfair and provides the reason for the login failure.

Info
This flow protects the implementing application from user login complexities, such as 2 factor auth, requiring national identifiers or jurisdictional migrations.

The Interactive Login is the same login flow used by the Betfair website and therefore, any message's will be returned directly by Betfair & handled in the same way.

errorCode
 Description
INVALID_USERNAME_OR_PASSWORD  the username or password are invalid
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED  The latest italian contract version must be accepted
KYC_SUSPEND  KYC suspended
NOT_AUTHORIZED_BY_REGULATOR_DK  the user identified by the given credentials is not authorized in the DK's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the DK's jurisdiction.
NOT_AUTHORIZED_BY_REGULATOR_IT  the user identified by the given credentials is not authorized in the IT's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the IT's jurisdiction.
MULTIPLE_USERS_WITH_SAME_CREDENTIAL There is more than one account with the same credential
PENDING_AUTH pending authentication
PERSONAL_MESSAGE_REQUIRED  personal message required for the user
SECURITY_QUESTION_WRONG_3X  the user has entered wrong the security question 3 times
SECURITY_RESTRICTED_LOCATION  the account is restricted due to security concerns
SELF_EXCLUDED  the account has been self excluded
SPAIN_MIGRATION_REQUIRED  spain migration required
SPANISH_TERMS_ACCEPTANCE_REQUIRED  The latest spanish terms and conditions version must be accepted
STRONG_AUTH_CODE_REQUIRED2 Step Authentication code is required. Please append this to your Betfair password.
SUSPENDED  the account is suspended
TELBET_TERMS_CONDITIONS_NA  Telbet terms and conditions rejected
TRADING_MASTER  Trading Master Account
TRADING_MASTER_SUSPENDED  Suspended Trading Master Account
TEMPORARY_BAN_TOO_MANY_REQUESTSThe limit for successful login requests per minute has been exceeded. New login attempts will be banned for 20 minutes
INVALID_USERNAME_OR_PASSWORD  the username or password are invalid
ACCOUNT_NOW_LOCKED  the account was just locked
ACCOUNT_ALREADY_LOCKED   the account is already locked
PENDING_AUTH  pending authentication
TELBET_TERMS_CONDITIONS_NA  Telbet terms and conditions rejected
DUPLICATE_CARDS  duplicate cards
SECURITY_QUESTION_WRONG_3X  the user has entered wrong the security answer 3 times
KYC_SUSPEND  KYC suspended
SUSPENDED  the account is suspended
CLOSED   the account is closed
SELF_EXCLUDED  the account has been self-excluded
INVALID_CONNECTIVITY_TO_REGULATOR_DK the DK regulator cannot be accessed due to some internal problems in the system behind or in at regulator; timeout cases included.
NOT_AUTHORIZED_BY_REGULATOR_DK  the user identified by the given credentials is not authorized in the DK's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the DK's jurisdiction.
INVALID_CONNECTIVITY_TO_REGULATOR_IT  the IT regulator cannot be accessed due to some internal problems in the system behind or in at regulator; timeout cases included.
NOT_AUTHORIZED_BY_REGULATOR_IT  the user identified by the given credentials is not authorized in the IT's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the IT's jurisdiction.
SECURITY_RESTRICTED_LOCATION  the account is restricted due to security concerns
BETTING_RESTRICTED_LOCATION  the account is accessed from a location where betting is restricted
TRADING_MASTER  Trading Master Account
TRADING_MASTER_SUSPENDED  Suspended Trading Master Account
AGENT_CLIENT_MASTER  Agent Client Master
AGENT_CLIENT_MASTER_SUSPENDED  Suspended Agent Client Master
DANISH_AUTHORIZATION_REQUIRED  Danish authorization required
SPAIN_MIGRATION_REQUIRED  Spain migration required
DENMARK_MIGRATION_REQUIRED  Denmark migration required
SPANISH_TERMS_ACCEPTANCE_REQUIRED  The latest Spanish terms and conditions version must be accepted. You must login to the website to accept the new conditions.
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED  The latest Italian contract version must be accepted. You must login to the website to accept the new conditions.
CERT_AUTH_REQUIRED  Certificate required or certificate present but could not authenticate with it
CHANGE_PASSWORD_REQUIRED  Change password required
PERSONAL_MESSAGE_REQUIRED  Personal message required for the user
INTERNATIONAL_TERMS_ACCEPTANCE_REQUIREDThe latest international terms and conditions must be accepted prior to logging in.
EMAIL_LOGIN_NOT_ALLOWED This account has not opted in to log in with the email
MULTIPLE_USERS_WITH_SAME_CREDENTIAL 

There is more than one account with the same credential

ACCOUNT_PENDING_PASSWORD_CHANGE The account must undergo password recovery to reactivate via https://identitysso.betfair.com/

...

 

Sample Code

A sample client, written in C#, is available to demonstrate this process on Github.  This is a C# project created under Visual Studio 2010, written against .Net 4, and is a Winforms Application.

The key steps demonstrated by this client are:

  • Embed identitysso.betfair.com into your application
  • Handle the login method and retrieval of a session token from the cookies
  • Handle the keep alive method
  • Handle the logout method

How it works

Upon start-up, the URL of the API login page is assigned to the web browser control:

Code Block
//Give embedded web browser Betfair api login page URL         

System.Uri u = new Uri(LogonURL);

When the web browser control receives data an event is triggered and the following function called: 

Code Block
private void webBrowser1_DocumentCompleted(object sender, WebBrowserDocumentCompletedEventArgs e)
{
            //On embeded web browser response get cookie
            string cookie = this.webBrowser1.Document.Cookie;

            if (cookie != null)
                this.ParseCookie(cookie);

            //If successfull login start KeepAlive 
            if (!m_LoggedOut && !m_KeepAliveTimer.Enabled)
            {
                webBrowser1.Visible = false;
                SetMessage("Logon successfull\r\n SSOID=" + m_SSOID);

                
                this.StartKeepAlive();
            }
}

Upon successful login the cookie is parsed for the SSOID. The webrowser control made invisible and the SSOID displayed in a TextBox. The keep-alive timer is started

Code Block
private void StartKeepAlive()
	{            
            m_KeepAliveTimer.Elapsed += new System.Timers.ElapsedEventHandler(OnKeepAliveTimer);
            // Set the Interval to 15 mins.
            m_KeepAliveTimer.Interval = 1000 * 60 * 15;
            m_KeepAliveTimer.Enabled = true;
        }

Above the StartKeepAlive function simply starts a 15 minute timer which invokes function OnKeepAliveTimer. 

OnKeepAliveTimer sends a Keep Alive message.

A message to this effect is then displayed.

Upon hitting the Logout button the following event handler is invoked:

Code Block
private void btnLogout_Click(object sender, EventArgs e)
        {
            m_KeepAliveTimer.Enabled = false;
            m_KeepAliveTimer.Close();
            m_LoggedOut = true;

            System.Uri u = new Uri(LogoutURL);
            this.webBrowser1.Url = u;
            this.webBrowser1.Navigate(u);

            SetMessage("Logged out");

        }

 

The keep alive timer is closed. The logout url is sent and a Logged out message is displayed.

...

view/recoverpassword
TEMPORARY_BAN_TOO_MANY_REQUESTSThe limit for successful login requests per minute has been exceeded. New login attempts will be banned for 20 minutes
ITALIAN_PROFILING_ACCEPTANCE_REQUIREDYou must login to the website to accept the new conditions
AUTHORIZED_ONLY_FOR_DOMAIN_ROYou are attempting to login to the Betfair Romania domain with a non .ro account.
AUTHORIZED_ONLY_FOR_DOMAIN_SEYou are attempting to login to the Betfair Swedish domain with a non .se account.
SWEDEN_NATIONAL_IDENTIFIER_REQUIREDYou must provided your Swedish National identifier via Betfair.se before proceeding.
SWEDEN_BANK_ID_VERIFICATION_REQUIREDYou must provided your Swedish bank id via Betfair.se before proceeding.
ACTIONS_REQUIREDYou must login to https://www.betfair.com to provide the missing information.
INPUT_VALIDATION_ERROR There is a problem with the validity of the data submitted.  Please check that the request is correctly formatted (including the required request headers).

URL Definition (Global)


https://identitysso.betfair.com/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

URL Definition - Other Jurisdictions

Please use the below if your country of residence is in one of the list jurisdictions.


JurisdictionEndpoint
Australia

https://identitysso.betfair.com.au/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

Italy

https://identitysso.betfair.it/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>

Spainhttps://identitysso.betfair.es/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>
Romaniahttps://identitysso.betfair.ro/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>
Sweden
https://identitysso.betfair.se/view/login?product=<theProductDescriptor>&url=<theRedirectUrl>


Parameters

NameDescriptionSample
product(mandatory)The product for which the login page is used and on which the user will do the login; This should be your application key."IhDSui3ODdsdwo"
url (mandatory)The url to which the the browser should be redirected in case of a successful login. 
By default only https://www.betfair.com will be allowed
https://www.betfair.com


Note

Please note that all method names are case sensitive, this includes login, keepAlive and logout.