Table of Contents |
---|
When & How to Use Vendor Services
There are two separate methods available to Vendors.
- Vendor Services API - Available to licensed software vendors who want to provide Betfair Exchange customers access to their certified software using a subscription based system.
- Vendor Web API - Available to licensed software vendors who want to develop web applications using the Betfair API for access by Betfair Exchange customers.
Anchor | ||||
---|---|---|---|---|
|
The Vendor Services API allows licensed and certified Software Vendors to manage the permissioning of Betfair accounts to their API-NG application/s.
...
There are two key processes that Vendor will need to following when using the Vendor Services in API-NG:
Each of these processes are detailed below.
Anchor | ||||
---|---|---|---|---|
|
Preconditions:
- Customer has a Betfair account.
- Vendor has a Betfair vendor account, the App Key for their app, and their (Vendor) session token
...
- Customer visits Vendor’s web site and decides to sign up for the Vendor’s app.
- The Customer purchases a 12 month subscription to the app from the Vendor’s web site.
- The Vendor’s website server then calls the Account API-NG operation getApplicationSubscriptionToken, passing in the Vendor’s App Key, a valid Session Token for the Vendor’s Betfair account (to prove that they own that App Key) and the length of the subscription required (365 days in this scenario).
- Betfair returns a Subscription Token in the form of ABCD-EFGH-IJKL to the Vendor
- The Subscription Token is then provided to the 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. - The Vendors app requires the Customer to login to Betfair using the Interactive Login method. See sample code Interactive Login sample code here
- Betfair returns Customer’s Session Token to the app.
- The subscription is then activated by the app calling activateApplicationSubscription passing in the Subscription Token and a valid Session Token for the Customer. Please note: the X-Application header is not required for the activateApplicationSubscription request.
Anchor CheckingSub CheckingSub
Checking a Customers Subscription History
CheckingSub | |
CheckingSub |
In this scenario the Vendor wishes to check the customer’s subscription status to establish if the customer has:
...
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:
- Vendor’s app client requires Customer to login to Betfair using the Interactive Login method.
- Betfair returns Customer’s Session Token to the Vendor’s app client.
- 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.
- 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)
Server side process:
- Vendor’s app client requires Customer to login to Betfair using Interactive Login method.
- Betfair returns Customer’s Session Token to the Vendor’s app client.
- Vendor’s app client calls getVendorClientId citing Customer’s session token from step 1.
- Betfair returns Customer’s vendorClientId.
- Vendor’s App client sends Customer’s vendorClientId to Vendor’s app server.
- Vendor’s app server calls getApplicationSubscriptionHistory citing Vendor’s Session Token, Vendor’s App Key, and the vendorClientID from step 4.
- 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).
Anchor | ||||
---|---|---|---|---|
|
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.
...
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:
...
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, e.g grant_type REFRESH_TOKEN.
...
Tip |
---|
You can user 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, it is 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.
...
Note |
---|
The getAccountStatement operation isn't available via the Vendor Web API |
User Revocation
The user may choose to revoke the permissions previously granted to your web application. 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.
Legacy Subscriptions
The way subscriptions are handled for web applications differ 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.
...
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
Sample Code
Sample code that demonstrates the web apps interaction is available via https://github.com/betfair/sample-web-app-vendor/
...