Versions Compared

Key

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

...

Appanvil karma designer
summary Home | API Status | Historical Data | Vendor Program | Developer Forum Vendor Services API
page{"id":"EJyr1dNQxAJdJguiodbJA","name":"page","children":[{"id":"iOCUkGtPzoYzSRQ_IZAXO","params":{"background":{"light":"#ffffff99","dark":"#1d212599"},"padding":20,"gap":10,"backgroundSize":"contain","image":{"value":"att19398657","target":"_blank","type":"attachment"}},"children":[],"name":"section"},{"params":{"padding":0,"gap":0,"image":{"value":"https://images.unsplash.com/photo-1554034483-04fda0d3507b?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wzMzg3MzF8MHwxfHNlYXJjaHw2fHxncmFkaWVudHxlbnwwfDB8fHwxNzAyMzkyMDI1fDA&ixlib=rb-4.0.3&q=80&w=1080","target":"_self","type":"link"},"background":{"type":"solid","dark":"#1D2125","light":"#000000"}},"children":[{"name":"row","children":[{"name":"column","children":[{"name":"text","params":{"templateId":"headline 2","value":[{"type":"paragraph","children":[{"type":"paragraph","children":[{"text":"","fontSize":18},{"type":"link","link":{"value":"https://betfair-developer-docs.atlassian.net/wiki/spaces/1smk3cen4v3lu3yomq5qye0ni/overview","target":"_blank","type":"link"},"children":[{"text":"Home","letterSpacing":0,"fontFamily":"Poppins, sans-serif","backgroundColor":{"type":"solid","light":"#000000"},"color":{"type":"solid","light":"#ffffff"},"fontSize":18}]},{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","text":" | ","backgroundColor":{"type":"solid","light":"#000000"},"color":{"type":"solid","light":"#ffffff"},"fontSize":18},{"type":"link","link":{"value":"https://status.developer.betfair.com/","target":"_blank","type":"link"},"children":[{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","text":"API Status ","backgroundColor":{"type":"solid","light":"#000000"},"color":{"type":"solid","light":"#ffffff"},"fontSize":18}]},{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","text":"| ","backgroundColor":{"type":"solid","light":"#000000"},"color":{"type":"solid","light":"#ffffff"},"fontSize":18},{"type":"link","link":{"value":"https://historicdata.betfair.com/","target":"_blank","type":"link"},"children":[{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","backgroundColor":{"type":"solid","light":"#000000"},"text":"Historical Data","color":{"type":"solid","light":"#ffffff"},"fontSize":18}]},{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","backgroundColor":{"type":"solid","light":"#000000"},"text":" | ","color":{"type":"solid","light":"#ffffff"},"fontSize":18},{"type":"link","link":{"value":"https://developer.betfair.com/en/vendor-program/the-process/","target":"_blank","type":"link"},"children":[{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","backgroundColor":{"type":"solid","light":"#000000"},"text":"Vendor Program","color":{"type":"solid","light":"#ffffff"},"fontSize":18}]},{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","backgroundColor":{"type":"solid","light":"#000000"},"text":" | ","color":{"type":"solid","light":"#ffffff"},"fontSize":18},{"type":"link","link":{"value":"https://forum.developer.betfair.com/","target":"_blank","type":"link"},"children":[{"letterSpacing":0,"fontFamily":"Poppins, sans-serif","text":"Developer Forum","backgroundColor":{"type":"solid","light":"#000000"},"color":{"type":"solid","light":"#ffffff"},"fontSize":18}]},{"text":""}],"align":"center"}]}]},"children":[],"id":"CO2FLq4NeFdddoCtq1lBg"}],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"rJ16aA1aMkr8JRkTqLleH"},{"name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"7fUpJjIL2DsfQknnq-wa0"},{"name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"PIPX4pcmcW98Txau_w0mN"},{"name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"cCTICr9-WCCKgM1zihI3a"},{"name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"7tcYt28H6ZBQHonx-iXCM"},{"name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":20,"verticalAlignment":"top"},"id":"uu1DjQWXgO_NO5oXOAHWf"}],"params":{"layout":[1],"gap":10,"minHeight":10,"padding":25,"borderRadius":0,"backgroundColor":{"light":"#000000","dark":"#1C2124"},"size":"full"},"id":"w72_YQeLVmnO_3H7W5tTY"}],"name":"section","id":"x_1tr1IPoFQQqIJn_2Jii"},{"id":"xq8go2x2nzRB53Gl6mcmu","params":{"background":{"light":"#ffc40099","dark":"#1d21259999"},"padding":0,"gap":10,"image":{"value":"att21397505","target":"_blank","type":"attachment"}},"children":[{"id":"SwCvX77I8YzeID8el1Ux2","name":"row","children":[{"id":"dZPbWKV2EsN6n_Qs5Y85N","name":"column","children":[{"name":"text","params":{"templateId":"headline and paragraph","value":[{"type":"paragraph","children":[{"type":"paragraph","children":[{"text":"Vendor Services API","fontWeight":700,"letterSpacing":-3,"lineHeight":"64px","color":{"light":"#000000","dark":"#ffffff"},"fontFamily":"unset","fontSize":48}],"align":"center"}]}]},"children":[],"id":"0TtmjnO-f4xz9ArW2UWHv"}],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}},{"id":"5gTC-wLx6Abt7H_z-FUDj","name":"column","children":[{"name":"image","params":{"templateId":"full-width","alignment":"center","position":"center center","borderRadius":{"all":10,"bbl":0,"bbr":0,"btl":0,"btr":0,"isIndividualCorners":false},"image":{"value":"https://images.unsplash.com/photo-1524758631624-e2822e304c36?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wzMzg3MzF8MHwxfHNlYXJjaHw4fHxPZmZpY2V8ZW58MHx8fHwxNjkzNTYzNzQ1fDA&ixlib=rb-4.0.3&q=80&w=1080","target":"_self","type":"link"}},"children":[],"id":"I9mL3DVNDAKTji5vQM2F7"}],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}},{"id":"sJ_W6Nh8Xt4FguMmSMhQR","name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}},{"id":"YrSohHBn4-xI7LMUQezzu","name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}},{"id":"3pjGIxBYtledL6ItUdDL8","name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}},{"id":"m8F56VGx_TDGDmXAo3-XI","name":"column","children":[],"params":{"borderRadius":{"all":0,"btl":0,"bbl":0,"btr":0,"bbr":0,"isIndividualCorners":false},"padding":0,"gap":40,"verticalAlignment":"top"}}],"params":{"layout":[1],"gap":100,"minHeight":100,"padding":10,"borderRadius":0}}],"name":"section"}]}

...

Table of Content Zone
minLevel1
maxLevel2
typeflat
separatorpipe

When & How to Use Vendor Services

There are two separate methods available to Vendors.

Anchor
vendorservices
vendorservices
Vendor Services API

The Vendor Services API allows licensed and certified Software Vendors to manage the permissioning of Betfair accounts to their API-NG application/s.

With the Vendor Services API, you can:

  • Grant permission for users to access your application

  • Set the permission to expire after a specific date

  • Store arbitrary information against each subscription

  • View existing and historical application subscriptions

Info
  • For details on the operations to manage subscriptions, please see the Accounts section of the API-NG Reference Guide.

There are two key processes that Vendor will need to follow when using the Vendor Services in API-NG:

Each of these processes is detailed below.

Anchor
Subscribing
Subscribing
Subscribing a Customer

Preconditions:

  • Customer has a Betfair account.

Sign up for subscription

  •  

  • Vendor has a Betfair vendor account, the App Key for their app, and their (Vendor) session token

Example flow:

  1. The customer visits Vendor’s website and decides to sign up for the

...

  1. Vendor’s app.

...

  1. The

...

  1. Customer purchases a 12-month subscription to

...

  1. the app from the Vendor’s website.

  2. The Vendor’s website server then calls the Account API-NG operation getApplicationSubscriptionToken, passing in

...

  1. the Vendor’s App Key, a valid

...

  1. Session Token for the Vendor’s Betfair account (to prove that they own that

...

  1. App Key) and the length of the subscription required (365 days in this scenario).

  2. Betfair

...

  1. returns a Subscription Token

...

  1. in the form of ABCD-EFGH-IJKL

...

  1. to the Vendor

  2. The

...

  1. Subscription Token is then provided to the

...

  1. instance of the Vendor’s app used by the Customer. 

    This may happen in a number of ways, including:

    i)  Emailed from Vendor to Customer, who then types the Subscription Token into the app.
    ii) Associated with the Customer’s app instance by the Vendor, so that the token can be cited by the app based on Customer login to the app.

  2. The Vendors app requires the Customer to login to Betfair using the Interactive Login method. See sample code Interactive Login sample code here

  3. Betfair returns Customer’s Session Token to the app.

  4. The subscription is then activated by the app calling activateApplicationSubscription

...

  1. passing in the

...

 

Image Removed

  1. Subscription Token and a valid

...

  1. Session Token for the Customer.  Please note:  the X-Application header is not required for the activateApplicationSubscription request.

Image Added

Anchor
CheckingSub
CheckingSub
Checking a Customers Subscription History

In this scenario, the Vendor wishes to check the customer’s subscription status to establish if the customer has:

  1. An existing active subscription.

  2. An expired subscription.

  3. A cancelled subscription.

  4. No current or previous subscription history (i.e. Customer is entirely new).

This can be done within the application itself (client side) or by Vendor on their app server (server side).  Each process is explained in more detail below:

Client side process:

  1. Vendor’s app client requires Customer to login to Betfair using the Interactive Login method.  

  2. Betfair returns Customer’s Session Token to the Vendor’s app client.

  3. Vendor’s app client calls getApplicationSubscriptionHistory citing Vendors App Key in the request body and the customer's Session Token in the X-Authentication header.

  4. Betfair returns Customer’s subscription history.  If an empty list is returned then the customer has no current or previous subscription history (i.e. Customer is entirely new)

Image Added

Server side process:

  1. Vendor’s app client requires the Customer to login to Betfair using Interactive Login method.  

  2. Betfair returns Customer’s Session Token to the Vendor’s app client.

  3. Vendor’s app client calls getVendorClientId citing the Customer’s session token from step 1.

  4. Betfair returns the Customer’s vendorClientId.

  5. Vendor’s App client sends the Customer’s vendorClientId to Vendor’s app server.

  6. Vendor’s app server calls getApplicationSubscriptionHistory citing Vendor’s Session Token, Vendor’s App Key, and the vendorClientID from step 4.

  7. Betfair returns Customer’s complete history for the Vendor’s app (as identified by the app key cited in step 5).  If an empty list is returned then the customer has no current or previous subscription history (i.e. Customer is entirely new).


Image Added

Anchor
vendorwebapi
vendorwebapi
Vendor Web API

The Vendor Web API is available to licensed Software Vendors who are creating web-based applications  These operations enable the web application to carry out operations on the users behalf using the OAuth2 protocol.

Operations

The following operations are available via the Vendor Web API

OAuth 2 Flow - Creating an Access Token

The user authentication via web apps is underpinned by the OAuth 2 protocol.

You will need to redirect the user to the Betfair login page (identitysso.betfair.com/view/vendor-login), along with up to three parameters:

  • client_id (mandatory): this is your vendor ID, returned to you by the getDeveloperAppKeys call provided you have been registered as a web vendor

  • response_type: this needs to be set to 'code', to indicate you are requesting an authorization code (see later)

  • redirect_uri (optional): this will be appended to the URL you provided upon sign-up to the Vendor Program when we redirect the user back to your site after login. The redirect_uri needs to be URL encoded.

Creating An Access Token - Betfair.com customers
Code Block
https://identitysso.betfair.com/view/vendor-login?client_id=123456&response_type=code&redirect_uri=newjoiner


Info

Other Jurisdictions

Please use the below URL for end users whose country of residence is in one of the listed jurisdictions.

Info



Tip

Linking OAuth 2 Flow to Affiliate PartnerId

If you're a Betfair Affiliate, you should append the following to the redirect_uri to ensure that any new account sign ups are linked to your assigned partnerId '&rfr=xxxx&PI=xxxx&pi=partnerxxxx'

Please replace 'xxxx' with your partnerId

For example: https://identitysso.betfair.com/view/vendor-login?client_id=123456&response_type=code&redirect_uri=newjoiner&rfr=12345&PI=12345&pi=partner12345

Then Encode the redirect_uri value: https://identitysso.betfair.com/view/vendor-login?client_id=123456&response_type=code&redirect_uri=newjoiner%26rfr%3D12345%26PI%3D12345%26pi%3Dpartner12345

This ensures that your partner id persists through the Betfair registration should a new user need to open a Betfair account via Join Now


The user will log in and be presented with a message asking them to allow you to perform Betfair calls on their behalf, as shown below.

Image Added


Info

Should they accept this message, they will be redirected to your site (using your redirect URL + any optional parameters). Critically, we will include an authorization code as a parameter, under the parameter name "code".

NOTE: The authorization code will be valid for a single use for 10 minutes.


Example redirect
Code Block
https://mywebsite.com/newjoiner?code=12345


Info

You will need to propagate this 'code' to your back-end, from which you will have to exchange it for an access token.

The access token will allow you to use the Betfair API on the user's behalf. To obtain the access token you will need to call the token operation on the Accounts API

Example Token Request

The token call takes the following parameters:

Request Headers

  • Header: 'X-Application' : 'Your app key' (This is the App Key assigned to your Vendor account)

  • Header: 'X-Authentication' : 'Your session token' (This is the session token generated by your Vendor account)

Request Body

  • client_id: your vendor ID, returned to you by the getDeveloperAppKeys call provided you have been registered as a web vendor

  • grant_type: in this context, this will have to be set to 'AUTHORIZATION_CODE' 

  • code: the code you were returned 

  • client_secret: your secret, obtained from GetDeveloperAppKeys

Response Parameters

  • access_token: the access token, used to call Betfair on the user's behalf 

  • token_type: metadata for the access token (see 'Making calls on the user's behalf') 

  • expires_in: how long the access token will be valid for (in seconds)

  • refresh_token: a token that can be used to create a new access token (see 'Using the refresh token')

  • application_subscription: contains the vendor client ID, a unique identifier for a user. Can also contain some subscription-related information (See 'Legacy Subscriptions')


Warning

IMPORTANT

To protect sensitive information such as your app key and secret, it is important that the token operation only be called from server to server.


Example token request - REST
Code Block
X-Application: 'your App key'
X-Authentication : 'your session token'
Accept:  application/json
Content-Type:  application/json
 
Endpoint

https://api.betfair.com/exchange/account/rest/v1.0/token/
 
Request Body

{"client_id"="4534","grant_type":"AUTHORIZATION_CODE","code":"-22a1-12151008-000007cb61","client_secret":"bc183d-f5-40dc-82a6-d97681"}
 
Response
 
{"access_token":"KeOi+kyg2RvDK4HM+W46CvSnP5w=","refresh_token":"50d76117-7f85-375v-a38f-ffb332713f93","application_subscription":{"vendor_client_id":"456238"},"token_type":"BEARER","expires_in":"14400"}


Example token request - JSON
Code Block
X-Application: 'your App key'
X-Authentication : 'your session token'
Accept:  application/json
Content-Type:  application/json

Endpoint

https://api.betfair.com/exchange/account/json-rpc/v1

Request

{"jsonrpc": "2.0", "method": "AccountAPING/v1.0/token", "params": {"client_id":"CLIENTID","grant_type":"AUTHORIZATION_CODE","code":"CODE","client_secret":"CLIENTSECRET"}, "id": 1 }


OAuth 2 Flow - Using the Refresh Token

When the access token expires, it is possible to create a new one without any user input, using the refresh token. This is done with the same call that was used to create it originally, the token operation, but with a different set of parameters, for example, grant_type: REFRESH_TOKEN and refresh_token:

Tip

Session Expiry

Please note: session expiry can differ from user to user depending on the customers' preference and jurisdiction. The default expiry limit is 24 hours and the lowest possible expiry time is 20 minutes,


Header: 'X-Application' : 'your app key'

Header: 'X-Authentication' : 'your session token' 

client_id: your vendor ID, obtained from /wiki/spaces/OL/pages/1671181

grant_type: 'REFRESH_TOKEN'

refresh_token: the refresh token for the user 

client_secret: your secret, obtained from/wiki/spaces/OL/pages/1671181


This will return the same information as the original call:


access_token: the access token, used to call Betfair on the user's behalf

token_type: metadata for the access token (see 'Making calls on the user's behalf')

expires_in: how long the access token will be valid for (in seconds)

refresh_token: the refresh token remains the same

application_subscription: contains the vendor client ID, a unique identifier for a user


Example Refresh Token request - REST
Code Block
X-Application: 'your App key'
X-Authentication : 'your session token'
Accept:  application/json
Content-Type:  application/json
 
Endpoint

https://api.betfair.com/exchange/account/rest/v1.0/token/
 
Request Body

{"client_id"="4534","grant_type":"REFRESH_TOKEN","refresh_token":"50d76117-7f85-375v-a38f-ffb332713f93","client_secret":"bc183d-f5-40dc-82a6-d97681"}
 
Response
 
{"access_token":"KeOi+kyg2RvDK4HM+W46CvSnP5w=","refresh_token":"50d76117-7f85-375v-a38f-ffb332713f93","application_subscription":{"vendor_client_id":"456238"},"token_type":"BEARER","expires_in":"14400"}



Tip

You can use the 'expires_in' value to determine when the access token will stop being valid. Alternatively, if calls made with the access token start returning an INVALID_SESSION error, its likely that the token has expired.

Making API Calls On The Users Behalf

Once you have an access token, you can start calling the Betfair API on the user's behalf based on their actions on your site.

You will need to populate headers in a different way to a standard API call:

X-Application: your application key

Authorization: token_type + " " + access_token

The Authorization header needs to be a concatenation of the token type and the access token (both returned by the token call), separated by a space.

Example:

Image Added

Betfair will use the access token to determine which user the calls are being made for.

These calls also have to be from back-end to back-end.

Note

Please Note

The following API operations aren't available using the Vendor Web API

  • Navigation Data for Applications.

  • getAccountStatement

  • Logout (use revokeAccessToWebApp only to remove the link between an account and a Vendor Web app)

User Revocation

The user may choose to revoke the permissions previously granted to your web application. You must provide the user with the facility to do so within any web app using the revokeAccessToWebApp operation.

This will invalidate the access token and destroy your refresh token. Any subsequent calls to Betfair using the access token, or any attempt to generate a new one using the refresh token will result in either an INVALID_SESSION exception or UNEXPECTED_ERROR respectively.

Example RevokeAccessToWebApp Request
Code Block
X-Application: 'your App key'
Authorization : 'the Authorization header'
Accept:  application/json
Content-Type:  application/json
 
Endpoint  https://api.betfair.com/exchange/account/rest/v1.0/revokeAccessToWebApp/'   

Request Body

{"vendorId"="your vendor ID, returned to you by the getDeveloperAppKeys"}
 

Legacy Subscriptions

The way subscriptions are handled for web applications differs greatly from the way they were for desktop-based applications. The subscription token model is no longer enforced, however, you may still choose to create and manage subscriptions using the existing API calls.

Please note that in this model, Betfair will no longer prevent requests for a user with an expired or canceled subscription. You can choose what action to take based on information contained in the application_subscription field returned by the token operation.

The available operations are the following:

If you do use these calls to manage subscriptions, the token call will return information on the most relevant subscription (i.e. the subscription with the latest expiration date) as part of the application_subscription object.

Flow Diagram

Image Added



Sample Code

Sample code that demonstrates the web apps interaction is available via https://github.com/betfair/sample-web-app-vendor/